NOWEB(1)						      General Commands Manual							  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 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 doc-
       umentation chunk must contain a LaTeX documentclass command, it must contain usepackage{noweb} in the preamble, and finally it must  also
       contain a LaTeX egin{document} command.

       Code  chunks  contain  program source code and references to other code chunks.	Several code chunks may have the same name; noweb concate-
       nates 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 under-
	      stands 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)