The CWEB System of Structured

Documentation
by Donald E. Knuth and Silvio Levy (Reading, Massachusetts: Addison-Wesley, 1993),
iv+227pp.
ISBN 0-201-57569-8
The third printing (Spring 2001) has a spiffy new cover and greatly improved pages
inside, featuring the latest extensions for hypertext! Look for ``Version 3.6'' on the cover.
WEB

is a software system that facilitates the creation of readable programs. It was originally
developed by Donald E. Knuth as he wrote the TeX typesetting system. Users of WEB are able
to

Write programs of superior quality;

Produce state-of-the-art documentation;
Greatly reduce debugging time;
Maintain programs easily as conditions change.

The main idea is to regard a program as a communication to human beings rather than as a set
of instructions to a computer. Your program is also viewed as a hypertext document, rather
like the World Wide Web. (Indeed, Knuth used the word WEB for this purpose long before
CERN grabbed it!)
CWEB

is a version of WEB for documenting C, C++, and Java programs. WEB was adapted to C
by Silvio Levy in 1987, and since then both Knuth and Levy have revised and enhanced the
system in many ways, notably to support C++ and ANSI C. Thus CWEB combines TeX with
today's most widely used professional programming languages.
If you are in the software industry and do not use CWEB but your competitors do, your
competitors will soon overtake you---and you'll miss out on a lot of fun besides.
More comments about CWEB can be found in Daniel Mall's website for Literate Programming.
See also Leo, Edward K. Ream's Python-based outlining-editor/browser compatible with CWEB
and other literate programming tools.
This book is the definitive user's guide and reference manual for the CWEB system. The CWEB
software itself is freely available via anonymous ftp from ftp.cs.stanford.edu, in
directory ~ftp/pub/cweb. It consists of two programs:
CTANGLE

converts a source file foo.w to a compilable program file foo.c;

CWEAVE

converts a source file foo.w to a prettily-printable and cross-indexed document file

foo.tex.
Both CTANGLE and CWEAVE are stable, well-tested, and highly portable. They have been
installed on a wide variety of computers and operating systems.
download the latest version of cweb.tar.gz

An electronic form of this book comes free with the CWEB system, but the printed version
costs less than the price of laserprinting and has a nice cover and binding. Unfortunately it's
now out of print, but you might be able to buy a cheap used copy.
The second printing of this book also contains Knuth's open letter to the U.S. Commissioner
of Patents and Trademarks.
Sergey V. Korop's Russian translation of the CWEB manual
Soojin Nam's Korean translation of the CWEB manual
Germn Gonzlez-Morris's Spanish translation of the CWEB manual

Errata
Known errors in CWEB or its documentation have always been corrected immediately in the
online version. Only a few trivial bugs in the programs have been found since Version 3.4
was released in April 1995, except that many of the more recent features of C++ were not
properly supported. Version 3.6 corrects these flaws and adds important new capabilities
related to PDF files (Adobe Portable Document Files for the Acrobat reader). Version 3.64
improves the latter capabilities.
If your program worked with Version 3.4 but is formatted strangely with Version 3.6, the
probable cause is that you have used identifiers that became reserved keywords in the latest
C++. For example, the identifiers `and', `compl', `not', `or', `xor', and `not_eq' are now
reserved; also 'bool' is predeclared. The cure is to put a line like this near the beginning of
your .w file:
@s not_eq normal

It tells CWEAVE to format not_eq as a normal identifier, not as a relational operator.

The authors do not intend to change CWEB henceforth unless some devastating new bug is
discovered. Non-catastrophic infelicities should therefore be considered permanent features of
CWEB.

Hyperdocumentation
Version 3.61 of CWEB introduced cool new features with which you can weave programs in
PDF format with clickable links, and these features have been refined in version 3.64. In fact,
the new software gives you two ways to proceed, either with standard TeX together with
Mark A. Wicks's program dvipdfm, or with an extension of TeX called pdfTeX. Instructions
on how to use these features are explained in the current CWEB manual and examples appear in
the Makefile.
(Note for those who like gory details: Version 3.63 --- vintage 2001 --- was almost as good as
3.64; but it didn't handle LaTeX and Acrobat simultaneously, and it didn't do nearly as good a
job when making the bookmarks for an Acrobat file. Most of the changes between 3.63 and
3.64 occur in the file cwebmac.tex, which contains some very instructive TeX macros.)

Related books
The philosophy of literate programming is explained fully in the book Literate Programming,
which also contains an extensive bibliography of the subject. More than 30 example CWEB
programs can be found in The Stanford GraphBase; ten more are in MMIXware. And I've
made several additional programs available for downloading.