cwebman.tex

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

put a short if--else construction on a single line.
If you say `\.{\{@+}' at the beginning of a compound statement
that is the body of a function, the first declaration or
statement of the function will appear on the same line as the
left brace, and it will be indented by the same amount as the
second declaration or statement on the next line.

\@; [MC] This control code is treated like a semicolon, for formatting
purposes, except that it is invisible. You can use it, for example, after
a section name or macro when the \CEE/ text represented by that section or macro
is a compound statement or ends
with a semicolon. Consider constructions like
$$\lpile{\.{if (condition) macro @;}\cr
\.{else break;}\cr}$$
where \\{macro} is defined to be a compound statement (enclosed in braces).
This is a well-known infelicity of \CEE/ syntax.

\@{[} [MC] See \.{@]}.

\@] [MC] Place \.{@[...@]} brackets around program text that \.{CWEAVE} is
supposed to format as an expression, if it doesn't already do so. (This
occasionally applies to unusual macro arguments.) Also
insert `\.{@[@]}' between a simple type name and a left parenthesis
when declaring a pointer to a function, as in
$$\.{int @[@] (*f)();}$$
otherwise \.{CWEAVE} will confuse the first part of that declaration with
the \CPLUSPLUS/ expression `\&{int}($*f$)'. Another example, for people
who want to use low-level \.{\#define} commands in the midst of \CEE/ code
and the definition begins with a cast:
$$\.{\#define foo @[(int)(bar)@]}$$

\subsec
The remaining control codes govern the input that \.{CWEB} sees.

\@{x @y @z}[\\{change\_file}]
\.{CWEAVE} and \.{CTANGLE} are designed to work with two input files,
called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains
data that overrides selected portions of \\{web\_file}. The resulting merged
text is actually what has been called the \.{CWEB} file elsewhere in this
report.

\more Here's how it works: The change file consists of zero or more ``changes,''
where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$%
new lines$\rangle$\.{@z}'. The special control codes \.{@x}, \.{@y}, \.{@z},
which are allowed only in change files, must appear at the beginning of a line;
the remainder of such a line is ignored.
The $\langle$old lines$\rangle$ represent material that exactly matches
consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$
represent zero or more lines that are supposed to replace the old. Whenever
the first ``old line'' of a change is found to match a line in the
\\{web\_file}, all the other lines in that change must match too.

\more Between changes, before the first change, and after the last change,
the change file can have any number of lines that do not begin with
`\.{@x}', `\.{@y}', or~`\.{@z}'. Such lines are bypassed and not used for
matching purposes.

\more This dual-input feature is useful when working with a master \.{CWEB}
file that has been received from elsewhere (e.g., \.{tangle.w} or
\.{weave.w} or \.{tex.web}), when changes are desirable to customize the
program for your local computer system. You will be able to debug your
system-dependent changes without clobbering the master web file; and once
your changes are working, you will be able to incorporate them readily
into new releases of the master web file that you might receive from time
to time.

\@i [\\{web\_file}]
Furthermore the \\{web\_file} itself can be a combination of
several files.  When either \.{CWEAVE} or \.{CTANGLE} is reading a file and
encounters the control code \.{@i} at the beginning of a line, it
interrupts normal reading and starts looking at the file named after the
\.{@i}, much as the \CEE/ preprocessor does when it encounters an \.{\#include}
line.  After the included file has been entirely read, the program
goes back to the next line
of the original file.  The file name following \.{@i} can be
surrounded by \." characters, but such delimiters are
optional. Include files can nest.

\more
Change files can have lines starting with \.{@i}. In this way
you can replace one included file with another. Conceptually, the
replacement mechanism described above does its work first, and
its output is then checked for \.{@i} lines. If \.{@i} \.{foo}
occurs between \.{@y} and \.{@z} in a change file, individual lines
of file \.{foo} and files it includes are not changeable; but changes
can be made to lines from files that were included by unchanged input.

\more On UNIX systems (and others that support environment variables),
if the environment variable \.{CWEBINPUTS} is set, or if the compiler flag
of the same name was defined at compile time,
\.{CWEB} will look for include files in the directory thus named, if
it cannot find them in the current directory.

\section Additional features and caveats.

1. In certain installations of \.{CWEB} that
{\def\\#1#2{`{\tentex\char'#1#2}'}%
have an extended character set, the characters
\\13, \\01, \\31, \\32, \\34, \\35,
\\36, \\37, \\04, \\20, and \\21}
can be typed as abbreviations for `\.{++}', `\.{--}', `\.{->}',
`\.{!=}', `\.{<=}', `\.{>=}', `\.{==}', `\.{\v\v}', `\.{\&\&}',
`\.{<<}', and `\.{>>}',
respectively.

