notangle
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] ...
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
R 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.
<<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
R 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
R 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
R PATH ,
then in
R /usr/lib/noweb .
Such filters
can be used to add features to
R notangle ;
for an example see
R /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
R nuweb (1)
format.
See
R 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
R troff (1)
markup (with no wrapper).
The result should be processed with
R 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,
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
R nuweb (1)
format.
See
R 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
\\nd{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
R LaTeX ,
R 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
R -filter btdefn.
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
R <<foo.h>> ,
and that your documentation is marked up using
R 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
R cpif (1),
R nodefs (1),
R noroots (1),
R noweb (1),
R noindex (1),
R noroff (1),
R nowebstyle (7),
R 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.
R noroots (1)
can be used to catch this mistake.
\".PP
\".I noweb
\"requires the new version of
\".IR awk .
\"DEC
\".I nawk
\"has a bug in that that causes
\".B noweave
\"to fail to translate braces correctly.
\"GNU
\".I gawk
\"is reported to work.
\".PP
\"DEC
\".I sh
\"has a bug that causes the
\".B -filter
\"option to fail whenever the filter command contains more than one word.
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.
R 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.
Noweb home page at http://www.eecs.harvard.edu/~nr/noweb.
ČLÁNKY DO MAILU