summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/cwebdir/cwebman.tex
diff options
context:
space:
mode:
authorAndreas Scherer <andreas_tex@freenet.de>2021-02-07 11:02:17 +0000
committerAndreas Scherer <andreas_tex@freenet.de>2021-02-07 11:02:17 +0000
commit3063cfbe5a32a13420a310bad225be72bcde4982 (patch)
tree01cdd5b69339785bc339eeaa5ec8e5e0dc7e29d0 /Build/source/texk/web2c/cwebdir/cwebman.tex
parent1842aa2477fe04aa641c9332262e21b78c4e50ed (diff)
CWEB – release 4.0, 2021-02-07.
In the course of the "2021 TeX tuneup", Don Knuth kindly transferred the responsibility for CWEB to me; see the original CWEB home page (https://www-cs-faculty.stanford.edu/~knuth/cweb.html), section "CWEB 4.0" and the updated CWEB development project (https://github.com/ascherer/cweb). This first new release draws heavily on the multi-decade work collected in my "CWEBbin" project (https://github.com/ascherer/cwebbin). I moved (almost) all stuff from the "*-patch.*" changefiles into the new CWEB sources and applied all of the "*-ansi.*" changes as well. Moreover, I made "common.h" the full interface of "common.w" in order to avoid code redundancy. And I tried to fix as many of the bugs reported by email to DEK and/or tex-k@tug.org. In total, "make; make cautiously; make fullmanual" runs flawlessly with GCC on Linux and with LLVM on MacOS. After the release of "CWEB 4.0", also "CWEBbin 2021" has also been fully revised. Thousands of lines of changefiles could be purged. What's left are the clearcut extensions for CWEB and the additional stuff for integration in "TeX Live 2021". git-svn-id: svn://tug.org/texlive/trunk@57658 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/cwebdir/cwebman.tex')
-rw-r--r--Build/source/texk/web2c/cwebdir/cwebman.tex204
1 files changed, 108 insertions, 96 deletions
diff --git a/Build/source/texk/web2c/cwebdir/cwebman.tex b/Build/source/texk/web2c/cwebdir/cwebman.tex
index 2e4ec65ea57..46c4a6db0fd 100644
--- a/Build/source/texk/web2c/cwebdir/cwebman.tex
+++ b/Build/source/texk/web2c/cwebdir/cwebman.tex
@@ -36,7 +36,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 3.64)}
+\def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 4.0)}
% This verbatim mode assumes that ! marks are !! in the text being copied.
\def\verbatim{\begingroup
@@ -50,7 +50,7 @@
\null\vfill
\centerline{\titlefont The {\ttitlefont CWEB} System of
Structured Documentation}
-\vskip 18pt\centerline{(Version 3.64 --- February 2002)}
+\vskip 18pt\centerline{(Version 4.0 --- February 2021)}
\vskip 24pt
\centerline{\authorfont Donald E. Knuth and Silvio Levy}
\vfill
@@ -87,6 +87,10 @@ for their own personal use.
Internet page \.{http://www-cs-faculty.stanford.edu/\char`\~knuth/cweb.html}
contains current info about \.{CWEB} and related topics.
+\smallskip\noindent
+From there you can also reach the \.{CWEB} development page
+\.{https://github.com/ascherer/cweb} with the really current news.
+
\pageno=0 \titletrue\eject
\titletrue
@@ -103,7 +107,7 @@ adapted to \CEE/ by Silvio Levy. Since its creation in 1987, \.{CWEB}
has been revised 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 sent to Levy (\.{levy@math.berkeley.edu}).
+should be sent to the \TeX-related mailing list \.{tex-k@tug.org}.
Readers who are familiar with Knuth's memo ``The \.{WEB} System of Structured
Documentation'' will be able
@@ -521,7 +525,7 @@ specifically below.
\@@ [LTMCrc] A double \.@ denotes the single character `\.@'. This is
the only control code that is legal everywhere.
Note that you must use this convention if you are giving an internet
-email address in a \.{CWEB} file (e.g., \.{levy@@math.berkeley.edu}).
+email address in a \.{CWEB} file (e.g., \.{tex-k@@tug.org}).
\subsec
Here are the codes that introduce the \TEX/ part of a section.
@@ -1151,6 +1155,8 @@ 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
+`\.{xetex}~\.{cob}'.
A more elaborate system called \.{CTWILL}, which extends the usual cross
references of \.{CWEAVE} by preparing links from the uses of identifiers
@@ -1184,17 +1190,16 @@ appendices D, E, and~F, which exhibit the complete source code for
This appendix consists
of four listings. The first shows the \.{CWEB} input that
-generated sections 12--15 of the file \.{common.w}, which contains
+generated sections 27--31 of the file \.{common.w}, which contains
routines common to \.{CWEAVE} and \.{CTANGLE}.
Note that some of the lines are indented to show the program structure;
the indentation is ignored by \.{CWEAVE} and \.{CTANGLE}, but users find
that \.{CWEB} files are quite readable if they have some such indentation.
-The second and third listings
-show corresponding parts
-of the \CEE/ code output by \.{CTANGLE} and of
-the corresponding \TEX/ code output by \.{CWEAVE}, when run on \.{common.w}.
-The fourth listing shows how that output looks when printed out.
+The second and third listings show corresponding parts of
+the \CEE/ code output by \.{CTANGLE} and of
+the \TEX/ code output by \.{CWEAVE}, when run on \.{common.w}.
+The fourth listing shows how that output looks in print.
\vskip 6pt
\begingroup \def\tt{\eighttt} \baselineskip9pt
@@ -1206,14 +1211,17 @@ 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 1; hence error messages will be reported correctly.
-@c
-void
-prime_the_change_buffer()
+@<Predecl...@>=
+static void prime_the_change_buffer(void);@/
+
+@ @c
+static void
+prime_the_change_buffer(void)
{
change_limit=change_buffer; /* this value is used if the change file ends */
- @<Skip over comment lines in the change file; |return| if end of file@>;
- @<Skip to the next nonblank line; |return| if end of file@>;
- @<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>;
+ @<Skip over comment lines in the change file; |return| if end of file@>@;
+ @<Skip to the next nonblank line; |return| if end of file@>@;
+ @<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>@;
}
@ While looking for a line that begins with \.{@@x} in the change file, we
@@ -1226,7 +1234,7 @@ while(1) {
if (!!input_ln(change_file)) return;
if (limit<buffer+2) continue;
if (buffer[0]!!='@@') continue;
- if (xisupper(buffer[1])) buffer[1]=tolower(buffer[1]);
+ if (xisupper(buffer[1])) buffer[1]=tolower((eight_bits)buffer[1]);
if (buffer[1]=='x') break;
if (buffer[1]=='y' || buffer[1]=='z' || buffer[1]=='i') {
loc=buffer+2;
@@ -1249,8 +1257,8 @@ do {
@ @<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>=
{
- change_limit=change_buffer-buffer+limit;
- strncpy(change_buffer,buffer,limit-buffer+1);
+ change_limit=change_buffer+(ptrdiff_t)(limit-buffer);
+ strncpy(change_buffer,buffer,(size_t)(limit-buffer+1));
}
!endgroup
@@ -1260,28 +1268,28 @@ do {
\def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CTANGLE}}
Here's the portion of the \CEE/ code generated by \.{CTANGLE} that corresponds
-to the source on the preceding page. Notice that sections~13, 14 and~15
-have been tangled into section~12.
+to the source on the preceding page. Notice that sections~29, 30 and~31
+have been tangled into section~28.
\vskip6pt
\begingroup \def\tt{\eighttt} \baselineskip9pt
\verbatim
-/*:9*//*12:*/
-#line 247 "common.w"
+/*:24*//*28:*/
+#line 236 "common.w"
-void
-prime_the_change_buffer()
+static void
+prime_the_change_buffer(void)
{
change_limit= change_buffer;
-/*13:*/
-#line 261 "common.w"
+/*29:*/
+#line 250 "common.w"
while(1){
change_line++;
if(!!input_ln(change_file))return;
if(limit<buffer+2)continue;
if(buffer[0]!!='@')continue;
-if(xisupper(buffer[1]))buffer[1]= tolower(buffer[1]);
+if(xisupper(buffer[1]))buffer[1]= tolower((eight_bits)buffer[1]);
if(buffer[1]=='x')break;
if(buffer[1]=='y'||buffer[1]=='z'||buffer[1]=='i'){
loc= buffer+2;
@@ -1290,11 +1298,11 @@ err_print("!! Missing @x in change file");
}
}
-/*:13*/
-#line 252 "common.w"
-;
-/*14:*/
-#line 278 "common.w"
+/*:29*/
+#line 241 "common.w"
+
+/*30:*/
+#line 267 "common.w"
do{
change_line++;
@@ -1305,23 +1313,23 @@ return;
}
}while(limit==buffer);
-/*:14*/
-#line 253 "common.w"
-;
-/*15:*/
-#line 288 "common.w"
+/*:30*/
+#line 242 "common.w"
+
+/*31:*/
+#line 277 "common.w"
{
-change_limit= change_buffer-buffer+limit;
-strncpy(change_buffer,buffer,limit-buffer+1);
+change_limit= change_buffer+(ptrdiff_t)(limit-buffer);
+strncpy(change_buffer,buffer,(size_t)(limit-buffer+1));
}
-/*:15*/
-#line 254 "common.w"
-;
+/*:31*/
+#line 243 "common.w"
+
}
-/*:12*//*16:*/
+/*:28*//*33:*/
!endgroup
\endgroup
\vfill\eject
@@ -1333,31 +1341,35 @@ Here is the corresponding excerpt from \.{common.tex}.
\vskip6pt
\begingroup \def\tt{\eighttt} \baselineskip9pt
\verbatim
-\M{12}Procedure \PB{\\{prime\_the\_change\_buffer}}
+\M{27}Procedure \PB{\\{prime\_the\_change\_buffer}}
sets \PB{\\{change\_buffer}} in preparation for the next matching operation.
Since blank lines in the change file are not used for matching, we have
\PB{$(\\{change\_limit}\E\\{change\_buffer}\W\R\\{changing})$} if and only if
the change file is exhausted. This procedure is called only when
\PB{\\{changing}} is 1; hence error messages will be reported correctly.
-!vskip-.5!baselineskip
-\Y\B\&{void} \\{prime\_the\_change\_buffer}(\,)\1\1\2\2\6
+
+\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
${}\{{}$\1\6
${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
change file ends }\6
-\X13:Skip over comment lines in the change file; \PB{\&{return}} if end of file%
-\X;\6
-\X14:Skip to the next nonblank line; \PB{\&{return}} if end of file\X;\6
-\X15:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}} and %
-\PB{\\{change\_limit}}\X;\6
+\X29:Skip over comment lines in the change file; \PB{\&{return}} if end of file%
+\X\6
+\X30:Skip to the next nonblank line; \PB{\&{return}} if end of file\X\6
+\X31:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}} and %
+\PB{\\{change\_limit}}\X\6
\4${}\}{}$\2\par
\fi
-!vskip-.5!baselineskip
-\M{13}While looking for a line that begins with \.{@x} in the change file, we
+
+\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
up).
-!vskip-.5!baselineskip
-\Y\B\4\X13:Skip over comment lines in the change file; \PB{\&{return}} if end
+
+\Y\B\4\X29:Skip over comment lines in the change file; \PB{\&{return}} if end
of file\X${}\E{}$\6
\&{while} (\T{1})\5
${}\{{}$\1\6
@@ -1369,7 +1381,7 @@ ${}\\{change\_line}\PP;{}$\6
\&{if} ${}(\\{buffer}[\T{0}]\I\.{'@'}){}$\1\5
\&{continue};\2\6
\&{if} (\\{xisupper}(\\{buffer}[\T{1}]))\1\5
-${}\\{buffer}[\T{1}]\K\\{tolower}(\\{buffer}[\T{1}]);{}$\2\6
+${}\\{buffer}[\T{1}]\K\\{tolower}{}$((\&{eight\_bits}) \\{buffer}[\T{1}]);\2\6
\&{if} ${}(\\{buffer}[\T{1}]\E\.{'x'}){}$\1\5
\&{break};\2\6
\&{if} ${}(\\{buffer}[\T{1}]\E\.{'y'}\V\\{buffer}[\T{1}]\E\.{'z'}\V\\{buffer}[%
@@ -1379,11 +1391,11 @@ ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
\\{err\_print}(\.{"!!\ Missing\ @x\ in\ cha}\)\.{nge\ file"});\6
\4${}\}{}$\2\6
\4${}\}{}$\2\par
-\U12.\fi
-!vskip-.5!baselineskip
-\M{14}Here we are looking at lines following the \.{@x}.
-!vskip-.5!baselineskip
-\Y\B\4\X14:Skip to the next nonblank line; \PB{\&{return}} if end of file\X${}%
+\U28.\fi
+
+\M{30}Here we are looking at lines following the \.{@x}.
+
+\Y\B\4\X30:Skip to the next nonblank line; \PB{\&{return}} if end of file\X${}%
\E{}$\6
\&{do}\5
${}\{{}$\1\6
@@ -1395,48 +1407,48 @@ ${}\{{}$\1\6
\4${}\}{}$\2\6
\4${}\}{}$\2\5
\&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
-\U12.\fi
-!vskip-.5!baselineskip
-\M{15}\B\X15:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}}
-and \PB{\\{change\_limit}}\X${}\E{}$\6
-${}\{{}$\1\6
-${}\\{change\_limit}\K\\{change\_buffer}-\\{buffer}+\\{limit};{}$\6
-${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39\\{limit}-\\{buffer}+%
-\T{1});{}$\6
-\4${}\}{}$\2\par
-\Us12\ET16.\fi
+\U28.\fi
!endgroup
\endgroup
+\medskip
+(Code for section 31 omitted for space reasons.)
\vfil\eject
\def\runninghead{APPENDIX A --- FINAL DOCUMENT}
And here's what the same excerpt looks like when typeset.
+(Can you spot the typographical nicety used in the \.{CWEB} code?)
+\let\K=\leftarrow
-\M{12}Procedure \PB{\\{prime\_the\_change\_buffer}}
+\M{27}Procedure \PB{\\{prime\_the\_change\_buffer}}
sets \PB{\\{change\_buffer}} in preparation for the next matching operation.
Since blank lines in the change file are not used for matching, we have
\PB{$(\\{change\_limit}\E\\{change\_buffer}\W\R\\{changing})$} if and only if
the change file is exhausted. This procedure is called only when
\PB{\\{changing}} is 1; hence error messages will be reported correctly.
-\Y\B\&{void} \\{prime\_the\_change\_buffer}(\,)\1\1\2\2\6
+\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
${}\{{}$\1\6
${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
change file ends }\6
-\X13:Skip over comment lines in the change file; \PB{\&{return}} if end of file%
-\X;\6
-\X14:Skip to the next nonblank line; \PB{\&{return}} if end of file\X;\6
-\X15:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}} and %
-\PB{\\{change\_limit}}\X;\6
+\X29:Skip over comment lines in the change file; \PB{\&{return}} if end of file%
+\X\6
+\X30:Skip to the next nonblank line; \PB{\&{return}} if end of file\X\6
+\X31:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}} and %
+\PB{\\{change\_limit}}\X\6
\4${}\}{}$\2\par
\fi
-\M{13}While looking for a line that begins with \.{@x} in the change file, we
+\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 up).
+\.{@z}, or \.{@i} (which would probably mean that the change file is fouled
+up).
-\Y\B\4\X13:Skip over comment lines in the change file; \PB{\&{return}} if end
+\Y\B\4\X29:Skip over comment lines in the change file; \PB{\&{return}} if end
of file\X${}\E{}$\6
\&{while} (\T{1})\5
${}\{{}$\1\6
@@ -1448,7 +1460,7 @@ ${}\\{change\_line}\PP;{}$\6
\&{if} ${}(\\{buffer}[\T{0}]\I\.{'@'}){}$\1\5
\&{continue};\2\6
\&{if} (\\{xisupper}(\\{buffer}[\T{1}]))\1\5
-${}\\{buffer}[\T{1}]\K\\{tolower}(\\{buffer}[\T{1}]);{}$\2\6
+${}\\{buffer}[\T{1}]\K\\{tolower}{}$((\&{eight\_bits}) \\{buffer}[\T{1}]);\2\6
\&{if} ${}(\\{buffer}[\T{1}]\E\.{'x'}){}$\1\5
\&{break};\2\6
\&{if} ${}(\\{buffer}[\T{1}]\E\.{'y'}\V\\{buffer}[\T{1}]\E\.{'z'}\V\\{buffer}[%
@@ -1458,11 +1470,11 @@ ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
\\{err\_print}(\.{"!\ Missing\ @x\ in\ cha}\)\.{nge\ file"});\6
\4${}\}{}$\2\6
\4${}\}{}$\2\par
-\U12.\fi
+\U28.\fi
-\M{14}Here we are looking at lines following the \.{@x}.
+\M{30}Here we are looking at lines following the \.{@x}.
-\Y\B\4\X14:Skip to the next nonblank line; \PB{\&{return}} if end of file\X${}%
+\Y\B\4\X30:Skip to the next nonblank line; \PB{\&{return}} if end of file\X${}%
\E{}$\6
\&{do}\5
${}\{{}$\1\6
@@ -1474,16 +1486,17 @@ ${}\{{}$\1\6
\4${}\}{}$\2\6
\4${}\}{}$\2\5
\&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
-\U12.\fi
+\U28.\fi
-\M{15}\B\X15:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}}
+\M{31}\B\X31:Move \PB{\\{buffer}} and \PB{\\{limit}} to \PB{\\{change\_buffer}}
and \PB{\\{change\_limit}}\X${}\E{}$\6
${}\{{}$\1\6
-${}\\{change\_limit}\K\\{change\_buffer}-\\{buffer}+\\{limit};{}$\6
-${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39\\{limit}-\\{buffer}+%
-\T{1});{}$\6
+${}\\{change\_limit}\K\\{change\_buffer}+(\&{ptrdiff\_t})(\\{limit}-%
+\\{buffer});{}$\6
+${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39(\&{size\_t})(\\{limit}-%
+\\{buffer}+\T{1}));{}$\6
\4${}\}{}$\2\par
-\Us12\ET16.\fi
+\Us28\ET33.\fi
\vfil\eject\titletrue
\rightskip=0pt % get out of C mode (cf. \B)
@@ -1579,7 +1592,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 3.64)\}{ }\\vfill\}}\cr}$$
+ \.{ { }\\vskip 15pt \\centerline\{(Version 4.0)\}{ }\\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.
@@ -1704,9 +1717,8 @@ with which one can say things like the following, anywhere in the \TeX\ parts
or the \CEE/ comments of a \.{CWEB} file:
$$\vbox{\halign{\.{#}\hfil\cr
You can send email to
- \\pdfURL\{the author\}\{mailto:andreas.scherer@@pobox.com\}\cr
-or visit \\pdfURL\{his home page\}\{http://www.pobox.com/%
- \\TILDE/scherer\}.\cr}}$$
+ \\pdfURL\{the author\}\{mailto:andreas\\UNDER/github@@freenet.de\}\cr
+or visit \\pdfURL\{his home page\}\{https://github.com/ascherer\}\cr}}$$
In a {\mc PDF} document, the first argument will appear in blue as
clickable text; the Acrobat reader, if correctly configured, will then
redirect those links to the user's browser and open either the