2. If you have an extended character set, you can use it with only minimal
restrictions, as discussed under the rules for \.{@l} above. But you should
stick to standard ASCII characters if you want to write programs that will
be useful to all the poor souls out there who don't have extended
character sets.

3. The \TEX/ file output by \.{CWEAVE} is broken into lines having at most
80 characters each. When
\TEX/ text is being copied, the existing line breaks are copied as well.
If you aren't doing anything too tricky, \.{CWEAVE} will recognize when
a \TEX/ comment is being split across two or more lines, and it will
append `\.\%' to the beginning of such continued comments.

4. \CEE/ text is translated by a ``bottom up'' procedure that
identifies each token as a ``part of speech'' and combines parts of speech
into larger and larger phrases as much as possible according to a special
grammar that is explained in the documentation of \.{CWEAVE}. It is easy to
learn the translation scheme for simple constructions like single
identifiers and short expressions, just by looking at a few examples of
what \.{CWEAVE} does, but the general mechanism is somewhat complex because
it must handle much more than \CEE/ itself. Furthermore the output
contains embedded codes that cause \TEX/ to indent and break lines as
necessary, depending on the fonts used and the desired page width. For
best results it is wise to avoid enclosing long \CEE/ texts in \pb, since the
indentation and line breaking codes are omitted when the \pb\ text is
translated from \CEE/ to \TEX/. Stick to simple expressions or
statements.  If a \CEE/ preprocessor command is enclosed in \pb,
the \.\# that introduces it must be at the beginning of a line,
or \.{CWEAVE} won't print it correctly.

5. Comments are not permitted in \pb\ text. After a `\.|'
signals the change from \TEX/ text to \CEE/ text, the next `\.|' that is
not part of a string or control text or section name ends the \CEE/ text.

6. A comment must have properly nested occurrences of left and right
braces, otherwise \.{CWEAVE} will complain. But it
does try to balance the braces, so that \TEX/ won't foul up too much.

7. When you're debugging a program and decide to omit some of your
\CEE/ code, do NOT simply ``comment it out.'' Such comments are not
in the spirit of \.{CWEB} documentation; they will appear to readers
as if they were explanations of the uncommented-out instructions.
Furthermore, comments of a program must be valid \TEX/ text; hence
\.{CWEAVE} will get confused if you enclose \CEE/ statements in
\.{/*...*/} instead of in \.{/*|...|*/}.  If you must comment out
\CEE/ code, you can surround it with preprocessor commands
like \.{\#if 0==1} and \.{\#endif}.

8. The \.{@f} feature allows you to define one identifier to act like
another, and these format definitions are carried out sequentially.
In general, a given identifier has only one printed format
throughout the entire document, and this format is used even before
the \.{@f} that defines it. The reason is that \.{CWEAVE} operates in two
passes; it processes \.{@f}'s and cross-references on the first pass and
it does the output on the second.  (However, identifiers that
implicitly get a boldface format, thanks to a \.{typedef} declaration,
don't obey this rule; they are printed differently before and after
the relevant \.{typedef}.  This is unfortunate, but hard to fix. You can
get around the restriction by saying, say, `\.{@s} \.{foo} \.{int}',
before or after the \.{typedef}.)

9. Sometimes it is desirable to insert spacing into formatted \CEE/ code that
is more general than the thin space provided by `\.{@,}'. The \.{@t} feature
can be used for this purpose; e.g., `\.{@t\\hskip 1in@>}' will
leave one inch of blank space. Furthermore, `\.{@t\\4@>}' can be
used to backspace by one unit of indentation, since the control sequence
\.{\\4} is defined in \.{cwebmac} to be such a backspace. (This
control sequence is used, for example, at the beginning of lines that
contain labeled statements, so that the label will stick out a little at
the left.) You can also use `\.{@t\}\\3\{-5@>}' to force a break
in the middle of an expression.

