Comparison with WEB

The Document package is much less complex than WEB and the various WEB-like and WEB-derivative packages. The entire source and documentation for Document is around 1000 lines, compared to 10,000 lines for the original WEB. Other differences between Document and the sea of WEB style programs are: ²

Input File:

Most WEB packages start from an input file that is not a valid source code file. A program called weave takes the input file and makes a formatting language file, while a program called tangle takes the input file and makes a source code file. The Document package takes an input file that is already a valid source code file. The formatting language commands are imbedded in the comments of the source code, so that no changes need to be made to the file for compilation.

Macros:

Most WEB packages allow the user to define macros that stand for chunks of code or documentation, and that can be used to move code around and alter the flow of the program. The Document package does not provide this feature, and therefore the source code must be in the order in which it is to be compiled. There is, however, a mechanism to print out multiple documentation files. When combined with a formatting language that provides for the inclusion of files, this allows the user to alter the structure of the documentation to his own needs.

Languages:

Many, but not all, of the WEB packages are language-specific (both formatting and source code). For example, the original WEB package only worked with Pascal and TEX. Document is only slightly language-specific in that it needs to know something about the syntax (mainly the comment characters) of the source code language. It can be easily extended to languages that are not already incorporated.

Indexing:

Many WEB packages provide automatic indexing of things like variables and routines. Document does not do indexing automatically, but it can be done if the formatting language supports it, as is possible with L^ATEX and L^ATEX2HTML.

For more information on Literate Programming, a good starting point is the Literate Programming FAQ located at ftp://rtfm.mit.edu/pub/usenet/news.answers/literate-programming-faq.