source/texk/web2c/cwebdir/cweb.1

   1 .TH CWEB 1L 2002-Apr-13
   2 .
   3 .SH NAME
   4 ctangle, cweave \- translate CWEB to C and/or TeX
   5 .
   6 .SH SYNOPSIS
   7 .na
   8 .B ctangle
   9 [
  10 .B \-bhp
  11 ] [
  12 .B +s
  13 ] webfile[.w] [changefile[.ch]] [outputfile[.c]]
  14 .br
  15 .B cweave
  16 [
  17 .B \-befhpx
  18 ] [
  19 .B +s
  20 ] webfile[.w] [changefile[.ch]] [outputfile[.tex]]
  21 .ad
  22 .
  23 .SH DESCRIPTION
  24 The
  25 .I 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 .I 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 .w is added if there is no
  47 extension).
  48 If that file cannot be opened, the extension .web is tried instead.
  49 (But .w is recommended, since .web usually implies Pascal.)
  50 If there is a second name, it is a change file (and .ch is added if there is
  51 no extension).
  52 The change file overrides parts of the WEB file,
  53 as described in the documentation.
  54 If there is a third name, it overrides
  55 the default name of the output file, which is ordinarily the same as
  56 the name of the input file (but on the current directory) with the
  57 extension .c or .tex.
  58 .PP
  59 Options in the command line may be either turned off with\ \-
  60 (if they are on by default) or turned on with\ + (if they are off by
  61 default).
  62 In fact, the options are processed from left to right,
  63 so a sequence like -f\ +f corresponds to +f (which is the default).
  64 .PP
  65 The
  66 .B \-b
  67 option suppresses the banner line that normally appears on your terminal
  68 when ctangle or cweave begins.
  69 The
  70 .B \-h
  71 option suppresses the happy message that normally appears if the processing
  72 was successful.
  73 The
  74 .B \-p
  75 option suppresses progress reports (starred module numbers) as the processing
  76 takes place.
  77 If you say -bhp, you get nothing but error messages.
  78 .PP
  79 The
  80 .B +s
  81 option prints statistics about memory usage at the end of a run
  82 (assuming that the programs have been compiled with the -DSTAT switch).
  83 .PP
  84 There are three other options applicable to
  85 .I cweave
  86 only:
  87 .B \-f
  88 means do not force a newline after every statement in the formatted output.
  89 .B \-e
  90 inhibits the enclosure of C\ material formatted by
  91 .I cweave
  92 in brackets
  93 \ePB{...}.
  94 Such brackets are normally inserted so that special hooks
  95 can be used by
  96 .I cweb-latex
  97 and similar programs.
  98 .B \-x
  99 means omit the index and table of contents.
 100 .
 101 .SH FILES
 102 .TP
 103 /usr/local/lib/tex/inputs/cwebmac.tex
 104 TeX macros used by cweave output.
 105 .TP
 106 /usr/local/src/cweb/cwebman.tex
 107 The user manual.
 108 .TP
 109 /usr/local/src/cweb/examples/wc.w
 110 An introductory example.
 111 .TP
 112 /usr/local/src/cweb/examples/wmerge.w
 113 Patch program based on CWEB-style change files.
 114 .TP
 115 /usr/local/lib/cweb
 116 Directory for cweb "include" files.
 117 .
 118 .SH "SEE ALSO"
 119 .TP
 120 .I Literate Programming
 121 by D. E. Knuth
 122 .TP
 123 .I Weaving a Program
 124 by Wayne Sewell
 125 .TP
 126 .I The CWEB System of Structured Documentation
 127 by Donald E. Knuth and Silvio Levy (hardcopy version of cwebman.tex
 128 and the source code listings)
 129 .TP
 130 tex(1), cc(1)
 131 .
 132 .SH AUTHORS
 133 Don Knuth wrote WEB for TeX and Pascal.
 134 Silvio Levy designed and developed CWEB
 135 by adapting the WEB conventions to\ C and by recoding everything in CWEB.
 136 Knuth began using CWEB and made further refinements.
 137 Many other helpers are acknowledged in the CWEB manual.
 138