Provided by: noweb_2.11b-11.1_amd64 
NAME
notangle, noweave, nountangle - noweb, a literate-programming tool
SYNOPSIS
notangle [-Rrootname ...] [-filter command] [-L[format]] [file] ...
nountangle [-ml|-m3|-c|-c++|-awk|-tex|-f77|-f90|-lisp|-matlab] [-Rrootname ...] [-filter command]
[-wwidth] [file] ...
noweave [options] [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, LaTeX, TeX, troff, or HTML source for typeset documentation. nountangle converts a
literate program into an ordinary program by turning interleaved documentation into comments. The 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, plain TeX, troff or HTML. With plain
TeX, it inserts a reference to a TeX macro package, nwmac, which 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, e.g., hypertext links. If quoted code ends with three or more square
brackets, noweave chooses the rightmost pair, so that, for example, [[a[i]]] is parsed correctly. The
names of code chunks may appear within quoted code unless that quoted code is itself part of the name of
a code chunk.
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. @<<).
Some programming or formatting languages may require a single @ sign in the first column. Noweb users
may achieve this effect by putting a doubled @@ in the first column; in this position only, it stands for
a single @ sign.
TANGLING
notangle and nountangle accept the same set of options, although some options have effects only on one or
the other. The options are:
-Rname Expand the <<name>> code chunk. The -R option can be repeated, in which case each chunk is
written to the output. If no -R option is given, expand the chunk named <<*>>.
-Lformat
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. nountangle ignores this option.
Common format strings include:
C -L'#line %L "%F"%N'
Sun FORTRAN -L'\# %L "%F"%N'
Icon -L'#line %-1L "%F"%N'
Modula-3 -L'<*LINE %L "%F" *>%N'
SML/NJ -L'(*#line %L "%F"*)'
To solve the converse problem, that is, to get noweb to do something sensible with #line in its
input, see the sharpline filter in the examples directory.
-tk Copy tabs untouched from input to output, and use tabs for indentation, assuming stops every k
columns. By default, tabs are expanded to spaces with stops every 8 columns.
-filter cmd
Filter the noweb source through cmd after converting it to tool form and before tangling.
notangle looks for cmd first on the user's PATH, then in /usr/lib/noweb. Such filters can be used
to add features to notangle; for an example see /usr/lib/noweb/emptydefn. For experts only.
-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.
-awk | -c | -icn | -icon | -ml | -m3 | -pascal | -f77 | -f90 | -tex
When nountangle transforms documentation chunks into comments, use the comment format of the
language named. -c is the default. notangle ignores these options.
-wn When nountangle transforms documentation chunks into comments, create comments on lines of width
n. notangle ignores this option.
WEAVING
Output from noweave can be used in TeX documents that \input nwmac, in LaTeX documents that use the
noweb package (see nowebstyle(1)), and in HTML documents to be browsed with Mosaic(1). Noweave treats
code chunks somewhat like LaTeX list environments. If the ``@ '' that terminates a code chunk is
followed immediately by text, that text follows the code chunk without a paragraph break. If the rest of
the line is blank, noweave puts TeX into ``vertical mode,'' and later text starts a fresh, indented
paragraph.
No page breaks occur in the middle of code chunks unless necessary to avoid an overfull vbox. The
documentation chunk immediately preceding a code chunk appears on the same page as that code chunk unless
doing so would violate the previous rule.
Noweave inserts no extra newlines in its TeX output, so the line numbers given in TeX error messages are
the same as those in the input file.
noweave has options that dictate choice of formatter and that support different formatting idioms and
tools. Basic options are described here; options related to index and cross-reference information are
described in the INDEXING AND CROSS-REFERENCE section.
-latex Emit LaTeX, including wrapper in article style with the noweb package and page style. (Default)
-tex Emit plain TeX, including wrapper with nwmac macros.
-html Emit HTML, using HTML wrapper. The output is uninteresting without -index or -x. The tags
<nowebchunks> and <nowebindex>, on lines by themselves, produce a list of chunks and an index of
identifiers, respectively. If these tags are not present, the list and index are placed at the
end of the file.
-latex+html
Assume documentation chunks are LaTeX, but generate HTML for code chunks, suitably marked so
conversion with latex2html(1) yields reasonable output. A LaTeX wrapper is implied, but can be
turned off with -n. Use of this option is deprecated; use -html with -filter l2h instead.
-troff Emit troff(1) markup (with no wrapper). The result should be processed with noroff(1). Bug
reports for -troff to Aharon Robbins <arnold@gnu.org>.
-n Don't use any wrapper (header or trailer). This option is useful when noweave's output will be a
part of a larger document. See also -delay.
-filter cmd
Filters the noweb source through cmd after converting it to tool form and before converting to
TeX. noweave looks for cmd first on the user's PATH, then in /usr/lib/noweb. Such filters can be
used to add features to noweave; for an example, see /usr/lib/noweb/noxref.krom. Noweave supports
up to four filters; one can get more by shell trickery, for example, -filter "icon.filter |
noidx". The -autodefs, -x, -index, and -indexfrom options are implemented as filters. Filters
are executed with the shell's eval command, so cmd should be quoted accordingly.
-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.
-option opt
Adds \noweboptions{opt} to the LaTeX header. See nowebstyle(1) for values of opt. Normally
useful only with the -latex option, but -option longxref works black magic with -html.
-delay By default, noweave puts file-name and other information into the output before the first chunk of
the program. -delay delays that information until after the first documentation chunk, making act
a little bit like the WEB ``limbo.'' The option is typically used to enable a user to put a
specialized LaTeX \documentclass command and other preamble material in the first documentation
chunk (i.e., before the first @ sign). This option also forces trailing cross-referencing
information to be emitted just before the final chunk, instead of at the end of the document; the
final chunk is expected to contain \end{document}. The -delay option implies the -n option.
-tk Expand tabs with stops every k columns. (Default is to expand every 8 columns.)
-t Copy tabs to the output.
-v Print the pipeline and RCS info on standard error.
INDEXING AND CROSS-REFERENCE
When used with LaTeX, troff, or HTML, noweave can provide indexing and cross-reference information for
chunks and for programming-language identifiers. Identifier definitions may be marked by hand using
backticks (`); the -filter btdefn option recognizes these markings. For some languages, defintioins may
be found automatically using the -autodefs option. This section describes the indexing and cross-
reference options; it might well be skipped on first reading.
-x For LaTeX, add a page number to each chunk name identifying the location of that chunk's
definition, and emit cross-reference information relating definitions and uses. For HTML, create
hypertext links between uses and definitions of chunks. When noweave -x is used with LaTeX, the
control sequence \nowebchunks expands to a sorted list of all code chunks.
-index Build cross-reference information (or hypertext links) for defined identifiers. Definitions are
those found in the input files by -autodefs language or by -filterbtdefn. Requires LaTeX or HTML.
-index implies -x; including both will generate strange-looking output. noweave does not generate
cross-references to identifiers that appear in quoted code (@[[...@]]), but it does generate
hypertext links. When noweave -index is used with LaTeX, the control sequence \nowebindex expands
to an index of identifiers.
-indexfrom index
Like -index, but the identifiers to be indexed are taken from file index. See noindex(1).
-autodefs lang
Discover identifier definitions automatically. Code in chunks must be in language lang.
Permissible langs vary but may include tex or icon. Useless without -index, which it must
precede.
-showautodefs
Show values of lang usable with -autodefs.
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.
EXAMPLES
If you have trouble digesting this man page, you're not alone. Here are a few examples to get you
started. I'll assume you have a foo.nw file with a C program in chunk <<foo.c>> and a header file in
chunk <<foo.h>>, and that your documentation is marked up using latex(1). I'll show you how to build
things using the most common options.
To rebuild your C source, try
notangle -L -Rfoo.c foo.nw > foo.c
To rebuild your header file, try
notangle -Rfoo.h foo.nw | cpif foo.h
There are two compromises here. Omitting -L keeps #line out of your header file, and using cpif prevents
the command from rewriting foo.h unless the contents have changed. Thus, this is good code to put in a
Makefile rule.
To build a printed document, run
noweave -autodefs c -index foo.nw > foo.tex
If you have your own preamble, containing \documentclass and all, you will also need the -delay option.
To build a web page, run
noweave -filter l2h -autodefs c -index -html foo.nw | htmltoc > foo.html
Have fun!
FILES
/usr/lib/noweb/markup markup preprocessor
/usr/lib/noweb/unmarkup inverts markup
/usr/lib/noweb/nt notangle proper
/usr/lib/noweb/finduses find uses of identifiers for index
/usr/lib/noweb/noidx generate index and cross-reference info
/usr/lib/noweb/toroff back end to emit troff
/usr/lib/noweb/totex back end to emit TeX or LaTeX
/usr/lib/noweb/tohtml back end to emit HTML
/usr/share/texmf/tex/plain/misc/nwmac.tex formatting TeX macros
/usr/share/texmf/tex/plain/misc/noweb.sty use in LaTeX documents; see nowebstyle(7)
SEE ALSO
cpif(1), nodefs(1), noroots(1), noweb(1), noindex(1), noroff(1), nowebstyle(7), nowebfilters(7)
BUGS
notangle and nountangle fail if names used on the command line contain single quotes.
Ignoring unused chunks can cause problems; if a chunk has multiple definitions and one is misspelled, the
misspelled definition is silently ignored. noroots(1) can be used to catch this mistake.
The -L option of notangle puts an implicit initial newline in the format string.
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.
latex2html(1) mangles some source files.
noweave has too many options, and this man page is too long.
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)