summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/cwebdir/cweb.1
blob: 93c5f1d9c4a1b77d359290ee44b5fffd60dbdddf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
.TH CWEB 1 2021-Mar-24
.
.SH NAME
ctangle, cweave \- translate CWEB to C and/or TeX
.
.SH SYNOPSIS
.na
.B ctangle
[
.B \-bhp
] [
.B +ks
] webfile[.w] [{changefile[.ch]|-} [outputfile[.c]]]
.br
.B cweave
[
.B \-befhpx
] [
.B +st
] webfile[.w] [{changefile[.ch]|-} [outputfile[.tex]]]
.ad
.
.SH DESCRIPTION
The
.I ctangle
program converts a CWEB
source document into a C\ program that may be compiled in the usual way.
The output file includes #line specifications so that debugging can be
done in terms of the CWEB source file.
.PP
The
.I cweave
program converts the same CWEB file into a TeX file that may be
formatted and printed in the usual way.
It takes appropriate care of typographic details like page
layout and the use of indentation, italics, boldface, etc., and it supplies
extensive cross-index information that it gathers automatically.
.PP
CWEB allows you to prepare a single
document containing all the information that is needed both to produce
a compilable C\ program and to produce a well-formatted document
describing the program in as much detail as the writer may desire.
The user of CWEB ought to be familiar with TeX as well as\ C.
.PP
The command line should have one, two, or three names on it.
The first is taken as the CWEB file (and .w is added if there is no
extension).
If that file cannot be opened, the extension .web is tried instead.
(But .w is recommended, since .web usually implies Pascal.)
If there is a second name, it is a change file (and .ch is added if there is
no extension).
The change file overrides parts of the WEB file,
as described in the documentation.
If there is a third name, it overrides
the default name of the output file, which is ordinarily the same as
the name of the input file (but on the current directory) with the
extension .c or .tex.
.PP
Options in the command line may be either turned off with\ \-
(if they are on by default) or turned on with\ + (if they are off by
default).
In fact, the options are processed from left to right,
so a sequence like -f\ +f corresponds to +f (which is the default).
.PP
The
.B \-b
option suppresses the banner line that normally appears on your terminal
when ctangle or cweave begins.
The
.B \-h
option suppresses the happy message that normally appears if the processing
was successful.
The
.B \-p
option suppresses progress reports (starred module numbers) as the processing
takes place.
If you say -bhp, you get nothing but error messages.
.PP
The
.B +s
option prints statistics about memory usage at the end of a run.
.PP
There is one other option applicable to
.I ctangle
only:
.B +k
means keep '-separators in numeric literals in the C/C++\ output.
.PP
There are four other options applicable to
.I cweave
only:
.B \-f
means do not force a newline after every statement in the formatted output.
.B \-e
inhibits the enclosure of C\ material formatted by
.I cweave
in brackets
\ePB{...};
such brackets are normally inserted so that special hooks
can be used by
.I cweb-latex
and similar programs.
.B \-x
means omit the index, the names of the sections, and the table of contents.
.B +t
means treat 'typename' in templates like 'typedef'.
.
.SH FILES
The location of the files mentioned below varies from system to system.
.TP
cwebmac.tex
TeX macros used by cweave output.
.TP
cwebman.tex
The user manual.
.TP
/usr/lib/cweb
Directory for cweb "include" files.
.
.SH "SEE ALSO"
.TP
.I Literate Programming
by D. E. Knuth
.TP
.I Weaving a Program
by Wayne Sewell
.TP
.I The CWEB System of Structured Documentation
by Donald E. Knuth and Silvio Levy (hardcopy version of cwebman.tex
and the source code listings)
.TP
tex(1), cc(1)
.
.SH AUTHORS
Don Knuth wrote WEB for TeX and Pascal.
Silvio Levy designed and developed CWEB
by adapting the WEB conventions to\ C and by recoding everything in CWEB.
Knuth began using CWEB and made further refinements.
Many other helpers are acknowledged in the CWEB manual.