path: root/Build/source/texk/web2c/cwebdir/cwebman-w2c.ch

@q Changes for CWEB in TeX Live from numerous contributors.              @>
@q This file is in the Public Domain.                                    @>

@q Most of the original Kpathsea changes by Wlodek Bzyl and Olaf Weber   @>
@q were merged with the set of change files of the CWEBbin project;      @>
@q see https://github.com/ascherer/cwebbin for the original parts.       @>

@q This stripped change file {comm,ctang,cweav,ctwill,cwebman}-w2c.ch    @>
@q has been created from the elaborate set of change files               @>
@q {comm,ctang,cweav,cwebman}-patch.ch,                                  @>
@q {comm,cweav,cwebman}-extensions.ch, {comm,ctang,cweav}-output.ch,     @>
@q {comm,ctang,cweav}-i18n.ch, and cweav-twill.ch for CTWILL, and        @>
@q {comm,ctang,cweav,ctwill,cwebman}-texlive.ch with the 'tie' processor @>
@q and is used as a monolithic changefile for {common,ctangle,cweave}.w  @>
@q and cwebman.tex in TeX Live.                                          @>

@q Please send comments, suggestions, etc. to tex-k@@tug.org.            @>

@x l.4
\input cwebmac
\pdffalse\acrohintfalse
@y
\input cwebmac
\ifhint \input hiplainpage \fi
@z

@x l.6
\def\page{\box255 } \normalbottom
@y
\let\page=\pagebody \raggedbottom
\newcount\footnotecount \footnotecount 1\relax
\def\cwebfootnote#1{\footnote{${}^{\the\footnotecount}$}{#1}%
  \advance\footnotecount by 1\relax}
@z

@x l.32
\outer\def\section #1.{\penalty-500\bigskip
        \centerline{\sectionfont\def\.##1{{\twelvett##1}} #1}\nobreak\vskip 6pt
        \everypar{\hskip-\parindent\everypar{}}}
@y
\ifacro
  \pdfpagewidth=\pagewidth \advance\pdfpagewidth by 2cm
  \pdfpageheight=\pageheight \advance\pdfpageheight by 3cm
  \ifpdflua \pdfhorigin=1cm \pdfvorigin=1cm
  \else \advance\pdfpageheight by 1cm \global\pageshift=-1.54cm
    \global\hoffset=-1.54cm \global\voffset=-1.54cm \fi
\fi

\newcount\destcount \destcount=1\relax

