NAME

       noweb - a simple literate-programming tool

SYNOPSIS

       noweb [-t] [-o] [-Lformat] [-markup parser] [file] ...

DESCRIPTION

       Noweb  is  a  literate-programming  tool  like  FunnelWEB  or nuweb, only simpler.  A noweb file contains
       program source code interleaved with documentation.  When noweb is invoked, it writes the program  source
       code to the output files mentioned in the noweb file, and it writes a TeX file for typeset documentation.

       The  noweb(1) command is for people who don't like reading man pages or who are switching from nuweb.  To
       get the most out of noweb, use notangle(1) and noweave(1) instead.

FORMAT OF NOWEB FILES

       A noweb file is a sequence of chunks, which may appear in  any  order.   A  chunk  may  contain  code  or
       documentation.   Documentation  chunks  begin  with  a line that starts with an at sign (@) followed by a
       space or newline.  They have no names.  Code chunks begin with
       <<chunk name>>=
       on a line by itself.  The double left angle bracket (<<)  must  be  in  the  first  column.   Chunks  are
       terminated  by the beginning of another chunk, or by end of file.  If the first line in the file does not
       mark the beginning of a chunk, it is assumed to be the first line of a documentation chunk.

       Documentation chunks contain text that is copied verbatim to the  TeX  file  (except  for  quoted  code).
       noweb  works  with  LaTeX;  the first documentation chunk must contain a LaTeX \documentclass command, it
       must  contain  \usepackage{noweb}  in  the  preamble,  and  finally  it  must  also   contain   a   LaTeX
       \begin{document} command.

       Code  chunks  contain  program  source code and references to other code chunks.  Several code chunks may
       have the same name; noweb concatenates their definitions  to  produce  a  single  chunk,  just  as  other
       literate-programming  tools do.  noweb looks for chunks that are defined but not used in the source file.
       If the name of such a chunk contains no spaces, the chunk is an ``output file;''  noweb  expands  it  and
       writes the result onto the file of the same name.  A code-chunk definition is like a macro definition; it
       contains references to other chunks, which are  themselves  expanded,  and  so  on.   noweb's  output  is
       readable;  it  preserves  the  indentation  of  expanded  chunks with respect to the chunks in which they
       appear.

       If a star (*) is appended to the name of an  output  file,  noweb  includes  line-number  information  as
       specified  by  the  -Lformat  option  (or for C if no -Lformat option is given).  The name itself may not
       contain shell metacharacters.

       Code may be quoted within documentation chunks by placing double square  brackets  ([[...]])  around  it.
       These double square brackets are used to give the code special typographic treatment in the TeX file.  If
       quoted code ends with three or more square brackets, noweb chooses  the  rightmost  pair,  so  that,  for
       example, [[a[i]]] is parsed correctly.

       In  code,  noweb  treats unpaired double left or right angle brackets as literal << and >>.  To force any
       such brackets, even paired brackets or brackets in  documentation,  to  be  treated  as  literal,  use  a
       preceding at sign (e.g. @<<).

OPTIONS

       -t     Suppress generation of a TeX file.

       -o     Suppress generation of output files.

       -Lformat
              Use format to format line-number information for starred output files.  (If the option is omitted,
              a format suitable for C is used.)  format is as defined by notangle(1);

       -markup parser
              Use parser to parse the input file.  Enables use of noweb tools on files  in  other  formats;  for
              example,   the  numarkup  parser  understands  nuweb(1)  format.   See  nowebfilters(7)  for  more
              information.  For experts only.

BUGS

       Ignoring unused chunks whose names contain spaces sometimes causes problems, especially in the case  when
       a  chunk  has  multiple  definitions  and  one  is misspelled; the misspelled definition will be silently
       ignored.  noroots(1) can be used as a sanity checker to catch this sort of mistake.

       noweb is intended for users who don't want the power or the complexity  of  command-line  options.   More
       sophisticated  users should avoid noweb and use noweave and notangle instead.  If the design were better,
       we could all use the same commands.

       noweb requires the new version of awk.  DEC nawk has a bug in that that causes problems  with  braces  in
       TeX output.  GNU gawk is reported to work.

       The  default  LaTeX  pagestyles  don't  set the width of the boxes containing headers and footers.  Since
       noweb code paragraphs are extra wide, this LaTeX bug sometimes results in extra-wide headers and footers.
       The remedy is to redefine the relevant ps@* commands; ps@noweb in noweb.sty can be used as an example.

SEE ALSO

       notangle(1), noweave(1), noroots(1), nountangle(1), nowebstyle(7), nowebfilters(7), nuweb2noweb(1)
       Norman Ramsey, Literate programming simplified, IEEE Software 11(5):97-105, September 1994.

VERSION

       This man page is from noweb version 2.11b.

AUTHOR

       Norman Ramsey, Harvard University.  Internet address nr@eecs.harvard.edu.
       Noweb home page at http://www.eecs.harvard.edu/~nr/noweb.

                                                 local 3/28/2001                                        NOWEB(1)