NAME¶
ctanglex, cweavex - translate CWEB(x) to C (or C++) and/or TeX
SYNOPSIS¶
ctanglex [
-bhpl ] [
+cs+ ]
cwebfile[.w]
[(
changefile[.ch]|+|-) [
outputfile[.c]]]
cweavex [
-bhpx ] [
+cs+dtefauwm ] [
+isearchpath ]
cwebfile[.w] [(
changefile[.ch]|+|-) [
outputfile[.tex]]]
DESCRIPTION¶
The
ctanglex program converts a CWEB(x) source document into a C program
that may be compiled in the usual way. The output file includes
#line
specifications so that error reporting and debugging can be done in terms of
the CWEB(x) source file.
The
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.
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.
The command line should have one, two, or three names on it. The first is taken
as the CWEB(x) file (and `
.w' is added if there is no extension). If
that file cannot be opened, the extension `
.web' is tried instead. If
there is a second name, it is a change file (and `
.ch' is added if
there is no extension), otherwise the name of the CWEB(x) file with its
extension replaced by `
.ch' is tried as change file name; if there no
such file, no change file is used. Instead of a change file one may specify `
-' or `
+'; `
-' means do not use a change file, and
`
+' 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 `
.c' (for
ctanglex ) or
`
.tex' (for
cweavex ); the default extension is also applied if
a third name is given without extension.
Options in the command line may be either turned on with `
+' and off
with `
-'; 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 `
-b +b' is equivalent to `
+b' (which is the default).
The
+b option shows a banner line on your terminal. The
+h option
shows a happy message if the processing was successful. The
+p option
shows progress reports (starred module numbers) as the processing takes place.
If you say `
-bhp', you get no terminal output but error messages.
The
+c option emulates Levy/Knuth CWEB. The
+s option prints
statistics about memory usage at the end of a run (assuming that the programs
have been compiled with the
-DSTAT switch, as they are by default on
Debian systems). By setting the option
++ one can select the C++
language instead of C.
The option
-l is applicable to
ctanglex only; when selected, the C
output is made more readable for humans by omitting
#line directives
and preserving layout and comments.
There are several other options applicable to
cweavex only. The option
-x means omit the index and table of contents. By setting the option
+d one causes
cweavex to report problems encountered in parsing
the program fragments. With
+t the index and module names will be
written to separate files. With
+e the table of contents is forced to
start on a new sheet when using a two-sided printer. The options
+f ,
+a ,
+u ,
+w , and
+m change the style in which
programs are formatted:
+f means force a newline after every simple
statement in the formatted output, and
+a means also force a newline
before every simple statement, even if it follows a label or a condition; the
option
+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
+w puts a line
break both before and after `{', producing a more symmetric layout at the
expense of some extra paper. Finally, the option
+m avoids forcing line
breaks between successive declarations in a local block. With the option
+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.
FILES¶
/usr/share/texmf/macros/litprog/cwebxmac.tex TeX macros used by cweavex
output.
/usr/share/texmf/macros/litprog/cwebcmac.tex TeX macros used in
compatibility mode.
/usr/share/texmf/macros/litprog/cwebhmac.tex TeX macros which can be
input after
cwebxmac to produce hyperlinks in the output.
/usr/share/doc/cwebx/manual.tex The user manual source.
/usr/share/doc/cwebx/manual.tex The user manual in DVI format.
SEE ALSO¶
Literate Programming by D. E. Knuth. (CSLI, Stanford, 1992)
tex(1),
cc(1),
cweb(1) and
web(1).
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.
BUGS¶
The syntactic support for C++ does not cover that language completely, so
formatting of complex C++ code may be bad.