1 Some words on Literate Programming

This section will discuss some general aspects of literate programming and give a historical overview of the existing program documentation systems known to the author. Readers interested only in ProgDoc can safely skip this section and continue with section 2 on page .

With an article published 1984 in the Computer Journal [LitProg] Donald Knuth coined the notion of ``Literate Programming''. Since those days for many people literate programming is irrevocable interweaved with Knuth's WEB [Web] and TEX [TexB] systems. And many people refuse literate programming solely because they refuse TEX or WEB.

Knuth justifies the term ``literate programming'' in [LitProg] with his belief that ``.. the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature.'' To support this programming style, he introduced the WEB system which is in fact both a language and a suite of utilities. In WEB, the program source code and the documentation are written together into one source file, delimited by special control sequences. The program source can be split into arbitrary chunks which can be presented in arbitrary order. The tangle program extracts these code chunks from the WEB file and assembles them in the right order into a valid source file. Another program called weave combines the documentation parts of the WEB files with pretty printed versions of the code chunks into a file which thereupon can be processed by TEX.

This system has many advantages. First of all, it fulfills the ``one source'' property. Because source code and documentation reside in one file, they are always consistent with each other. Second, the programmer is free to present the code he writes in arbitrary order. Usually, he will present the code in a manner more suitable for a human reader to understand the program. This can be done by rearranging code chunks, but also by using macros inside the code chunks, which can be defined later on in the WEB file. This way a top-down development approach can be achieved, in which the the structure of a program as a whole is presented in the beginning and then subsequently refined. tangle will expand these macros at the right place when constructing the source file out of the WEB file.

Another feature of the WEB system is the automatic construction of exhaustive indexes and cross references by weave. Every code chunk is accompanied by references which link it to all other chunks which reference or use it. Also an index of keywords with respect to code chunks is created and the source code is pretty printed for the documentation part. The best way to convince yourself of WEB's capabilities is to have a look at Knuth's TEX implementation [Tex]. It was entirely written in WEB and is undoubtful a masterpiece of publishing and literate programming.