summaryrefslogtreecommitdiff
path: root/indexing/glo+idxtex/idxtex.tex
blob: ee8f8654d87ce3edbc8bb8c83921f6b44375b93d (plain)
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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
\documentstyle[oldlfont,glo_idx]{pamphlet}
\def\IdxTeX{Idx\TeX}
\pagestyle{headings}
\makeindex
\begin{document}
%\coverstyle{userguide}
\title{\IdxTeX\ Program}
\author{R L Aurbach}
\authorfacts{CR\&DS MIS Group \\ Monsanto Company \\ 800 N. Lindbergh Blvd.
\\ St. Louis, MO 63167 \\ (314)--694--5453}
\version{Version 2.0}
\file{IdxTeX}
\date{April 19, 1987}
\begin{thetitle}
\begin{abstract}
The \IdxTeX\ program is used to automate the generation of an Index in a
\LaTeX\ document.  It uses the .IDX file generated by the \verb+\makeindex+
command to create a file which is \verb+\input+ in the document to generate
the Index.
Version 2.0 improves the visual appearance of the Index and adds support
for page ranges, index cross references, and the generation of a Master Index.
\end{abstract}
\end{thetitle}

\makeheading
\section{The Index Problem}

The \LaTeX\ text formatting program is an extremely versatile tool for the
generation of high-quality documents.  However, its handling of an Index is
incomplete.

\subsection{\LaTeX\ Index Processing}

To make an Index using \LaTeX, the writer includes the 
\verb+\makeindex+\index{\verb+\makeindex+ Command} command
in the preamble\index{Preamble} of the document.  This causes an auxiliary 
file (with file type .IDX\index{IDX File}) to be generated.  For every 
\verb+\index+\index{\verb+\index+ Command} command in the document, a
\verb+\indexentry+\index{\verb+\indexentry+ Command} command is written to 
the auxiliary file, containing the text supplied in the \verb+\index+ command
and the page number of the page on which the \verb+\index+ command occurred.

It is then the writer's responsibility to use the auxiliary file to create the
series of commands needed to format an appropriate index and to insert these
commands into the document at the appropriate place.

