Provided by: noweb_2.11b-3_i386

#### 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



#### FORMATOFNOWEBFILES

       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.



#### SEEALSO

       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.