NAME¶
noindex - build external index for noweb document
SYNOPSIS¶
noindex basename[.tex]
DESCRIPTION¶
noindex looks through
LaTeX .aux files for identifiers that
should go in a
noweb external index. It sorts all identifiers and
writes the results on
basename.nwi.
NOWEB INDEXING STRATEGIES¶
A
noweb program consists of one or more files. In the simple case, these
files are run through
noweave together, to produce a single
LaTeX file.
noweave -index suffices to produce an index and
cross-referencing information; neither
nodefs nor
noindex is
required.
When a
noweb program consists of several source files, it is often better
to run each source file through
noweave to produce its own
LaTeX
file, then use
noindex to produce an external index. This technique has
several advantages:
- The line numbers in the LaTeX files correspond to
the line numbers in the source files, so it is easier to diagnose
LaTeX errors.
- The LaTeX \includeonly feature can be used,
making it possible to format parts of large programs while retaining
complete cross-reference information.
- When used with make(1), the technique avoids running
noweave over source files that have not changed.
- Using the external index places fewer demands on
LaTeX's memory, making it read its .aux files much more
quickly.
The disadvantages are that
nodefs and
noindex are needed for full
cross-referencing and a properly sorted index.
EXAMPLE¶
This example assumes a
noweb program of three source files:
a.nw ,
b.nw , and
c.nw. The file
doc.tex is assumed to contain
LaTeX boilerplate, including the commands
- \noweboptions{externalindex}
\include{a}
\include{b}
\include{c}
The first sequence of steps is to create a file listing all the identifiers
defined anywhere in
a,
b, or
c.
- nodefs a.nw > a.defs
nodefs b.nw > b.defs
nodefs c.nw > c.defs
sort -u a.defs b.defs c.defs | cpif all.defs
Using
sort -u and
cpif(1) avoids changing
all.defs unless
the set of identifiers changes. This technique, used in a Makefile, avoids
unnecessary rebuilding.
The next series of steps is to create
LaTeX files with full
cross-reference information for all identifiers.
- noweave -n -indexfrom all.defs a.nw > a.tex
noweave -n -indexfrom all.defs b.nw > b.tex
noweave -n -indexfrom all.defs c.nw > c.tex
The final steps run
LaTeX once to create
.aux files, then
noindex to create the index, then
LaTeX again to format the
complete document.
- latex doc
noindex doc
latex doc
In a Makefile,
noindex can be run before every invocation of
LaTeX.
BUGS¶
noindex is distributed in awk and Icon versions. The awk version is slow
and does a poorer job sorting.
There is no comparable machinery to make it possible to use multiple files with
the HTML back end.
SEE ALSO¶
noweave(1),
nodefs(1),
cpif(1)
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.
