1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
.TH NOWEB 1 "local 10/40/2008"
.SH NAME
noindex \- build external index for noweb document
.SH SYNOPSIS
.B noindex \fIbasename\fP\fR[\fP.tex\fR]
.SH DESCRIPTION
.I noindex
looks through
.I LaTeX
.B .aux
files for identifiers that should go in a
.I noweb
external index.
It sorts all identifiers and writes the results on
.I basename\fB.nwi\fP.
.SH NOWEB INDEXING STRATEGIES
A
.I noweb
program consists of one or more files.
In the simple case, these files are run through
.I noweave
together, to produce a single
.I LaTeX
file.
.I "noweave \-index"
suffices to produce an index and cross-referencing information;
neither
.I nodefs
nor
.I noindex
is required.
.PP
When a
.I noweb
program
consists of several source files, it is often better to run each source file
through
.I noweave
to produce its own
.I LaTeX
file, then use
.I noindex
to produce an external index.
This technique has several advantages:
.IP
The line numbers in the
.I LaTeX
files correspond to the line numbers in the source files, so it is easier
to diagnose
.I LaTeX
errors.
.IP
The
.I LaTeX
.B "\\\\includeonly"
feature can be used, making it possible to format parts of large programs while retaining
complete cross-reference information.
.IP
When used with
.IR make (1),
the technique
avoids running
.I noweave
over source files that have not changed.
.IP
Using the external index places fewer demands on \fILaTeX\fP's memory,
making it read its
.B .aux
files much more quickly.
.PP
The disadvantages are that
.I nodefs
and
.I noindex
are needed for full cross-referencing and a properly sorted index.
.SH EXAMPLE
This example assumes a
.I noweb
program of three source files:
.B a.nw ,
.B b.nw ,
and
.BR c.nw .
The file
.B doc.tex
is assumed to contain
.I LaTeX
boilerplate, including the commands
.IP
\\noweboptions{externalindex}
.nf
\\include{a}
\\include{b}
\\include{c}
.fi
.PP
The first sequence of steps is to create a file listing all the
identifiers defined anywhere in
.BR a ,
.BR b ,
or
.BR c .
.IP
nodefs a.nw > a.defs
.nf
nodefs b.nw > b.defs
nodefs c.nw > c.defs
sort \-u a.defs b.defs c.defs | cpif all.defs
.fi
.PP
Using
.I "sort \-u"
and
.IR cpif (1)
avoids changing
.B all.defs
unless the set of identifiers changes.
This technique, used in a Makefile, avoids unnecessary rebuilding.
.PP
The next series of steps is to create
.I LaTeX
files with full cross-reference information for all identifiers.
.IP
noweave \-n \-indexfrom all.defs a.nw > a.tex
.nf
noweave \-n \-indexfrom all.defs b.nw > b.tex
noweave \-n \-indexfrom all.defs c.nw > c.tex
.fi
.PP
The final steps run
.I LaTeX
once to create
.B .aux
files, then
.I noindex
to create the index,
then
.I LaTeX
again to format the complete document.
.IP
latex doc
.nf
noindex doc
latex doc
.fi
.PP
In a Makefile,
.I noindex
can be run before every invocation of
.I LaTeX.
.SH BUGS
.I noindex
is distributed in awk and Icon versions.
The awk version is slow and does a poorer job sorting.
.PP
There is no comparable machinery to make it possible to use multiple files
with the HTML back end.
.SH SEE ALSO
.IR noweave (1),
.IR nodefs (1),
.IR cpif (1)
.SH VERSION
This man page is from
.I noweb
version 2.12.
.SH AUTHOR
Norman Ramsey, Tufts University.
Internet address \fBNorman.Ramsey@tufts.edu\fP.
.br
Noweb home page at \fBhttp://www.cs.tufts.edu/~nr/noweb\fP.
|