The entire process is described in Sections~4.5 and C.10.5 of the {\em \LaTeX\ 
User's Guide and Reference Manual}.

\subsection{The \IdxTeX\ Solution}

While this procedure is capable of generating an effective, high-quality Index,
a substantial amount of work is required to convert the auxiliary .IDX file into
the appropriate set of commands.  The \IdxTeX\ program was written to automate
this manual part of the process.

\IdxTeX\ uses the .IDX\index{IDX File} auxiliary file to generate a new file
with file type .IND\index{IND File} which contains all of the necessary commands
to create an attractive, two-column index.  This .IND file may then be included
in the document at the appropriate place to generate the Index.

The \IdxTeX\ program
\begin{itemize}
\item Generates\index{\IdxTeX\ Features>Complete Index Generation}
all of the commands necessary to build the Index, including the
\verb+\begin{theindex}+\index{theindex Environment} and \verb+\end{theindex}+
commands. 
\item Generates\index{\IdxTeX\ Features>Alphabetized, Two-Column Index}
an alphabetized, two-column index.
\item Supports \index{\IdxTeX\ Features>Three Levels of Indexing}
three levels of indexing --- index items, index subitems, and
index subsubitems.
\item Supports \index{\IdxTeX\ Features>Page Number Ranges} special 
formatting of ranges of consecutive page numbers, to enhance the visual
appearance of the Index.
\item Supports \index{\IdxTeX\ Features>Index Item Highlighting}
highlighting effects such as boldface, italics, etc., in the
index items, while maintaining proper alphabetization of entries.
\item Supports \index{\IdxTeX\ Features>Page Number Highlighting}
highlighting effects (boldface, italics, and underlining) of
page numbers.
\item Supports \index{\IdxTeX\ Features>\verb~\verb~ Command Supported}
the use of \LaTeX\ commands, including \verb+\verb+ commands,
in the index items, while maintaining proper alphabetization of entries.
\item Supports \index{\IdxTeX\ Features>Cross References} references within
one index entry to other index entries.
\item Supports \index{\IdxTeX\ Features>Master Index Generation} the generation
of a Master Index for a set of documents.
\end{itemize}

\section{Using \IdxTeX}

The \IdxTeX\ program is easy to use.  However, like B{\sc ib}\TeX, there are a
number of steps necessary to generate the index and to get it included properly
in your document.

\begin{infomap}
\item[Command \\ Definition]  The \IdxTeX\ program is a foreign DCL
command.\footnote{On the Monsanto BB1T VAXcluster, the IdxTeX symbol is defined
by issuing the CRLSETUP command.} \vspace{2em}
\item[Preparing the \\ Document]
Include the \verb+\makeindex+\index{\verb+\makeindex+ Command}
command in the preamble\index{Preamble} area of the document
source file (i.e., between the \verb+\documentstyle+ and \verb+\begin{document}+
commands).  Also, include the appropriate \verb+\index+\index{\verb+\index+
Command} commands (as described below) in the source file.
\item[Generate \\ the IDX File]
Use \LaTeX\ to generate an initial form of the document.  \LaTeX\ will
generate an auxiliary file which has the same filename as the main document file
and a filetype of .IDX\index{IDX File}.
\item[Run \IdxTeX]
Use \IdxTeX\ to generate the formatted index file.\index{Syntax}
\begin{verbatim}
        $ IdxTeX   file  [/TOC={ ARTICLE | REPORT }]
\end{verbatim}
where ``file''\index{Syntax>Filename Parameter} is the filename of the .IDX 
file.  \IdxTeX\ generates a file with the same filename as the .IDX file and a
filetype of .IND\index{IND File}.

The \verb+/TOC+ qualifier\index{Syntax>/TOC Qualifier} is optional.  If you
specify it, you must specify either the value \verb+ARTICLE+ or the value
\verb+REPORT+.  The /TOC qualifier is used to add an entry into the Table of
Contents for the Index.  The standard document styles ({\em article\/} and
{\em report\/}) do not automatically make a Table of Contents entry for the 
Index.  If you want the Index to be listed in the Table of Contents, you 
{\bf must} use the /TOC qualifier.  The value \verb+ARTICLE+ should be used
with documents which use the {\em article\/} document style or one of its 
derivatives.  The value \verb+REPORT+ should be used with documents which use
the {\em report\/} or {\em book\/} document styles.

\begin{note}
A number of document styles have been developed which automatically include
a Table of Contents entry for the Index\footnote{Examples of these styles 
include the Monsanto {\em pamphlet}, {\em manual}, and {\em memo\/} styles.}.
You {\bf should not} use the /TOC qualifier with one of these document styles.
If you do, the Index will be listed in the Table of Contents twice.
\end{note}

\item[Generate\\the Document]
Insert the command \verb+\input{file.IND}+ into
\index{\verb+\input{file.IND}+} your document source file just before the
\verb+\end{document}+ command.

Finally, run the document through \LaTeX\ twice (to make sure that the Table of
Contents includes the page reference for the Index).  Your document is now
complete, including a formatted Index.
\end{infomap}

\section{Special Features}

The \IdxTeX\ program attempts to perform all of the operations needed to
generate an Index which you can be proud of.  Of course, the quality of the
Index is a function of the amount of effort you put into your writing --- the
program can only generate index entries for items you tell it to index for you.
But if you do a good job of generating index entries, \IdxTeX\ should do a good
job formatting them for you.

\begin{infomap}
\item[Index \\ Generation] \index{^\IdxTeX\ Features>Complete Index Generation}
The .IND\index{IND File} file generated by \IdxTeX\ contains all of the commands
necessary to generate the index. 
The file contains a 
\verb+\begin{theindex}+\index{\verb+\begin{theindex}+ Command} command.  This
sets up the Index environment according to your current \verb+\documentstyle+.
For example, in the {\em article\/} \verb+\documentstyle+, the index is an
unnumbered section.  In the {\em report\/} \verb+\documentstyle+, the index is
an unnumbered chapter.

The last line in the file is a \verb+\end{theindex}+\index{\verb+\end{theindex}+
Command} command.  This command ends the Index environment.  Between these lines
are found all of the commands needed to generate the Index.

\item[Alphabetical\\Index] \index{^\IdxTeX\ Features>Alphabetized, Two-Column
Index} The index is generated in an alphabetized, two-column format by major
index entry.  Special characters such as ``\verb+\+'' don't participate in the
alphabetization, so a term like \verb+\begin+ is indexed under ``B'', not
under ``\verb+\+''.

For clarity, the group of index entries which begin with one letter of the
alphabet are set off from the index entries beginning with the next letter of
the alphabet with vertical spacing and a heading.  See the index of this
document for examples. 

\item[Index Levels] \index{^\IdxTeX\ Features>Three Levels of Indexing}
Items are inserted into the Index by using the \verb+\index+ command.  For 
example, to index the term ``entry'', enter \verb+\index{Entry}+\index{Entry}
at the appropriate place in the text of your document.  The information entered
as the argument to \verb+\index+\index{\verb+\index+ Command} will appear as 
specified (special visual effects are discussed below).  The page number on
which the \verb+\index+ command appeared will be displayed. 

This approach generates a simple Index.  That is, all terms are on the same
footing.  It is often convenient, however, to have terms appear as subindices
under an index term.  For example, if you were discussing ``Commands'', you
might wish to have separate index entries for ``Add Command'' and ``Change
Command''.  However, in addition, you should create an index entry for 
``Commands'' and place ``Add'' and ``Change'' as subindices under it.  This 
technique generates an index which is more helpful for the person looking for
information.

\IdxTeX\ actually supports three such levels of indexing --- a main index item,
a subindex item, and a subsubindex item.  In analogy to the indexing 
capabilities of the RUNOFF program, the 
``\verb+>+''\index{SubIndex (\verb$>$) Command}
\index{\verb+\index+ Command>Use of \verb$>$}
symbol is used to separate
the index term from the subindex term and the subindex term from the subsubindex
term in the \verb+\index+ command.  

For example,

\begin{verbatim}
        \index{Top Level Item>SubItem>SubSubItem}
\end{verbatim}

\index{Top Level Item>SubItem>SubSubItem}generates such three-level deep
index entry in the index.  Look at the index of this document to see it.

There are two important points to note here.

\begin{itemize}
\item First, each \verb+\index+ command generates a single page number reference
in the index.  The page number is associated with the lowest level of the index
specified.  Therefore, in this example, the page number is associated with the
``SubSubItem'' entry, not any of the higher entries.  If you want page numbers
at all levels, you must use several \verb+\index+ commands.

All subitems are displayed in alphabetical order below their top-level item.
All subsubitems are displayed in alphabetical order below their second-level
item.

\item Second, the \verb+>+ symbol used to separate items of different levels
is normally a math symbol.  As such, it is possible that you will want to
index a math expression which contains it.  This is okay, because \IdxTeX\
is sensitive to the use of {\tt \$} as a command to enter or leave math mode and
will not consider \verb+>+ a level separator unless it is {\em not\/} in math
mode.

\end{itemize}

While \IdxTeX\ allows you to be pretty wordy in your index terms (there is a
practical limit of about 110 characters for the text contained in an
\verb+\index+ command), your index will be most effective if you select short
and concise index terms.  People usually scan an index quickly, looking for
something that looks like what they are interested in.  A lengthy exposition in
an index term makes this difficult.

\item[Item \\ Highlighting] \index{^\IdxTeX\ Features>Index Item Highlighting}
Sometimes it is desirable to make a word or phrase (or even an entire index
entry) stand out in the Index.  This is referred to as Item Highlighting, and
is an effective technique to make the Index more useful, if not overdone.

Use the normal \LaTeX\ commands to generate the desired highlighting.  For 
example, the following commands appear in this document.

\begin{verbatim}
  \index{Highlighting>A {\bf boldface} entry}
        \index{Highlighting>An {\em italic\/} entry}
\end{verbatim}

\index{Highlighting>A {\bf boldface} entry}\index{Highlighting>An {\em italic\/}
entry} Look for the result in the index!

From the standpoint of \IdxTeX, the item, subitem, and subsubitem are processed
as different text elements.  Therefore, if you wish to highlight more than one
level of the index, you must handle each one independently.  That is,

\verb+\index{{\bf One>Two>Three}}+ \hfill WRONG!

is incorrect, but

\verb+\index{{\bf One}>{\bf Two}>{\bf Three}}+ \hfill CORRECT!
 
will produce the desired result.

\item[Page Number\\Highlighting] \index{^\IdxTeX\ Features>Page Number 
Highlighting}  Sometimes, when you are indexing the same term in many places in
a document, you may wish to help the reader decide which is the primary
reference and which are secondary references.  One way of doing this is to
provide visual highlighting of important page numbers.

\IdxTeX\ provides a mechanism to cause a page number of a reference to be
printed in {\bf boldface}, in {\em italics}, or \underline{underlined}.  There
are three special characters recognized by \IdxTeX\ {\bf when they appear as the
first character of an \verb+\index+ command argument}.

\begin{itemize}

\item The \verb+^+ command\index{\verb+\index+ Command>Use of \verb+^+} is 
used to make the page number reference appear in {\bf boldface}. 
\item The \verb!~! command\index{\verb+\index+ Command>Use of \verb!~!} is 
used to make the page number reference appear in {\em italics}.
\item The {\tt\_} command\index{\verb+\index+ Command>Use of {\tt\_}} is used to
make the page number reference appear \underline{underlined}. 
\end{itemize}

For example, in this document, the following \verb+index+ commands appear.

\begin{verbatim}
        \index{^Page Numbers>boldface}
        \index{~Page Numbers>italics}
        \index{_Page Numbers>underlined}
\end{verbatim}
\index{^Page Numbers>boldface}\index{~Page Numbers>italics}
\index{_Page Numbers>underlined}  Look at the index to see the results!
\begin{note}
These special characters must appear as the first character of an \verb+\index+
command argument.  If they appear after a \verb+>+ (i.e., as the first character
of a subindex entry or a subsubindex entry), they will not work. In fact, they
will cause a \LaTeX\ error!
\end{note}

\item[Special \\ \LaTeX \\ Commands]
\index{^\IdxTeX\ Features>\verb+\verb+ Command Supported}
Occasionally (such as in this document), it is desirable to include \LaTeX\
commands in the index in an index entry to create special effects or because
the command itself is being referenced.  \IdxTeX\ supports this --- just type
the entries as you would expect them to appear.

The trick is that \IdxTeX\ tries to alphabetize your entries correctly.  This
means that it must figure out how to alphabetize \LaTeX\ commands, whose 
displayed images are different than the character strings which generate them.

The following rules attempt to indicate how \IdxTeX\ treats \LaTeX\ commands
when it finds them.

\begin{itemize}
\item Accents are ignored when figuring out how to spell a term.  This means,
for example, that ``\verb+se\~{n}or+'' is treated as if it were spelled 
``\verb+senor+''.

\item Text contained in ``\verb+\verb+'' or ``\verb+\verb*+'' commands are
spelled as if the command were not present.  For example, the index entry
``\verb~\verb+\Pi+~'' is treated as if it were spelled ``\verb+\Pi+''.

\item Commands which affect font size or type style are ignored when figuring
out how something is spelled.  For example, ``\verb+\sc term+'' is treated as if
it were spelled ``\verb+term+''.  Note, however, that this applies only to
spelling. The term will be displayed as you want it.

\item Case is ignored in spelling considerations.  Terms like ``large'' and
``Large'' are treated as identical.  Only one reference (with two page numbers) 
will appear --- the first form seen will be used.

\item \IdxTeX\ ignores the grouping commands ``\{'', ``\}'', and ``\$'' when
placing a term in alphabetical order.  On the other hand, the sequences which 
generate explicit characters (i.e., ``\verb+\{+'', ``\verb+\}+'', and
``\verb+\$+'') are handled as if they were the characters themselves --- the
``\verb+\+'' is ignored for spelling. For example, the term ``\verb+{\bf The \{
Command}+'' will be alphabetized as if it were spelled ``\verb+The { Command+''.

\item All ``\verb+\+'' characters are ignored.  The term ``\verb+\begin+'' will
be located in the Index as if it began with the ``b'', not the ``\verb+\+''. 
\end{itemize}
\end{infomap}

\section{Page Ranges}

\IdxTeX\ supports two types of page ranges\index{#Page Ranges} --- implicit and
explicit.

An implicit page range is one which is discovered during index processing.  For
example, if it turns out that a particular item is indexed on three consecutived
pages, then this is an implicit range. 

An explicit page range is one in which you specifically indicate that an item
being referenced is discussed on a particular page and succeeding pages. 

\subsection{Implicit Page Ranges}

Suppose\index{#Page Ranges>Implicit} that you index the term ``Command'' a
number of times within your document and it turn out (when you use \LaTeX\ to
format it) that the references occur on pages 10, 15, 16, 17, 20, and 21.
\IdxTeX\ will recognize that there are two implicit page ranges here and will
display the reference in the index as
\begin{quote}
\qquad Command, 10, 15--17, 20--21
\end{quote}
This processing occurs automatically --- you need not do anything special to
get it to occur (except, of course, insert the \verb+\index+ commands where
they are needed).

In some document styles, chapter-oriented page numbering is used.  From the
standpoint of \IdxTeX, a chapter oriented page number is any page number which
consists of a string (which is usually numeric) followed by one or more dashes,
followed by a page number.  For example, \verb+2--6+ and \verb+Ref--12+ are
typical chapter oriented page numbers.

Since the \IdxTeX\ program parses and recognizes page numbers in this format
as well as simple numeric page numbers, it is able to correctly build ranges
for chapter oriented documents.  For example, if references to ``Command''
occurred on pages 2--6, 3--7, 3--8, 3--9, and 4--10, then \IdxTeX\ would
build an index entry of the form
\begin{quote}
\qquad Command, 2--6, 3--7 to 3--9, 4--10
\end{quote}

So far, we have considered page numbers which have no visual highlights.  If
one or more of the page number references in a range has a highlight, the range
is broken up into sub-ranges, so that each sub-range has the same visual
highlight.  For example, if references to ``Noise'' occurred on pages 20 through
26, with the references on pages 22 and 23 flagged as underlined and the 
references on pages 24 and 25 flagged as boldface, then \IdxTeX\ would generate
an index entry of the form
\begin{quote}
\qquad Noise, 20--21, \underline{22--23}, {\bf 24--25}, 26
\end{quote}

\subsection{Explicit Page Ranges}

Another form of page range\index{#Page Ranges>Explicit} occurs when a single
reference indicates that a particular topic is covered on a particular page
and following pages.  In this kind of reference, only one index item is
needed --- for the first page referenced.  By convention, the letters {\sf ff}
follow that page reference to mean ``and following''.

To specify this type of reference, use the {\tt \#}
\index{\verb+\index+ Command>Use of \verb+#+} symbol as the first 
character in the index entry (just as if it were a special type of page 
highlight).  For example, the reference \verb+\index{#Page Ranges>Explicit}+
was placed at the beginning of this section.  Look to the index to see the
result.

There are two special features of this notation.
\begin{itemize}
\item Explicit page ranges take precedence over implicit page ranges.  That is,
if an explicit range entry occurs within an implicit range, then the whole
implicit range is condensed into a single explicit reference.  For example,
if the reference to ``Command'' was made on pages 20 through 25 and the 
reference on page 23 was explicit, then the output would have the form
\begin{quote}
\qquad Command, 20{\sf ff}
\end{quote}
rather than.
\begin{quote}
\qquad Command, 20--22, 23{\sf ff}, 24--25
\end{quote}
\item Explicit page ranges take precedence over all page highlighting.  If
\begin{verbatim}
    \index{~Command}\index{#Command}
\end{verbatim}
occurs, for example, then the italic reference is ignored.
\end{itemize}

\section{Cross References}

It\index{#Cross References} is not uncommon in an index to want to reference a
term in a variety of different ways, so that people will be easily able to find
the reference they need.  This is often a lot of work, however, because you
don't normally want to repeat a big list of \verb+\index+ commands for every 
place where a term is referenced.  Instead, a great deal of effort can be saved 
if you can index the term thoroughly once, and then {\em cross reference\/} it
in all its synonyms.

For example, suppose you are describing the syntax of a command.  You index
the various forms of the command under the term ``Syntax''.  However, you also
want to place an alternate entry in the index under ``Command Syntax'' in case
people look there first.  Obviously, you'd rather not repeat all of your
index commands twice to get a complete set of references.  Instead, you'd like
to {\bf refer} the reader who looks up ``Command Syntax'' to try ``Syntax''
for the information.

\IdxTeX\ supports this capability.\index{Command Syntax&Syntax}  The special
symbol ``\verb+&+''\index{\verb+\index+ Command>Use of {\tt \&}} is used too
indicate the beginning of a cross reference, which is used {\bf instead of the
page reference} in the entry.  In our example above, entering 
\verb+\index{Command Syntax&Syntax}+ produces the desired result --- look at the
index. 

You can combine cross references with page references.  For example,
\begin{verbatim} 
    \index{Combining References}
    \index{Combining References&Cross References}
\end{verbatim}
\index{Combining References}\index{Combining References&Cross References} 
contains a page reference and a cross reference, as is shown in the index.

For convenience, the notation \verb+\index{aaa&bbb>ccc>ddd}+ generates a
cross reference to \verb+bbb, ccc, ddd+, so you can use the same syntax in
your cross references as you do in your index terms themselves.  Note that the
text following the ``\verb+&+'' must obey all of the rules associated with
index entries in general.

You can include as many cross references as you like.  For example, the
sequence
\begin{verbatim}
    \index{aaa&bbb} \index{aaa&ccc} \index{aaa&ddd}
\end{verbatim}
is perfectly acceptable. In the index, it generates 
\begin{quote}
\hspace*{10pt}aaa, {\em see}\\
\hspace*{40pt}$\bullet$ bbb\\d
\hspace*{40pt}$\bullet$ ccc\\e
\hspace*{42pt}$\bullet$ dddD
\end{quote}

Also note that a cross-reference entry does not, in itself, contain any 
page number information.  Therefore, the index entries containing cross
referencing may appear anywhere.  For example, you could build a basic index
in your document, then add all the appropriate cross reference entries later,
all in one place in your text.  Note, however, that cross references in index
entries are treated like simple text --- \IdxTeX\ does not check to make sure
that a cross reference entry actually exists.  So be careful when creating them,
to avoid misleading your reader.

\section{Master Index Processing}

A Master Index \index{Master Index}\index{Master Index>Definition}
is a document in a set of documents which contains a complete
index of all terms indexed in {\bf any} of the other volumes of the document
set.  \IdxTeX\ provides support for the automatic generation of a Master
Index.

\begin{infomap}

\item[Prepare the \\ Individual Indices]
The first step is to run all of the other documents in the document set 
through \LaTeX, so that all of the {\tt .IDX} files are generated.  These 
files are used by \IdxTeX\ to format the Master Index.

\item[Build the \\ .MDX File]
\IdxTeX\ must be made aware of which {\tt .IDX} files to use to build the 
Master Index.  In addition, it is important to define a {\em label\/} which 
is associated with each volume in the Master Index, so that the reader can
figure out which volume to look to find the reference.

Both of these requirements are handled by a new auxiliary file called the
{\tt MDX} File.\index{Master Index}\index{Master Index>The {\tt .MDX} File}
The format of this file is quite simple.  For each volume which you wish to
be included in the Master Index, insert a line in the {\tt .MDX} file of the
form
\begin{verbatim}
    \usefile{label}{idx-file}
\end{verbatim}
Here, ``{\em label\/}'' is the label which you wish to be associated with
the volume in the Master Index and ``{\em idx-file\/}'' is the file 
specification of the associated {\tt .IDX} file which contains the relevant
information.

For example, suppose you have a document set containing four documents ---
a User's Guide, a Reference Manual, an Operations Manual, and an Installation
Guide.  You wish to build an Introduction document which contains a Master
Index of the document set.  In this case, you might build an {\tt .MDX} file
named {\tt INTRO.MDX} which contains the following lines
\begin{verbatim}
    \usefile{User}{user_guide}
    \usefile{Ref}{ref_manual}
    \usefile{Operator}{op_manual}
    \usefile{Install}{install}
\end{verbatim}
This example assumes that the {\tt .IDX} file for the User's Guide is 
{\tt USER\_GUIDE.IDX}, etc.  When \IdxTeX\ processes the Master Index, it
uses a default file specification of {\tt SYS\$DISK:[].IDX} with each file
specified in the {\tt .MDX} file.

\item[Run \IdxTeX] \index{Master Index}\index{Master Index>The {\tt .MND} File}
\index{Syntax>/MASTER Qualifier}  Next, process the {\tt .MDX} file with
\IdxTeX.
\begin{verbatim}
    $ IDXTEX intro /MASTER
\end{verbatim}
The /MASTER qualifier indicates that \IdxTeX\ is to prepare a Master Index. 
In this case, the filename parameter\index{Syntax>Filename Parameter} of the
\IdxTeX\ command is the specification of the {\tt .MDX} file.  A default
file specification of {\tt SYS\$DISK:[].MDX} is used.

\IdxTeX\ will read the specified {\tt .MDX} file and will read and process
each of the {\tt .IDX} files specified in it.  It will generate a master
index output file which has the same name as the {\tt .MDX} file, but with
the {\tt .MND} filetype.  In this example, \IdxTeX\ will generate the file
{\tt INTRO.MND}.

\item[Build the \\ Master Index] \index{Master Index} 
\index{Master Index>Generation} The final step in building the Master Index is
to include a \verb+\input+ command to incorporate the {\tt .MND} file into the
final volume and to run \LaTeX\ on it, just as in the normal index case.

In our example, include the command
\begin{verbatim}
    \input{intro.mnd} 
\end{verbatim}
in the file {\tt INTRO.TEX} and process this file using \LaTeX\ as usual. 
\end{infomap}

The result will be a Master Index, which contains all of the index information
contained in the volume set, formatted so that users will easily be able to
find it.  In particular, if a term is referenced in more than one volume of 
the volume set, its references for each volume are clearly separated from each
other to make it clearer which volumes are associated with which page 
references.

In short, \IdxTeX\ now makes it as easy to generate an attractive Master Index
to a set of documents as it does to generate an Index to each volume of the
set.

\input{idxtex.ind}

\tableofcontents

\end{document}