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