cwebman.tex

著名算法大师高爷爷设计的语言。此语言结合了Tex和C

might as well leave all depths zero.  A starred section always begins
a new page in the output, unless the depth is greater than~1.

\subsec
The middle part of each section consists of any number of
macro definitions (beginning with \.{@d}) and format definitions (beginning
with \.{@f} or \.{@s}), intermixed in any order.

\@d [TM\to M] Macro definitions begin with \.{@d}, followed by
an identifier and optional parameters and \CEE/ text as explained earlier.

\@f [TM\to M] Format definitions begin with \.{@f}; they cause
\.{CWEAVE} to treat identifiers in a special way when they appear in
\CEE/ text. The general form of a format definition is `\.{@f} \|l
\|r', followed by an optional comment enclosed between
\.{/*} and \.{*/}, where \|l and \|r
are identifiers; \.{CWEAVE} will subsequently treat identifier \|l as it
currently treats \|r. This feature allows a \.{CWEB} programmer to invent
new reserved words and/or to unreserve some of \CEE/'s reserved
identifiers. For example, the common words `error' and `line'
have been given a special meaning in the \CEE/ preprocessor,
so \.{CWEAVE} is set up to format them specially; if you want a variable
named \\{error} or \\{line}, you should say
$$\.{@f error normal}\qquad\qquad\.{@f line normal}$$
somewhere in your program.

\more If \|r is the special identifier `\\{TeX}', identifier \|l
will be formatted as a \TEX/ control sequence; for example,
`\.{@f foo TeX}' in the \.{CWEB} file will cause identifier \\{foo} to
be output as \.{\\foo} by \.{CWEAVE}. The programmer should define
\.{\\foo} to have whatever custom format is desired, assuming \TEX/
math mode. (Each underline
character is converted to \.{x} when making the \TEX/ control sequence,
and each dollar sign is converted to~\.X;
thus \\{foo\_bar} becomes \.{\\fooxbar}. Other characters, including digits,
are left untranslated, so \TEX/ will consider them as macro parameters,
not as part of the control sequence itself. For example,
$$\.{\\def\\x\#1\{x\_\{\#1\}\} @f x1 TeX @f x2 TeX}$$
will format \.{x1} and \.{x2} not as \\{x1} and \\{x2} but as $x_1$ and $x_2$.)

\more If \|r is the special identifier `\\{make\_pair}', identifier \|l will
be treated as a \CPLUSPLUS/ function template. For example, after
\.{@f}~\.{convert}~\.{make\_pair} one can say `\.{convert<int>(2.5)}' without
having \.< and \.> misunderstood as less-than and greater-than signs.

\more \.{CWEAVE} knows that identifiers being
defined with a \&{typedef} should become reserved words; thus you
don't need format definitions very often.

\@s [TM\to M;\;L] Same as \.{@f}, but \.{CWEAVE} does not show the format
definition in the output, and the optional \CEE/ comment is not
allowed. This is used mostly in \.{@i} files.

\subsec
Next come the codes that govern the \CEE/ part of a section.

\@{c @p} [TM\to C] The \CEE/ part of an unnamed section begins with \.{@c}
(or with \.{@p} for ``program''; both control codes do the same thing).
This causes \.{CTANGLE} to append the following \CEE/ code
to the first-order program text, as explained on page~\tangref.
Note that \.{CWEAVE} does not print a `\.{@c}' in the \TEX/
output, so if you are creating a \.{CWEB} file based on a \TEX/-printed
\.{CWEB} documentation you have to remember to insert \.{@c} in the
appropriate places of the unnamed sections.

\@< [TM\to C;\; C;\; c] $*$ This control code introduces a
section name (or unambiguous prefix, as discussed above), which
consists of \TEX/ text and extends to the matching \.{@>}.
The whole construct \.{@<...@>} is conceptually a \CEE/ element.
The behavior is different depending on the context:

\more A \.{@<} appearing in contexts $T$ and $M$ attaches the
following section name to the current section, and inaugurates the
\CEE/ part of the section.  The closing \.{@>} should be followed by
\.{=} or \.{+=}.

\more
In context $C$, \.{@<} indicates that the named
section is being used---its \CEE/ definition is spliced in by
\.{CTANGLE}, as explained on page~\tangref.
As an error-detection measure,
\.{CTANGLE} and \.{CWEAVE} complain if such a section name is followed
by \.=, because most likely this is meant as the definition of a new
section, and so should be preceded by \.{@\ }.  If you really want to
say $\langle\,$foo$\,\rangle=\\{bar}$, where $\langle\,$foo$\,\rangle$
is being used and not defined, put a newline before the \.=.

\more
Finally, in inner \CEE/ context (that is, within `\pb' in the \TEX/ part
of a section or in a comment), \.{@<...@>}
means that the named section is being
cited.  Such an occurrence is ignored by \.{CTANGLE}. Note that
even here we think of the section name as being a \CEE/ element, hence the \pb.

