NOWEB(1)                    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..nnwwii_.

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-referenc‐
       ing information; neither nodefs nor noindex is required.

       When a noweb program consists of several source files, it is often bet‐
       ter  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 num‐
              bers 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 identi‐
       fiers defined anywhere in aa, bb, or cc.

              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 unnec‐
       essary rebuilding.

       The  next series of steps is to create LaTeX files with full cross-ref‐
       erence 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.12.

AUTHOR
       Norman   Ramsey,   Tufts   University.   Internet  address  Norman.Ram‐
       sey@tufts.edu.
       Noweb home page at http://www.cs.tufts.edu/~nr/noweb.




                               local 10/40/2008                       NOWEB(1)