10. Each identifier in \.{CWEB} has a single formatting convention. Therefore
you shouldn't use the same identifier to denote, say, both a type name and
part of a \.{struct}, even though \CEE/ does allow this.

\section Running the programs.
The \UNIX/ command line for \.{CTANGLE} is
$$\.{ctangle [options] web\_file[.w] [\{change\_file[.ch]|-\} [out\_file]]}$$
and the same conventions apply to \.{CWEAVE}. If `\.-' or no change file is
specified, the change file is null. The extensions \.{.w} and \.{.ch}
are appended only if the given file names contain no dot. If the
web file defined in this way cannot be found, the extension \.{.web}
will be tried. For example, `\.{cweave} \.{cob}' will try to read
\.{cob.w}; failing that, it will try \.{cob.web} before giving up.
If no output file name is specified, the name of the \CEE/ file output by
\.{CTANGLE} is obtained by appending the extension \.{.c};
the name of the \TEX/ file output by \.{CWEAVE} gets the extension \.{.tex}.
Index files output by \.{CWEAVE} replace \.{.tex} by \.{.idx} and \.{.scn}.

Programmers who like terseness might choose to set up their
 operating shell so that `\.{wv}' expands to
`\.{cweave -bhp}'; this will suppress most terminal output from \.{CWEAVE}
except for error messages.

Options are introduced either by a \.- sign, to turn an option off,
or by a \.+ sign to turn one on. For example, `\.{-fb}' turns off
options \.f and \.b; `\.{+s}' turns on option \.s. Options can be
specified before the file names, after the file names, or both. The following
options are currently implemented:

\yskip
\def\option#1 {\textindent{\.#1}\hangindent2\parindent}

\option b Print a banner line at the beginning of execution. (On
by default.)

\option e Enclose \CEE/ material formatted by \.{CWEAVE} in
brackets \.{\\PB\{...\}}, so that special hooks can be used.
(Off by default; has no effect on \.{CTANGLE}.)

\option f Force line breaks after each \CEE/ statement formatted
by \.{CWEAVE}. (On by default; \.{-f} saves paper but looks less \CEE/-like
to some people.) (Has no effect on \.{CTANGLE}.)

\option h Print a happy message at the conclusion of a successful
run. (On by default.)

\option p Give progress reports as the program runs. (On by default.)

\option s Show statistics about memory usage after the program
runs to completion. (Off by default.)
If you
have large \.{CWEB} files or sections, you may need to see
how close you come to exceeding the capacity of \.{CTANGLE} and/or \.{CWEAVE}.

\option x Include indexes and a table of contents in the \TEX/ file
output by \.{CWEAVE}. (On by default.) (Has no effect on \.{CTANGLE}.)

\section Further details about formatting.
You may not like the way \.{CWEAVE} handles certain
situations. If you're desperate, you can customize \.{CWEAVE}
by changing its grammar.  This means changing the source code,
a task that you might find amusing. A table of grammar rules
appears in the \.{CWEAVE} source listing, and you can make a separate
copy of that table by copying the file \.{prod.w} found in the \.{CWEB}
sources and saying `\.{cweave}~\.{-x}~\.{prod}', followed by
`\.{tex}~\.{prod}'.

You can see exactly
how \.{CWEAVE} is parsing your \CEE/ code by preceding
it with the line `\.{@ @c @2}'. (The control code `\.{@2}'
turns on a ``peeping'' mode, and `\.{@0}' turns it off.)
For example, if you run \.{CWEAVE} on the file
\medskip
\begingroup
\verbatim
@ @c @2
main (argc,argv)
char **argv;
{ for (;argc>0;argc--) printf("%s\n",argv[argc-1]); }
!endgroup
\endgroup
\medskip\noindent
you get the following gibberish on your screen:
\medskip
\begingroup
\verbatim
[...]
4:*exp ( +exp+ )...
11:*exp +exp+ int...
5:*+exp+ int +unorbinop+...
[...]
60: +fn_decl+*+{+ -stmt- +}-
55:*+fn_decl+ -stmt-
52:*+function-
[...]
!endgroup
\endgroup
\medskip