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.

                                             7/12/90                                     CWEBX(1)