A new implementation of L^{A}TEX’s indexing commands^{∗}

David M. Jones

1995/09/28

1 Introduction

This style file reimplements L^{A}TEX’s indexing macros to provide better and more robust support for indexes. In particular, it provides the following features:^{1}

1. Support for multiple indexes.

2. Indexing of items by counters other than the page number.

3. A ∗-variant of the \index command that, in addition to putting it’s argument in the index, also typesets it in the running text.

4. The showidx style option has been merged into this file. The command \proofmodetrue can be used to enable the printing of index entries in the margin of pages. The size and style of font can be controlled with the

\indexproofstyle command.

5. A two-stage process, similar to that used to create tables of contents, for creating the raw index files. This means that when processing a portion of a document using the \includeonly command, the index entries from the rest of the document are not lost.

6. A more robust \index command. In particular, it no longer depends on \catcode changes to work properly, so the new \index command can be used in places that the original couldn’t, such as inside the arguments of other macros.

2 Creating an index with L^{A}TEX

Conceptually, there are four stages to creating an index. First, L^{A}TEX must be informed of your intention to include an index in your document. Second, you must add appropriate markup commands to your document to tell L^{A}TEX what to put in the index. Third, after L^{A}TEX has been run on your document, the raw index information must be processed and turned into a form that L^{A}TEX can process to typeset the index. Finally, the finished index must be inserted at the appropriate point in your document.

∗This file has version number v4.1beta, last revised 1995/09/28, documentation dated 7 March 1994. The definitive version of this file is at ftp://theory.lcs.mit.edu/pub/tex/index/.

1Earlier versions of this package provided a “shortindexing” feature (see below for description).

This feature is now deprecated and will be removed in a future release of this package.

In L^{A}TEX, these steps are accomplished with the commands \makeindex, \index, \printindex, and (typically) with the auxiliary program MakeIndex. For example, assuming that your main file is called foo.tex, \makeindex opens the file foo.idx and initializes it for holding the raw index entries, and \index is used to add raw index entries into foo.idx. Then the raw index file is processed by MakeIndex, which puts the finished index in foo.ind. Finally, the \printindex command is used in your L^{A}TEX document to indicate where the file foo.idx should be inserted, i.e., where the index should appear in your document.

   The index package modifies the \makeindex, \index, and \printindex com-

mands, as described below.

3 The user interface

There are four pieces of information associated with each index:

1. A short, unique tag that identifies the index.

2. The extension of the output file where the raw index information will be put by L^{A}TEX.

3. The extension of the input file where the processed information created by MakeIndex will be stored to be read in later by L^{A}TEX.

4. The title of the index.

\newindex Correspondingly, the \newindex command has four required arguments. For example, to declare an author index, you might use the following:

    \newindex{aut}{adx}{and}{Name Index}

Here, aut is the tag used to identify the author index, and “Name Index” is the title of the index. If the name of your main file is root.tex, then L^{A}TEX will write the raw index entries to the file root.adx, and you will execute the following MakeIndex command to process the author index:

    makeindex -o root.and root.adx

By default, the \index tags its argument with the page number (i.e., the value of \thepage), but occasionaly you may want to index items according to a different counter. For example, you may want an index that contains figure numbers instead of page numbers. To accomodate, this, the \newindex command takes an optional argument, which is the name of the command that generates the number that should be included in the index. For instance, to include the number of a figure, you might say

    \newindex[thefigure]{fig}{fdx}{fnd}{Figures}

However, this introduces a new technicality: When creating an index with page numbers, the choice of which page number is to be written to the aux file should be deferred until the page containing the entry is shipped out to the dvi file, otherwise the wrong number will sometimes be chosen. However, when using counters other than the page counter, one normally wants the opposite behaviour: the number written to the aux file should be chosen immediately, otherwise every item on a given page will be tagged with the number of the last item on that page. So, when a counter is specified using the optional argument of \newindex, it is assumed that the counter should be evaluated immediately. If for some reason you need the choice to be deferred until the page is written to the dvi file, you can force this behaviour by putting a ∗ after the optional argument:

    \newindex[thefigure]*{fig}{fdx}{fnd}{Figures}

