DragonFly On-Line Manual Pages

Search: Section:  

NOWEB(1)               DragonFly General Commands Manual              NOWEB(1)


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.

                                local 3/28/2001                       NOWEB(1)

Search: Section: