6.1.2 Creating Glossaries, Lists of Symbols or Acronyms (glossaries package)

There are a number of packages available to assist producing a list of acronyms (such as the acronym package) or a glossary (such as the nomencl package). You can see a list of available packages in the OnLine TeX Catalogue's Topic Index [3]. Here, I've chosen to describe the glossaries package. Firstly, it encompasses the functionality of both acronym and nomencl as glossaries allows you to define multiple lists of acronyms, lists of symbols or glossaries. Secondly, I wrote the glossaries package, so it's the one with which I am most familiar.

The glossaries package is very flexible, but the downside to that is that it has too many features to cover briefly. I'm therefore only going to introduce the basics here. If you want more detail you'll have to read the user manual [16]. I will use the term “glossary” to mean a list of terms or a list of notation or a list of symbols or a list of acronyms.

Note:

⚠

If you want to use both glossaries and hyperref, you must load hyperref before glossaries. This is an exception to the usual advice of loading hyperref last.

6.1.2.1 Defining Glossary Entries

Firstly, in order to make the glossary (or glossaries, if you have more than one) appear, you must use the command

\makeglossaries

in the preamble. This is analogous to the \makeindex command described in §6.1.1. Creating an Index (makeidx package).

Next you need to define the terms you want to appear in the glossary. This is done using the command:

\newglossaryentry{<label>}{<key-val list>}

The first argument <label> is a unique label so that you can refer to this entry in your document text. The entry will only appear in the glossary if you have referenced it in the document using one of the commands listed later. The second argument is a comma-separated list of <key>=<value> options. Common keys are:

name
The name of the entry (as it will appear in the glossary).
description
A brief description of this entry (to appear in the glossary).
text
How this entry will appear in the document text where the singular form is required. If this key is omitted the value of name will be used.
first
How this entry will appear in the document text the first time it is used, where the first use requires the singular form. If this key is omitted the value of text is used.
plural
How this entry will appear in the document text where the plural form is required. If this key is omitted, the value is obtained by appending the letter “s” to the value of the text key.
firstplural
How this entry will appear in the document text the first time it is used, where the first use requires the plural form. If this field is omitted, the value is obtained by appending the letter “s” to the value of the first key.
symbol
This key is provided to allow the user to specify an associated symbol, but most glossary styles ignore this value.
sort
This value indicates how to sort this entry (analogous to using the @ character in the argument of \index, as described in §6.1.1. Creating an Index (makeidx package)). If this key is omitted the value of name is used.
type
This is the glossary type to which this entry belongs (see §6.1.2. Defining New Glossaries). If omitted the main (default) glossary is assumed.

Examples:

The following defines the term “set” and assigns a brief description. The term is given the label set. This is the minimum amount of information you must give:

\newglossaryentry{set}% the label {% name={set},% the term description={a collection of objects}% a brief description }

The following entry also has an associated symbol:

\newglossaryentry{U}% the label {% name={universal set},% the term description={the set of all things},% a brief description symbol={\ensuremath{\mathcal{U}}}% the associate symbol }

The plural of the word “matrix” is “matrices” not “matrixs”, so the term needs the plural form set explicitly:

\newglossaryentry{matrix}% the label {name={matrix},% the term description={a rectangular table of elements},% brief description plural={matrices}% the plural }

The glossaries package also provides the shortcut command:

\newacronym[<key-val list>]{<label>}{<abbrv>}{<long>}

The default behaviour of this command is equivalent to:

\newglossaryentry{<label>}{name={<abbrv>}, description={<long>}, text={<abbrv>}, first={<long> (<abbrv>)}, plural={<abbrv>s}, firstplural={<long>s (<abbrv>s)}, <key-val list>}

Example:

\newacronym{svm}{SVM}{support vector machine}

is equivalent to

\newglossaryentry{svm}% the label {% name={SVM},% description={support vector machine},% first={support vector machine (SVM)},% firstplural={support vector machines (SVMs)},% text={SVM},% plural={SVMs}% }

There are some package options that modify the behaviour of \newacronym. For example, the package option description changes \newacronym so that you need to explicitly set the description in the optional argument. For example:

\usepackage[description]{glossaries}

\newacronym[description={a statistical pattern recognition technique}]{svm}{SVM}{support vector machine}

Another package option is footnote which will modify the behaviour of \newacronym so that the long form is displayed as a footnote on first use. For a full list of available options, see the glossaries documentation [16].

6.1.2.2 Displaying Terms in the Document

Any glossary term that has been defined using \newglossaryentry or \newacronym, as described above, can be displayed in the document using one of the commands described in this section. (There are other less commonly used commands available as well, see the glossaries documentation [16] for details of them.)

Each term has an associated first use flag. This is a boolean (true/false) switch that determines whether or not the entry has been used. This is how the glossaries package determines whether to display the value of the first key or to display the value of the text key. You can reset this flag using:

\glsreset{<label>}

Conversely, you can unset it using:

\glsunset{<label>}

To display a term that has previously been defined using either \newglossaryentry or \newacronym you can use one of the following commands:

