% 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 4.3)} % 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 4.3 --- May 2021)}\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. \smallskip\noindentFrom there you can also reach the \.{CWEB} development page\.{https://github.com/ascherer/cweb} with the really current news. \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 the \TeX-related mailing list \.{tex-k@tug.org}. 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. Section names must otherwise match character for character, exceptthat consecutive characters of white space (spaces, tab marks, newlines, and/orform feeds) are treated as equivalent to a single space, and such spaces aredeleted at the beginning and end of the name. Thus, `\.{@< Clear { }thearrays @>}' will also match the name in the previous example.Spaces following the ellipsis in abbreviations are ignored as well, butnot those before, so that `\.{@<Clear t ...@>}' would not match`\.{@<Clear the arrays@>}'. \section What \.{CTANGLE} Does.We have said that a section begins with `\.{@\ }' or `\.{@*}', but wedidn't say how it gets divided up into a \TEX/ part, a middle part,and a \CEE/ part. The middle part begins with the first appearance of`\.{@d}' or `\.{@f}' in the section, and the \CEE/ part begins withthe first appearance of `\.{@c}' or `\.{@<section name@>=}'.  In thelatter case you are saying, in effect, that the section name standsfor the \CEE/ text that follows. Alternatively, if the \CEE/ partbegins with `\.{@c}' instead of a section name, the current section issaid to be {\sl unnamed}. The construct `\.{@<section name@>}' can appearany number of times in the \CEE/ part of a section:Subsequent appearances indicate that a named section is being``used'' rather than ``defined.'' In other words, the\CEE/ code for the named section, presumably defined elsewhere, should bespliced in at this point in the \CEE/ program.  Indeed,the main idea of \.{CTANGLE} is to make a \CEE/ program out ofindividual sections, named and unnamed.  The exact way in which this is doneis this: First all the macro definitionsindicated by `\.{@d}' are turned into \CEE/ preprocessor macro definitionsand copied at the beginning.Then the \CEE/ parts of unnamed sections are copied down,in order; this constitutes the first-orderapproximation to the text of the program. (There should be at leastone unnamed section, otherwise there will be no program.) Then all sectionnames that appear in the first-order approximation are replaced by the \CEE/parts of the corresponding sections, and this substitution processcontinues until no section names remain. All comments are removed, becausethe \CEE/ program is intended only for the eyes of the \CEE/ compiler. If the same name has been given to more than one section, the \CEE/ textfor that name is obtained by putting together all of the \CEE/ parts inthe corresponding sections. This feature is useful, for example, in asection named `Global variables', since one can thendeclare global variables in whatever sections those variables areintroduced. When several sections have the same name, \.{CWEAVE} assigns thefirst section number as the number corresponding to that name, and itinserts a note at the bottom of that section telling the reader to `Seealso sections so-and-so'; this footnote gives the numbers of all the othersections having the same name as the present one. The \CEE/ textcorresponding to a section is usually formatted by \.{CWEAVE} so that theoutput has an equivalence sign in place of the equals sign in the \.{CWEB}file; i.e., the output says `$\langle\,$sectionname$\,\rangle\equiv\null$\CEE/ text'. However, in the case of the secondand subsequent appearances of a section with the same name, this `$\equiv$'sign is replaced by `$\mathrel+\equiv$', as an indication that thefollowing \CEE/ text is being appended to the \CEE/ text of another section. As \.{CTANGLE} enters and leaves sections, it inserts preprocessor\.{\#line} commands into the \CEE/ output file.  This means thatwhen the compiler gives you error messages, or when you debug your program,the messages refer to line numbers in the \.{CWEB} file, and not in the\CEE/ file.  In most cases you can thereforeforget about the \CEE/ file altogether. \section What \.{CWEAVE} Does.The general idea of \.{CWEAVE} is to make a \.{.tex} file from the \.{CWEB}file in the following way: The first line of the \.{.tex} filetells \TEX/ to input a file with macros thatdefine \.{CWEB}'s documentation conventions. The next lines of the filewill be copied from whatever \TEX/ text is in limbo before the firstsection.  Then comes the output for each section in turn, possiblyinterspersed with end-of-page marks.  Finally, \.{CWEAVE} will generate across-reference index that lists each section number in which each \CEE/identifier appears, and it will also generate an alphabetized listof the section names, as well as a table of contents thatshows the page and section numbers for each ``starred'' section. What is a ``starred'' section, you ask? A section that begins with `\.{@*}'instead of `\.{@\ }' is slightly special in that it denotes a new majorgroup of sections. The `\.{@*}' should be followed by the title of thisgroup, followed by a period. Such sections will always start on a new pagein the \TEX/ output, and the group title will appear as a running headlineon all subsequent pages until the next starred section. The title will alsoappear in the table of contents, and in boldface type at the beginning ofits section. Caution:  Do not use \TEX/ control sequences in such titles,unless you know that the \.{cwebmac} macros will do the right thing withthem. The reason is that these titles are converted to uppercase whenthey appear as running heads, and they are converted to boldface when theyappear at the beginning of their sections, and they are also written out toa table-of-contents file used for temporary storage while \TEX/ isworking; whatever control sequences you use must be meaningful in allthree of these modes. The \TEX/ output produced by \.{CWEAVE} for each section consists ofthe following: First comes the section number (e.g., `\.{\\M123.}'at the beginning of section 123, except that `\.{\\N}' appears in place of`\.{\\M}' at the beginning of a starred section). Then comes the\TEX/ part of the section, copied almost verbatim except as notedbelow. Then comes the middle part and the \CEE/ part, formattedso that there will be a little extra space between them if both arenonempty. The middle and \CEE/ parts are obtained by insertinga bunch of funny-looking \TEX/ macros into the \CEE/ program; thesemacros handle typographic details about fonts and proper math spacing,as well as line breaks and indentation. \section C Code in \TEX/ Text and Vice Versa.When you are typing \TEX/ text, you will probably want to make frequentreference to variables and other quantities in your \CEE/ code, and youwill want those variables to have the same typographic treatmentwhen they appear in your text as when they appear in yourprogram.  Therefore the \.{CWEB} language allows you to get the effect of\CEE/ editing within \TEX/ text, if you place `\.|' marks before andafter the \CEE/ material. For example, suppose you want to say somethinglike this:$$\hbox{If \PB{\\{pa}} is declared as `\PB{\&{int} ${}{*}\\{pa}$}',the assignment \PB{$\\{pa}\K{\AND}\|a[\T{0}]$} makes \PB{\\{pa}}point to the zeroth element of \PB{\|a}.}$$The \TEX/ text would look like this in your \.{CWEB} file:$$\lpile{\.{If |pa| is declared as `|int *pa|', the assignment}\cr\.{|pa=\&a[0]| makes |pa| point to the zeroth element of |a|.}\cr}$$And \.{CWEAVE} translates this into somethingyou are glad you didn't have to type:$$\lpile{\.{If \\PB\{\\\\\{pa\}\} is declared as `\\PB\{\\\&\{int\}  \$\{\}\{*\}\\\\\{pa\}\$\}', the}\cr\.{assignment \\PB\{\$\\\\\{pa\}\\K\{\\AND\}\\|a[\\T\{0\}]\$\}  makes \\PB\{\\\\\{pa\}\} point}\cr\.{to the zeroth element of \\PB\{\\|a\}.}\cr}$$Incidentally, the cross-reference index that \.{CWEAVE} would make, inthe presence of a comment like this, would includethe current section number as one of the index entries for \\{pa},even though \\{pa} might not appear in the \CEE/ part ofthis section. Thus, the index covers references to identifiers inthe explanatory comments as well as in the program itself; you willsoon learn to appreciate this feature. However, the identifiers\&{int} and \|a\ would not be indexed,because \.{CWEAVE} does not make index entries for reserved words orsingle-letter identifiers. Such identifiers are felt to be so ubiquitousthat it would be pointless to mention every place where they occur. Although a section begins with \TEX/ text and ends with \CEE/ text, wehave noted that the dividing line isn't sharp, since \CEE/ text can beincluded in \TEX/ text if it is enclosed in `\pb'.  Conversely, \TEX/ textappears frequently within \CEE/ text, because everything incomments (i.e., between \.{/*} and \.{*/}, or following \.{//})is treated as \TEX/ text.Likewise, the text of a section name consists of \TEX/ text, butthe construct \.{@<section name@>} as a whole is expected to be foundin \CEE/ text; thus, one typically goes back and forthbetween the \CEE/ and \TEX/ environments in a natural way, as in theseexamples:$$\displaylines{\hbox{\.{if} \.{(x==0)} \.{@<Empty} \.{the} \.{|buffer|} \.{array@>}} \cr\hbox{\.{...} \.{using}  \.{the} \.{algorithm}\.{in} \.{|@<Empty} \.{the} \.{|buffer|} \.{array@>|.}} }$$The first of these excerptswould be found in the \CEE/ part of a section, into which the codefrom the sectionnamed ``Empty the \\{buffer} array'' is being spliced. The second excerptwould be found in the \TEX/ part of the section, and the named sectionis being ``cited'', rather than defined or used.(Note the `\pb' surrounding the section name in this case.) \section Macros.The control code \.{@d} followed by$$\\{identifier}\.{ }\hbox{\CEE/ text}\qquad\hbox{or by}\qquad\\{identifier}\.(\\{par}_1,\ldots,\\{par}_n\.{) }\hbox{\CEE/ text}$$(where there is no blank between the\\{identifier} and the parentheses in the second case) istransformed by \.{CTANGLE} into a preprocessor command, starting with\.{\#define}, which is printed at the top of the \CEE/ output fileas explained earlier. A `\.{@d}' macro definition can go on for several lines, and thenewlines don't have to be protected by backslashes, since \.{CTANGLE}itself inserts the backslashes.   Iffor any reason you need a \.{\#define} command at a specific spot inyour \CEE/ file, you can treat it as \CEE/ code, instead of as a\.{CWEB} macro; but then you do have to protect newlines yourself. \section Strings and constants.If you want a string to appear in the \CEE/ file, delimited by pairs of\.' or \." marks as usual, you can type it exactly so in the \.{CWEB} file,except that the character `\.@' should be typed `\.{@@}' (it becomes acontrol code, the only one that can appear in strings; see below).Strings should end on the same line as they begin, unless there's abackslash at the end of lines within them. \TEX/ and \CEE/ have different ways to refer to octal and hex constants,because \TEX/ is oriented to technical writing while \CEE/ is oriented tocomputer processing.  In \TEX/ youmake a constant octal or hexadecimal by prepending \.' or \.",respectively, to it; in \CEE/ the constant should be preceded by \.0or \.{0x}.  In \.{CWEB} it seems reasonable to let each convention holdin its respective realm; so in \CEE/ text you get $40_8$ by typing`\.{040}', which \.{CTANGLE} faithfully copies into the \CEE/ file (forthe compiler's benefit) and which \.{CWEAVE} prints as $\T{\~40/}$.Similarly, \.{CWEAVE} prints the hexadecimal \CEE/ constant `\.{0x20}'as \T{\^20/}. The use of italic font for octal digits and typewriter fontfor hexadecimal digits makes the meaning of such constants clearer ina document. For consistency, then, you should type `\.{|040|}'  or`\.{|0x20|}' in the \TEX/ part of the section. And if you type a binary constant like `\.{0b00101010}', \.{CWEAVE} printsit as $\T{\\00101010/}$. In all numeric literals you may add \.' separatorsfor improved readability. \section Control codes.A \.{CWEB} {\sl control code\/}is a two-character combination of which the first is `\.@'.We've already seen the meaning of several control codes; it's time tolist them more methodically. In the following list,the letters in brackets after a control code indicate in what contexts thatcode is allowed.  $L$ indicates that the code is allowed in limbo; $T$(for \TEX/), $M$ (for middle), and $C$ (for \CEE/) mean that the code isallowed in each of the three parts of a section, at top level---that

Lines 1–500 of 1780. Load more