Node: CWEB Documentation, Next: , Previous: About This Manual, Up: Introduction


CWEB Documentation

As mentioned above, 3DLDF has been programmed using CWEB, which is a "literate programming" tool developed by Donald E. Knuth and Silvio Levy. See Sources of Information, for a reference to the CWEB manual. Knuth's TeX--The Program and Metafont--The Program both include a section "How to read a WEB" (pp. x-xv, in both volumes).

CWEB files combine source code and documentation. Running ctangle on a CWEB file, for example, main.web, produces the file main.c containing C or C++ code. Running cweave main.web creates a TeX file with pretty-printed source code and nicely formatted documentation. I find that using CWEB makes it more natural to document my code as I write it, and makes the source files easier to read when editing them. It does have certain consequences with regard to compilation, but these are taken care of by make. See Adding a File, and Changes, for more information.

The CWEB files in the directory 3DLDF-1.1.5.1/CWEB/ contain the source code for 3DLDF. The file 3DLDFprg.web in this directory is only ever used for cweaving; it is never ctangled and contains no C++ code for compilation. It does, however, include all of the other CWEB files, so that cweave 3DLDFprg.web generates the TeX file containing the complete documentation of the source code of 3DLDF.

The files 3DLDF-1.1.5.1/CWEB/3DLDFprg.tex, 3DLDF-1.1.5.1/CWEB/3DLDFprg.dvi, and 3DLDF-1.1.5.1/CWEB/3DLDFprg.ps are included in the distribution of 3DLDF as a convenience. However, users may generate them themselves, should there be some reason for doing so, by entering make ps from the command line of a shell from the working directory 3DLDF-1.1.5.1/ or 3DLDF-1.1.5.1/CWEB. Alternatively, the user may generate them by hand from the working directory 3DLDF-1.1.5.1/CWEB/ in the following way:

  1. cweave 3DLDFprg.web generates 3DLDFprg.tex.
  2. tex 3DLDFprg or tex 3DLDFprg.tex generates 3DLDFprg.dvi.
  3. dvips -o 3DLDFprg.ps 3DLDFprg (possibly with additional options) generates 3DLDFprg.ps.
  4. lpr -P<print queue> 3DLDFprg.ps sends 3DLDFprg.ps to a printer, on a UNIX or UNIX-like system.

The individual commands may differ, depending on the system you're using.