\gls[<options>]{<label>}[<insert>]

\glspl[<options>]{<label>}[<insert>]

\Gls[<options>]{<label>}[<insert>]

\Glspl[<options>]{<label>}[<insert>]

These commands all have the same syntax: <label> is the label that uniquely identifies the term (as supplied in \newglossaryentry or \newacronym), <insert> is additional text to insert after the term (but inside the hyperlink, if used with the hyperref package), and <options> is a <key>=<value> list of options. Available options are:

format
This specifies how to format the associated location for this entry. It is analogous to the | special character used in \index (see §6.1.1. Setting the Location Format). As with \index, the format must not include the initial backslash. For example, format=textbf indicates that the location should be displayed in bold. (If you are using the hyperref package, you should use the hyper<xx> formats instead, such as hyperbf, see the glossaries documentation [16] for further detail.)
counter
This specifies which counter to use for the associated location in the glossary. This is usually the page number, but can be changed to, say, the section in which the term is used.
hyper
This is a boolean key which can be used to enable/disable the hyperlink to the relevant entry in the glossary. Note that setting hyper=true will only have an effect if hyperlinks are supported (through loading the hyperref package before loading the glossaries package). The above commands all have starred versions that are a shortcut for hyper=false. For example \gls*{svm} is equivalent to \gls[hyper=false]{svm}.

The above commands \gls and \Gls will display the value of the first or text key, depending on whether or not the entry has already been used. Similarly, \glspl and \Glspl will display the value of the firstplural or plural key, depending on whether or not the entry has already been used. The upper case forms, \Gls and \Glspl, will capitalise the first letter.

Example:

Suppose I have defined the following entry:

\newglossaryentry{matrix}% the label {name={matrix},% the term description={a rectangular table of elements},% brief description plural={matrices}% the plural }

Then (later in the document)

will display:

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

If you have used the symbol key when you defined a term, you can access its value with:

\glssymbol[<options>]{<label>}[<insert>]

This has the same syntax as commands like \gls but it doesn't affect or query the first use flag.

Terms that have been defined using \newacronym can also be referenced using the commands:

\acrshort[<options>]{<label>}[<insert>]
\Acrshort[<options>]{<label>}[<insert>]

\acrlong[<options>]{<label>}[<insert>]
\Acrlong[<options>]{<label>}[<insert>]

\acrfull[<options>]{<label>}[<insert>]
\Acrfull[<options>]{<label>}[<insert>]

These commands don't affect the first use flag. The first two (\acrshort and \Acrshort) will display the abbreviation only, the middle two (\acrlong and \Acrlong) will display the long form only, and the last two (\acrfull and \Acrfull) display both the long and short form. These commands have the same syntax as \gls and \Gls.

If you find these commands a little long-winded to type, you can use the package option shortcuts, which will provide shorter synonyms, such as \acs, \acl and \acf. This option also defines \ac which is equivalent to \gls. See the glossaries user guide [16] for further details.

Another Example:

Suppose I have defined an acronym as follows:

\newacronym{svm}{SVM}{support vector machine}

Then (later in the document):

First use: \gls{svm}\@. Next use: \gls{svm}\@. Short: \acrshort{svm}\@. Long: \acrlong{svm}. Full: \acrfull{svm}\@.

produces:

(Recall \@ from Volume 1.)

Note:

⚠

Avoid using commands like \gls in section headings or captions. Instead, use commands like:

\glsentrytext{<label>}

(displays the value of the text key without a hyperlink) or

\glsentryfirst{<label>}

(displays the value of the first key without a hyperlink). These commands don't affect the first use flag. For related commands, see the glossaries user guide [16].

⚠

