The CWEB System of Structured Documentation
(Version3.64—February2002)
Donald E.Knuth and Silvio Levy
T E X is a trademark of the American Mathematical Society.
Acrobat Reader is a trademark of Adobe Systems Incorporated.
The printed form of this manual is copyright c 1994by Addison-Wesley Publishing Company,Inc.All rights rerved.
辩证法和形而上学The electronic form is copyright c 1987,1990,1993,2000by Silvio Levy and Donald E.Knuth. Permission is granted to make and distribute verbatim copies of the electronic form of this document provided that the electronic copyright notice and this permission notice are prerved on all copies.
Permission is granted to copy and distribute modified versions of the electronic form of this document under the conditions for verbatim copying,provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Individuals may make copies of the documentation from the electronicfiles for their own personal u. Internet page www−cs−faculty.stanford.edu/~knuth/cweb.html contains current info about CWEB and related topics.
The CWEB System of Structured Documentation
Donald E.Knuth and Silvio Levy
This document describes a version of Don Knuth’s WEB system,adapted to C by Silvio Levy.Since its creation in1987,CWEB has been revid and enhanced in various ways,by both Knuth and Levy.We now believe that its evolution is near an end;however,bug reports,suggestions and comments are still welcome, and should be nt to Levy(levy@math.berkeley.edu).
Readers who are familiar with Knuth’s memo“The WEB System of Structured Documentation”will be able to skim this material rapidly,becau CWEB and WEB share the same philosophy and(esntially)the same syntax.In some respects CWEB is a simplification of WEB:for example,CWEB does not need WEB’s features for macro definition and string handling,becau C and its preprocessor already take care of macros and strings.Similarly,the WEB conventions of denoting octal and hexadecimal constants by@’77and@"3f are replaced by C’s conventions077and
0x3f.All other features of WEB have been retained,and new features have been added.
We thank all who contributed suggestions and criticism to the development of CWEB.We are especially grateful to Steve Avery,Nelson Beebe,Hans-Hermann Bode,Klaus Guntermann,Norman Ramy,Joachim Schnitter,and Saroj Mahapatra,who contributed code,and to Cameron Smith,who made many suggestions improving the manual.Ramy has made literate programming accessible to urs of yet other languages by means of his SPIDER system[e Communications of the ACM32(1989),1051–1055].The book Literate Programming by Knuth(1992)contains a comprehensive bibliography of related early work.Bode,Schnitter, and Mahapatra adapted CWEB so that it works for C++as well;therefore in the text below you can read C++ for C if you so desire.
Introduction
The philosophy behind CWEB is that programmers who want to provide the best possible documentation for their programs need two things simultaneously:a language like T E X for formatting,and a language like C for programming.Neither type of language can provide the best documentation by itlf.But when both are appropriately combined,we obtain a system that is much more uful than either language parately. The structure of a software program may be thought of
as a“web”that is made up of many interconnected pieces.To document such a program,we want to explain each individual part of the web and how it relates to its neighbors.The typographic tools provided by T E X give us an opportunity to explain the local structure of each part by making that structure visible,and the programming tools provided by C make it possible for us to specify the algorithms formally and unambiguously.By combining the two,we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software,and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation.
The CWEB system consists of two programs named CWEAVE and CTANGLE.When writing a CWEB program the ur keeps the C code and the documentation in the samefile,called the CWEBfile and generally named something.w.The command‘cweave something’creates an outputfi,which can then be fed to T E X,yielding a“pretty printed”version of something.w that correctly handles typographic details like page layout and the u of indentation,italics,boldface,and mathematical symbols.The typet output also includes extensive cross-index information that is gathered automatically.Similarly,if you run the command‘ctangle something’you will get a Cfile something.c,which can then be compiled to yield executable code.
Besides providing a documentation tool,CWEB enhances the C language by providing the ability to permute pieces of the program text,so that a large system can be understood entirely in terms of small ctions and their local interrelationships.The CTANGLE program is so named becau it takes a given web and moves the ctions from their web structure into the order required by C;the advantage of programming in CWEB is that the algorithms can be expresd in“untangled”form,with each ction explained parately.The CWEAVE program is so named becau it takes a given web and intertwines the T E X and C portions contained in each ction,then it knits the whole fabric into a structured document.(Get it?Wow.)Perhaps there is some deep connection here with the fact that the German word for“weave”is“webe”,and the corresponding Latin imperative is“texe”!
燔诗书而明法令2CWEB USER MANUAL(VERSION3.64)
A ur of CWE
足球明星有哪些
B should be fairly familiar with the
C programming language.A minimal amount of acquain-tance with T E X is also desirable,but in fact it can be acquired as one us CWEB,since straight text can be typet in T E X with virtually no knowledge of that language.To someone familiar with both C and T E X the amount of effort necessa
ry to learn the commands of CWEB is small.
Overview
俄罗斯翻译
Two kinds of material go into CWEBfiles:T E X text and C text.A programmer writing in CWEB should be thinking both of the documentation and of the C program being ,the programmer should be instinctively aware of the different actions that CWEAVE and CTANGLE will perform on the CWEBfile.T E X text is esntially copied without change by CWEAVE,and it is entirely deleted by CTANGLE;the T E X text is“pure documentation.”C text,on the other hand,is formatted by CWEAVE and it is shuffled around by CTANGLE, according to rules that will become clear later.For now the important point to keep in mind is that there are two kinds of text.Writing CWEB programs is something like writing T E X documents,but with an additional “C mode”that is added to T E X’s horizontal mode,vertical mode,and math mode.
A CWEBfile is built up from units called ctions that are more or less lf-contained.Each ction has three parts:
•A T E X part,containing explanatory material about what is going on in the ction.
新鲜无花果
•A middle part,containing macro definitions that rve as abbreviations for C constructions that would be less comprehensible if written out in full each time.They are turned by CTANGLE into preprocessor macro definitions.
坏事变好事的例子
•A C part,containing a piece of the program that CTANGLE will produce.This C code should ideally be about a dozen lines long,so that it is easily comprehensible as a unit and so that its structure is readily perceived.
The three parts of each ction must appear in this ,the T E X commentary must comefirst,then the middle part,andfinally the C code.Any of the parts may be empty.
A ction begins with either of the symbols‘@ ’or‘@*’,where‘ ’denotes a blank space.A ction ends at the beginning of the next ,at the next‘@ ’or‘@*’),or at the end of thefile,whichever comes first.The CWEBfile may also contain material that is not part of any ction at all,namely the text(if any) that occurs before thefirst ction.Such text is said to be“in limbo”;it is ignored by CTANGLE and copied esntially verbatim by CWEAVE,so its function is to provide any additional formatting instructions that may be desired in the T E X output.Indeed,it is customary to begin a CWEBfile with T E X code in limbo that loads special fonts,defines special macros,changes the page sizes,and/or produces a title page.
Sections are numbered concutively,starting with1.The numbers appear at the beginning of each c-tion of the T E X documentation output by CWEAVE,and they appear as bracketed comments at the beginning and end of the code generated by that ction in the C program output by CTANGLE.
Section Names
Fortunately,you never mention the numbers yourlf when you are writing in CWEB.You just say‘@ ’or‘@*’at the beginning of each new ction,and the numbers are supplied automatically by CWEAVE and CTANGLE.As far as you are concerned,a ction has a name instead of a number;its name is specified by writing‘@<’followed by T E X text followed by‘@>’.When CWEAVE outputs a ction name,it replaces the‘@<’and‘@>’by angle brackets and inrts the ction number in small type.Thus,when you read the output of CWEAVE it is easy to locate any ction that is referred to in another ction.
For expository purpos,a ction name should be a good description of the contents of that , it should stand for the abstraction reprented by the ction.Then the ction can be“plugged into”one or more other ctions in such a way that unimportant details of its inner workings are suppresd.A ction name therefore ought to be long enough to convey the necessary meaning.
Unfortunately,it is laborious to type such long names over and over again,and it is also difficult to specify a long name twice in exactly the same way so that CWEAVE and CTANGLE will be able to match the names to the ctions.To ameliorate this situation,CWEAVE and CTANGLE let you abbreviate a ction name,so long as the full name appears somewhere in the CWEBfile;you can type simply‘@<α...@>’,whereαis any string that is a prefix of exactly one ction name appearing in thefile.For example,‘@<Clear the arrays@>’can be abbreviated to‘@&@>’if no other ction name begins with thefive letters‘Clear’.Elwhere you might u the abbreviation‘@<@>’,and so on.
CWEB USER MANUAL(VERSION3.64)3 Section names must otherwi match character for character,except that concutive characters of white space(spaces,tab marks,newlines,and/or form feeds)are treated as equivalent to a single space,and such spaces are deleted at the beginning and end of the name.Thus,‘@<Clear the arrays@>’will also match the name in the previous example.Spaces following the ellipsis in abbreviations are ignored as well,but not tho before,so that‘@<@>’would not match‘@<Clear the arrays@>’.
What CTANGLE Does
We have said that a ction begins with‘@ ’or‘@*’,but we didn’t say how it gets divided up into a T E X part,a middle part,and a C part.The middle part begins with thefirst appearance of‘@d’or‘@f’in the ction,and the C part begins with thefirst appearance of‘@c’or‘@<ction name@>=’.In the latter ca you are saying,in effect,that the ction name stands for the C text that follows.Alternatively,if the C part begins with‘@c’instead of a ction name,the current ction is said to be unnamed.
The construct‘@<ction name@>’can appear any number of times in the C part of a ction:Subquent appearances indicate that a named ction is being“ud”rather than“defined.”In other words,the C code for the named ction,presumably defined elwhere,should be spliced in at this point in the C program. Indeed,the main idea of CTANGLE is to make a C program out of individual ctions,named and unnamed. The exact way in which this is done is this:First all the macro definitions indicated by‘@d’are turned into C preprocessor macro definitions and copied at the beginning.Then the C parts of unnamed ctions are copied down,in order;this constitutes thefirst-order approximation to the text of the program.(There should be at least one unnamed ction,otherwi there will be no program.)Then all ction names that appear in thefirst-order approximation are replaced by the C parts of the corresponding ctions,and this substitution process continues until no ction names remain.All comments are removed,becau the C program is intended only for the eyes of the C compiler.
If the same name has been given to more than one ction,the C text for that name is obtained by putting together all of the C parts in the corresponding ctions.This feature is uful,for example,in a ction named‘Global variables’,since one can then declare global variables in whatever ctions tho variables are introduced.When veral ctions have the same name,CWEAVE assigns thefirst ction number as the number corresponding to that name,and it inrts a note at the bottom of that ction telling the reader to ‘See also ctions so-and-so’;this footnote gives the numbers of all the other ctions having the same name as the prent one.The C text corresponding to a ction is usually formatted by CWEAVE so that the output has an equivalence sign in place of the equals sign in the CWEBfi,the output says‘ ction name ≡C text’.However,in the ca of the cond and subquent appearances of a ction with the same name,this ‘≡’sign is replaced by‘+≡’,as an indication that the following C text is being appended to the C text of another ction.
As CTANGLE enters and leaves ctions,it inrts preprocessor#line commands into the C outputfile. This means that when the compiler gives you error messages,or when you debug your program,the messages refer to line numbers in the CWEBfile,and not in the Cfile.In most cas you can therefore forget about the Cfile altogether.
What CWEAVE Does
The general idea of CWEAVE is to file from the CWEBfile in the following way:Thefirst line file tells T E X to input afile with macros that define CWEB’s documentation conventions.The next lines of thefile will be copied from whatever T E X text is in limbo before thefirst ction.Then comes the output for each ction in turn,possibly intersperd with end-of-page marks.Finally,CWEAVE will generate a cross-reference index that lists each ction number in which each C identifier appears,and it will also generate an alphabetized list of the ction names,as well as a table of contents that shows the page and ction numbers for each“starred”ction.
网络卡顿What is a“starred”ction,you ask?A ction that begins with‘@*’instead of‘@ ’is slightly special in that it denotes a new major group of ctions.The‘@*’should be followed by the title of this group, followed by a period.Such ctions will always start on a new page in the T E X output,and the group title will appear as a running headline on all subquent pages until the next starred ction.The title will also appear in the table of contents,and in boldface type at the beginning of its ction.Caution:Do not u T E X control quences in such titles,unless you know that the cwebmac macros will do the right thing with them.The reason is that the titles are converted to upperca when they appear as running heads,and they are converted to boldface when they appear at the beginning of their ctions,and they are also written
4CWEB USER MANUAL(VERSION3.64)
out to a table-of-contentsfile ud for temporary storage while T E X is working;whatever control quences you u must be meaningful in all three of the modes.
The T E X output produced by CWEAVE for each ction consists of the following:First comes the ction ,‘\M123.’at the beginning of ction123,except that‘\N’appears in place of‘\M’at the beginning of a starred ction).Then comes the T E X part of the ction,copied almost verbatim except as noted below.Then comes the middle part and the C part,formatted so that there will be a little extra space between them if both are nonempty.The middle and C parts are obtained by inrting a bunch of funny-looking T E X macros into the C program;the macros handle typographic details about fonts and proper math spacing,as well as line breaks and indentation.
C Code in T E X Text and Vice Versa
When you are typing T E X text,you will probably want to make frequent reference to variables and other quantities in your C code,and you will want tho variables to have the same typographic treatment when they appear in your text as when they appear in your program.Therefore the CWEB language allows you to get the effect of C editing within T E X text,if you place‘|’marks before and aft
er the C material.For example,suppo you want to say something like this:
If pa is declared as‘int∗pa’,the assignment pa=&a[0]makes pa point to the zeroth element of a. The T E X text would look like this in your CWEBfile:
进入你的世界If|pa|is declared as‘|int*pa|’,the
assignment|pa=&a[0]|makes|pa|point to the zeroth element of|a|.
And CWEAVE translates this into something you are glad you didn’t have to type:
If\\{pa}is declared as‘\&{int}${}{*}\\{pa}$’,
the assignment$\\{pa}\K{\AND}\|a[\T{0}]$
makes\\{pa}point to the zeroth element of\|a.
Incidentally,the cross-reference index that CWEAVE would make,in the prence of a comment like this,would include the current ction number as one of the index entries for pa,even though pa might not appear in the C part of this ction.Thus,the index covers references to identifiers in the ex
planatory comments as well as in the program itlf;you will soon learn to appreciate this feature.However,the identifiers int and a would not be indexed,becau CWEAVE does not make index entries for rerved words or single-letter identifiers.Such identifiers are felt to be so ubiquitous that it would be pointless to mention every place where they occur.
Although a ction begins with T E X text and ends with C text,we have noted that the dividing line isn’t sharp,since C text can be included in T E X text if it is enclod in‘|...|’.Converly,T E X text appears frequently within C text,becau everything in ,between/*and*/,or following//)is treated as T E X text.Likewi,the text of a ction name consists of T E X text,but the construct@<ction name@> as a whole is expected to be found in C text;thus,one typically goes back and forth between the C and T E X environments in a natural way,as in the examples:
if(x==0)@<Empty the|buffer|array@>
...using the algorithm in|@<Empty the|buffer|array@>|.
Thefirst of the excerpts would be found in the C part of a ction,into which the code from the ction named“Empty the buffer array”is being spliced.The cond excerpt would be found in the T E X part of the ction,and the named ction is being“cited”,rather than defined or ud.(Note the‘|...|’
surrounding the ction name in this ca.)
Macros
The control code@d followed by
identifier C text or by identifier(par1,...,par n)C text
(where there is no blank between the identifier and the parenthes in the cond ca)is transformed by CTANGLE into a preprocessor command,starting with#define,which is printed at the top of the C output file as explained earlier.
