Front/back matter (LaTeX2e unofficial reference manual (October 2018))

## Front/back matter

### Table of contents etc.

Synopsis, one of:

    \tableofcontents
    \listoffigures
    \listoftables

Produce a table of contents, or list of figures, or list of tables. Put the command in the input file where you want the table or list to go. You do not type the entries; for example, typically the table of contents entries are automatically generated from the sectioning commands `\chapter`, etc.

This example illustrates the first command, `\tableofcontents`. LaTeX will produce a table of contents on the book’s first page.

    \documentclass{book}
    % \setcounter{tocdepth}{1}
    \begin{document}
    \tableofcontents\newpage
      ...
    \chapter{...}
      ...
    \section{...}
      ...
    \subsection{...}
      ...
    \end{document}

Uncommenting the second line would cause that table to contain chapter and section listings but not subsection listings, because the `\section` command has level 1. See Sectioning for level numbers of the sectioning units. For more on the `tocdepth` see Sectioning/tocdepth.

Another example of the use of `\tableofcontents` is in Larger book template.

If you want a page break after the table of contents, write a `\newpage` command after the `\tableofcontents` command, as above.

To make the table of contents LaTeX stores the information in an auxiliary file named `root-file.toc` (see Splitting the input). For example, this LaTeX file `test.tex`

    \documentclass{article}
    \begin{document}
    \tableofcontents\newpage
    \section{First section}
    \subsection{First subsection}
      ...

writes the following line to `test.toc`.

    \contentsline {section}{\numberline {1}First section}{2}
    \contentsline {subsection}{\numberline {1.1}First subsection}{2}

The `section` or `subsection` is the sectioning unit. The hook `\numberline` lets you to change how the information appears in the table of contents. Of its two arguments, `1` or `1.1` is the sectioning unit number and `First section` or `First subsection` is the title. Finally, `2` is the page number on which the sectioning units start.

One consequence of this auxiliary file storage strategy is that to get the contents page correct you must run LaTeX twice, once to store the information and once to get it. In particular, the first time that you run LaTeX on a new document, the table of contents page will be empty except for its ‘`Contents`’ header. Just run it again.

The commands `\listoffigures` and `\listoftables` produce a list of figures and a list of tables. They work the same way as the contents commands; for instance, these work with information stored in `.lof` and `.lot` files.

To change the header for the table of contents page do something like the first line here.

    \renewcommand{\contentsname}{Table of contents}
    \renewcommand{\listfigurename}{Plots}
    \renewcommand{\listtablename}{Tables}

Similarly, the other two lines will do the other two. Internationalization packages such as `babel` or `polyglossia` will change the headers depending on the chosen base language.

CTAN has many packages for the table of contents and lists of figures and tables. One convenient one for adjusting some aspects of the default, such as spacing, is `tocloft`. And, `tocbibbind` will automatically add the bibliography, index, etc. to the table of contents.

#### `\addcontentsline`

Synopsis:

    \addcontentsline{ext}{unit}{text}

Add an entry to the file specified by ext. Usually ext is one of `toc` for the table of contents, `lof` for the list of figures, or `lot` for the list of tables.

The following will result in an ‘`Appendices`’ line in the table of contents.

    \addcontentsline{toc}{section}{\protect\textbf{Appendices}}

It will appear at the same indentation level as the sections, will be in boldface, and will be assigned the page number associated with the point where it appears in the input file.

The `\addcontentsline` command writes information to the file `root-name.ext`. It writes that information as the text of the command `\contentsline{unit}{text}{num}`, where `num` is the current value of counter `unit`. The most common case is the table of contents and there num is the page number of the first page of unit.

This command is invoked by the sectioning commands `\chapter`, etc., and also by `\caption` inside a float environment. But it is also used by authors. For example, in a book to have the preface unnumbered, you may use the starred `\chapter*`. But that does not put in table of contents information, so you can enter it manually, as here.

    \chapter*{Preface}
    \addcontentsline{toc}{chapter}{\protect\numberline{}Preface}

In the `.toc` file LaTeX will put the line `\contentsline {chapter}{\numberline {}Preface}{3}`; note the page number ‘`3`’.

All of the arguments for `\addcontentsline` are required.

