| 1 |
.\" Automatically generated by Pandoc |
| 2 |
.\" |
| 3 |
.TH "CTWILL" "1" "February 3, 2026." "Web2c 2026" "General Commands Manual" |
| 4 |
.SH NAME |
| 5 |
ctwill, ctwill-proofsort, ctwill-refsort, ctwill-twinx \- translate CWEB to TeX with |
| 6 |
mini-indexes |
| 7 |
.SH SYNOPSIS |
| 8 |
\f[B]ctwill\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w] |
| 9 |
[{\f[I]changefile\f[R][.ch]|\-} [\f[I]outfile\f[R][.tex]]] |
| 10 |
.PD 0 |
| 11 |
.P |
| 12 |
.PD |
| 13 |
( \f[B]ctwill-proofsort\f[R] < \f[I]texfile\f[R].tex ) 1<> |
| 14 |
\f[I]texfile\f[R].tex |
| 15 |
.PD 0 |
| 16 |
.P |
| 17 |
.PD |
| 18 |
\f[B]ctwill-refsort\f[R] < \f[I]indexfile\f[R].ref > \f[I]indexfile\f[R].sref |
| 19 |
.PD 0 |
| 20 |
.P |
| 21 |
.PD |
| 22 |
\f[B]ctwill-twinx\f[R] \f[I]outfile\f[R].tex [\f[I]outfile\f[R].tex \&...] |
| 23 |
> index.tex |
| 24 |
.SH DESCRIPTION |
| 25 |
The \f[B]ctwill\f[R] program converts a CWEB source document into a |
| 26 |
TeX\ file that may be formatted and printed in the usual way. |
| 27 |
It takes appropriate care of typographic details like page layout and |
| 28 |
the use of indentation, \f[I]italics\f[R], \f[B]boldface\f[R], etc., and |
| 29 |
it supplies extensive cross-index information that it gathers |
| 30 |
automatically. |
| 31 |
.PP |
| 32 |
CWEB allows you to prepare a single document containing all the |
| 33 |
information that is needed both to produce a compilable C/C++\ program |
| 34 |
and to produce a well-formatted document describing the program in as |
| 35 |
much detail as the writer may desire. |
| 36 |
The user of CWEB ought to be familiar with TeX as well as C/C++. |
| 37 |
.SH USAGE |
| 38 |
The command line should have one, two, or three names on it. |
| 39 |
The first is taken as the CWEB input file (and \f[B].w\f[R] is added if |
| 40 |
there is no extension). |
| 41 |
If there is a second name, it is a change file (and \f[B].ch\f[R] is |
| 42 |
added if there is no extension). |
| 43 |
The change file overrides parts of the CWEB file, as described in the |
| 44 |
documentation. |
| 45 |
If there is a third name, it overrides the default name of the output |
| 46 |
file, which is ordinarily the same as the name of the input file (but on |
| 47 |
the current directory) with the extension \f[B].tex\f[R]. |
| 48 |
If you just want to change the output file name, but don\(cqt have a |
| 49 |
change file to apply, you can use `\f[B]\-\f[R]' as the second argument. |
| 50 |
.PP |
| 51 |
\f[B]ctwill\f[R] is exactly like \f[B]cweave\f[R] except that it |
| 52 |
produces much better documentation, for which you must work much harder. |
| 53 |
You should run \f[B]ctwill\f[R] twice, once to prime the pump and once |
| 54 |
to get decent answers. |
| 55 |
Moreover, you must run the output twice through TeX. |
| 56 |
.PP |
| 57 |
After \f[B]tex foo\f[R] you will have output that looks like final pages |
| 58 |
except that the entries of mini-indexes won\(cqt be alphabetized. |
| 59 |
The first run produces a weird file called \f[B]foo.ref\f[R]. |
| 60 |
Say \f[B]ctwill-refsort < foo.ref > foo.sref\f[R] and then another \f[B]tex |
| 61 |
foo\f[R] will produce alphabetized output. |
| 62 |
.PP |
| 63 |
The \f[B]ctwill-twinx\f[R] program compiles a master index for a set of related |
| 64 |
programs that have been processed by \f[B]ctwill\f[R] (\f[I]not\f[R] by |
| 65 |
\f[B]cweave\f[R], mind you!). |
| 66 |
The individual programs should define their names with a line of the |
| 67 |
form \f[B]\(rsdef\(rstitle{NAME}\f[R]. |
| 68 |
For your convenience, \f[B]ctwill-twinx\f[R] grabs the first \(lqword\(rq in |
| 69 |
\f[B]\(rstitle\f[R] and turns it into uppercase form. |
| 70 |
You should adapt file \f[B]twinx-startup.tex\f[R] for the first page of |
| 71 |
the master index. |
| 72 |
.PP |
| 73 |
The mini-indexes list identifiers that are used but not defined on each |
| 74 |
two-page spread. |
| 75 |
At the end of each section, \f[B]ctwill\f[R] gives TeX a list of |
| 76 |
identifiers used in that section and information about where they are |
| 77 |
defined. |
| 78 |
.PP |
| 79 |
The current meaning of every identifier is initially |
| 80 |
\f[B]\(rsuninitialized\f[R]. |
| 81 |
Then \f[B]ctwill\f[R] reads the \f[B].aux\f[R] file for your job, if |
| 82 |
any. |
| 83 |
.PP |
| 84 |
Before reading the \f[B].aux\f[R] file, \f[B]ctwill\f[R] actually looks |
| 85 |
for a file called \f[B]system.bux\f[R], which will be read if present. |
| 86 |
And after \f[B]foo.aux\f[R], a third possibility is \f[B]foo.bux\f[R]. |
| 87 |
The general convention is to put definitions of system procedures such |
| 88 |
as \f[I]printf\f[R] into \f[B]system.bux\f[R], and to put definitions |
| 89 |
found in specifically foo-ish header files into \f[B]foo.bux\f[R]. |
| 90 |
Like the \f[B].aux\f[R] files, \f[B].bux\f[R] files should contain only |
| 91 |
\f[B]\(at$\f[R] specifications. |
| 92 |
.PP |
| 93 |
The meaning specified by \f[B]\(at$\&...\(at>\f[R] generally has four |
| 94 |
components: an identifier (followed by space), a program name (enclosed |
| 95 |
in braces), a section number (followed by space), and a TeX\ part. |
| 96 |
.PP |
| 97 |
A special \f[I]proofmode\f[R] is provided so that you can check |
| 98 |
\f[B]ctwill\f[R]\(cqs conclusions about cross-references. |
| 99 |
Run \f[B]ctwill\f[R] with the flag \f[B]+P\f[R], and TeX will produce a |
| 100 |
specially formatted document with mini-indexes for each section, so |
| 101 |
that you can check that your specifications are correct. |
| 102 |
.PP |
| 103 |
This \f[I]proofmode\f[R] format is used in conjunction with |
| 104 |
\f[B]pdfctproofmac.tex\f[R] that creates active hyperlinks in PDF and HINT |
| 105 |
output. |
| 106 |
You can use \f[B]ctwill-proofsort\f[R] to get the index entries in alphabetical |
| 107 |
order; just invoke |
| 108 |
.PP |
| 109 |
( \f[B]ctwill-proofsort\f[R] < \f[I]texfile\f[R].tex ) 1<> |
| 110 |
\f[I]texfile\f[R].tex |
| 111 |
.PP |
| 112 |
after invoking \f[B]ctwill\f[R] (twice), but before invoking TeX (once). |
| 113 |
.PP |
| 114 |
More details how to use \f[B]ctwill\f[R] can be found in the first |
| 115 |
sections of its source code, respectively the change file |
| 116 |
\f[B]cweav-twill.ch\f[R] applicable to the \f[B]cweave.w\f[R] source. |
| 117 |
A complete example with all bells and whistles is described in |
| 118 |
\f[B]Mini-Indexes for Literate Programs\f[R], pages 225\(en245 of |
| 119 |
Knuth\(cqs \f[B]Digital Typography\f[R] (\f[I]CSLI\f[R], 1999). |
| 120 |
.SH DIFFERENCES TO ORIGINAL CTWILL |
| 121 |
The present incarnation of \f[B]ctwill\f[R] and its utilities tries hard |
| 122 |
to be a drop-in replacement for the original package. |
| 123 |
There are, however, a few differences worth noting: |
| 124 |
.IP \(bu 2 |
| 125 |
This version is based on the most recent version of CWEB (4.12.2). |
| 126 |
.IP \(bu 2 |
| 127 |
In TeX\ Live the utility programs are prefixed with \f[B]ctwill\-\f[R] |
| 128 |
and the macro files with \f[B]ct\f[R] for technical reasons. |
| 129 |
.IP \(bu 2 |
| 130 |
Options \f[B]\-\-help\f[R], \f[B]\-\-quiet\f[R], \f[B]\-\-verbose\f[R], |
| 131 |
\f[B]\-\-version\f[R], and flags \f[B]+c\f[R], \f[B]\-i\f[R], |
| 132 |
\f[B]\-o\f[R], and \f[B]+lX\f[R] are new in CWEBbin and TeX\ Live. |
| 133 |
.IP \(bu 2 |
| 134 |
Option \f[B]+lX\f[R] is accompanied by example wrapper files for |
| 135 |
\f[B]ctwimac.tex\f[R] and \f[B]ctproofmac.tex\f[R] with translated |
| 136 |
captions for German (\f[B]+ld\f[R]). |
| 137 |
.IP \(bu 2 |
| 138 |
Option \f[B]+lX\f[R] is also accompanied by an extended |
| 139 |
\f[B]pdfctwimac.tex\f[R] for production of PDF and HINT output with |
| 140 |
active hyperlinks (\f[B]+lpdf\f[R]). |
| 141 |
.IP \(bu 2 |
| 142 |
File lookup with the environment variable CWEBINPUTS is extended to |
| 143 |
permit several, colon-separated, paths; see ENVIRONMENT below. |
| 144 |
.IP \(bu 2 |
| 145 |
If properly configured, the main program \f[B]ctwill\f[R] is localized |
| 146 |
with the \(lqGNU gettext utilities\(rq. |
| 147 |
.SH OPTIONS |
| 148 |
Options on the command line may be either turned off with `\f[B]\-\f[R]' |
| 149 |
(if they are on by default) or turned on with `\f[B]+\f[R]' (if they are |
| 150 |
off by default). |
| 151 |
In fact, the options are processed from left to right, so a sequence |
| 152 |
like \f[B]\-\-verbose \-h\f[R] will only show the \f[B]banner line\f[R] |
| 153 |
(\f[B]+b\f[R]) and the \f[B]progress report\f[R] (\f[B]+p\f[R]), but |
| 154 |
leave out the \f[B]happy message\f[R] (\f[B]\-h\f[R]). |
| 155 |
.IP \(bu 2 |
| 156 |
\f[B]+b\f[R]: print banner line on terminal |
| 157 |
.IP \(bu 2 |
| 158 |
\f[B]+h\f[R]: print success message on completion |
| 159 |
.IP \(bu 2 |
| 160 |
\f[B]+p\f[R]: print progress report messages |
| 161 |
.IP \(bu 2 |
| 162 |
\f[B]+q\f[R]/\f[B]\-q\f[R]: shortcut for \f[B]\-bhp\f[R]; also |
| 163 |
\f[B]\-\-quiet\f[R] |
| 164 |
.IP \(bu 2 |
| 165 |
\f[B]+v\f[R]/\f[B]\-v\f[R]: shortcut for \f[B]+bhp\f[R]; also |
| 166 |
\f[B]\-\-verbose\f[R] (default) |
| 167 |
.IP \(bu 2 |
| 168 |
\f[B]+c\f[R]: check temporary output for changes |
| 169 |
.IP \(bu 2 |
| 170 |
\f[B]\-e\f[R]: do not enclose C/C++\ material in \f[B]\(rsPB{\&...}\f[R] |
| 171 |
.IP \(bu 2 |
| 172 |
\f[B]\-f\f[R]: do not force a newline after every C/C++\ statement in |
| 173 |
output |
| 174 |
.IP \(bu 2 |
| 175 |
\f[B]\-F\f[R]: do not force a compound statement to start on a new line |
| 176 |
.IP \(bu 2 |
| 177 |
\f[B]\-i\f[R]: suppress indentation of parameter declarations |
| 178 |
.IP \(bu 2 |
| 179 |
\f[B]\-o\f[R]: suppress separation of declarations and statements |
| 180 |
.IP \(bu 2 |
| 181 |
\f[B]\-x\f[R]: omit indices, section names, table of contents |
| 182 |
.IP \(bu 2 |
| 183 |
\f[B]+P\f[R]: \f[B]\(rsinput ctproofmac.tex\f[R] instead of |
| 184 |
\f[B]ctwimac.tex\f[R] |
| 185 |
.IP \(bu 2 |
| 186 |
\f[B]+lX\f[R]/\f[B]\-lX\f[R]: use macros for language \f[I]X\f[R] as of |
| 187 |
\f[I]X\f[R]{\f[B]ctwimac\f[R]|\f[B]ctproofmac\f[R]}\f[B].tex\f[R] |
| 188 |
.IP \(bu 2 |
| 189 |
\f[B]+s\f[R]: print usage statistics |
| 190 |
.IP \(bu 2 |
| 191 |
\f[B]+t\f[R]: treat \f[B]typename\f[R] in a template like |
| 192 |
\f[B]typedef\f[R] |
| 193 |
.IP \(bu 2 |
| 194 |
\f[B]\-\-help\f[R]: display help message and exit |
| 195 |
.IP \(bu 2 |
| 196 |
\f[B]\-\-version\f[R]: output version information and exit |
| 197 |
.SH ENVIRONMENT |
| 198 |
The environment variable CWEBINPUTS is used to search for the input |
| 199 |
files, or the system default if CWEBINPUTS is not set. |
| 200 |
See tex(1) for the details of the searching. |
| 201 |
To avoid conflicts with other programs that also use the CWEBINPUTS |
| 202 |
environment, you can be more specific and use CWEBINPUTS_cweb for |
| 203 |
special requirements in CWEB. |
| 204 |
.PP |
| 205 |
If prepared for NLS support, \f[B]ctwill\f[R] like \f[B]ctangle\f[R] and |
| 206 |
\f[B]cweave\f[R] uses the environment variable TEXMFLOCALEDIR to |
| 207 |
configure the parent directory where the \(lqGNU gettext utilities\(rq |
| 208 |
search for translation catalogs. |
| 209 |
.PP |
| 210 |
These variables are preconfigured in TeX\ Live\(cqs \f[B]texmf.cnf\f[R]. |
| 211 |
.SH FILES |
| 212 |
The location of the files mentioned below varies from system to system. |
| 213 |
Use the \f[B]kpsewhich\f[R] utility to find their locations. |
| 214 |
.IP \(bu 2 |
| 215 |
\f[B]ctwimac.tex\f[R]: The default TeX\ macros \f[B]\(rsinput\f[R] in |
| 216 |
the first line of the output file. |
| 217 |
.IP \(bu 2 |
| 218 |
\f[B]ctproofmac.tex\f[R]: If \f[B]ctwill\f[R] is invoked with the |
| 219 |
\f[B]+P\f[R] option, it will change the first line of the output file to |
| 220 |
\f[B]\(rsinput ctproofmac.tex\f[R]. |
| 221 |
.PP |
| 222 |
In both cases you can request some prefix \f[I]X\f[R] with the |
| 223 |
\f[B]+lX\f[R] option, e.g., \f[B]+ld\f[R] will \f[B]\(rsinput |
| 224 |
dctwimac.tex\f[R] and \f[B]+Pld\f[R] will \f[B]\(rsinput |
| 225 |
dctproofmac.tex\f[R]. |
| 226 |
A special application is the use of option \f[B]+lpdf\f[R] that will |
| 227 |
\f[B]\(rsinput pdfctwimac.tex\f[R] or \f[B]\(rsinput |
| 228 |
pdfctproofmac.tex\f[R] for production of PDF and HINT output with active |
| 229 |
hyperlinks. |
| 230 |
.IP \(bu 2 |
| 231 |
\f[I]webfile\f[R]\f[B].bux\f[R]: Reference definitions to resolve from |
| 232 |
other modules. |
| 233 |
.IP \(bu 2 |
| 234 |
\f[B]system.bux\f[R]: Reference definitions to resolve from |
| 235 |
C/C++\ standard library header files like \f[B]<stdio.h>\f[R]. |
| 236 |
.PP |
| 237 |
Other \f[B]aux\f[R]iliary files with references are created |
| 238 |
automatically by \f[B]ctwill\f[R] and the actual index files are created |
| 239 |
by TeX. |
| 240 |
.IP \(bu 2 |
| 241 |
\f[B]cwebman.tex\f[R]: The CWEB user manual, available in PDF from \c |
| 242 |
.UR https://ctan.org/pkg/cweb |
| 243 |
CTAN |
| 244 |
.UE \c |
| 245 |
\&. |
| 246 |
.SH SEE ALSO |
| 247 |
.IP \(bu 2 |
| 248 |
The CWEB System of Structured Documentation: by Donald E.\ Knuth and |
| 249 |
Silvio Levy (hardcopy version of \f[B]cwebman.tex\f[R] and the source |
| 250 |
code listings of \f[B]common.w\f[R], \f[B]ctangle.w\f[R], and |
| 251 |
\f[B]cweave.w\f[R]). |
| 252 |
.IP \(bu 2 |
| 253 |
CTWILL program source, section 287: |
| 254 |
.RS 2 |
| 255 |
.PP |
| 256 |
https://mirror.ctan.org/info/knuth-pdf/cweb/ctwill.pdf |
| 257 |
.RE |
| 258 |
.IP \(bu 2 |
| 259 |
Digital Typography: by D.\ E.\ Knuth (\f[I]CSLI\f[R], 1999). |
| 260 |
.IP \(bu 2 |
| 261 |
Literate Programming: by D.\ E.\ Knuth (\f[I]CSLI\f[R], 1992). |
| 262 |
.IP \(bu 2 |
| 263 |
Weaving a Program: by Wayne Sewell. |
| 264 |
.PP |
| 265 |
cweb(1), tex(1), cc(1) |
| 266 |
.SH AUTHORS |
| 267 |
Don Knuth wrote \f[B]ctwill\f[R] based on \f[B]cweave\f[R] by Silvio |
| 268 |
Levy and Knuth. |
| 269 |
.PD 0 |
| 270 |
.P |
| 271 |
.PD |
| 272 |
Contemporary development on https://github.com/ascherer/cwebbin. |