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.