NOWEB(1)

NAME
notangle, noweave, nountangle, noroots - noweb, a literate programming tool

SYNOPSIS
notangle [-Rrootname] [-L[format]] [file] ...
noweave [-l|-n|-x] [file] ...
nountangle [-ml|-m3|-c|-awk] [-Rrootname] [-wwidth] [file] ...
noroots [file] ...

DESCRIPTION
Noweb is a literate programming tool like Knuth's WEB, only simpler. A noweb file contains program source code interleaved with documentation. When notangle is given a noweb file, it writes the program on standard output. When noweave is given a noweb file, it reads the noweb source and produces, on standard output, TeX source for typeset documentation. nountangle is a version of notangle that converts a literate program into an ordinary program by turning interleaved documentation into comments. noroots finds the roots of a noweb file: it prints the names of all code chunks that are defined but not used. A `-' in place of a file name refers to standard input.

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 ignored by notangle and copied verbatim to standard output by noweave (except for quoted code). noweave can work with LaTeX, or it can insert a reference to a standard TeX macro package, nwmac, that defines commands like \chapter and \section.

Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; notangle concatenates their definitions to produce a single chunk, just as does tangle(1). Code chunk definitions are like macro definitions; notangle extracts a program by expanding one chunk (by default, the chunk named <<*>>). The definition of that chunk contains references to other chunks, which are themselves expanded, and so on. notangle's output is readable; it preserves the indentation of expanded chunks with respect to the chunks in which they appear.

Code may be quoted within documentation chunks by placing double square brackets ([[...]]) around it. These double square brackets are ignored by notangle, but they may be used by noweave to give the code special typographic treatment.

If the double left or right angle bracket is to be used in code or documentation, not as part of a chunk name, it should be preceded by an at sign (e.g. @<<), although the at sign is not required if there is no matching double bracket.

OPTIONS
Given the -Rname option, notangle will expand the <<name>> code chunk instead of <<*>>.

Given the -Lformat option, notangle will emit line number indications at chunk boundaries. A line number indication identifies the source of the line that follows it. In format, `%F' indicates the name of the source file, `%L' indicates the line number of the source file, `%N' indicates a newline, and `%%' indicates a percent sign. A sign and digit may be inserted between the percent sign and the `L', in which case the line number will be adjusted by that amount. If format is omitted, the default format is that accepted by the C preprocessor: `#line %L "%F"%N'. When using the -Lformat option, notangle ensures that all text appears in the same column in input and output.

By default, notangle and noweave expand tabs with stops every 8 columns. The -tk option makes notangle copy tabs untouched from input to output and use tabs for indentation, assuming stops every k columns. The -tk option makes noweave expand tabs with stops every k columns. The -t option makes noweave copy tabs to its output.

nountangle accepts various language options that determine the format of the comments into which it transforms the documentation chunks. The -wnn option tells it to create comments for a line nn characters wide. notangle and nountangle accept (and ignore) each other's options.

The -l option makes noweave emit header and trailer for a LaTeX document instead of for a TeX document. The -n option suppresses the emission of header and trailer. The -x option makes noweave add a page number to each chunk name and generate LaTeX cross-reference information for the chunks.

Output from noweave that lacks header and trailer can be used in TeX documents that include `nwmac' and in LaTeX documents that use the `noweb' document-style option. That style option defines a `webcode' environment, in which you can place fragments of code, and in which only backslash and curly braces have their special meanings; all other characters are taken literally.

ERROR MESSAGES
If notangle or noweave encounters a chunk name within documentation, it assumes that this indicates an error, usually misspelling ``<<name>>=''. Other error messages should be self-explanatory.

It is incorrect to refer to a chunk that is never defined, but it is OK for chunks to be defined and not used.

FILES

|LIBDIR|/markup	markup preprocessor
|LIBDIR|/unmarkup	inverts markup
|LIBDIR|/nt	notangle proper
|TEXINPUTS|/nwkernel.tex	kernel TeX macros
|TEXINPUTS|/nwmac.tex	formatting TeX macros
|TEXINPUTS|/noweb.sty	use in LaTeX documents

BUGS
notangle and nountangle won't work if file names or chunk names mentioned on the command line contain embedded single quotes.

Ignoring unused chunks 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 can be used as a sanity checker to catch this sort of mistake.

noweb requires the new version of awk, assumed to be called nawk. DEC nawk has a bug in that that causes noweave to fail to translate backslashes correctly. GNU gawk is reported to work.

AUTHOR
Norman Ramsey, Princeton University. Internet address nr@princeton.edu.