NOWEB(1)NOWEB(1)NAMEnoweb - a simple literate-programming tool
SYNOPSISnoweb [-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 ALSOnotangle(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)
