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