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
172
173
174
175
176
177
178
179
180
181
182
183
|
TeXIDX - TeX/LaTeX Index Filter
[07-Jan-88]
TeXIDX (TeXINDEX on Unix systems) is a filter for converting the
index file output of TeX and LaTeX to a form suitable for later
input and generation of an index, with entries sorted by primary
text entries, and within these, sorted by secondary text entries,
and with duplicate page numbers eliminated. Elision of page
ranges is not yet supported.
TeXIDX expects one or more files of index entries output by TeX
or LaTeX in the forms
\entry{sort key}{page number}{primary entry}
\entry{sort key}{page number}{primary entry}{secondary entry}
Several examples are given below.
TeXIDX is run by
@TeXIDX file1 file2 ... filen
and produces output files with the same name, but the letter `s'
appended. Thus `foo.idx' is transformed to `foo.idxs'.
The output of TeXIDX will contain lines like:
\initial {c} % before the first topic whose
% initial is c
\entry {topic}{pagelist} % for a topic that is used
% without subtopics
\primary {topic} % for the beginning of a topic
% that is used with subtopics
\secondary {subtopic}{pagelist} % for each subtopic.
All sorting is by the sort key field ONLY, with letter case
IGNORED. This means that if two primary/secondary fields have
the same leading text, a sort key must be given which includes
both the primary and secondary fields to preserve the correct
order, and this key must be distinguishable from another which
just happens to have a primary string equal to the concatenated
primary and secondary strings of the first. For example,
\entry{text editing}{18}{text editing}
\entry{text}{20}{text}
\entry{text<TAB>editing}{32}{text}{editing}
\entry{text<TAB>buffering}{57}{text}{buffering}
will produce correct index entries
text, 20
buffering, 57
editing, 32
text editing, 37
whereas simple juxtaposition of the primary and secondary fields
in the sort keys
\entry{text editing}{18}{text editing}
\entry{text}{20}{text}
\entry{text editing}{32}{text}{editing}
\entry{text buffering}{57}{text}{buffering}
will produce INCORRECT ordering:
text, 20
buffering, 57
text editing, 18
editing, 32
Any ASCII character which collates below space (dec. 32) will do
as a separator between the primary and secondary fields in the
sort key, but the only one that TeX will accept as input without
modification of character \catcode's is <TAB> (dec. 9).
Therefore, make sure that <TAB> characters are not used in the
primary or secondary text values themselves.
In order for TeXIDX to be used, you must first provide TeX/LaTeX
with definitions of macros that create the output index file;
neither the TeX manmac macros (p. 423ff of the TeXbook) or the
LaTeX \index{} macros (p. 78, p. 189 of the LaTeX User's Guide
and Reference Manual) are suitable. Once TeXIDX has been run,
you must have definitions of \initial, \entry, \primary, and
\secondary so that the index file can be processed.
Since these definitions only have to be done once, they have been
put in a LaTeX style file which can be automatically included in
the documentstyle option list:
\documentstyle[gnuindex]{...}
This will cause the file texinputs:gnuindex.sty to be read by
LaTeX at startup. This file defines \initial, \entry, \primary,
and \secondary, so that LaTeX can format your index, and provides
you with two macros to use to generate index entries.
\INDEX{sortkey}{primary}
\SUBINDEX{sortkey}{primary}{secondary}
For \SUBINDEX{}, the {secondary} field is automatically appended
to the sort key, but separated from it by an ASCII <TAB>
character; in most cases, this makes it possible to use the just
primary field as the sort key too, as long as the primary and
secondary fields do not have special characters, font changes, or
TeX control sequences embedded in them.
To save some typing, and reduce the chances of error, you will
probably want to produce your own macros which reference these.
Here are two useful ones:
\newcommand{\X}[1]{{#1}\INDEX{#1}{#1}}
\newcommand{\XX}[2]{{#1}\SUBINDEX{#1}{#1}{#2}}
You can then type
\X{gnats and gnus}
to get the phrase `gnats and gnus' into the document text, as
well as into the index both as a sort key, and as a primary
field. Typing
This chapter will discuss the cooking of
\XX{gnats and gnus}{cooking directions} ...
will put the same phrase `gnats and gnus' into the document text,
but the index will get the sort key `gnats and gnus<TAB>cooking
directions', a primary field `gnats and gnus', and a secondary
field `cooking directions'. You would use \XX{} instead of \X{}
when you wanted to make the index entry more precise, but only
have the primary string in the running text.
For those occasions when you need special fonts, or TeX control
sequences, in your index, you can still use \INDEX{} and
\SUBINDEX{} directly:
\INDEX{LaTeX's gnus}{\string\LaTeX{}'s gnus}
\INDEX{gnats}{\string\sc GNATS}
Note the use of `\string' in front of each control sequence--it
prevents the expansion of the following control sequence. That
way, your index file will contain the words `\LaTeX' and `\sc',
instead of the messy expansions of these.
In summary, then, here is what your `foo.ltx' file might look like:
\documentstyle[gnuindex]{...}
\makeindex
\begin{document}
...
\begin{theindex}
\input{foo.idxs} % Change this to whatever your file is called
\end{theindex}
\end{document}
To process it, you need to run LaTeX twice and TeXIDX once:
@LaTeX foo.ltx
@TeXIDX foo.idx
@LaTeX foo.ltx
TeXIDX was written by Richard Stallman as part of the GNU Project
at the Free Software Foundation in Cambridge, MA, and is in the
public domain (though subject to a liberal copyright contained in
the source file). It uses no proprietary software and should be
implementable with most C compilers on micros, minis, and
mainframes. In particular, all sorting is done with its own
code, rather than relying on system or library sorting routines.
The sorting is done in-core when possible, and otherwise,
automatically spills to scratch files which are individually
sorted, then merged.
Nelson H.F. Beebe
Center for Scientific Computing
South Physics Building
University of Utah
Salt Lake City, UT 84112
Tel: (801) 581-5254
Net mail:
BEEBE@SCIENCE.UTAH.EDU {preferred}
BEEBE@CS.UTAH.EDU
BEEBE@CTRSCI.UTAH.EDU
BEEBEN@RUAC.UTAH.EDU
|
