.TH CWEBX 1 7/12/90
.SH NAME
ctanglex, cweavex \- translate CWEB(x) to C (or C++) and/or TeX
.SH SYNOPSIS
.B ctanglex
[
.B \-bhpl
] [
.B \+cs+
] \fIcwebfile\fR[.w] [(\fIchangefile\fR[.ch]|+|-) [\fIoutputfile\fR[.c]]]
.br
.B cweavex
[
.B \-bhpx
] [
.B \+cs+dtefauwm
] [
.B +isearchpath
] \fIcwebfile\fR[.w] [(\fIchangefile\fR[.ch]|+|-) [\fIoutputfile\fR[.tex]]]

.SH DESCRIPTION
The
.B ctanglex
program converts a CWEB(x)
source document into a C program that may be compiled in the usual way.
The output file includes \fI#line\fR specifications so that error
reporting and debugging can be done in terms of the CWEB(x) source file.
.PP
The
.B cweavex
program converts the same CWEB(x) 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-reference information that it gathers automatically.
.PP
CWEBx 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 CWEBx ought to have some familiarity with TeX as well as knowledge
of C.
.PP
The command line should have one, two, or three names on it. The first is
taken as the CWEB(x) file (and `\fI.w\fR' is added if there is no
extension). If that file cannot be opened, the extension `\fI.web\fR'
is tried instead. If there is a second name, it is a change file (and
`\fI.ch\fR' is added if there is no extension), otherwise the name of
the CWEB(x) file with its extension replaced by `\fI.ch\fR' is tried as
change file name; if there no such file, no change file
is used. Instead of a change file one may specify `\fB-\fR' or
`\fB+\fR'; `\fB-\fR' means do not use a change file, and `\fB+\fR'
means use a change file only if a file of the
default name exists (just as if only one name was given). The change file
overrides parts of the CWEB(x) file, as described in the
documentation. A third name, if present, specifies the output file
name explicitly. The default output file name is that of the CWEB(x)
file with extension `\fI.c\fR' (for
.B ctanglex
) or `\fI.tex\fR' (for
.B cweavex
); the default extension is also applied if a third
name is given without extension.
.PP
Options in the command line may be either turned on with `\fB+\fR' and
off with `\fB-\fR'; several characters may follow in the same argument, which
indicate several options that are turned on respectively off simultaneously.
In fact, the options are processed from left to right,
so a sequence like `\fB-b +b\fR' is equivalent to `\fB+b\fR' (which is
the default).
.PP
The
.B \+b
option shows a banner line on your terminal. The
.B \+h
option shows a happy message if the processing was successful. The
.B \+p
option shows progress reports (starred module numbers) as the processing
takes place. If you say `\fB-bhp\fR', you get no terminal output but
error messages.
.PP
The
.B \+c
option emulates Levy/Knuth CWEB.
The
.B \+s
option prints statistics about memory usage at the end of a run
(assuming that the programs have been compiled with the \fI-DSTAT\fR
switch, as they are by default on Debian systems).
By setting the option
.B \++
one can select the C++ language instead of C.
.PP
The option
.B \-l
is applicable to
.B ctanglex
only; when selected, the C output is made more readable for humans by omitting
.B #line
directives and preserving layout and comments.
.PP
There are several other options applicable to
.B cweavex
only. The option
.B \-x
means omit the index and table of contents. By setting the option
.B \+d
one causes
.B cweavex
to report problems encountered in parsing the program fragments. With
.B \+t
the index and module names will be written to separate files. With
.B \+e
the table of contents is forced to start on a new sheet when using a
two-sided printer.
The options
.B \+f
, 
.B \+a
,
.B \+u
, 
.B \+w
, and
.B \+m
change the style in which programs are
formatted:
.B \+f
means force a newline after every simple statement in the formatted output,
and
.B \+a
means also force a newline before every simple statement, even if it follows
a label or a condition; the option
.B \+u
will change the style so that a line break goes after `{' instead of before,
thus preventing them from aligning with their matching `}' (this is the
style of Levy/Knuth CWEB), while the option
.B \+w
puts a line break both before and after `{', producing a more symmetric
layout at the expense of some extra paper. Finally, the option
.B \+m
avoids forcing line breaks between successive declarations in a local block.
With the option
.B \+isearchpath
one can specify a place to look for header files, when they are not found in
the current directory. The string following the `+i' will be stored and
prepended to a header file name if it cannot be found otherwise (so the
string should probably end with a pathname separator '/'). More than one
such search path can be specified; they will be tried in order from left to
right.
.PP
.SH FILES
.I /usr/share/texmf/macros/litprog/cwebxmac.tex
TeX macros used by cweavex output.
.br
.I /usr/share/texmf/macros/litprog/cwebcmac.tex
TeX macros used in compatibility mode.
.br
.I /usr/share/texmf/macros/litprog/cwebhmac.tex
TeX macros which can be input after \fIcwebxmac\fR to produce
hyperlinks in the output.
.br
.I /usr/share/doc/cwebx/manual.tex
The user manual source.
.br
.I /usr/share/doc/cwebx/manual.tex
The user manual in DVI format.
.SH "SEE ALSO"
.I Literate Programming
by D. E. Knuth. (CSLI, Stanford, 1992)
.br
.BR tex (1),
.BR cc (1),
.BR cweb (1)
and
.BR web (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.
Frank Jensen adapted the programs to ANSI/ISO C, and Marc van Leeuwen made
numerous changes for version x3.0, and wrote a new manual.
.SH "BUGS"
The syntactic support for C++ does not cover that language completely, so
formatting of complex C++ code may be bad.