(One consequence of this scheme is that if, for some reason, you need the choice of page number to be made immediately instead of being deferred until a page is shipped out to the dvi file, you can acomplish this by beginning your index declaration with

    \newindex[thepage]*

\renewindex The \renewindex command takes the same arguments as the \newindex com-

mand and can be used to redefine indexes that have been previously declared.

\makeindex For backwards compatibility, the \makeindex command is redefined to use \newindex. It is essentially equivalent to

    \newindex{default}{idx}{ind}{Index}

The index labeled default is special: it is the one that will be used by \index and \printindex unless another index is specified (see below).

\printindex The \printindex command is modified by the addition of an optional argu-

ment, which is the tag of the index that should be printed. \index The \index command is modified in two ways. First, there is a ∗-variant of the

command that, in addition to putting its argument into an index, also typesets it on the page. Second, \index now takes an optional argument to indicate which index the new entry should be added to. If given, the optional argument should be the identifying tag of a previously-defined index. If no such tag is supplied, the default index (such as that opened by \makeindex above) is used.

\shortindexingon Perhaps the most dubious feature of index.sty is that it allows you to define \shortindexingoff the characters ^and _to be abbreviations for \index* and \index outside of math

mode. These abbreviations are enabled by the \shortindexingon command and disabled by the \shortindexingoff command. The scope of both of these latter commands is local to the current group. (This might be useful, for example, if you wanted the abbreviations turned on throughout most of the documentation,

shortindexingon but turned off in one particular environment.) In addition, shortindexingon can be used as an environment if that seems appropriate. Warning: This feature is deprecated and will disappear in a future release of this package.

\proofmodetrue As mentioned above, the showidx document-style option has been merged

\proofmodefalse
\indexproofstyle

into index.sty. It can be turned on with \proofmodetrue and turned off with \proofmodefalse. When it is turned on, all index entries^{2} will be put in the margin of the page where they appear. By default, they appear in the typewriter font at \footnotesize, but the user can override this with the \indexproofstyle command; for example,

    \indexproofstyle{\footnotesize\it}

2Well, most, at least. There are some circumstances under which the index entries won’t show up in the proofs, although they will show up in the index.

will cause them to be put in italics instead.

\disableindex There are some circumstances where it might be helpful to suppress the writing of a particular index. The \disableindex command is provided for this purpose. It takes one argument, a comma-separated list of tags of the indexes that should be disabled. This command should come before the declarations for the indexes that are being disabled^{3}. One situation where the \disableindex command might be useful is if there are so many indexes that you are exhausting TEX’s supply of output streams^{4}. For example, suppose you have 10 indexes, but only 5 output streams available for indexes. Then you could add a \disableindex command to the top of your file to suppress the writing of all but 5 of the indexes. (Note that the index entries would still get written to the aux file; they just wouldn’t get copied to the individual raw index files at the end of the run.) At the end of the run, you could then re-run your main file a couple of times with different indexes disabled until you had created all of the raw index files. This is somewhat clumsy, but safer than any alternative I’ve come up with^{5}.

4 Caveats

In order to implement this style file, it’s been necessary to modify a number of L^{A}TEX commands seemingly unrelated to indexing, namely, \@starttoc,

\raggedbottom, \flushbottom, \addcontents, \markboth, and \markright.

Naturally, this could cause incompatibilities between index.sty and any style files that either redefine these same commands or make specific assumptions about how they operate. See Section ?? for explanations of why these various commands needed modification.

The redefinition of \@starttoc is particularly bad, since it introduces an incompatibility with the AMS document classes. This will be addressed soon.

Unfortunately, it’s also been necessary to modify the theindex environment, so if you don’t like the default L^{A}TEX definition, you’ll need copy the definition of theindex from this file and modify it appropriately.

In the current implementation, index.sty uses one output stream for each index. Since there are a limited number of output indexes, this means that there is a limit on the number of indexes you can have in a document. See the description of \disableindex for a fuller discussion of this problem and one way around it.

5 To do’s

It might be nice if the \index* command parsed its argument so that, for example,

instead of writing ‘\index{sin@$\sin$}$\sin$’, one could write ‘index*{sin@$\sin$}’.

3This limits its usefulness somewhat, but since the output file for an index is opened when the index is declared, the damage has already been done. We could close the file, but we can’t prevent a new output stream from being allocated and we can’t keep the old file from being truncated.

4TEX only has 16 output streams, which are allocated with the \newwrite command. The standard L^{A}TEX styles use from 3 to 7 of these, which should leave room for up to 9 indexes. Of course, if you have extra output files, then there will be fewer output streams left for indexes.

5A less clumsy (for the user, at least) solution would be to read the aux file multiple times at the end of the run, each time writing just one of the raw index files. The main disadvantage of this scheme at present is that it would require a modification of \enddocument.

However, this is fraught with numerous dangers, and I’m both too lazy and too cowardly to undertake it now.

It would be reasonable to add support for \makeglossary and similar things, if they were well-defined enough to decide what the general syntax for defining them should be.

The documentation should be carefully read, edited, and finished, especially since it’s still based on the 2.09 version, even though a few substantial changes have been made for the L^{A}TEX 2ε version.

For some truly outlandish ideas, see the file TODO in the distribution.

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

D

\disableindex . . . . . . 4

E

environments:

   shortindexingon . 3

I

\index . . . . . . . . . . . . 3

\indexproofstyle . . . 3

M

                          \makeindex . . . . . . . . 3

N \newindex . . . . . . . . . 2

P

                          \printindex . . . . . . . . 3
                          \proofmodefalse . . . . 3
                          \proofmodetrue . . . . . 3

R

                                                   \renewindex . . . . . . . . 3

S

                                                   \shortindexingoff . . 3
                                                   \shortindexingon . . . 3
                                                   shortindexingon (envi-

ronment) . . . . . 3