ext

  Typically one of the strings `toc` for the table of contents, `lof` for the list of figures, or `lot` for the list of tables. The filename extension of the information file.

unit

  A string that depends on the value of the ext argument:

  `toc`

    For the table of contents, this is the name of a sectional unit: `part`, `chapter`, `section`, `subsection`, etc.

  `lof`

    For the list of figures: `figure`.

  `lot`

    For the list of tables: `table`.

text

  The text of the entry. You must `\protect` any commands that are fragile (see \protect).

The `\addcontentsline` command has an interaction with `\include` (see \include & \includeonly). If you use them at the same level, as with `\addcontentsline{...}{...}{...}\include{...}` then lines in the table of contents can come out in the wrong order. The solution is to move `\addcontentsline` into the file being included.

If you use a unit that LaTeX does not recognize, as here

    \addcontentsline{toc}{setcion}{\protect\textbf{Appendices}}

then you don’t get an error but the formatting in the table of contents will not make sense.

#### `\addtocontents`

Synopsis:

    \addtocontents{ext}{text}

Add text, which may be text or formatting commands, directly to the auxiliary file with extension ext. This is most commonly used for the table of contents so that is the discussion here, but this also applies to the list of figures and list of tables.

This will put some vertical space in the table of contents after the ‘`Contents`’ header.

    \tableofcontents\newpage
    \addtocontents{toc}{\protect\vspace*{3ex}}

The `\addtocontents` command has two arguments. Both are required.

ext

  Typically one of: `toc` for the table of contents, `lof` for the list of figures, or `lot` for the list of tables. The extension of the file holding the information.

text

  The text, and possibly commands, to be written.

The sectioning commands such as `\chapter` use the `\addcontentsline` command to store information. This command creates lines in the `.toc` auxiliary file containing the `\contentsline` command (see \addcontentsline). In contrast, the command `\addtocontents` puts material directly in that file.

The `\addtocontents` command has an interaction with `\include` (see \include & \includeonly). If you use them at the same level, as with `\addtocontents{...}{...}\include{...}` then lines in the table of contents can come out in the wrong order. The solution is to move `\addtocontents` into the file being included.

#### `\nofiles`

Synopsis:

    \nofiles

Prevent LaTeX from writing any auxiliary files. The only output will be the `.log` and `.pdf` (or `.dvi`) files. This command must go in the preamble.

Because of the `\nofiles` command this example will not produce a `.toc` file.

    \documentclass{book}
    \nofiles
    \begin{document}
    \tableofcontents\newpage
    \chapter{...}
      ...

LaTeX will not erase any existing auxiliary files, so if you insert the `\nofiles` command after you have run the file and gotten a `.toc` then the table of contents page will continue to show the old information.

### Indexes

This document has an index.

    \documentclass{article}
    \usepackage{makeidx} \makeindex
      ...
    \begin{document}
      ...
    Recall Wilson's Theorem: \index{Wilson's Theorem}
    a number \( n>1 \) is prime if and only if the factorial of \( n-1 \)
    is congruent to \( -1 \) modulo~\( n \).
      ...
    \printindex
      ...

The `\usepackage{makeidx}` and `\makeindex` in the preamble bring in the relevant commands.

Producing an index is a three stage process. First, in the document body you declare index entries with the `\index` command (see \index). When you run LaTeX, the `\index` writes its information to an auxiliary file `root-name.idx`. Next, to alphabetize and to do other manipulations you run an external command, typically `makeindex` or `xindy` (see makeindex). These output a file `root-name.ind`. Finally, you bring the information back into your document and typeset it with the `\printindex` command (see \printindex).

There are many packages that apply to indexing commands. The `showidx` package causes each index entries to be shown in the margin on the page where the entry appears. This can help in preparing the index. The `multind` package supports multiple indexes. See also the TeX FAQ entry on this topic, http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind.

#### `\index`

Synopsis:

    \index{index-entry-string}

Declare an entry in the index. This command is fragile (see \protect).

For example, as described in Indexes, one way to get an index from what’s below is to compile the document with `pdflatex test`, then process the index entries with `makeindex test`, and then compile again with `pdflatex test`.

    W~Ackermann (1896--1962).\index{Ackermann}
      ...
    Ackermann function\index{Ackermann!function}
      ...
    rate of growth\index{Ackermann!function!growth rate}

