diff options
Diffstat (limited to 'Build/source/texk/web2c/cwebdir/cwebman.tex')
-rw-r--r-- | Build/source/texk/web2c/cwebdir/cwebman.tex | 204 |
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 |