1CTWILL(1)                   General Commands Manual                  CTWILL(1)
2
3
4

NAME

6       ctwill, ctwill-refsort, ctwill-twinx - translate CWEB to TeX with mini-
7       indexes
8

SYNOPSIS

10       ctwill [options] webfile[.w] [{changefile[.ch]|-} [outfile[.tex]]]
11       ctwill-refsort < indexfile.ref > indexfile.sref
12       ctwill-twinx outfile.tex [outfile.tex ...] > index.tex
13

DESCRIPTION

15       The ctwill program converts a CWEB source document into a TeX file that
16       may  be  formatted  and printed in the usual way.  It takes appropriate
17       care of typographic details like page layout and the  use  of  indenta‐
18       tion,  italics,  boldface,  etc., and it supplies extensive cross-index
19       information that it gathers automatically.
20
21       CWEB allows you to prepare a single document containing all the  infor‐
22       mation that is needed both to produce a compilable C/C++ program and to
23       produce a well-formatted document describing the program in as much de‐
24       tail  as  the writer may desire.  The user of CWEB ought to be familiar
25       with TeX as well as C/C++.
26

USAGE

28       The command line should have one, two, or three names on it.  The first
29       is  taken as the CWEB input file (and .w is added if there is no exten‐
30       sion).  If there is a second name, it is a  change  file  (and  .ch  is
31       added  if  there  is no extension).  The change file overrides parts of
32       the CWEB file, as described in the documentation.  If there is a  third
33       name,  it overrides the default name of the output file, which is ordi‐
34       narily the same as the name of the input file (but on the  current  di‐
35       rectory)  with the extension .tex.  If you just want to change the out‐
36       put file name, but don’t have a change file to apply, you can  use  `-'
37       as the second argument.
38
39       ctwill is exactly like cweave except that it produces much better docu‐
40       mentation, for which you must  work  harder.   You  should  run  ctwill
41       twice,  once  to  prime the pump and once to get decent answers.  More‐
42       over, you must run the output twice through TeX.
43
44       After tex foo you will have output that looks like final  pages  except
45       that  the entries of mini-indexes won’t be alphabetized.  The first run
46       produces a weird file called foo.ref.  Say ctwill-refsort <  foo.ref  >
47       foo.sref and then another tex foo will produce alphabetized output.
48
49       The  ctwill-twinx  program compiles a master index for a set of related
50       programs that have been processed by ctwill.  The  individual  programs
51       should define their names with a line of the form \def\title{NAME}.
52
53       The mini-indexes list identifiers that are used but not defined on each
54       two-page spread.  At the end of each section, ctwill gives TeX  a  list
55       of  identifiers  used  in that section and information about where they
56       are defined.
57
58       The current meaning of every identifier  is  initially  \uninitialized.
59       Then ctwill reads the .aux file for your job, if any.
60
61       Before  reading  the .aux file, ctwill actually looks for a file called
62       system.bux, which will be read if present.  And after foo.aux, a  third
63       possibility  is  foo.bux.  The general convention is to put definitions
64       of system procedures such as printf into system.bux, and to put defini‐
65       tions  found  in  specifically foo-ish header files into foo.bux.  Like
66       the .aux files, .bux files should contain only @$ specifications.
67
68       The meaning specified by @$...@>  generally  has  four  components:  an
69       identifier  (followed by space), a program name (enclosed in braces), a
70       section number (followed by space), and a TeX part.
71
72       A special proofmode is provided so that you can check ctwill’s  conclu‐
73       sions  about  cross-references.   Run  ctwill with the flag +P, and TeX
74       will produce a specially formatted document (without  mini-indexes)  in
75       which you can check that your specifications are correct.
76
77       More  details  how  to use ctwill can be found in the first sections of
78       its source code, respectively the change file cweav-twill.ch applicable
79       to the cweave.w source.  A complete example with all bells and whistles
80       is described in Mini-Indexes for Literate Programs,  pages  225–245  of
81       Knuth’s Digital Typography.
82

DIFFERENCES TO ORIGINAL CTWILL

84       The  present incarnation of ctwill and its utilities tries hard to be a
85       drop-in replacement for the original package.  There  are,  however,  a
86       few differences worth noting:
87
88       • This version is based on the most recent version of CWEB (4.2).
89
90       • In  TeX Live  the  utility programs are prefixed with ctwill- and the
91         macro files with ct for technical reasons.
92
93       • Options --help, --quiet, --verbose, --version, and flags -i, -o,  -t,
94         and +lX are new in CWEBbin and TeX Live.
95
96       • Option  +lX  is  accompanied by example wrapper files for ctwimac.tex
97         and ctproofmac.tex with translated captions for German (+ld).
98
99       • Option +lX is also accompanied by an extended pdfctwimac.tex for pro‐
100         duction of PDF output with active hyperlinks (+lpdf).
101
102ctwill  in  TeX Live  operates silently by default; use the --verbose
103         option to get the original behavior.
104
105       • File lookup with the environment variable CWEBINPUTS is  extended  to
106         permit several, colon-separated, paths; see ENVIRONMENT below.
107
108       • If properly configured, the main program ctwill is localized with the
109         “GNU gettext utilities”.
110

OPTIONS

112       Options on the command line may be either turned off with `-' (if  they
113       are  on by default) or turned on with `+' (if they are off by default).
114       In fact, the options are processed from left to right,  so  a  sequence
115       like  --verbose -h will only show the banner line (+b) and the progress
116       report (+p), but leave out the happy message (-h).
117
118+b: print banner line on terminal
119
120+h: print success message on completion
121
122+p: print progress report messages
123
124+q/-q: shortcut for -bhp; also --quiet (default)
125
126+v/-v: shortcut for +bhp; also --verbose
127
128-e: do not enclose C/C++ material in \PB{...}
129
130-f: do not force a newline after every C/C++ statement in output
131
132-i: suppress indentation of parameter declarations
133
134-o: suppress separation of declarations and statements
135
136-t: ignore temporary output irrespective of changes
137
138-x: omit indices, section names, table of contents
139
140+P: \input ctproofmac.tex instead of ctwimac.tex
141
142+lX/-lX: use macros for language X as of X{ctwimac|ctproofmac}.tex
143
144+s: print usage statistics
145
146--help: display help message and exit
147
148--version: output version information and exit
149

ENVIRONMENT

151       The environment variable CWEBINPUTS is used to  search  for  the  input
152       files,  or the system default if CWEBINPUTS is not set.  See tex(1) for
153       the details of the searching.  To avoid conflicts with  other  programs
154       that  also use the CWEBINPUTS environment, you can be more specific and
155       use CWEBINPUTS_cweb for special requirements in CWEB.
156
157       If prepared for NLS support, ctwill like ctangle and  cweave  uses  the
158       environment  variable  TEXMFLOCALEDIR to configure the parent directory
159       where the “GNU gettext utilities” search for translation catalogs.
160
161       These variables are preconfigured in TeX Live’s texmf.cnf.
162

FILES

164       The location of the files mentioned below varies from system to system.
165       Use the kpsewhich utility to find their locations.
166
167ctwimac.tex:  The  default TeX macros \input in the first line of the
168         output file.
169
170ctproofmac.tex: If ctwill is invoked with  the  +P  option,  it  will
171         change the first line of the output file to \input ctproofmac.tex.
172
173       In  both cases you can request some prefix X with the +lX option, e.g.,
174       +ld will \input dctwimac.tex and +Pld will \input  dctproofmac.tex.   A
175       special  application  is  the  use  of  option  +lpdf  that will \input
176       pdfctwimac.tex for production of PDF output with active hyperlinks.
177
178webfile.bux: Reference definitions to resolve from other modules.
179
180system.bux: Reference definitions to resolve from C/C++ standard  li‐
181         brary header files like <stdio.h>.
182
183       Other  auxiliary  files  with  references  are created automatically by
184       ctwill and the actual index files are created by TeX.
185
186cwebman.tex: The  CWEB  user  manual,  available  in  PDF  from  CTAN
187         (https://ctan.org/pkg/cweb).
188

SEE ALSO

190       • The  CWEB  System of Structured Documentation: by Donald E. Knuth and
191         Silvio Levy (hardcopy version of  cwebman.tex  and  the  source  code
192         listings of common.w, ctangle.w, and cweave.w).
193
194       • Digital Typography: by D. E. Knuth.
195
196       • Literate Programming: by D. E. Knuth.
197
198       • Weaving a Program: by Wayne Sewell.
199
200       cweb(1), tex(1), cc(1)
201

AUTHORS

203       Don Knuth wrote ctwill based on cweave by Silvio Levy and Knuth.
204       ctwill and its utilities ctwill-refsort and ctwill-twinx have been ful‐
205       ly integrated with the CWEBbin extension that serves as the  basis  for
206       CWEB  in  TeX Live;  see  the  project page (https://github.com/ascher
207       er/cwebbin).
208
209
210
211Web2c 2021                     February 6, 2021                      CTWILL(1)
Impressum