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)