All three index entries will get a page number, such as ‘`Ackermann, 22`’. LaTeX will format the second as a subitem of the first, on the line below it and indented, and the third as a subitem of the second. Three levels deep is as far as you can nest subentries. (If you add `\index{Ackermann!function!growth rate!comparison}` then `makeindex` says ‘`Scanning input file test.idx....done (4 entries accepted, 1 rejected)`’ and nothing appears in the index).

If you enter a second `\index` with the same index-entry-string then you will get a single index entry with two page numbers (unless they happen to fall on the same page). Thus, adding `as for Ackermann.\index{Ackermann}` later in the same document as above will give an index entry like ‘`Ackermann, 22, 151`’. Also, you can enter the index entries in any order, so for instance `\index{Ackermann!function}` could come before `\index{Ackermann}`.

Get a page range in the output, like ‘`Hilbert, 23--27`’, as here.

    W~Ackermann (1896--1962).\index{Ackermann}
      ...
    D~Hilbert (1862--1943)\index{Ackermann!Hilbert\(}
      ...
    disapproved of his marriage.\index{Ackermann!Hilbert\)}

If the beginning and ending of the page range are equal then the system just gives a single page entry, not a range.

If you index subentries but not a main entry, as with `\index{Jones!program}` and `\index{Jones!results}`, then the output is the item ‘`Jones`’ with no comma or page number, followed by two subitems, like ‘`program, 50`’ and ‘`results, 51`’.

Generate a index entry that says ‘`See`’ by using a vertical bar character: `\index{Ackermann!function|see{P\'eter's function}}`. You can instead get ‘`See also`’ with `seealso`. (The text ‘`See`’ is defined by `\seename`, and ‘`See also`’ by `\alsoname`. You can redefine these either by using an internationalization package such as `babel` or `polyglossia`, or directly as with `\renewcommand{\alsoname}[1]{Also see #1}`.)

