summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/cwebdir/cwebman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/web2c/cwebdir/cwebman.tex')
-rw-r--r--Build/source/texk/web2c/cwebdir/cwebman.tex102
1 files changed, 54 insertions, 48 deletions
diff --git a/Build/source/texk/web2c/cwebdir/cwebman.tex b/Build/source/texk/web2c/cwebdir/cwebman.tex
index df652232b72..26cdb93f1ca 100644
--- a/Build/source/texk/web2c/cwebdir/cwebman.tex
+++ b/Build/source/texk/web2c/cwebdir/cwebman.tex
@@ -1,5 +1,4 @@
% This file generates the user manual; TeX it, don't read it!
-% update 14 Nov 2016 by DEK: corrected obsolete remarks re debugging info
\def\tangref{3} % where the main explanation of CTANGLing is given
\input cwebmac
@@ -36,7 +35,7 @@
\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.2)}
+\def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 4.3)}
% This verbatim mode assumes that ! marks are !! in the text being copied.
\def\verbatim{\begingroup
@@ -50,7 +49,7 @@
\null\vfill
\centerline{\titlefont The {\ttitlefont CWEB} System of
Structured Documentation}
-\vskip 18pt\centerline{(Version 4.2 --- February 2021)}
+\vskip 18pt\centerline{(Version 4.3 --- April 2021)}
\vskip 24pt
\centerline{\authorfont Donald E. Knuth and Silvio Levy}
\vfill
@@ -394,9 +393,9 @@ program. Therefore the \.{CWEB} language allows you to get the effect of
\CEE/ editing within \TEX/ text, if you place `\.|' marks before and
after the \CEE/ material. For example, suppose you want to say something
like this:
-$$\hbox{ If \\{pa} is declared as `\&{int} ${}{*}\\{pa}$',
-the assignment $\\{pa}\K{\AND}\|a[\T{0}]$ makes \\{pa}
-point to the zeroth element of \|a.}$$
+$$\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}$$
@@ -477,13 +476,16 @@ respectively, to it; in \CEE/ the constant should be preceded by \.0
or \.{0x}. In \.{CWEB} it seems reasonable to let each convention hold
in its respective realm; so in \CEE/ text you get $40_8$ by typing
`\.{040}', which \.{CTANGLE} faithfully copies into the \CEE/ file (for
-the compiler's benefit) and which \.{CWEAVE} prints as $\T{\~40}$.
+the 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 font
+as \T{\^20/}. The use of italic font for octal digits and typewriter font
for hexadecimal digits makes the meaning of such constants clearer in
-a document. For consistency, then, you
-should type `\.{|040|}' or `\.{|0x20|}'
-in the \TEX/ part of the section.
+a 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} prints
+it as $\T{\\00101010/}$. In all numeric literals you may add \.' separators
+for improved readability.
\section Control codes.
A \.{CWEB} {\sl control code\/}
@@ -761,11 +763,11 @@ 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
+\.{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}
+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
@@ -1042,7 +1044,7 @@ by default.)
\option e Enclose \CEE/ material formatted by \.{CWEAVE} in
brackets \.{\\PB\{...\}}, so that special hooks can be used.
-(On by default; has no effect on \.{CTANGLE}.)
+(On 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
@@ -1051,13 +1053,18 @@ 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 k Keep single quotes (\.') in numeric literals in the
+\CEE//\CPLUSPLUS/ output. (Off by default.) (\.{CTANGLE} only.)
+
\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}.
+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 t Treat \&{typename} in a template like \&{typedef}.
+(Off by default.) (Has no effect on \.{CTANGLE}.)
\option x Include indexes and a table of contents in the \TEX/ file
output by \.{CWEAVE}. (On by default.) (Has no effect on \.{CTANGLE}.)
@@ -1155,7 +1162,7 @@ for the macros that make this work.)
Alternatively, thanks to H\`an Th\^e\kern-.3em\raise.3ex\hbox{\'{}} Th\`anh
and Andreas Scherer, you can generate \.{cob.pdf} in one step by simply
saying `\.{pdftex}~\.{cob}'.
-A third way to create PDF output from \.{CWEB} input is to say
+And a third way to create PDF output from \.{CWEB} input is to say
`\.{xetex}~\.{cob}'.
A more elaborate system called \.{CTWILL}, which extends the usual cross
@@ -1211,10 +1218,7 @@ Since blank lines in the change file are not used for matching, we have
the change file is exhausted. This procedure is called only when
|changing| is |true|; hence error messages will be reported correctly.
-@<Predecl...@>=
-static void prime_the_change_buffer(void);@/
-
-@ @c
+@c
static void
prime_the_change_buffer(void)
{
@@ -1224,6 +1228,8 @@ prime_the_change_buffer(void)
@<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>@;
}
+@ @<Predecl...@>=@+static void prime_the_change_buffer(void);
+
@ While looking for a line that begins with \.{@@x} in the change file, we
allow lines that begin with \.{@@}, as long as they don't begin with \.{@@y},
\.{@@z}, or \.{@@i} (which would probably mean that the change file is fouled up).
@@ -1268,20 +1274,20 @@ do {
Here's the portion of the \CEE/ code generated by \.{CTANGLE} that corresponds
to the source on the preceding page. Notice that sections~29, 30 and~31
-have been tangled into section~28.
+have been tangled into section~27.
\vskip6pt
\begingroup \def\tt{\eighttt} \baselineskip9pt
\verbatim
-/*:24*//*28:*/
-#line 234 "common.w"
+/*:23*//*27:*/
+#line 227 "common.w"
static void
prime_the_change_buffer(void)
{
change_limit= change_buffer;
/*29:*/
-#line 248 "common.w"
+#line 243 "common.w"
while(true){
change_line++;
@@ -1298,10 +1304,10 @@ err_print("!! Missing @x in change file");
}
/*:29*/
-#line 239 "common.w"
+#line 232 "common.w"
/*30:*/
-#line 265 "common.w"
+#line 260 "common.w"
do{
change_line++;
@@ -1313,10 +1319,10 @@ return;
}while(limit==buffer);
/*:30*/
-#line 240 "common.w"
+#line 233 "common.w"
/*31:*/
-#line 275 "common.w"
+#line 270 "common.w"
{
change_limit= change_buffer+(ptrdiff_t)(limit-buffer);
@@ -1324,11 +1330,11 @@ strncpy(change_buffer,buffer,(size_t)(limit-buffer+1));
}
/*:31*/
-#line 241 "common.w"
+#line 234 "common.w"
}
-/*:28*//*33:*/
+/*:27*//*32:*/
!endgroup
\endgroup
\vfill\eject
@@ -1349,11 +1355,7 @@ the change file is exhausted. This procedure is called only when
\PB{\\{changing}} is \PB{\\{true}}; hence error messages will be reported
correctly.
-\Y\B\4\X7:Predeclaration of procedures\X${}\mathrel+\E{}$\6
-\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void});\par
-\fi
-
-\M{28}\B\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void})\1\1\2\2\6
+\Y\B\1\1\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void})\2\2\6
${}\{{}$\1\6
${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
change file ends }\6
@@ -1365,6 +1367,10 @@ change file ends }\6
\4${}\}{}$\2\par
\fi
+\M{28}\B\X7:Predeclaration of procedures\X${}\mathrel+\E{}$\5
+\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void});\par
+\fi
+
\M{29}While looking for a line that begins with \.{@x} in the change file, we
allow lines that begin with \.{@}, as long as they don't begin with \.{@y},
\.{@z}, or \.{@i} (which would probably mean that the change file is fouled
@@ -1392,7 +1398,7 @@ ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
\\{err\_print}(\.{"!!\ Missing\ @x\ in\ cha}\)\.{nge\ file"});\6
\4${}\}{}$\2\6
\4${}\}{}$\2\par
-\U28.\fi
+\U27.\fi
\M{30}Here we are looking at lines following the \.{@x}.
@@ -1408,7 +1414,7 @@ ${}\{{}$\1\6
\4${}\}{}$\2\6
\4${}\}{}$\2\5
\&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
-\U28.\fi
+\U27.\fi
!endgroup
\endgroup
\vfil\eject
@@ -1427,11 +1433,7 @@ the change file is exhausted. This procedure is called only when
\PB{\\{changing}} is \PB{\\{true}}; hence error messages will be reported
correctly.
-\Y\B\4\X7:Predeclaration of procedures\X${}\mathrel+\E{}$\6
-\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void});\par
-\fi
-
-\M{28}\B\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void})\1\1\2\2\6
+\Y\B\1\1\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void})\2\2\6
${}\{{}$\1\6
${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
change file ends }\6
@@ -1443,6 +1445,10 @@ change file ends }\6
\4${}\}{}$\2\par
\fi
+\M{28}\B\X7:Predeclaration of procedures\X${}\mathrel+\E{}$\5
+\&{static} \&{void} \\{prime\_the\_change\_buffer}(\&{void});\par
+\fi
+
\M{29}While looking for a line that begins with \.{@x} in the change file, we
allow lines that begin with \.{@}, as long as they don't begin with \.{@y},
\.{@z}, or \.{@i} (which would probably mean that the change file is fouled
@@ -1470,7 +1476,7 @@ ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
\\{err\_print}(\.{"!\ Missing\ @x\ in\ cha}\)\.{nge\ file"});\6
\4${}\}{}$\2\6
\4${}\}{}$\2\par
-\U28.\fi
+\U27.\fi
\M{30}Here we are looking at lines following the \.{@x}.
@@ -1486,7 +1492,7 @@ ${}\{{}$\1\6
\4${}\}{}$\2\6
\4${}\}{}$\2\5
\&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
-\U28.\fi
+\U27.\fi
\M{31}\B\X31:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}}
and \PB{\\{change\_limit}}\X${}\E{}$\6
@@ -1496,7 +1502,7 @@ ${}\\{change\_limit}\K\\{change\_buffer}+(\&{ptrdiff\_t})(\\{limit}-%
${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39(\&{size\_t})(\\{limit}-%
\\{buffer}+\T{1}));{}$\6
\4${}\}{}$\2\par
-\Us28\ET33.\fi
+\Us27\ET32.\fi
\vfil\eject\titletrue
\rightskip=0pt % get out of C mode (cf. \B)
\sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50
@@ -1591,7 +1597,7 @@ $$\lpile{\.{\\def\\topofcontents\{\\null\\vfill}\cr
\.{ { }\\titlefalse \% include headline on the contents page}\cr
\.{ { }\\def\\rheader\{\\mainfont The \{\\tt CWEAVE\}{ }processor\\hfil\}}\cr
\.{ { }\\centerline\{\\titlefont The \{\\ttitlefont CWEAVE\}{ }processor\}}\cr
- \.{ { }\\vskip 15pt \\centerline\{(Version 4.2)\}{ }\\vfill\}}\cr}$$
+ \.{ { }\\vskip 15pt \\centerline\{(Version 4.3)\}{ }\\vfill\}}\cr}$$
Redefining \.{\\rheader}, which is the headline for right-hand pages,
suffices in this case to put the desired information at the top of the
contents page.