summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/man/cweb.man
blob: 6f00a0ed9ebe1ddbcd5c05f09e266d775ea6ff22 (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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
.TH CWEB 1 "10 January 2018" "Web2C @VERSION@"
.\"=====================================================================
.SH NAME
ctangle, cweave \- translate CWEB to C and/or TeX
.\"=====================================================================
.SH SYNOPSIS
.B ctangle
.RB [ +bhps ]
.IR webfile [ \fB.w\fP ]
.RI [{ changefile [ \fB.ch\fP ]| \fB\-\fP }
.RI [ outfile [ \fB.c\fP ]]]
.br
.B cweave
.RB [ +bhps ]
.RB [ \-efiox ]
.RB [ \-lX | +lX ]
.IR webfile [ \fB.w\fP ]
.RI [{ changefile [ \fB.ch\fP ]| \fB\-\fP }
.RI [ outfile [ \fB.tex\fP ]]]
.\"=====================================================================
.SH DESCRIPTION
The
.B 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
.B 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
.B .w
is added if there is no extension).
If that file cannot be opened, the extension
.B .web
is tried instead. (But
.B .w
is recommended, since
.B .web
usually implies Pascal.)
If there is a second name, it is a change file (and
.B .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
.B .c
or
.BR .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
Both programs operate silently by default (as of 2019).
.PP
The
.B +b
option prints the banner line on your terminal
when ctangle or cweave begins.
The
.B +h
option prints the happy message if the processing
was successful.
The
.B +p
option prints progress reports (starred module numbers) as the processing
takes place.
.PP
The
.B +s
option prints statistics about memory usage at the end of a run.
.PP
There are six other options applicable to
.B cweave
only:
.B \-e
inhibits the enclosure of C\ material formatted by
.B cweave
in
\ePB{.\|.\|.}
brackets.
Such brackets are normally inserted so that special hooks
can be used by
.I cweb-latex
and similar programs.
By default,
\ePB{.\|.\|.}.
is defined as a no-op.
.B \-f
means do not force a newline after every statement in the formatted output.
.B \-i
suppresses the indentation of parameter declarations.
.B \-lX
(or +lX) uses macros for language X\ from Xcwebmac.tex.
.B \-o
suppresses the visual separation of declarations and statements.
.B \-x
means omit the index and table of contents.
.\"=====================================================================
.SH ENVIRONMENT
The environment variable CWEBINPUTS is used to search for the input files,
or the system default if CWEBINPUTS is not set.  See
.BR tex (1)
for the details of the searching.
.\"=====================================================================
.SH FILES
The location of the files mentioned below varies from system to
system.  Use the
.B kpsewhich
utility to find their locations.
.TP
.I cwebmac.tex
TeX macros used by cweave output.
.TP
.I cwebman.tex
The user manual.
.\"=====================================================================
.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).
.PP
.BR tex (1),
.BR cc (1).
.\"=====================================================================
.SH AUTHORS
Don Knuth wrote WEB for TeX and Pascal.
.br
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.
.br
As of 2019, the CWEB system in TeX Live is based on the CWEBbin extension
that collects ideas and improvements from numerous contributors;
see https://github.com/ascherer/cwebbin.