[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Axiom-developer] [noweb] (new)
|
From: |
Bill Page |
|
Subject: |
[Axiom-developer] [noweb] (new) |
|
Date: |
Tue, 18 Oct 2005 21:22:03 -0500 |
Changes http://wiki.axiom-developer.org/Noweb/diff
--
<H2>NAME</H2><PRE>
notangle, noweave, nountangle - noweb, a literate-
programming tool
</PRE>
<H2>SYNOPSIS</H2><PRE>
notangle [-Rrootname ...] [-filter command] [-L[format]]
[file] ...
nountangle [-ml|-m3|-c|-c++|-awk|-tex|-f77|-f90] [-Rrootname
...] [-filter command] [-wwidth] [file] ...
noweave [options] [file] ...
</PRE>
<H2>DESCRIPTION</H2><PRE>
<U>Noweb</U> is a literate-programming tool like Knuth's <U>WEB</U>, only
simpler. A <U>noweb</U> file contains program source code inter-
leaved with documentation. When <U>notangle</U> is given a <U>noweb</U>
file, it writes the program on standard output. When
<U>noweave</U> is given a <U>noweb</U> file, it reads the <U>noweb</U>
source and
produces, on standard output, <U>LaTeX</U>, <U>TeX</U>, or <U>HTML</U>
source for
typeset documentation. <U>nountangle</U> converts a literate pro-
gram into an ordinary program by turning interleaved docu-
mentation into comments. The file name `-' refers to stan-
dard input.
</PRE>
<H2>FORMAT OF NOWEB FILES</H2><PRE>
A <U>noweb</U> file is a sequence of <U>chunks</U>, 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
<<<U>chunk</U> <U>name</U>>>=
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 <U>notan-</U>
<U>gle</U> and copied verbatim to standard output by <U>noweave</U>
(except for quoted code). <U>noweave</U> can work with <U>LaTeX</U>,
plain <U>TeX</U>, or <U>HTML</U>. With plain <U>TeX</U>, it inserts a
reference
to a <U>TeX</U> macro package, <U>nwmac</U>, 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; <U>notangle</U> concatenates their definitions to produce a
single chunk, just as does <B>tangle</A></B>. Code chunk definitions
are like macro definitions; <U>notangle</U> 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.
<U>notangle</U>'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 <U>notangle</U>, but they may be
used by <U>noweave</U> to give the code special typographic treat-
ment, e.g., hypertext links. If quoted code ends with three
or more square brackets, <U>noweave</U> choose 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.
If double left and right angle brackets are not paired, they
are treated as literal << and >>. Users can force any such
brackets, even paired brackets, to be treated as literal by
using a preceding at sign (e.g. @<<).
Some programming or formatting languages may require a sin-
gle @ 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.
Any line beginning with `@ ' terminates a code chunk, but if
the line has the form
@ %def <U>identifiers</U>
it is taken to mean that the preceding chunk defines the
identifiers listed in <U>identifiers</U>. This list contains iden-
tifiers separated by whitespace; any sequence of nonwhite
characters may be an identifier. <U>noweb</U> uses a simple
heuristic to avoid recognizing identifiers that are sub-
strings of other identifiers.
</PRE>
<H2>TANGLING</H2><PRE>
<U>notangle</U> and <U>nountangle</U> accept the same set of options,
although some options have effects only on one or the other.
The options are:
-R<U>name</U>
Expand the <<<U>name</U>>> 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 <<*>>.
-L<U>format</U>
Emit line number indications at chunk boundaries. A
line number indication identifies the source of the
line that follows it. In <U>format</U>, %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 <U>format</U> is
omitted, the default format is that accepted by the C
preprocessor: `#line %L "%F"%N'. When using the
-L<U>format</U> option, <U>notangle</U> ensures that all text appears
in the same column in input and output. <U>nountangle</U>
ignores this option.
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.
-t<U>k</U> Copy tabs untouched from input to output, and use tabs
for indentation, assuming stops every <U>k</U> columns. By
default, tabs are expanded to spaces with stops every 8
columns.
-filter <U>cmd</U>
Filter the <U>noweb</U> source through <U>cmd</U> after converting it
to tool form and before tangling. <U>notangle</U> looks for
<U>cmd</U> first on the user's PATH, then in
/usr/cs/contrib/lib/noweb. Such filters can be used to
add features to <U>notangle</U>; for an example see
/usr/cs/contrib/lib/noweb/emptydefn. For experts only.
-markup <U>parser</U>
Use <U>parser</U> to parse the input file. Enables use of
noweb tools on files in other formats; for example, the
numarkup parser understands <B>nuweb</B> format. See
<B>nowebfilters</B> for more information. For experts
only.
-tex | -awk | -c | -icn | -icon | -ml | -m3 | -pascal | -f77 | -f90
When <U>nountangle</U> transforms documentation chunks into
comments, use the comment format of the language named.
-c is the default. <U>notangle</U> ignores these options.
-w<U>n</U> When <U>nountangle</U> transforms documentation chunks into
comments, create comments on lines of width <U>n</U>. <U>notan-</U>
<U>gle</U> ignores this option.
</PRE>
<H2>WEAVING</H2><PRE>
Output from <U>noweave</U> can be used in <U>TeX</U> documents that \input
nwmac, in <U>LaTeX</U> documents that use the noweb package (see
<B>nowebstyle</B>), and in <U>HTML</U> documents to be browsed with
<B>Mosaic</A></B>. <U>Noweave</U> treats code chunks somewhat like
<U>LaTeX</U>
<U>list</U> <U>environments</U>. 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, <U>noweave</U> puts <U>TeX</U> 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.
<U>Noweave</U> inserts no extra newlines in its <U>TeX</U> output, so the
line numbers given in <U>TeX</U> error messages are the same as
those in the input file.
<U>noweave</U> 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 unin-
teresting without -index or -x. The tags <nowebchunks>
and <nowebindex>, on lines by themselves, produce a
list of chunks and an index of identifiers, respec-
tively. 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 <B>latex2html</B> yields reasonable output. A LaTeX
wrapper is implied, but can be turned off with -n. <U>Use</U>
<U>of</U> <U>this</U> <U>option</U> <U>is</U> deprecated; use -html
with - filter
l2h instead.
-troff
Emit <B>troff</B> markup (with no wrapper). The result
should be processed with <B>noroff</B>. Bug reports for -
troff to Phil Bewig <address@hidden>.
-n Don't use any wrapper (header or trailer). This
option is useful when <U>noweave</U>'s output will be a part
of a larger document. See also -delay.
-filter <U>cmd</U>
Filters the <U>noweb</U> source through <U>cmd</U> after converting
it to tool form and before converting to <U>TeX</U>. <U>noweave</U>
looks for <U>cmd</U> first on the user's PATH, then in
/usr/cs/contrib/lib/noweb. Such filters can be used to
add features to <U>noweave</U>; for an example, see
/usr/cs/contrib/lib/noweb/noxref.krom. <U>Noweave</U> supports
up to four filters; one can get more by shell trickery,
for example, -filter "icon.filter | noidx". The -auto-
defs, -x, -index, and -indexfrom options are imple-
mented as filters. Filters are executed with the
shell's eval command, so <U>cmd</U> should be quoted accord-
ingly.
-markup <U>parser</U>
Use <U>parser</U> to parse the input file. Enables use of
noweb tools on files in other formats; for example, the
numarkup parser understands <B>nuweb</B> format. See
<B>nowebfilters</B> for more information. For experts
only.
-option <U>opt</U>
Adds \noweboptions{<U>opt</U>} to the <U>LaTeX</U> header. See
<B>nowebstyle</B> for values of <U>opt</U>. Normally useful only
with the -latex option, but - option longxref works
black magic with -html.
-delay
By default, <U>noweave</U> puts file-name and other informa-
tion into the output before the first chunk of the pro-
gram. -delay delays that information until after the
first documentation chunk, making act a little bit like
the <U>WEB</U> ``limbo.'' The option is typically used to
enable a user to put a specialized <U>LaTeX</U> \documentclass
command and other preamble material in the first docu-
mentation chunk. 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.
-t<U>k</U> Expand tabs with stops every <U>k</U> columns. (Default is
to expand every 8 columns.)
-t Copy tabs to the output.
-v Print the pipeline and RCS info on standard error.
</PRE>
<H2>INDEXING AND CROSS-REFERENCE</H2><PRE>
When used with <U>LaTeX</U> or <U>HTML</U>, <U>noweave</U> can provide
indexing
and cross-reference information for chunks and for
programming-language identifiers. Identifier definitions
may be marked by hand using @ %def, or for some languages
they 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 <U>LaTeX</U>, add a page number to each chunk name iden-
tifying the location of that chunk's definition, and
emit cross-reference information relating definitions
and uses. For <U>HTML</U>, create hypertext links between
uses and definitions of chunks. When noweave -x is
used with <U>LaTeX</U>, the control sequence \nowebchunks
expands to a sorted list of all code chunks.
-index
Build cross-reference information (or hypertext links)
for identifiers defined by
@ %def <U>identifiers</U>
Definitions are those found in input files. Requires
<U>LaTeX</U> or <U>HTML</U>. -index implies -x; including both will
generate strange-looking output. <U>noweave</U> does not gen-
erate cross-references to identifiers that appear in
quoted code (@address@hidden), but it does generate hypertext
links. When noweave -index is used with <U>LaTeX</U>, the
control sequence \nowebindex expands to an index of
identifiers.
-indexfrom <U>index</U>
Like -index, but the identifiers to be indexed are
taken from file <U>index</U>. See <B>noindex</B>.
-autodefs <U>lang</U>
Discover identifier definitions automatically. Code in
chunks must be in language <U>lang</U>. Permissible <U>lang</U>s
vary but may include tex or icon. Useless without -
index, which it must precede.
-showautodefs
Show values of <U>lang</U> usable with -autodefs.
</PRE>
<H2>ERROR MESSAGES</H2><PRE>
If <U>notangle</U> or <U>noweave</U> encounters a chunk name within docu-
mentation, 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.
</PRE>
<H2>EXAMPLES</H2><PRE>
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. 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!
</PRE>
<H2>FILES</H2><PRE>
/usr/cs/contrib/lib/noweb/markup markup
preprocessor
/usr/cs/contrib/lib/noweb/unmarkup inverts
markup
/usr/cs/contrib/lib/noweb/nt notangle
proper
/usr/cs/contrib/lib/noweb/finduses find uses
of identifiers for index
/usr/cs/contrib/lib/noweb/noidx generate
index and cross-reference info
/usr/cs/contrib/lib/noweb/totex back end to
emit <U>TeX</U> or <U>LaTeX</U>
/usr/cs/contrib/lib/noweb/tohtml back end to
emit HTML
/usr/cs/contrib/share/texmf/tex/latex2e/contrib/nwmac.tex formatting
<U>TeX</U> macros
/usr/cs/contrib/share/texmf/tex/latex2e/contrib/noweb.sty use in
<U>LaTeX</U> documents; see <B>nowebstyle</B>
</PRE>
<H2>BUGS</H2><PRE>
<U>notangle</U> and <U>nountangle</U> 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. <B>noroots</B> can be used to
catch this mistake.
<U>noweb</U> requires the new version of <U>awk</U>, assumed to be called
<U>nawk</U>. DEC <U>nawk</U> has a bug in that that causes noweave to fail
to translate braces correctly. GNU <U>gawk</U> is reported to
work.
DEC <U>sh</U> has a bug that causes the - filter option to fail
whenever the filter command contains more than one word.
The default <U>LaTeX</U> pagestyles don't set the width of the
boxes containing headers and footers. Since <U>noweb</U> code
paragraphs are extra wide, this <U>LaTeX</U> bug sometimes results
in extra-wide headers and footers. The remedy is to rede-
fine the relevant address@hidden commands; address@hidden in noweb.sty
can
be used as an example.
<B>latex2html</B> mangles some source files.
<U>noweave</U> has too many options, and this man page is too long.
</PRE>
<H2>VERSION</H2><PRE>
This man page is from <U>noweb</U> version 2.8a.
</PRE>
<H2>AUTHOR</H2><PRE>
Norman Ramsey, University of Virginia. Internet address
address@hidden
Noweb home page at <a href="http://www.cs.virginia.edu/~nr/noweb";>
http://www.cs.virginia.edu/~nr/noweb</a>.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html";>man2html</a>
</ADDRESS>
--
forwarded from http://wiki.axiom-developer.org/address@hidden
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Axiom-developer] [noweb] (new),
Bill Page <=