producing the index

index@“verb=“index=

makeidx document-style option@“tt makeidx document-style option LaTeX man-

ual@“LaTeX“

manual printindex@“verb=“printindex= idx file@“tt idx file files@files!“tt idx running makeindex@running “MakeIndex

makeindex@“MakeIndex!running ind file@“tt ind file files@files!“tt ind makeindex com-

mand@“verb=“makeindex= command!removing idx file@“tt idx file files@files!“tt idx error messages

MakeIndex: An Index Processor For LaTEX

Leslie Lamport

17 February 1987

1 How to Use MakeIndex

MakeIndex is a program for making an index in a document generated with LaTEX. The first step in producing the index is to put the necessary \index commands in your document, as described in the next section. Here, I describe how to generate the index after the \index commands are in place.

Let’s suppose that the root file of your document is myfile.tex. You must make the following changes to your document:

• Add the makeidx document-style option to the list of options in the \documentstyle command. (See page 21 of the LaTEX manual.)

• Put a \makeindex command in the preamble (between the

     \documentstyle and \begin{document} commands).

• Put a \printindex command where you want the index to appear— usually at the end, right before the \end{document} command.

You then run LaTEX on your entire document, causing it to generate the file myfile.idx, which I will call the idx file. Next, run the MakeIndex program by typing the following Unix command:

     makeindex myfile.idx

This produces the file myfile.ind, which I will call the ind file. If MakeIndex generated no error messages, you can now rerun LaTEX on your document and the index will appear. (You can remove the \makeindex command first so the idx file is not regenerated.) If there were error messages, see Section 3.

mistakes

editing!avoiding indexing!professional

advice Spiker, Sina Wisconsin Press index!professional guidelines pen!ball-point pen!quill index!cards cards!index index!the hard

way word list!making a Trickey, Howard delatex@“tt delatex LaTeX com-

mands@“LaTeX“ commands!stripping

index!getting started index!making a word list index!unique words unique words word list

By reading the index, you may discover additional mistakes. These should be corrected by changing the appropriate \index commands in the document and regenerating the ind file. If there are problems that cannot be corrected in this way, you can always edit the ind file directly. However, such editing is to be avoided because it must be repeated every time you generate a new version of the index.

2 How to Generate Index Entries

2.1 When, Why, What, and How to Index

It’s tempting to generate the index as you write the document. Resist the temptation. It is virtually impossible to obtain any consistency in an index that is generated in this way.

An index is there to help the reader find what he’s looking for. With this in mind, common sense can help in figuring out what should be in the index and how it should be organized. Since it’s often hard to distinguish common sense from equally common nonsense, professional advice is useful. Many style guides discuss indexing; the pamphlet Indexing Your Book by Sina Spiker (The University of Wisconsin Press, 1954) is, according to its subtitle, “A Practical Guide for Authors”.

Unfortunately, these guides to indexing seem to have been written when high tech meant using a ball-point pen instead of a quill, so their advice on the mechanics of creating an index revolve around how to stack your 3 × 5 index cards. You’ll have to figure out your own method of using the computer to lighten the chore. An alphabetical list of every word in your document, with duplicates removed, is not a bad place to start. If your system has Howard Trickey’s delatex program, then the following Unix command generates such a list from the file myfile.tex and puts it on the file foo:

     delatex myfile.tex | sort -uf > foo

The computer is only a tool; it can’t write the index for you. It may be easy to choose which words are important and mechanically generate an index citing every occurrence of those words, but the resulting index will not be as useful to the reader as one prepared with more care.

index@“verb=“index=

index!entries

idx file@“tt idx file files@files!“tt idx index@“verb=“index=!duplicates subentries index!subentries index!main entries ”! charac-

ter@“verb=”!= character subsubentries index!subsubentries subsubsubentries entries!subsubsubentries

(can’t have) index!maximum levels allowed

2.2 The Basics

Each \index command causes LaTEX to write an entry on the idx file. The following example shows some simple \index commands and the index entries that they produce. The page number refers to the page containing the text where the \index command appears.^{1}

     Page ii \index{Alpha}
     Page viii: \index{alpha}
     Page ix: \index{alpha}

               \index{Alphabet}

     Page 22: \index{alpha}

               \index{alphas}

     Page 23: \index{alphabet}

               \index{alphabet}

     Page 24: \index{alpha bet}