The ‘`See`’ feature is part of a more general functionality. After the vertical bar you can put the name of a one-input command, as in `\index{group|textit}` (note the missing backslash on the `\textit` command) and the system will apply that command to the page number, here giving something like `\textit{7}`. You can define your own one-input commands, such as `\newcommand{\definedpage}[1]{{\color{blue}#1}}` and then `\index{Ackermann!function|definedpage}` will give a blue page number (see Color). Another, less practical, example is this,

    \newcommand\indexownpage[1]{#1, \thepage}
      ... Epimenides.\index{self-reference|indexownpage}

which creates an entry citing the page number of its own index listing.

The two functions just described combine, as here

    \index{Ackermann!function|(definedpage}
      ...
    \index{Ackermann!function|)}

which outputs an index entry like ‘`function, 23--27`’ where the page number range is in blue.

Consider an index entry such as ‘`α-ring`’. Entering it as `$\alpha$-ring` will cause it to be alphabetized according to the dollar sign. You can instead enter it using an at-sign, as `\index{alpha-ring@$\alpha$-ring}`. If you specify an entry with an at-sign separating two strings, `pos@text`, then pos gives the alphabetical position of the entry while text produces the text of the entry. Another example is that `\index{Saint Michael's College@SMC}` produces an index entry ‘`SMC`’ alphabetized into a different location than its spelling would naturally give it.

To put a `!`, or `@`, or `|` character in an index entry, preceding it with a double quote, `"`. (The double quote gets deleted before alphabetization.)

A number of packages on CTAN have additional functionality beyond that provided by `makeidx`. One is `index`, which allows for multiple indices and contains a command `\index*{index-entry-string}` that prints the index-entry-string as well as indexing it.

The `\index` command writes the indexing information to the file `root-name.idx` file. Specifically, it writes text of the command `\indexentry{index-entry-string}{page-num}`, where page-num is the value of the `\thepage` counter. On occasion, when the `\printindex` command is confused, you have to delete this file to start with a fresh slate.

If you omit the closing brace of an `\index` command then you get a message like this.

    Runaway argument?  {Ackermann!function
    !  Paragraph ended before \@wrindex was complete.

#### `makeindex`

Synopsis, one of:

    makeindex filename
    makeindex -s style-file filename
    makeindex options filename0 ...

Sort, and otherwise process, the index information in the auxiliary file filename. This is a command line program. It takes one or more raw index files, `filename.idx` files, and produces the actual index file, the `filename.ind` file that is input by `\printindex` (see \printindex).

The first form of the command suffices for many uses. The second allows you to format the index by using an index style file, a `.isty` file. The third form is the most general; see the full documentation on CTAN.

This is a simple `.isty` file.

    % book.isty
    %   $ makeindex -s book.isty -p odd book.idx
    % creates the index as book.ind, starting on an odd page.
    preamble
    "\\pagestyle{empty}
    \\small
    \\begin{theindex}
    \\thispagestyle{empty}"

    postamble
    "\n
    \\end{theindex}"

The description here covers only some of the index formatting possibilities in style-file. For a full list see the documentation on CTAN.

A style file consists of a list of pairs: specifier and attribute. These can appear in the file in any order. All of the attributes are strings, except where noted. Strings are surrounded with double quotes, `"`, and the maximum length of a string is 144 characters. The `\n` is for a newline and `\t` is for a tab. Backslashes are escaped with another backslash, `\\`. If a line begins with a percent sign, `%`, then it is a comment.

`preamble`

  Preamble of the output file. Defines the context in which the index is formatted. Default: `"\\begin{theindex}\n"`.

`postamble`

  Postamble of the output file. Default: `"\n\n\\end{theindex}\n"`.

`group_skip`

  Traditionally index items are broken into groups, typically a group for entries starting with ‘`a`’, etc. This specifier gives what is inserted when a new group begins. Default: `"\n\n \\indexspace\n"` (`\indexspace` is a rubber length with default value `10pt plus5pt minus3pt`).

`lethead_flag`

  An integer. It governs what is inserted for a new group or letter. If it is 0 (which is the default) then other than `group_skip` nothing will be inserted before the group. If it is positive then at a new letter the `lethead_prefix` and `lethead_suffix` will be inserted, with that letter in uppercase between them. If it is negative then what will be inserted is the letter in lowercase. The default is 0.

`lethead_prefix`

  If a new group begins with a different letter then this is the prefix inserted before the new letter header. Default: `""`

`lethead_suffix`

  If a group begins with a different letter then this is the suffix inserted after the new letter header. Default: `""`.

`item_0`

  What is put between two level 0 items. Default: `"\n \\item "`.

`item_1`

  Put between two level 1 items. Default: `"\n \\subitem "`.

`item_2`

  put between two level 2 items. Default: `"\n \\subsubitem "`.

`item_01`

  What is put between a level 0 item and a level 1 item. Default: `"\n \\subitem "`.

`item_x1`

  What is put between a level 0 item and a level 1 item in the case that the level 0 item doesn’t have any page numbers (as in `\index{aaa|see{bbb}}`). Default: `"\n \\subitem "`.

`item_12`

  What is put between a level 1 item and a level 2 item. Default: `"\n \\subsubitem "`.

`item_x2`

  What is put between a level 1 item and a level 2 item, if the level 1 item doesn’t have page numbers. Default: `"\n \\subsubitem "`.

`delim_0`

  Delimiter put between a level 0 key and its first page number. Default: a comma followed by a blank, `", "`.

`delim_1`

  Delimiter put between a level 1 key and its first page number. Default: a comma followed by a blank, `", "`.

`delim_2`

  Delimiter between a level 2 key and its first page number. Default: a comma followed by a blank, `", "`.

`delim_n`

  Delimiter between two page numbers for the same key (at any level). Default: a comma followed by a blank, `", "`.

`delim_r`

  What is put between the starting and ending page numbers of a range. Default: `"--"`.

`line_max`

  An integer. Maximum length of an index entry’s line in the output, beyond which the line wraps. Default: `72`.

`indent_space`

  What is inserted at the start of a wrapped line. Default: `"\t\t"`.

`indent_length`

  A number. The length of the wrapped line indentation. The default `indent_space` is two tabs and each tab is eight spaces so the default here is `16`.

`page_precedence`

  A document may have pages numbered in different ways. For example, a book may have front matter pages numbered in lowercase roman while main matter pages are in arabic. This string specifies the order in which they will appear in the index. The `makeindex` command supports five different types of numerals: lowercase roman `r`, and numeric or arabic `n`, and lowercase alphabetic `a`, and uppercase roman `R`, and uppercase alphabetic `A`. Default: `"rnaRA"`.

There are a number of other programs that do the job `makeindex` does. One is `xindy`, which does internationalization and can process indexes for documents marked up using LaTeX and a number of other languages. It is highly configurable, both in markup terms and in terms of the collating order of the text, as described in its documentation.

#### `\printindex`

Synopsis:

    \printindex

Place the index into the output.

To get an index you must first include `\usepackage{makeidx}\makeindex` in the document preamble and compile the document, then run the system command `makeindex`, and then compile the document again. See Indexes for further discussion and an example of the use of `\printindex`.

### Glossaries

Synopsis:

    \usepackage{glossaries} \makeglossaries
      ...
    \newglossaryentry{label}{settings}
      ...
    \gls{label}.
      ...
    \printglossaries

The `glossaries` package allows you to make glossaries, including multiple glossaries, as well as lists of acronyms.

To get the output from this example, compile the document (for instance with `pdflatex filename`), then run the command line command `makeglossaries filename`, and then compile the document again.

    \documentclass{...}
    \usepackage{glossaries} \makeglossaries
    \newglossaryentry{tm}{%
      name={Turing machine},
      description={A model of a machine that computes.  The model is simple
                   but can compute anything any existing device can compute.
                   It is the standard model used in Computer Science.},
      }
    \begin{document}
    Everything begins with the definition of a \gls{tm}.
      ...
    \printglossaries
    \end{document}

That gives two things. In the main text it outputs ‘`... definition of a Turing machine`’. In addition, in a separate sectional unit headed ‘`Glossary`’ there appears a description list. In boldface it says ‘`Turing machine`’ and the rest of the item says in normal type ‘`A model of a machine … Computer Science`’.

The command `\makeglossary` opens the file that will contain the entry information, `root-file.glo`. Put the `\printglossaries` command where you want the glossaries to appear in your document.

The `glossaries` package is very powerful. For instance, besides the commands `\newglossaryentry` and `\gls`, there are similar commands for a list of acronyms. See the package documentations on CTAN.

#### `\newglossaryentry`

Synopsis, one of:

    \newglossaryentry{label}
    {
      name={name},
      description={description},
      other options, ...
    }

or

    \longnewglossaryentry{label}
    {
      name={name},
      other options ...,
    }
    {description}

Declare a new entry for a glossary. The label must be unique for the document. The settings associated with the label are pairs: `key=value`.

This puts the blackboard bold symbol for the real numbers ℝ in the glossary.

    \newglossaryentry{R}
    {
      name={\ensuremath{\mathbb{R}}},
      description={the real numbers},
    }

Use the second command form if the description spans more than one paragraph.

For a full list of keys see the package documentation on CTAN but here are a few.

`name`

  (Required.) The word, phrase, or symbol that you are defining.

`description`

  (Required.) The description that will appear in the glossary. If this has more than one paragraph then you must use the second command form given in the synopsis.

`plural`

  The plural form of name. Refer to the plural form using `\glspl` or `\Glspl` (see \gls).

`sort`

  How to place this entry in the list of entries that the glossary holds.

`symbol`

  A symbol, such as a mathematical symbol, besides the name.

#### `\gls`

Synopsis, one of:

    \gls{label}
    \glspl{label}
    \Gls{label}
    \Glspl{label}

Refer to a glossary entry. The entries are declared with `\newglossaryentry` (see \newglossaryentry).

This

    \newglossaryentry{N}{%
      name={the natural numbers},
      description={The numbers $0$, $1$, $2$, $\ldots$\@},
      symbol={\ensuremath{\mathbb{N}}},
      }
      ...
    Consider \gls{N}.

gives the output ‘`Consider the natural numbers`’.

The second command form `\glspl{label}` produces the plural of name (by default it tries adding an ‘`s`’). The third form capitalizes the first letter of name, as does the fourth form, which also takes the plural.