Many books should have an index, particularly scientific or technical ones. Since the first days, LaTeX has a companion program called MakeIndex that helps in sorting the index entries one can specify in the LaTeX document with

.

Having to run a helper program is often a nuisance and people tend to forget it, unless some automated system is used. Another well known helper program is BibTeX (or Biber), but for bibliographic cross references LaTeX has a means to make us notice that a run of BibTeX is possibly needed. How can one avoid forgetting to run MakeIndex? Well, it’s possible to forget running it without losing anything: read on!

The old days

The traditional setting was

A limitation of this approach is that only one index can be generated. But more on this later; for the moment let’s assume we have only one index.

The making of the index is asynchronous: a LaTeX run on

produces, if

is issued in it, the auxiliary file

that must be processed with MakeIndex which sorts and compacts the entries and finally writes the file

that, if present, is input by the command

.

Thus a typical session involving a bibliography and an index would require

in order that the bibliographical references are resolved and the index entries show the correct page number. Of course, during the preparation of the book it’s not necessary to do all those runs (and nowadays probably

is run instead of

, but that’s another question).

Failing to run MakeIndex can lead to incorrect page numbers. But while changed references related to

or

make LaTeX issue the well known message

nothing of this sort is available for index entries.

The new era

At the GuITmeeting 2009 Claudio Beccari announced TeX Live’s plan to allow some selected programs to be run from inside (La)TeX and presented a strategy for ensuring that MakeIndex was run automatically during the LaTeX compilation of a document. Unfortunately (or happily) the feature was not included in TeX Live 2009, but delayed to the 2010 release. The idea of developing a package out of the small kernel presented by Claudio popped out immediately; the name chosen for it was, without much fantasy,

(maybe “improved

“). We foresaw the possibility, with TeX Live 2010 or later, to shorten the necessary steps to

by only changing

into

. The only real limitation was (and is) that no index entry may appear after the index itself. The MakeIndex run is safely called without user intervention!

Multiple indices

Some packages had already been developed for supporting multiple indices in books:

,

and

, so one of our tasks was to provide support for more than one index. We decided for a key-value interface; here are the main ones:

For example

will enable to say

in order to insert the famous mathematician’s name in an index titled “Index of names”, processed using the MakeIndex style

, and compressing blanks (any set of MakeIndex options can be specified); the index will be listed in the main table of contents and will be typeset in three column format. The number of columns can be also one, for annotated indices; the default is, as usual, two.

In this case, printing the index will be obtained by the command

With only one index it’s not necessary to specify a

option.

Apart from the optional argument that tells LaTeX what index the entry belongs to, the syntax for the mandatory argument to

is the same as the standard one. So, for instance,

can be used so that “Gödel” will be sorted as if it were “Godel”.

Multiple index troubles

What about having ten different indices maybe along with glossaries, nomenclatures and acronym lists? No,

doesn’t support those kinds of lists, but they can be needed in a book and there are very good packages around for managing them. The problem is that every index uses up an output stream and TeX is able to write only in 16 different files at the same time; for a book there can be already four streams in use for writing the main

file, the table of contents, the list of tables and the list of figures. It’s easy to overflow the limit.

Markus Kohm’s

package comes to the rescue, because it provides also a helper program, called

that we decided to make available also to

users: one can pass an option to the package

and all the index entries will be saved in only one file, that will be automatically split at the first call of

. There is one catch, however:

is not in the list of programs that can be run from inside a (La)TeX run, so in this case one has to launch

(as well as

,

or

) with the

option

We hope that

can be amended so that it can be included in the restricted list.

Xindy

For some years there’s been another index processor around, much more powerful than MakeIndex. It can sort by different collation rules (useful for languages other than English) and apply many processing options. One can choose this processor globally

or on a per index basis with

where

stands for the other options discussed so far (maybe also

). This option actually calls the script

that chooses a set of Xindy options specially tailored for LaTeX. The “naked” program can be called by the option

(a recent addition to the package, in version 1.2). Since

and

are not in the restricted list, the

switch is needed when an index has to be processed with Xindy in any of its forms.

Compatibility

The package is compatible with all main classes we know (with the notable exception of the AMS classes, for which a different system is needed, using

). It’s also compatible with

, with the caveat that its internal method for doing multiple indices is hijacked by ours. Recent updates to the package have removed small incompatibilities (particularly with

).

Bell and whistles

Yes, there’s more. One can define prologues to indices, that is, text that’s printed between the index title and the entries. Other aspects of the indices can be changed and the package is compatible with

by Thomas Titz.

Final words

You can forget to run MakeIndex. But don’t forget to prepare a good index for your book: your readers will be grateful.