\@( [TM\to C;\;C;\;c] $*$ A section name can begin with \.{@(}.
Everything works just as for \.{@<}, except that the \CEE/ code
of the section named \.{@(foo@>} is written by \.{CTANGLE}
to file \.{foo}. In this way you can get multiple-file output from
a single \.{CWEB} file. (The \.{@d} definitions are not output
to such files, only to the master \.{.c} file.) One use of this feature
is to produce header files for other program modules that will be loaded
with the present one. Another use is to produce a test routine that
goes with your program. By keeping the sources for a program and its
header and test routine together, you are more likely to keep
all three consistent with each other. Notice that the output of a named
section can be incorporated in several different output files, because
you can mention \.{@<foo@>} in both \.{@(bar1@>} and \.{@(bar2@>}.

\@h [Cc] Causes \.{CTANGLE}
to insert at the current spot the \.{\#define} statements
from the middle parts of all sections,
and {\it not\/} to write them at the beginning of the \CEE/ file.
Useful when you want the macro definitions to come after the include files,
say. (Ignored by \.{CTANGLE} inside `\pb'.)

\subsec
The next several control codes introduce ``control
texts,'' which end with the next `\.{@>}'.  The closing `\.{@>}' must be on
the same line of the \.{CWEB} file as the line where the control text began.
The context from each of these control codes to the matching \.{@>} is
restricted.

\@\^ [TMCc] $*$ The control text that follows, up to the next
`\.{@>}', will be entered into the index together with the identifiers of
the \CEE/ program; this text will appear in roman type. For example, to
put the phrase ``system dependencies'' into the index that is output by
\.{CWEAVE}, type
`\.{@\^system dependencies@>}' in each section
that you want to index as system dependent.

\@. [TMCc] $*$ The control text that follows will be entered into the index
in \.{typewriter} \.{type}.

\@: [TMCc] $*$ The control text that follows will be entered into the index
in a format controlled by the \TEX/ macro `\.{\\9}', which you
should define as desired.

\@t [MCc] $*$ The control text that follows will
be put into a \TEX/ \.{\\hbox} and formatted along with the neighboring
\CEE/ program. This text is ignored by \.{CTANGLE}, but it can be used
for various purposes within \.{CWEAVE}. For example, you can make comments
that mix \CEE/ and classical mathematics, as in `$\\{size}<2^{15}$', by
typing `\.{|size < 2@t\$\^\{15\}\$@>|}'.

\@= [MCc] $*$ The control text that follows will
be passed verbatim to the \CEE/ program.

\@q [LTMCc] $*$ The control text that follows will
be totally ignored---it's a comment for readers of the \.{CWEB} file only.
A file intended to be included in
limbo, with \.{@i}, can identify itself with \.{@q} comments.
Another use is to balance unbalanced parentheses in C strings,
so that your text editor's parenthesis matcher doesn't go into a tailspin.

\@! [TMCc] $*$
The section number in an index entry will be underlined if `\.{@!}'
immediately precedes the identifier or control text being indexed. This
convention is used to distinguish the sections where an identifier is
defined, or where it is explained in some special way, from the sections
where it is used. A~reserved word or an identifier of length one will not
be indexed except for underlined entries. An `\.{@!}' is implicitly inserted
by \.{CWEAVE} when an identifier is being defined or declared in \CEE/
code; for example, the definition
$$\hbox{\&{int} \\{array}[\\{max\_dim}], \\{count}${}=\\{old\_count};$}$$
makes the names \\{array} and \\{count} get an underlined entry in the
index.  Statement labels, function definitions like
\\{main}(\&{int}~\\{argc},\,\&{char}~$*$\\{argv}[\,]),
and \&{typedef} definitions also
imply underlining. An old-style
function definition (without prototyping) doesn't define its arguments;
the arguments will, however, be considered to be defined
(i.e., their index entries will be underlined) if their types are
declared before the body of the function in the usual way
(e.g., `\&{int}~\\{argc}; \&{char}~${*}\\{argv}[\,]$; $\{\,\ldots\,\}$').
Thus \.{@!} is not needed very often, except in unusual constructions
or in cases like
$$\.{enum boolean \{@!false, @!true\};}$$
here \.{@!} gives the best results because individual constants enumerated
by \.{enum} are not automatically underlined in the index at their
point of definition.

\subsec
We now turn to control codes that affect only the operation of
\.{CTANGLE}.

\@' [MCc] This control code is dangerous because it has quite different
meanings in \.{CWEB} and the original \.{WEB}. In \.{CWEB} it produces the
decimal constant corresponding to the ASCII code for a string of length~1
(e.g., \.{@'a'} is \.{CTANGLE}d into \.{97} and \.{@'\\t'} into
\.9). You might want to use this if you need to work in ASCII on a
non-ASCII machine; but in most cases the \CEE/ conventions of
\.{<ctype.h>} are adequate for character-set-independent programming.

\@\& [MCc] The \.{@\&} operation causes whatever is on its left to be
adjacent to whatever is on its right, in the \CEE/ output. No spaces or
line breaks will separate these two items.

\@l [L] \.{CWEB} programmers have the option of using any 8-bit character
code from the often-forbidden range 128--255 within \TEX/ text; such
characters are also permitted in strings and even in identifiers of the
\CEE/ program.
Under various extensions of the basic
ASCII standard, the higher 8-bit codes correspond
to accented letters, letters from non-Latin alphabets,
and so on. When such characters occur in identifiers, \.{CTANGLE} must replace
them by standard ASCII alphanumeric characters or
\.{\_}, in order to generate legal \CEE/ code.  It does this by means
of a transliteration table, which by default associates the string
\.{Xab} to the character with ASCII code \T{\^}$ab$ (where $a$ and $b$ are
hexadecimal digits, and $a\ge8$).  By placing the
construction \.{@l\ ab\ newstring} in limbo, you are telling
\.{CTANGLE} to replace this character by \.{newstring} instead.
For example, the ISO Latin-1 code for the letter `\"u' is \T{\^FC}
(or \.{'\char`\\374'}),
and \.{CTANGLE} will normally change this code to the
three-character sequence \.{XFC} if it
appears in an identifier. If you say \.{@l} \.{fc} \.{ue}, the code will
be transliterated into \.{ue} instead.

\more
\.{CWEAVE} passes 8-bit characters straight through to \TEX/ without
transliteration; therefore \TEX/ must be prepared to receive them.
If you are formatting all your nonstandard identifiers as ``custom''
control sequences, you should
make \TEX/ treat all their characters as letters. Otherwise you should either
make your 8-bit codes ``active'' in \TEX/, or load fonts that
contain the special characters you need in the correct positions.
(The font selected by \TEX/ control sequence \.{\\it} is used for
identifiers.)
Look for special macro packages designed for \.{CWEB} users in your language;
or, if you are brave, write one yourself.

\subsec
The next eight control codes (namely `\.{@,}', `\.{@/}', `\.{@|}', `\.{@\#}',
`\.{@+}', `\.{@;}', `\.{@[}', and `\.{@]}') have no effect on the \CEE/
program output by \.{CTANGLE}; they merely help to improve the readability
of the \TEX/-formatted \CEE/ that is output by \.{CWEAVE}, in unusual
circumstances. \.{CWEAVE}'s built-in formatting method is fairly good
when dealing with syntactically correct \CEE/ text, but
it is incapable of handling all possible cases, because it must deal with
fragments of text involving macros and section names; these fragments do
not necessarily obey \CEE/'s syntax. Although \.{CWEB} allows you to
override the automatic formatting, your best strategy is not to worry
about such things until you have seen what \.{CWEAVE} produces automatically,
since you will probably need to make only a few corrections when you are
touching up your documentation.

\@, [MCc] This control code inserts a thin space in \.{CWEAVE}'s output.
Sometimes you need this extra space if you are using
macros in an unusual way, e.g., if two identifiers are adjacent.

\@/ [MC] This control code causes a line break to occur within a \CEE/
program formatted by \.{CWEAVE}. Line breaks
are chosen automatically by \TEX/ according to a scheme that works 99\%\
of the time, but sometimes you will prefer to force a line break so that
the program is segmented according to logical rather than visual
criteria. If a comment follows, say `\.{@/@,}' to break the line
before the comment.

\@| [MC] This control code specifies an optional line break in the midst of
an expression. For example, if you have
a long expression on the right-hand side of an assignment
statement, you can use `\.{@|}' to specify breakpoints more logical than
the ones that \TEX/ might choose on visual grounds.

\@\# [MC] This control code forces a line break, like \.{@/} does,
and it also causes a little extra white space to appear between the lines at
this break. You might use it, for example,
between groups of macro definitions that are logically separate but within
the same section. \.{CWEB} automatically inserts this extra space
between functions, between external declarations and functions, and
between declarations and statements within a function.

\@+ [MC] This control code cancels a line break that might otherwise be
inserted by \.{CWEAVE}, e.g., before the word `\&{else}', if you want to