Debian Codegraph @

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

raw
1 .\" Automatically generated by Pandoc
2 .\"
3 .TH "CWEB" "1" "April 30, 2025." "Web2c 2026" "General Commands Manual"
4 .SH NAME
5 ctangle, cweave \- translate CWEB to C/C++ and/or TeX
6 .SH SYNOPSIS
7 \f[B]ctangle\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w]
8 [{\f[I]changefile\f[R][.ch]|\-} [\f[I]outfile\f[R][.c]]]
9 .PD 0
10 .P
11 .PD
12 \f[B]cweave\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w]
13 [{\f[I]changefile\f[R][.ch]|\-} [\f[I]outfile\f[R][.tex]]]
14 .SH DESCRIPTION
15 The \f[B]ctangle\f[R] program converts a CWEB source document into a
16 C/C++\ program that may be compiled in the usual way.
17 The output file includes \f[B]#line\f[R] specifications so that
18 debugging can be done in terms of the CWEB source file.
19 .PP
20 The \f[B]cweave\f[R] program converts the same CWEB file into a
21 TeX\ file that may be formatted and printed in the usual way.
22 It takes appropriate care of typographic details like page layout and
23 the use of indentation, \f[I]italics\f[R], \f[B]boldface\f[R], etc., and
24 it supplies extensive cross-index information that it gathers
25 automatically.
26 .PP
27 CWEB allows you to prepare a single document containing all the
28 information that is needed both to produce a compilable C/C++\ program
29 and to produce a well-formatted document describing the program in as
30 much detail as the writer may desire.
31 The user of CWEB ought to be familiar with TeX as well as C/C++.
32 .SH USAGE
33 The command line should have one, two, or three names on it.
34 The first is taken as the CWEB input file (and \f[B].w\f[R] is added if
35 there is no extension).
36 If there is a second name, it is a change file (and \f[B].ch\f[R] is
37 added if there is no extension).
38 The change file overrides parts of the CWEB file, as described in the
39 documentation.
40 If there is a third name, it overrides the default name of the output
41 file, which is ordinarily the same as the name of the input file (but on
42 the current directory) with the extension \f[B].tex\f[R].
43 If you just want to change the output file name, but don\(cqt have a
44 change file to apply, you can use `\f[B]\-\f[R]' as the second argument.
45 .SH DIFFERENCES TO ORIGINAL CWEB
46 CWEBbin tries hard to be a drop-in replacement for CWEB, so in general
47 you should not notice any differences in invoking the programs nor in
48 the resulting output.
49 There are, however, a few differences worth noting:
50 .IP \(bu 2
51 Options \f[B]\-\-help\f[R], \f[B]\-\-quiet\f[R], \f[B]\-\-verbose\f[R],
52 \f[B]\-\-version\f[R], and flags \f[B]+c\f[R], \f[B]\-i\f[R],
53 \f[B]\-o\f[R], \f[B]+u\f[R], and \f[B]+lX\f[R] are new in CWEBbin and
54 TeX\ Live.
55 .IP \(bu 2
56 Option \f[B]+lX\f[R] is accompanied by several wrapper files for
57 \f[B]cwebmac.tex\f[R] with translated captions for German
58 (\f[B]+ld\f[R]), French (\f[B]+lf\f[R]), and Italian (\f[B]+li\f[R]).
59 .IP \(bu 2
60 File lookup with the environment variable CWEBINPUTS is extended to
61 permit several, colon-separated, paths; see ENVIRONMENT below.
62 .IP \(bu 2
63 If properly configured, the main programs \f[B]ctangle\f[R] and
64 \f[B]cweave\f[R] are localized with the \(lqGNU gettext utilities\(rq.
65 .SH OPTIONS
66 Options on the command line may be either turned off with `\f[B]\-\f[R]'
67 (if they are on by default) or turned on with `\f[B]+\f[R]' (if they are
68 off by default).
69 In fact, the options are processed from left to right, so a sequence
70 like \f[B]\-\-verbose \-h\f[R] will only show the \f[B]banner line\f[R]
71 (\f[B]+b\f[R]) and the \f[B]progress report\f[R] (\f[B]+p\f[R]), but
72 leave out the \f[B]happy message\f[R] (\f[B]\-h\f[R]).
73 .PP
74 The first batch of options are common to both \f[B]ctangle\f[R] and
75 \f[B]cweave\f[R]:
76 .IP \(bu 2
77 \f[B]+b\f[R]: print banner line on terminal
78 .IP \(bu 2
79 \f[B]+h\f[R]: print success message on completion
80 .IP \(bu 2
81 \f[B]+p\f[R]: print progress report messages
82 .IP \(bu 2
83 \f[B]+q\f[R]/\f[B]\-q\f[R]: shortcut for \f[B]\-bhp\f[R]; also
84 \f[B]\-\-quiet\f[R]
85 .IP \(bu 2
86 \f[B]+v\f[R]/\f[B]\-v\f[R]: shortcut for \f[B]+bhp\f[R]; also
87 \f[B]\-\-verbose\f[R] (default)
88 .IP \(bu 2
89 \f[B]+c\f[R]: check temporary output for changes
90 .IP \(bu 2
91 \f[B]+s\f[R]: print usage statistics
92 .IP \(bu 2
93 \f[B]\-\-help\f[R]: display help message and exit
94 .IP \(bu 2
95 \f[B]\-\-version\f[R]: output version information and exit
96 .PP
97 There are two other options applicable to \f[B]ctangle\f[R] only:
98 .IP \(bu 2
99 \f[B]+k\f[R]: keep separators in numeric literals in the output
100 .IP \(bu 2
101 \f[B]+u\f[R]: transliterate UTF-8 characters in C code
102 .PP
103 There are eight other options applicable to \f[B]cweave\f[R] only:
104 .IP \(bu 2
105 \f[B]\-e\f[R]: do not enclose C/C++\ material in \f[B]\(rsPB{\&...}\f[R]
106 .IP \(bu 2
107 \f[B]\-f\f[R]: do not force a newline after every C/C++\ statement in
108 output
109 .IP \(bu 2
110 \f[B]\-F\f[R]: do not force a compound statement to start on a new line
111 .IP \(bu 2
112 \f[B]\-i\f[R]: suppress indentation of parameter declarations
113 .IP \(bu 2
114 \f[B]\-o\f[R]: suppress separation of declarations and statements
115 .IP \(bu 2
116 \f[B]\-x\f[R]: omit indices, section names, table of contents
117 .IP \(bu 2
118 \f[B]+lX\f[R]/\f[B]\-lX\f[R]: use macros for language \f[I]X\f[R] as of
119 \f[I]X\f[R]\f[B]cwebmac.tex\f[R]
120 .IP \(bu 2
121 \f[B]+t\f[R]: treat \f[B]typename\f[R] in a template like
122 \f[B]typedef\f[R]
123 .SH ENVIRONMENT
124 The environment variable CWEBINPUTS is used to search for the input
125 files, or the system default if CWEBINPUTS is not set.
126 See tex(1) for the details of the searching.
127 To avoid conflicts with other programs that also use the CWEBINPUTS
128 environment, you can be more specific and use CWEBINPUTS_cweb for
129 special requirements in CWEB.
130 .PP
131 If prepared for NLS support, \f[B]ctangle\f[R] and \f[B]cweave\f[R] use
132 the environment variable TEXMFLOCALEDIR to configure the parent
133 directory where the \(lqGNU gettext utilities\(rq search for translation
134 catalogs.
135 .PP
136 These variables are preconfigured in TeX\ Live\(cqs \f[B]texmf.cnf\f[R].
137 .SH FILES
138 The location of the files mentioned below varies from system to system.
139 Use the \f[B]kpsewhich\f[R] utility to find their locations.
140 .IP \(bu 2
141 \f[B]cwebmac.tex\f[R]: The default TeX\ macros \f[B]\(rsinput\f[R] in
142 the first line of the \f[B]cweave\f[R] output file.
143 .IP \(bu 2
144 \f[B]cwebman.tex\f[R]: The CWEB user manual, available in PDF from \c
145 .UR https://ctan.org/pkg/cweb
146 CTAN
147 .UE \c
148 \&.
149 .SH SEE ALSO
150 .IP \(bu 2
151 The CWEB System of Structured Documentation: by Donald E.\ Knuth and
152 Silvio Levy (hardcopy version of \f[B]cwebman.tex\f[R] and the source
153 code listings of \f[B]common.w\f[R], \f[B]ctangle.w\f[R], and
154 \f[B]cweave.w\f[R]).
155 .IP \(bu 2
156 Literate Programming: by D.\ E.\ Knuth.
157 .IP \(bu 2
158 Weaving a Program: by Wayne Sewell.
159 .PP
160 cweb(1), tex(1), cc(1)
161 .SH AUTHORS
162 Don Knuth wrote WEB for TeX and Pascal.
163 .PD 0
164 .P
165 .PD
166 Silvio Levy designed and developed CWEB by adapting the WEB conventions
167 to C and by recoding everything in CWEB.
168 Knuth began using CWEB and made further refinements.
169 .PD 0
170 .P
171 .PD
172 Many other helpers are acknowledged in the CWEB manual.
173 .PD 0
174 .P
175 .PD
176 Contemporary development on https://github.com/ascherer/cweb.