From 3063cfbe5a32a13420a310bad225be72bcde4982 Mon Sep 17 00:00:00 2001
From: Andreas Scherer <andreas_tex@freenet.de>
Date: Sun, 7 Feb 2021 11:02:17 +0000
Subject: CWEB – release 4.0, 2021-02-07.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 Build/source/texk/web2c/cwebdir/cwebman.tex | 204 +++++++++++++++-------------
 1 file changed, 108 insertions(+), 96 deletions(-)

(limited to 'Build/source/texk/web2c/cwebdir/cwebman.tex')

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
-- 
cgit v1.2.3

