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)