Alpha, ii

alpha, viii, ix, 22 alpha bet, 24 Alphabet, ix alphabet, 23 alphas, 22

Note that the duplicate \index{alphabet} commands on page 23 produce only one “23” in the index.

To produce a subentry, the argument of the \index command should contain both the main entry and the subentry, separated by a ! character.

     Page 7: \index{gnat!size of}
     Page 32: \index{gnat}
     Page 35: \index{gnat!anatomy}

              \index{gnus!good}

     Page 38: \index{gnus!bad}

gnat, 32 anatomy, 35 size of, 7

gnus bad, 38 good, 35

You can also have subsubentries.

     Page 8: \index{bites!animal!gnats}
     Page 10: \index{bites!animal!gnus}
     Page 12 : \index{bites!vegetable}

bites

animal gnats, 8 gnus, 10 vegetable, 12

LaTEX and MakeIndex support only three levels of indexing; you can’t have subsubsubentries.

1To avoid any ambiguity if a page break occurs right at an \index command, it’s a good idea to attach the command to a word instead of putting it between words.

page range

page range!opening command page range!closing command index!crossreference cross-reference see command@“tt

see

command!using see command@“tt see command!placement of ”@ charac-

ter@“verb=”@= character

index!alphabetizing index!funny

characters in

To specify a page range, put an \index{...|(} command at the beginning of the range and an \index{...|)} command at the end of the range.

     Page vi: \index{gnat|(}
     Page x: \index{gnat|)}
     Page 22: \index{gnat}

              \index{gnus!bad|(}
              \index{gnus!bad|)}

     Page 28: \index{gnus!good|(}
     Page 30: \index{gnus!good}
     Page 32: \index{gnus!good|)}

gnat, vi–x, 22 gnus

bad, 22 good, 28–32

Note that MakeIndex does the right thing when both ends of the range fall on the same page.^{2}

Sometimes, you want to add a cross-reference with no page number. This is done as follows;

     Page 2: \index{at}
     Page 2: \index{at!bat|see{bat, at}}

at, 2 bat, see bat, at

Since the “see” entry does not print any page number, it doesn’t matter where the \index{...|see{...}} command goes, so long as it follows the \begin{document} command. You might want to put all such crossreferencing commands in one place.

If you specify an entry of the form σ@τ, the string σ determines the alphabetical position of the entry, while the string τ produces the text of the entry.

     Page 44: \index{twenty}
     Page 46: \index{twenty-one}
     Page 55: \index{twenty@xx}

twenty, 44 xx, 55 twenty-one, 46

This feature is useful because the argument of the \index command provides the actual input string that LaTEX uses to generate the index entry. In the following example, the input $\alpha$ produces the symbol α,

     Page 12: \index{alphas}
     Page 13: \index{alpha}
     Page 14: \index{alpha@$\alpha$}

alpha, 13 α, 14 alphas, 12

2The use of “28ff.” rather than “28–32” is frowned upon by the experts.

page numbers

page

numbers!italic page

numbers!entries in footnotes see command@“tt

see

command!example makeidx

document-style option@“tt makeidx document-style option

idx file@“tt idx file files@files!“tt idx index!expansion of commands in robust commands commands!robust fragile commands commands!fragile protect@“verb=“protect= protect@“verb=“protect=—see“tt

“symbol’134string protect@“verb=“string=—see“tt

“symbol’134protect string@“tt

“symbol’134string

Similarly, the command \index{gnu@{\bf gnu}} produces a boldface gnu index entry.

