summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/cwebdir/cwebman.tex
diff options
context:
space:
mode:
authorAndreas Scherer <andreas_tex@freenet.de>2021-05-03 13:03:46 +0000
committerAndreas Scherer <andreas_tex@freenet.de>2021-05-03 13:03:46 +0000
commit60712e2174bfaa66828692206c37af9b20d9fc9a (patch)
tree3e9284ecd37b56a42a67118bb5aa94482e07112b /Build/source/texk/web2c/cwebdir/cwebman.tex
parentd3de05fb9dda5d710a51f3ad2097d67d8452a166 (diff)
[CWEB] New release 4.3.1.
This release is almost the same as CWEB 4.3 of 2021-04-16, but * it fixes the indexing bug in CWEAVE/CTWILL that got retracted * it extracts and collects all additions made in CTWILL, so that the section numbers of CWEAVE are retained up to ยง272 and new material is described in the (first) appendix, including the CTWILL user manual * it provides fully revised and (hopefully) corrected mini-indexes for CTWILL, if it is processed by itself (to be published in package 'knuth-pdf' on CTAN) git-svn-id: svn://tug.org/texlive/trunk@59061 c570f23f-e606-0410-a88d-b1316a301751
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..4d4206ee64d 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 --- May 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.