\def\subsections{0}
\outer\def\section #1.{\penalty-500\bigskip
        \centerline{\sectionfont\def\.##1{{\twelvett##1}}
  \ifacro\vbox to 0pt{\kern-2.5ex\relax
    \ifpdflua\pdfdest num \destcount fith\relax
    \else\special{pdf: dest (\the\destcount) [ @thispage /FitH @ypos ]}\fi
    \def\.##1{##1}\def\TeX{TeX}%
    \ifpdflua\pdfoutline goto num \destcount
      \ifnum\subsections>0 count -\subsections\fi {#1}\relax
    \else\special{pdf: outline 0 << /Title (#1)
      /A << /S /GoTo /D (\the\destcount) >> >>}\fi
    \gdef\subsections{0}%
    \global\advance\destcount by 1\relax
    \kern2.5ex\relax
  }\fi #1}\nobreak\vskip 6pt
        \everypar{\hskip-\parindent\everypar{}}}

\def\appA{15}
\def\appB{16}
\def\appC{17}

\def\Appendix#1{\leavevmode
  \ifacro\ifpdflua
    \pdfstartlink attr{/Border[0 0 0]} goto num\csname app#1\endcsname\relax
    \Blue\hbox{Appendix}~#1\Black
    \pdfendlink
  \else
    \setbox0=\hbox{\special{pdf: bc [ \pdflinkcolor ]}{\hbox{Appendix}~#1}%
    \special{pdf: ec}}\special{pdf: ann width \thewidth height \theheight
      depth \thedepth << /Type /Annot /Subtype /Link /Border [0 0 0]
      /A << /S /GoTo /D (\csname app#1\endcsname) >> >>}\box0\relax
  \fi\else Appendix~#1\fi}

\newcount\subdestcount \subdestcount=151\relax

\outer\def\subsection #1.{\ifacro
    \ifpdflua\pdfdest num \subdestcount fith\relax
      \pdfoutline goto num \subdestcount {#1}\relax
    \else\special{pdf: dest (\the\subdestcount) [ @thispage /FitH @ypos ]}%
      \special{pdf: outline 1 << /Title (#1)
        /A << /S /GoTo /D (\the\subdestcount) >> >>}\fi
    \global\advance\subdestcount by 1\relax
  \fi}
@z

@x l.38
\def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 4.11)}
@y
\def\Kpathsea/{{\mc KPATHSEA\spacefactor1000}}
\def\runninghead{{\tentt CWEB} USER MANUAL (Version 4.11 [\TeX~Live])}
@z

@x l.52
\vskip 18pt\centerline{(Version 4.11 --- December 2023)}
@y
\vskip 18pt\centerline{(Version 4.11 --- December 2023)%
\footnote*{This document describes the extended \.{CWEB} (Version 4.11 [\TeX~Live]).}}
@z

@x l.83
Internet page \.{http://www-cs-faculty.stanford.edu/\char`\~knuth/cweb.html}
@y
Internet page
\pdfURL{\.{http://www-cs-faculty.stanford.edu/\char`\~knuth/cweb.html}}%
          {http://www-cs-faculty.stanford.edu/\TILDE/knuth/cweb.html}
@z

@x l.88
\.{https://github.com/ascherer/cweb} with the really current news.
@y
\pdfURL{\.{https://github.com/ascherer/cweb}}%
          {https://github.com/ascherer/cweb}
with the really current news.
@z

@x l.106
should be sent to the \TeX-related mailing list \.{tex-k@tug.org}.
@y
should be sent to the \TeX-related mailing list
\pdfURL{\.{tex-k@tug.org}}%
   {mailto:tex-k@tug.org}.
@z

@x l.108
Readers who are familiar with Knuth's memo ``The \.{WEB} System of Structured
Documentation'' will be able
@y
Readers who are familiar with Knuth's memo ``\pdfURL{The \.{WEB} System of
Structured Documentation}{../web/webman.pdf}'' will be able
@z

@x l.527
email address in a \.{CWEB} file (e.g., \.{tex-k@@tug.org}).
@y
email address in a \.{CWEB} file (e.g.,
\pdfURL{\.{tex-k@@tug.org}}%
   {mailto:tex-k@tug.org}).
@z

@x l.922
it cannot find them in the current directory.
@y
it cannot find them in the current directory.%
\cwebfootnote{In this extended implementation, if an \.{@i}nclude file can not
be found in the current directory, \.{CWEB} will use the conventions of the
\Kpathsea/ library as outlined in {\pdffalse\acrohintfalse section~\X93:File
lookup with \Kpathsea/\X~of} \pdfURL{appendix~D}{common-changes.pdf} to look
for it.
% FIXME
(This is true for any other input or change file lookup.)}
@z

@x l.1029
except for error messages.
@y
except for error messages.%
\cwebfootnote{\.{CWEB} in \TeX~Live runs `\.{--quiet}ly', i.\,e.,
options `\.{b}', `\.{h}', and `\.{p}' are `off' by default.}
@z

@x l.1035
options are currently implemented:

\yskip
\def\option#1 {\textindent{\.#1}\hangindent2\parindent}
@y
\def\option#1 {\textindent{\.#1}\hangindent2\parindent}%
options are currently implemented:%
\cwebfootnote{This extended version of \.{CWEB} adds the following options
to the list:
\hfil\smallskip
\option c Check temporary output files for changes.  (Off by default.)
\hfil\vskip\normallineskip
\option d Set the debugging variable \\{kpathsea\_debug} to the numeric
value $N\in[0,127]$ of this option.  See section~95 % FIXME
of \pdfURL{appendix~D}{common-changes.pdf} for details.
\hfil\vskip\normallineskip
\option i Indent parameters in function declarations.  (On by default;
\.{-i} typesets declarations flush left; some people think this to be
more logical than indenting them.) (Has no effect on \.{CTANGLE}.)
\hfil\vskip\normallineskip
\option l This option takes the string of characters to its right as its
argument to switch between different user languages and macro packages.
(Off by default.) (Has no effect on \.{CTANGLE}.)
\hfil\vskip\normallineskip
\option o Separate declarations and the first statement in a function block.
(On by default.) (\.{CWEAVE} only.)
\hfil\vskip\normallineskip
\option u Transliteration of UTF-8 multi-byte characters.
(Off by default.) (Has no effect on \.{CWEAVE}.)}

\yskip
@z

@x l.1071
\option x Include indexes and a table of contents in the \TEX/ file
output by \.{CWEAVE}. (On by default.) (Has no effect on \.{CTANGLE}.)
@y
\option x Include indexes and a table of contents in the \TEX/ file
output by \.{CWEAVE}. (On by default.) (\.{CWEAVE} only.)
@z

@x l.1127
Sometimes things don't work as smoothly, and you get a bunch of
@y
\pdffalse\acrohintfalse
Sometimes things don't work as smoothly, and you get a bunch of
@z

@x l.1135
`$\\{main}(\\{argc},\39\\{argv}{}$)'.
@y
`$\\{main}(\\{argc},\39\\{argv}{}$)'.
\ifx\pdf+\pdftrue\fi \ifxetex\pdftrue\fi
\ifpdflua\ifnum\pdfoutput>0\pdftrue\fi\fi
\ifpdf\acrohinttrue\fi \ifhint\acrohinttrue\fi
@z

@x l.1145
the `\.{@\#}' will put extra space after `$\langle\,$Other locals$\,\rangle$'.
@y
the `\.{@\#}' will put extra space after `$\langle\,$Other locals$\,\rangle$'.%
\cwebfootnote{This extended version of \.{CWEB} acknowledges the \.{-o} option
to suppress the extra space globally.}
@z

@x l.1147
\section Hypertext and hyperdocumentation.
@y
\vfill\eject
\section Hypertext and hyperdocumentation.
@z

@x l.1171
from \.{https://hint.userweb.mwn.de/hint/hintview.html}.
@y
from
\pdfURL{\.{https://hint.userweb.mwn.de/hint/hintview.html}}%
          {https://hint.userweb.mwn.de/hint/hintview.html}.%
@z

@x l.1180
the program sources at \.{ftp://ftp.cs.stanford.edu/pub/ctwill}.
@y
the program sources at
\pdfURL{\.{http://ftp.cs.stanford.edu/pub/ctwill}}%
          {http://ftp.cs.stanford.edu/pub/ctwill}.%
\cwebfootnote{\TeX~Live comes with an up-to-date
\.{ctwill} executable -- and its associated helpers -- out of the box.}
@z

@x l.1184
As an example of a real program written in \.{CWEB}, Appendix~A
@y
As an example of a real program written in \.{CWEB}, \Appendix A
@z

@x l.1189
Appendix B displays the files that set \TEX/ up to accept
the output of \.{CWEAVE}, and Appendix~C discusses how to use some of those
@y
\Appendix B displays the files that set \TEX/ up to accept
the output of \.{CWEAVE}, and \Appendix C discusses how to use some of those
@z

@x l.1195
appendices D, E, and~F, which exhibit the complete source code for
\.{CTANGLE} and \.{CWEAVE}.

\vfil\eject\titletrue
@y
appendices \pdfURL{D}{common.pdf}, \pdfURL{E}{ctangle.pdf},
and~\pdfURL{F}{cweave.pdf}, which exhibit the complete source code for
\.{CTANGLE} and \.{CWEAVE}.%
\cwebfootnote{Actually, \pdfURL{Appendix~D}{common.pdf} contains the source
code for \.{COMMON}, and the additional \pdfURL{Appendix~G}{ctwill.pdf}
exhibits the source code for \.{CTWILL}, which is based on \.{CWEAVE}.}

\eject\titletrue
@z

@x l.1201
\section Appendix A: Excerpts from a \.{CWEB} Program.
@y
\def\subsections{4}
\section Appendix A: Excerpts from a \.{CWEB} Program.
\subsection CWEB file format.
@z

@x l.1205
generated sections 27--31 of the file \.{common.w}, which contains
@y
generated sections 27--31 of the file
\pdfURL{\.{common.w}}{common.pdf}, which contains
@z

@x l.1276
\def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CTANGLE}}
@y
\def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CTANGLE}}
\subsection Translation by CTANGLE.
@z

@x l.1344
\def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CWEAVE}}
@y
\def\runninghead{APPENDIX A --- TRANSLATION BY {\tentt CWEAVE}}
\subsection Translation by CWEAVE.
@z

@x l.1433
\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
@y
\def\runninghead{APPENDIX A --- FINAL DOCUMENT}
\subsection Final document.

\pdffalse\acrohintfalse
And here's what the same excerpt looks like when typeset.
(Can you spot the typographical niceties used in the \.{CWEB} code?)
\let\K=\leftarrow
\def\C#1{\5\5\quad$\triangleright\,${\cmntfont#1}$\,\triangleleft$}
@z

@x l.1515
\vfil\eject\titletrue
@y
\vfil\eject\titletrue
\ifx\pdf+\pdftrue\fi \ifxetex\pdftrue\fi
\ifpdflua\ifnum\pdfoutput>0 \pdftrue\fi\fi
\ifacro\acrohinttrue\fi \ifhint\acrohinttrue\fi
@z

@x l.1617
  \.{ { }\\vskip 15pt \\centerline\{(Version 4.11)\}{ }\\vfill\}}\cr}$$
@y
  \.{ { }\\vskip 15pt \\centerline\{(Version 4.11)\}{ }\\vfill\}}\cr}$$
@z

@x l.1732
if you have a duplex printer. Appendices D, E, and F of the complete
version of this manual are printed using a commented-out option that
substitutes `$\gets$' for `$=$' in the program listings. Looking at those
@y
if you have a duplex printer. Appendices \pdfURL{D}{common.pdf},
\pdfURL{E}{ctangle.pdf}, and \pdfURL{F}{cweave.pdf}\cwebfootnote{And
\pdfURL{Appendix~G}{ctwill.pdf}.} of the complete
version of this manual are printed using a commented-out option that
substitutes `$\gets$' for `$=$' in the program listings.\cwebfootnote{They
also make use of the alternative format for \CEE/ comments.}
Looking at those
@z

@x l.1784
\point 20. Furthermore, group titles can be converted to an arbitrary
@y
\vfill\eject
\point 20. Furthermore, group titles can be converted to an arbitrary
@z

@x l.1796
\vfill\end
@y
\point 21. With modern \TeX\ engines like `\.{luatex}', `\.{pdftex}', and
`\.{xetex}' (but \\{not} with classic `\.{tex}') you can say `\.{\\input
pdfwebtocfront}' as the last command in the limbo section and run \TeX\
\\{twice} on your woven \.{CWEB} document, in order to shift the
table-of-contents to the front of the {\mc PDF} output.

\vfill\end
@z