Take care if you want to use the uppercase variants, such as \Gls or \Acrlong. If the first letter is an accent (either entered using accents commands such as \'{e} or entered directly such as é with the inputenc package) then you must group that letter when you define the term.

Example:

\newglossaryentry{elite}% label {% name={{é}lite},% description={select group or class}% }

6.1.2.3 Defining New Glossaries

If you want the list of acronyms to be separate from the main glossary, you need to use the package option acronym. This will change the effect of \newacronym so that it adds the term to the list of acronyms instead of to the main glossary.

You can also define your own custom glossaries using

\newglossary[<log-ext>]{<name>}{<in-ext>}{<out-ext>}{<title>}[<counter>]

where <name> is a label that uniquely defines this new glossary and <title> is the title to be used when the glossary is displayed in the document via \printglossary or \printglossaries, see §6.1.2. Displaying Glossaries. The other mandatory arguments, <in-ext> and <out-ext>, specify the file extensions to give to the input and output files for this new glossary. The first optional argument <log-ext> is the extension for the log file. This information is provided for the benefit of the makeglossaries application. The final optional argument <counter> is the name of the counter used by default in the location lists for this new glossary. If omitted, the page counter is used (unless overridden by the counter package option).

Note:

⚠

All glossaries must be defined before \makeglossaries to ensure that the relevant output files are opened.

Example:

The following defines a new glossary called “notation”:

\newglossary[nlg]{notation}{not}{ntn}{Notation}

When it gets displayed (using \printglossary or \printglossaries) the title will default to “Notation”. I now need to use the type key if I want to define an entry to go in this new glossary:

\newglossaryentry{not:set}% label {% type=notation,% glossary type name={$\mathcal{S}$},% description={A set},% sort={S}% }

Later in the document I can use this entry:

A \gls{not:set} is a collection of objects.

6.1.2.4 Displaying Glossaries

Now that you know how to define entries and how to use them in the document text, let's now look at the more complicated task of displaying the glossaries. To display all the defined glossaries use:

\printglossaries

To only display a particular glossary use:

\printglossary[<options>]

where <options> is a comma-separated list of <key>=<value> options. Available keys:

type
The glossary to print. If omitted, the main (default) glossary is assumed.
style
The glossary style to use. There are a lot of predefined styles to choose from, such as list, long or tree. See the glossaries user manual [16] for further details.
title
Overrides the default title for this glossary.
toctitle
Overrides the default title for the table of contents.
numberedsection
Put this glossary in a numbered section (instead of an unnumbered section).
nonumberlist
Suppress the location lists for this glossary.

Note:

⚠

By default, the glossaries aren't added to the table of contents. If you want them added to the table of contents use the package option toc.

\usepackage[toc]{glossaries}

Only those entries that have been used in the document (via commands like \gls) are displayed in the glossary. If you want to add an entry without displaying it in the document, use

\glsadd[<options>]{<label>}

where <label> is the unique label identifying the entry. The optional argument <options> is the same as for commands like \gls except there is no hyper key.

Alternatively, you can add all defined entries using:

\glsaddall[<options>]

where <options> is the same as for \glsadd except that there is also a types key where the value should be a comma-separated list of all the glossaries to iterate over. For example, to add all entries defined in the “acronym” glossary and the “notation” glossary, but not the “main” glossary:

\glsaddall[types={acronym,notation}]

Note:

⚠

As with \printindex the glossaries won't be displayed until the relevant files have been created either by makeindex or by xindy. Unlike in §6.1.1. Creating an Index (makeidx package), if you want to use xindy to create your glossary files, you can't use the texindy wrapper but must either use xindy directly or use the makeglossaries wrapper, described below. If you want to use xindy with the glossaries package, you must use the xindy package option:

\usepackage[xindy]{glossaries}

If omitted, makeindex will be assumed.

If you have Perl installed, you can use the makeglossaries application that comes with the glossaries package. If you have been using latexmk or xindy, then you already have Perl installed. If you don't want to install Perl for some reason, there's a Java alternative to makeglossaries called makeglossariesgui that's available from CTAN . However, if you don't install Perl, you are restricting your options as you won't be able to use xindy^6.1.

If you are using arara (see §1.1.2. Arara), then all you need to do is add another % arara: directive in your source code:

% arara: makeglossaries

If you are using latexmk, then make sure you have added the custom dependencies for .gls as described in §1.1.1. LaTeXmk. If you are not using any automated tool to build your document, you will have to invoke makeglossaries between (PDF)LaTeX runs (see §1.1. Building Your Document).

Adding to Listing 19:

Listing 20:

% In the preamble: % arara: pdflatex: { synctex: on } % arara: biber % arara: makeglossaries % arara: makeindex % arara: pdflatex: { synctex: on } % arara: pdflatex: { synctex: on } \documentclass[oneside,12pt]{scrbook} \usepackage[toc,acronym]{glossaries} \newglossary[nlg]{notation}{not}{ntn}{Notation} \makeglossaries \newglossaryentry{matrix}% the label {name={matrix},% the term description={a rectangular table of elements},% brief description plural={matrices}% the plural } \newacronym{svm}{SVM}{support vector machine} \newglossaryentry{not:set}% label {% type=notation,% glossary type name={$\mathcal{S}$},% description={A set},% sort={S}% } % Later in the document:

\Glspl{matrix} are usually denoted by a bold capital letter, such as $\mathbf{A}$. The \gls{matrix}['s] $(i,j)$th element is usually denoted $a_{ij}$. \Gls{matrix} $\mathbf{I}$ is the identity \gls{matrix}.

First use: \gls{svm}\@. Next use: \gls{svm}\@. Short: \acrshort{svm}\@. Long: \acrlong{svm}. Full: \acrfull{svm}\@.

A \gls{not:set} is a collection of objects.

% At the end of the document: \backmatter \printglossaries

6.1.2.5 Troubleshooting

If you run into difficulties with the glossaries package, first consult the glossaries FAQ. You can also check my bug tracker if you think you've stumbled on a bug. If you are using TeXnicCenter instead of TeXworks, there are instructions on how to get TeXnicCenter to run makeglossaries in an article I wrote on the LaTeX Community's Know How section [13].

If you're completely confused about how to generate the glossary files, you might want to consider using datagidx instead, described next.

Footnotes

...xindy ^6.1: or a lot of other useful Perl scripts, such as epstopdf

⇦

⇧

⇨

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