In some indexes, certain page numbers are specially formatted—for example, an italic page number may indicate the primary reference, and an n after a page number may denote that the item appears in a footnote on that page. MakeIndex makes it easy to format an individual page number any way you want. For any string of characters σ, the command \index{...|σ} produces a page number of the form \σ{n}. Similarly, the command \index{...|(σ} may produce a page number of the form \σ{n–m}. Thus, suppose the document contains the following command definitions:

     \newcommand{\ii}[1]{{\it #1}}
     \newcommand{\nn}[1]{#1n}

We could then have:

     Page 3: \index{gnat|ii}
     Page 4: \index{gnat|nn}
     Page 5: \index{gnu}
     Page 44: \index{gnu|(ii}
     Page 46: \index{gnu|)}

gnat, 3, 4n gnu, 5, 44–46

The “see” option is a special case of this facility, where the \see command is predefined by the makeidx document-style option.

2.3 The Fine Print

Commands in an index entry are expanded when the index is typeset, not when the idx file is written. Hence, the command \index{\gnu} produces an entry that is alphabetized by \gnu, regardless of how the \gnu command is defined.

Recall that special characters like \ may appear in the argument of an \index command only if that command is not itself contained in the argument of another command. This is most likely to be a problem when indexing items in a footnote. Even in this case, robust commands can be placed in the “@” part of an entry, as in \index{gnu@{\it gnu}}, and fragile commands can be used if protected with the \protect command.^{3}

3In versions of L�TEX released before 3 February 1987, you must use the \string command instead of \protect.

braces!matching

page

numbers!arabic page

numbers!roman numerals

page numbers!order of index!funny

characters in ”” charac-

ter@“verb=””= character quote character index!quoting characters in index!spaces in index!don’t split across lines error messages ilg file@“tt ilg file files@files!“tt ilg idx file@“tt idx file files@files!“tt idx ind file@“tt ind file files@files!“tt ind

Remember that the argument of an \index command must always have matching braces, where the brace in a \{ or \} command counts.

MakeIndex assumes that all page numbers are either arabic or lowercase roman numerals; it assumes that pages numbered with roman numerals precede those numbered with arabic numerals.

To put a !, @, or | character in an index entry, quote it by preceding the character with a ". More precisely, any a character is said to be quoted if it follows an unquoted " that is not part of a \" command. A quoted !, @, or | character is treated like an ordinary character rather than having its usual meaning. The " preceding a quoted character is deleted before the entries are alphabetized.

     Page 2: \index{exclaim ("!)}
     Page 3: \index{exclaim ("!)!loudly}
     Page 4: \index{fur@f\"{u}r}
     Page 5: \index{quote (\verb+""+)}

exclaim (!), 2 loudly, 3

für, 4

quote (""), 5

MakeIndex regards spaces as ordinary characters when alphabetizing the entries and deciding whether two entries are the same. Thus, letting “␣” denote a space character, the commands \index{gnu}, \index{␣gnu}, and \index{gnu␣} produce three separate entries, the first appearing near the beginning of the index, since ␣ comes before any letter in MakeIndex’s “alphabetical” order. All three entries look the same when printed, since LaTEX ignores extra spaces in the input. Similarly, \index{a␣space} and \index{a␣␣space} produce two different entries that look the same when printed. Do not split the argument of an \index command across lines in the input file.

3 Error Messages

MakeIndex types out on the terminal the number of lines read and written and how many errors were found. Message to identify the error are written on a file with extension ilg. There are two phases in which MakeIndex can produce error messages: when it is reading the idx file, and when it is writing the ind file. Each error message prints the nature of the error followed by a line number, identifying where in the file the error occurs. In the reading phase, the line number refers to the idx file; in the writing phase, it refers to the ind file.

”! character@“verb=”!= character ”@ charac-

ter@“verb=”@= character ”! charac-

ter@“verb=”!= character index!long arguments idx file@“tt idx file files@files!“tt idx

3.1 Errors in Reading Phase

Extra `!'  at position ...

The \index command’s argument has more than two unquoted ! characters. Perhaps some of them should be quoted.

Extra `@' at position ...

The \index command argument has two or more unquoted @ characters with no intervening !. Perhaps one of the @ characters should be quoted.

Extra `|' at position ...

The \index command’s argument has more than one unquoted ! characters. Perhaps the extras should be quoted.

Illegal null field

The \index command argument doesn’t make sense because some string is null that shouldn’t be. The command \index{!big} will produce this error, since it specifies a subentry “big” with no entry. Similarly, the command \index{@big} is incorrect because it specifies a null string for alphabetizing.

Argument ...  too long (max 1024).

Your document contained an \index command with a very long argument. You probably forgot the right brace that was supposed to delimit the argument.

Other errors

MakeIndex can produce a variety of other error messages indicating that something is seriously wrong with the idx file. If you get one, it probably means that the idx file was corrupted in some way. If LaTEX did not generate any errors when it created the idx file, then it is highly unlikely to have produced a bad idx file. If it did, you’ll have to examine the idx file to figure out what went wrong.

page range range!of pages index!conflicting entries in C language Chen, Peehong Urban, Mike Rose, Marshall Web language Pascal lan-

guage—seeWeb

language makeindex@“MakeIndex!in

Web language Beebe, Nelson H.F.

mistakes—seeerrors

page

breaks—seeambiguities range—seepage

3.2 Errors in Writing Phase

Unmatched range opening operator

An \index{...|(} command was not followed by a matching \index{...|)} command. The “...” in the two commands must be completely identical.

Unmatched range closing operator

An \index{...|(} command was not preceded by a matching

\index{...|)} command.
Extra range opening operator

Two \index{...|(} commands appear in the document with no intervening

\index{...|)} command.
Inconsistent page encapsulator ...  within range

MakeIndex has been instructed to include a page range for an entry and a single page number within that range that is formatted differently—for example, by having a \index{gnu|ii} command between a \index{gnu|(}

and a \index{gnu|)} command.
Conflicting entries

MakeIndex thinks it has been instructed to print the same page number twice in two different ways—for example, by the commands \index{gnu} and \index{gnu|(see{...}} appearing on the same page.

Acknowledgements

MakeIndex is a C program written by Peehong Chen, with a little advice from me. It was inspired by a program written by Mike Urban, which was based on a program written by Marshall Rose. Perhaps someday someone will rewrite MakeIndex in Web, making it available to all LaTEX users.

This version of makeindex.tex, test.tex, has index entries generated by Nelson H.F. Beebe to serve as a test file for the MakeIndex program.

Index

! character, 3, 7 " character, 6 @ character, 4, 7

ambiguities, 3

Beebe, Nelson H.F., 8 behavior

frowned-upon, 4 braces

matching, 6

C language, 8 cards

index, 2 Chen, Peehong, 8 commands

fragile, 5 robust, 5

cross-reference, 4

delatex, 2

editing

avoiding, 2 entries

subsubsubentries (can’t have),

3 error messages, 1, 6 examples, 3–6 experts, 4

behavior of, 4

ff.

avoiding, 4 files

idx, 1, 3, 5–7

ilg, 6

ind, 1, 6 fragile commands, 5

idx file, 1, 3, 5–7 ilg file, 6 ind file, 1, 6 index

alphabetizing, 4 cards, 2 conflicting entries in, 8 cross-reference, 4 don’t split across lines, 6 entries, 3 expansion of commands in, 5 funny characters in, 4, 6 getting started, 2 long arguments, 7 main entries, 3 making a word list, 2 maximum levels allowed, 3 professional guidelines, 2 quoting characters in, 6 spaces in, 6 subentries, 3 subsubentries, 3 the hard way, 2 unique words, 2

\index, 1, 3

duplicates, 3 indexing

professional advice, 2

LaTEX commands

stripping, 2 LaTEX manual, 1 makeidx document-style option, 1,

5 MakeIndex

in Web language, 8 running, 1

\makeindex command

removing, 1 mistakes, 2, see errors

page breaks, see ambiguities page numbers, 5

arabic, 6

entries in footnotes, 5 italic, 5 order of, 6 roman numerals, 6

page range, 4, 8 avoiding ff., 4 closing command, 4 opening command, 4

Pascal language, see Web language pen

ball-point, 2 quill, 2

\printindex, 1

producing the index, 1

\protect, see \string, 5
\string, see \protect

quote character, 6

range, see page

of pages, 8 robust commands, 5 Rose, Marshall, 8 running MakeIndex, 1

see command example, 5 placement of, 4

using, 4 Spiker, Sina, 2

                                  \string, 5

subentries, 3 subsubentries, 3 subsubsubentries, 3

Trickey, Howard, 2

unique words, 2 Urban, Mike, 8

Web language, 8 Wisconsin Press, 2 word list, 2

making a, 2