Debian Codegraph @

texmf-dist/doc/man/man1/ctwill.1

raw
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.