source/texk/web2c/man/cweb.man

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