This article is from the Literate Programming FAQ, by David B. Thompson email@example.com with numerous contributions by others.
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings. In fact,
literate programs should be enjoyable reading, even inviting! (Sorry
Bob, I couldn't resist!) In general, literate programs combine source
and documentation in a single file. Literate programming tools then
parse the file to produce either readable documentation or compilable
source. The WEB style of literate programming was created by D.E.
Knuth during the development of his TeX typsetting software.
All the original work revolves around a particular literate
programming tool called WEB. Knuth says:
The philosophy behind WEB is that an experienced system pro-
grammer, who wants to provide the best possible documenta-
tion of his or her software products, needs two things
simultaneously: a language like TeX for formatting, and a
language like C for programming. Neither type of language
can provide the best documentation by itself; but when both
are appropriately combined, we obtain a system that is much
more useful than either language separately.
The structure of a software program may be thought of as a
web that is made up of many interconnected pieces. To docu-
ment such a program we want to explain each individual part
of the web and how it relates to its neighbours. The typo-
graphic tools provided by TeX give us an opportunity to
explain the local structure of each part by making that
structure visible, and the programming tools provided by
languages such as C or Fortran make it possible for us to
specify the algorithms formally and unambigously. By combin-
ing the two, we can develop a style of programming that max-
imizes our ability to perceive the structure of a complex
piece of software, and at the same time the documented pro-
grams can be mechanically translated into a working software
system that matches the documentation.
See Section ``Other Opinions'' for some additional thoughts on