Skip to content
Topos Uranos
English

Indexes and glossaries

Summary

This lesson teaches how to build the subject index of a book or a thesis, and its glossaries. It explains what a subject index is for and how it differs from the table of contents; it presents the imakeidx package, with \makeindex, \index and \printindex, and the compilation cycle in which makeindex sorts the entries between two runs of the engine; it teaches subentries, the sort keys that correct the position of words with diacritics, the cross-references, which English labels “see” and “see also”, page ranges and highlighted page numbers; it shows how to keep several indexes at once, one of names and another of subjects; it presents the glossaries package, with its defined terms and its acronyms, which are spelled out the first time they appear, and the glossaries-extra variant; and it ends with the most frequent errors: the index that is not updated, words with diacritics sorted out of place, and entries duplicated by a different spelling.

Learning objectives

  1. Distinguish the subject index from the table of contents and from the glossary by what each one orders and by what it offers the reader.
  2. Mark index entries with subentries, sort keys, cross-references, ranges and highlighted page numbers, and predict what each mark prints.
  3. Explain the compilation cycle with makeindex and which file each step produces, and recognise why an index is not updated.
  4. Keep several indexes in the same document and send each entry to its own.
  5. Define terms and acronyms with glossaries, foresee what each mention prints, and typeset the glossary and the list of acronyms.
  6. Diagnose duplicated entries, words with diacritics sorted out of place and glossary errors from the printed index and from the log.

What a subject index is for

The lesson on sections, the table of contents and appendices dealt with the table of contents, which \tableofcontents typesets at the beginning of the document and which babel titles “Contents”: it reproduces the divisions in the order in which they appear and answers the question of how the text is organised. The subject index, which babel titles “Index”, answers another question: where something is discussed. It lists in alphabetical order the concepts, names and works that the text deals with, and gives for each the pages on which they are found. A reader who wants to know what a history of science says about Kepler, or what a biochemistry textbook says about enthalpy, cannot find it in the table of contents, because no section title names it; the reader finds it in the index.

It follows that the index is not obtained from the structure of the document, as the table of contents is, but from a decision of the author: which terms deserve to appear, under what form and with what subdivisions. An index that records every occurrence of every word is useless, because it returns all the pages to the reader; a good one records the places where a term is defined, discussed or applied, and refers the reader from the forms the reader might look up to the form chosen. That is why it belongs to books, textbooks and long theses, and not to a ten-page article.

The glossary is a third tool. It does not say where a term is discussed, but what it means: it is a list of definitions, often accompanied by the list of the acronyms that the text uses, with their expanded form. Both are built with the same mechanism, which this lesson studies first in the index.