% This file generates the user manual; TeX it, don't read it!\def\tangref{3} % where the main explanation of CTANGLing is given\input cwebmac\acrofalse\pdffalse\pdftexfalse\def\page{\box255 } \normalbottom\parskip 0pt plus 1pt\def\RA{\char'31 } % right arrow\def\hang{\hangindent 4em\ignorespaces}\font\eightrm=cmr8\font\ninerm=cmr9\font\ninett=cmtt9\font\eighttt=cmtt8\font\twelvett=cmtt12\font\quoterm=cmssq8\font\quoteit=cmssqi8\font\authorfont=cmr12\font\sectionfont=cmbx12\def\pb{\.{|...|}}\def\v{\.{\char'174}} % vertical (|) in typewriter font\def\lpile{\def\cr{\hfill\endline}\matrix} % I only use \lpile by itself\abovedisplayskip=.5\abovedisplayskip\belowdisplayskip=.5\belowdisplayskip\abovedisplayshortskip=.5\abovedisplayshortskip\belowdisplayshortskip=.5\belowdisplayshortskip\advance\baselineskip by -.5pt\advance\pageheight by \baselineskip % the manual just got a bit longer\advance\fullpageheight by \baselineskip\setpage\outer\def\section #1.{\penalty-500\bigskip        \centerline{\sectionfont\def\.##1{{\twelvett##1}} #1}\nobreak\vskip 6pt        \everypar{\hskip-\parindent\everypar{}}}\def\lheader{\mainfont\the\pageno\hfill\sc\runninghead\hfill}\def\rheader{\hfill\sc\runninghead\hfill\mainfont\the\pageno}\def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 3.64)}% This verbatim mode assumes that ! marks are !! in the text being copied.\def\verbatim{\begingroup  \def\do##1{\catcode`##1=12 } \dospecials  \parskip 0pt \parindent 0pt \let\!=!  \catcode`\ =13 \catcode`\^^M=13  \tt \catcode`\!=0 \verbatimdefs \verbatimgobble}{\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} %  \gdef\verbatimgobble#1^^M{}}\null\vfill\centerline{\titlefont The {\ttitlefont CWEB} System of    Structured Documentation}\vskip 18pt\centerline{(Version 3.64 --- February 2002)}\vskip 24pt\centerline{\authorfont Donald E. Knuth and Silvio Levy}\vfill\noindent\TeX\ is a trademark of the American Mathematical Society.\noindentAcrobat Reader is a trademark of Adobe Systems Incorporated.\bigskip\noindentThe printed form of this manual is copyright \copyright\ 1994  by Addison-Wesley Publishing Company, Inc.  All rights reserved.\smallskip\noindentThe electronic form is copyright \copyright\ 1987, 1990, 1993, 2000  by Silvio Levy and Donald E. Knuth.\bigskip\noindentPermission is granted to make and distribute verbatim copies of theelectronic form of this document provided that the electronic copyrightnotice and this permission notice are preserved on all copies.\smallskip\noindentPermission is granted to copy and distribute modified versions of theelectronic form of this document under the conditions for verbatim copying,provided that the entire resulting derived work is distributed under the termsof a permission notice identical to this one.\smallskip\noindentIndividuals may make copies of the documentation from the electronic filesfor their own personal use.\smallskip\noindentInternet page \.{http://www-cs-faculty.stanford.edu/\char`\~knuth/cweb.html}contains current info about \.{CWEB} and related topics.\pageno=0 \titletrue\eject\titletrue\centerline{\titlefont The {\ttitlefont CWEB} System of    Structured Documentation}\vskip 15pt plus 3pt minus 3pt\centerline{\authorfont Donald E. Knuth and Silvio Levy}\vskip 24pt plus 3pt minus 3pt\noindentThis document describes a version of Don Knuth's \.{WEB} system,adapted to \CEE/ by Silvio Levy.  Since its creation in 1987, \.{CWEB}has been revised and enhanced in various ways, by both Knuth and Levy.We now believe that its evolution is near an end; however, bugreports, suggestions and comments are still welcome, andshould be sent to Levy (\.{levy@math.berkeley.edu}).Readers who are familiar with Knuth's memo ``The \.{WEB} System of StructuredDocumentation'' will be ableto skim this material rapidly, because \.{CWEB} and \.{WEB} sharethe same philosophy and (essentially) the same syntax.  In some respects\.{CWEB} is a simplificationof \.{WEB}: for example, \.{CWEB} does not need \.{WEB}'s featuresfor macro definition and string handling, because \CEE/ and itspreprocessor already take care of macros and strings. Similarly, the \.{WEB}conventions of denoting octal and hexadecimal constants by \.{@'77}and \.{@"3f} are replaced by \CEE/'s conventions \.{077} and\.{0x3f}. All other features of \.{WEB} have beenretained, and new features have been added.We thank all who contributed suggestions and criticism tothe development of \.{CWEB}. We are especially grateful to SteveAvery, Nelson Beebe, Hans-Hermann Bode, Klaus Guntermann, Norman Ramsey,Joachim Schnitter, and Saroj Mahapatra,who contributed code, and to Cameron Smith, whomade many suggestions improving the manual.  Ramsey has madeliterate programming accessible to users of yet other languages by means ofhis \.{SPIDER} system [see {\sl Communications of the ACM\/ \bf32} (1989),1051--1055]. The book {\sl Literate Programming\/} by Knuth (1992) containsa comprehensive bibliography of related early work.Bode, Schnitter, and Mahapatra adapted \.{CWEB} so that it worksfor \CPLUSPLUS/ as well; therefore in the text below you can read \CPLUSPLUS/for \CEE/ if you so desire.\section Introduction.The philosophy behind \.{CWEB} isthat programmers who want to provide the bestpossible documentation for their programs need two thingssimultaneously:  a language like \TEX/ for formatting, and a language like\CEE/ for programming. Neither type of language can provide thebest documentation by itself. But when both are appropriately combined, weobtain a system that is much more useful than either language separately.The structure of a software program may be thought of as a ``web'' that ismade up of many interconnected pieces. To document such a program, we wantto explain each individual part of the web and how it relates to itsneighbors. The typographic tools provided by \TEX/ give us an opportunityto explain the local structure of each part by making that structurevisible, and the programming tools provided by \CEE/ make it possiblefor us to specify the algorithms formally and unambiguously. By combiningthe two, we can develop a style of programming that maximizes our abilityto perceive the structure of a complex piece of software, and at the sametime the documented programs can be mechanically translated into a workingsoftware system that matches the documentation.The \.{CWEB} system consists of two programs named \.{CWEAVE} and \.{CTANGLE}.When writing a \.{CWEB} program the user keeps the\CEE/ code and the documentation in the same file, called the \.{CWEB}file and generally named \.{something.w}.  The command`\.{cweave} \.{something}' creates an output file \.{something.tex}, whichcan then be fed to \TEX/, yielding a ``pretty printed'' version of\.{something.w} that correctly handlestypographic details like page layout and the use of indentation,italics, boldface, and mathematical symbols. The typeset output alsoincludes extensive cross-indexinformation that is gathered automatically.  Similarly, if you run thecommand `\.{ctangle} \.{something}' you will get a \CEE/ file \.{something.c},which can then be compiled to yield executable code.Besides providing a documentation tool, \.{CWEB} enhances the \CEE/language by providing theability to permute pieces of the program text, so that a large system canbe understood entirely in terms of small sections and their localinterrelationships.  The \.{CTANGLE} program is so named because it takes agiven web and moves the sections from their web structure into the orderrequired by \CEE/; the advantage of programming in \.{CWEB} is that thealgorithms can be expressed in ``untangled'' form, with each sectionexplained separately.  The \.{CWEAVE} program is so named because it takesa given web and intertwines the \TEX/ and \CEE/ portions contained ineach section, then it knits the whole fabric into a structured document.(Get it? Wow.)  Perhaps there is some deep connection here with the factthat the German word for ``weave'' is ``{\it webe\/}'', and thecorresponding Latin imperative is ``{\it texe\/}''!A user of \.{CWEB} should be fairly familiar with the \CEE/programming language.  A minimal amount of acquaintance with \TEX/ is alsodesirable, but in fact it can be acquired as one uses \.{CWEB}, sincestraight text can be typeset in \TEX/ with virtually no knowledge ofthat language.  To someone familiar with both \CEE/ and \TEX/ the amount ofeffort necessary to learn the commands of \.{CWEB} is small.\section Overview.Two kinds of material go into \.{CWEB} files: \TEX/ text and \CEE/ text.A programmer writing in \.{CWEB} should be thinking both of thedocumentation and of the \CEE/ program being created;i.e., the programmer should be instinctively aware of the differentactions that \.{CWEAVE} and \.{CTANGLE} will perform on the \.{CWEB} file.\TEX/ text is essentially copied without change by \.{CWEAVE}, and it isentirely deleted by \.{CTANGLE}; the \TEX/ text is ``puredocumentation.'' \CEE/ text, on the other hand, is formatted by\.{CWEAVE} and it is shuffled around by \.{CTANGLE}, according to rules thatwill become clear later. For now the important point to keep in mind isthat there are two kinds of text. Writing \.{CWEB} programs is somethinglike writing \TEX/ documents, but with an additional ``\CEE/ mode''that is added to \TEX/'s horizontal mode, vertical mode, and math mode.A \.{CWEB} file is built up from units called {\sl sections\/} that are moreor less self-contained.  Each section has three parts:\yskip\item{$\bullet$} A \TEX/ part, containing explanatory material about whatis going on in the section.\item{$\bullet$} A middle part, containing macro definitions that serve asabbreviations for \CEE/ constructions that would be less comprehensibleif written out in full each time. They are turned by \.{CTANGLE} intopreprocessor macro definitions.\item{$\bullet$} A \CEE/ part, containing a piece of the program that\.{CTANGLE} will produce. This \CEE/ code should ideally be about adozen lines long, so that it is easily comprehensible as a unit and sothat its structure is readily perceived.\yskip\noindent The three parts of each section must appear in this order;i.e., the \TEX/ commentary must come first, then the middle part, andfinally the \CEE/ code. Any of the parts may be empty.A section begins with either of the symbols `\.{@\ }' or `\.{@*}', where`\.{\ }' denotes a blank space. A section endsat the beginning of the next section (i.e., at the next`\.{@\ }' or `\.{@*}'), or at the end of the file, whichever comes first.The \.{CWEB} file may also contain material that is not part of any sectionat all, namely the text (if any) that occurs before the first section.Such text is said to be ``in limbo''; it is ignored by \.{CTANGLE}and copied essentially verbatim by \.{CWEAVE}, so its function is toprovide any additional formatting instructions that may be desired in the\TEX/ output. Indeed, it is customary to begin a \.{CWEB} file with\TEX/ code in limbo that loads special fonts, defines special macros,changes the page sizes, and/or produces a title page.Sections are numbered consecutively, starting with 1. These numbers appearat the beginning of each section of the \TEX/ documentation output by\.{CWEAVE}, and they appearas bracketed comments at the beginning and end of the code generated by thatsection in the \CEE/ program output by \.{CTANGLE}.\section Section Names.Fortunately, you never mention these numbers yourself when you are writingin \.{CWEB}. You just say `\.{@\ }' or `\.{@*}' at the beginning of eachnew section, and the numbers are supplied automatically by \.{CWEAVE} and\.{CTANGLE}. As far as you are concerned, a section has a{\sl name\/} instead of a number; its name is specified by writing`\.{@<}' followed by \TEX/ text followed by `\.{@>}'. When \.{CWEAVE}outputs a section name, it replaces the `\.{@<}' and `\.{@>}' byangle brackets and inserts the section number in small type. Thus, when youread the output of \.{CWEAVE} it is easy to locate any section that isreferred to in another section.For expository purposes, a section name should be a good description of thecontents of that section; i.e., it should stand for the abstractionrepresented by the section. Then the section can be ``plugged into'' one ormore other sections in such a waythat unimportant details of its inner workingsare suppressed.  A section name therefore ought to be long enough to conveythe necessary meaning.Unfortunately, it is laborious to typesuch long names over and over again, and it is also difficult to specify along name twice in exactly the same way so that \.{CWEAVE} and \.{CTANGLE}will be able to match the names to the sections. To ameliorate this situation,\.{CWEAVE} and \.{CTANGLE} let you abbreviate a section name, so long asthe full name appears somewhere in the \.{CWEB} file; you can type simply`\.{@<$\alpha$...@>}', where $\alpha$ is any string that is a prefix ofexactly one section name appearing in the file. For example, `\.{@<Clearthe arrays@>}' can be abbreviated to `\.{@<Clear...@>}' if no other sectionname begins with the five letters `\.{Clear}'.  Elsewhereyou might use the abbreviation `\.{@<Clear t...@>}', and so on.