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:
2
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 LATEX and
LATEX2HTML.
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.
Michael L. Hall