Your support for our advertisers helps cover the cost of hosting, research, and maintenance of this document

Formatting Information — An introduction to typesetting with LATEX

Chapter 5: Textual tools

Section 5.4: Indexes and glossaries

In this section…

  1. Indexes
  2. Glossaries

Indexes and glossaries are tools for directing or helping the reader. Any book or report sized document should have an index, although they are uncommon in theses. Glossaries are usually only needed where there is a substantial number of technical terms needing formal definition and cross-referencing.

5.4.1 Indexes

LATEX has an automated indexing facility which uses the standard makeindex program for sorting and collation. To use indexing, use the package makeidx and include the \makeindex command in your Preamble to initialise the index:

\usepackage{makeidx}
\makeindex
	

When you want to index something, use the command \index followed by the entry in curly braces, as you want it to appear in the index, in one of the following formats:

Plain entry

Typing \index{beer} will create an entry for ‘beer’ with the current page number;

Subindex entry

For an entry with a subentry use an exclamation mark to separate them: \index{beer!lite}. You can create another level as well, so you can have subsubentries like \index{beer!lite!American};

Cross-references

‘See’ entries are done with the vertical bar (one of the rare times it does not get interpreted as a math character): \index{Microbrew|see{beer}};

Font changes

To change the style of an entry, use the @-sign followed by a font change command:

\index{beer!Rogue!Chocolate Stout@\textit{Chocolate Stout}}
	      

This example indexes Chocolate Stout as a third-level entry and italicises it at the same time. Any of the standard \text font-change commands work here: see Table 6.7 for details.

You can also change the font of the index number on its own, as for first-usage references, by using the vertical bar in a similar way to the ‘see’ entries above, but substituting a font-change command name alone (without a backslash or curly braces) such as textbf for bold-face text (see the index):

\index{beer!Rogue!Chocolate Stout|textbf}
	      
Out of sequence

The same method can be used as for font changes, but using the alternate index word instead of the font command name, so \index{Oregon Brewing Company@Rogue} will add an entry for ‘Rogue’ in the ‘O’ section of the index, as if it was spelled ‘Oregon Brewing Company’.

When the document has been processed through LATEX it will have created a .idx file, which you run through the makeindex program by clicking the Index button or menu entry in your editor, or by typing the makeindex command followed by your document name without the .tex filetype.

The program will look for the .idx file with the same name as your document, and output a .ind file with the sorted index in it. This is what gets used by the command \printindex which you put at the end of your document, where you want the index printed. The default index format is two columns with a space between letters of the alphabet. The Unix manual page for the makeindex program has details of how to add letter headings to each alphabet group.

5.4.2 Glossaries

Glossaries can be done in a similar manner to indexes, using the command \makeglossary in the Preamble and the command \glossary in the same way as \index. There are some subtle differences in the way glossaries are handled: both the books by Lamport (1994) and by Mittelbach, Goossens, Braams, Carlisle and Rowley (2004) duck the issue, but there is some documentation on glotex on CTAN. There is also a gloss package based on BIBTEX which uses \gloss in the same way as \cite.

However, by far the best way is to use the glossaries package (not glossary, which is obsolete, and not gloss). This is a relatively complex package, as glossaries are a relatively complex tool, but there is extensive help in the documentation. It requires the makeglossaries script from CTAN (there is also a makeglossariesgui Java GUI).

Basically, you need to create a set of definitions, one per item to be glossed, using the \newglossaryentry command:

\newglossaryentry{esis}{name={ESIS},description={The
  \textbf{Element Structure Information Set} of a
  marked-up document, originally defined for SGML
  (replaced for XML using W3C Schemas by the
  Post-Schema-Validation InfoSet, PSVI). See
  \url{http://xml.coverpages.org/WG8-n931a.html}}}
	

This specifies a) the label you will use (esis); b) the name of the item as it will be printed (ESIS); and c) the textual description to go in the glossary. Probably the bext place to put these is in a separate file like mygloss.tex, which you can get LATEX to read with an \input{mygloss.tex} command in your Preamble.

You can then use the \gls command in your text to produce the printable name of any entry, using the label to refer to it, eg \gls{esis}. It is possible to use or define variant commands to handle references at the start of a sentence (where you need a capital letter if the name is not an acronym), and grammatical alteration like unusual plurals or forms ending in ‘—ing’.

At the end of your document, where you want the glossary printed, you use the command \printglossaries. The glossary need to be processed separately from the main document, using the makeglossaries script, exactly the same way as you do for biber, bibtex, and makeindex. The Build function of your editor should do this for you, or use a Makefile or a utility like latexmk. As with all these tools, there are many more facilities built into them: read the documentation.

The acronym package can also be used to create a kind of glossary containing a list of acronyms and their expansions, as well as driving the use of expansion on first mention. However, the glossaries package now contains built-in support for acronyms.

  1. On Unix & GNU/Linux systems (including Apple Macintosh OS X, just type the command man makeindex; the page is also available in many reference sites on the web.