NOWEB(1)							      NOWEB(1)

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 sim‐
       pler.  A noweb file contains program source code interleaved with docu‐
       mentation.  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 notan‐
       gle(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 new‐
       line.  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 documen‐
       tation chunk.

       Documentation chunks contain text that is copied verbatim  to  the  TeX
       file (except for quoted code).  noweb works with LaTeX; the first docu‐
       mentation 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  spa‐
       ces,  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  pre‐
       serves 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	right‐
       most 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, assumed to be called nawk.   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  contain‐
       ing  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.har‐
       vard.edu.
       Noweb home page at http://www.eecs.harvard.edu/~nr/noweb.

				local 3/28/2001			      NOWEB(1)

Vote for polarhome