6.1.1 Creating an Index (makeidx package)

Volume 1 introduced the command:

\index{<text>}

to index the word given in <text>. For example, if \index{circuit} occurs on page 42, then “42” will be added to the location list for the term “circuit”.

Note:

⚠

\index doesn't display any text. It just adds a line to the index file with the information required by makeindex or xindy to sort and collate the information.

The default action of \index simply ignores its argument. To ensure the indexing mechanism works, you must activate it by placing

\makeindex

in the document preamble.

Finally, you need to use

\printindex

(defined in the makeidx package) to display the index.

Note:

⚠

\printindex won't produce any text until you have run the external indexing application.

Here's an example document:

Listing 18:

% arara: pdflatex: { synctex: on } % arara: makeindex % arara: pdflatex: { synctex: on } \documentclass[12pt,oneside]{scrbook} \usepackage{makeidx} \makeindex \title{Sample Document} \author{Me} \begin{document} \maketitle \chapter{Sample} Stuff about eigenvectors\index{eigenvector} and eigenvalues\index{eigenvalue}. \chapter{Another Sample} Some more stuff about eigenvectors\index{eigenvector} and eigenvalues\index{eigenvalue}. Something about eigen-decomposition\index{eigen-decomposition}. \backmatter \printindex \end{document}

If you are using arara to build your document (see §1.1.2. Arara), remember to include the % arara: comments, as shown in the above listing. If you are using latexmk to build your document, remember to include the .idx custom dependency to your RC file, as described in §1.1.1. LaTeXmk.

If you aren't using an automated method to build your document, you will need to run PDFLaTeX, then run makeindex, and then run PDFLaTeX again (see §1.1. Building Your Document).

If you prefer to use xindy instead of makeindex, you need to run texindy (a xindy wrapper customised for LaTeX documents). If you are using arara, change the line:

% arara: makeindex

to (change the language as required):

% arara: texindy: { language: english }

(Make sure you have added the texindy rule as described in §1.1.2. Arara.) If you are using latexmk to build your document, you will need to change the custom dependency for .idx files, as described in §1.1.1. LaTeXmk.

6.1.1.1 Overriding the Default Sort

By default the index entry will be sorted according to the word being indexed. However, you can override this by writing the argument of \index in the form:

<sort>@<word>

where <sort> is how to sort the term and <word> is how the term should appear in the index.

The makeindex application doesn't understand LaTeX commands. It simply sorts the term as is. So, for example, if you do

\index{\AE olian}

then makeindex will sort it according to the characters \, A, E, ␣ (space), o, l, i, a, n. Since makeindex sorts symbols (such as \) before letters, it will put \AE␣olian before, say, adze, since \ comes before “a”.

To get around this, you need to specify the sort key:

\index{AEolian@\AE olian}

Now makeindex will put “Æolian” after “adze”. Here's another example that indexes a function or method:

\index{sqrt()@\texttt{sqrt()}}

You will also need to do something similar if you are entering the character directly via the inputenc package:

\index{elite@élite}

Note, however, that you don't need to do this if you are using xindy. You just need to make sure you match the input encoding. For example:

% arara: pdflatex: { synctex: on } % arara: texindy: { language: english, codepage: latin1} % arara: pdflatex: { synctex: on } \documentclass[12pt,oneside]{scrbook} \usepackage[latin1]{inputenc} \usepackage{makeidx}

Later in the document:

\index{élite}

6.1.1.2 Setting the Location Format

Each index entry has an associated location list that directs the reader to the pages in the document associated with that entry. For example, if you look up \index in this book's index, the entry's location list will include this page. If the location list is long, it's helpful to highlight a particular location to direct the reader to the principle definition or discussion related to that term. This is usually done by formatting the relevant location in a different font, for example bold or italic.

You can specify the format for the location by writing the argument of \index in the form:

<word>|<format>

where <format> is the name of a text-block command without the leading backslash. For example:

\index{eigenvector|textbf}

You can combine @ and |. For example:

\index{sqrt()@\texttt{sqrt()}|textbf}

Note:

⚠

Make sure the format you use is the name of a command that takes an argument. While it won't cause an error to use, say, bfseries instead of textbf, it will cause the unexpected side-effect of rendering the rest of your index in that font, instead of just that particular location.

You can also use <format> to cross-reference another entry. If you have an entry that's just a synonym for another entry, you can use:

<word>|see{<name>}

where <name> is the other entry. If you want to direct the reader to a similar topic, you can use:

<word>|seealso{<topic>}

where <topic> is the other entry.

For example:

\index{eigenvector|seealso{eigenvalue}}

6.1.1.3 Sub Levels

An entry in the index may have sub-items. With makeindex you can have a maximum of three levels. With xindy you can have an arbitrary number of levels. However, it's a good idea to consider the advice in the Oxford Style Manual [12]: “In all but the most complex indexes, subentries within subentries (sub-subentries) should be avoided.” In other words, just because it's possible to do something doesn't mean you should do it.

To indicate a subentry, the argument of \index should be in the form:

<main entry>!<subentry>

For example:

\index{reptile!caiman}

If you really must have a sub-subentry:

\index{reptile!crocodylian!caiman}

You can combine @, | and !. For example:

\index{methods!sqrt()@\texttt{sqrt()}|textbf}

Listing 17 can now be modified as follows (download the document for the complete code):

Listing 19:

% In the preamble: % arara: pdflatex: { synctex: on } % arara: biber % arara: makeindex % arara: pdflatex: { synctex: on } % arara: pdflatex: { synctex: on } \documentclass[oneside,12pt]{scrbook} \usepackage{makeidx} \makeindex % Later in the document: Some sample code is shown in Listing~\ref{lst:sample}. This uses the function \lstinline"sqrt()"% \index{sqrt()@\texttt{sqrt()}}% \index{functions!sqrt()@\texttt{sqrt()}}% \index{square root|see{\texttt{sqrt()}}}. \begin{Definition}[Tautology] A \emph{tautology}\index{tautology|textbf} is a proposition that is always true for any value of its variables. \end{Definition} \begin{Definition}[Contradiction] A \emph{contradiction}\index{contradiction|textbf} is a proposition that is always false for any value of its variables. \end{Definition} % At the end of the document: \printbibliography \printindex \end{document}

The index for the above document looks like:

Image showing typeset output click here for a more detailed description.

6.1.1.4 Troubleshooting

My index hasn't appeared.
1. Make sure you have the command \printindex at the place where you want the index to appear (this command is defined in the makeidx package).
2. Make sure you have the command \makeindex in the preamble.
3. If you are building the document using arara make sure you included all the % arara: directives as shown in Listing 19. If you are using latexmk, make sure you have included the .idx dependency, as described in §1.1.1. LaTeXmk. If you're not using an automated tool, make sure you run (PDF)LaTeX, then makeindex and then (PDF)LaTeX again (see §1.1. Building Your Document).
4. Check makeindex's log file (which has the extension .ilg by default) for error messages.
I want to index the character ", @, ! or | but it's not working.
If you want any of these symbols in your index, you will need to prefix the character with the double-quote symbol ". For example to index the @ symbol:

\index{"@}
I have multiple entries of the same item. For example:
identity matrix, 10, 22-30
identity matrix, 4

Check to make sure the sort argument to each of the corresponding \index commands is the same. Pay particular attention to spaces as makeindex will treat the following entries differently:

\index{identity␣matrix} \index{identity␣␣matrix}

LaTeX however treats multiple spaces the same as a single space, so the text will appear the same in the index.
LaTeX says that the command \printindex is undefined.
You have forgotten to load the makeidx package.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-02-9).