LaTeX glossaries quick start (acronyms and terms)

Published 2023-12-30T12:30+02:00 Author Sampo Rapeli Available in en ↩ All posts

I faced a few issues setting up a glossary and list of acronyms in a LaTeX document, so here are the steps to hopefully help my future self.

Background

LaTeX can keep track of acronyms and terms used in the text and automatically create lists of them. This is useful since I can simply reference an acronym, and LaTeX will use the correct form (abbreviation, long-form, or both compared). LaTeX can also link the acronyms and terms between the text and the glossary lists. Automating things like this is precisely what makes LaTeX so good for writing. In fact, the ease of referencing literature and managing reference lists is what first intrigued me when getting started with LaTeX, and it’s very similar to working with glossaries.

The package acro is sometimes used for defining, using, and listing acronyms. I tried that first, and it seems to work all right, but if you need a glossary in addition to a list of acronyms, consider using glossaries for both. In my opinion, glossaries provides a more intuitive syntax for defining the acronyms, and it handles both acronyms and glossaries simultaneously and similarly.

Setup

Install `texlive-glossaries-english`

Seems like I had the glossaries TeX Live package already installed, but the package for English was missing. I installed that alongside the Finnish variant with openSUSE’s package manager:

sudo zypper in texlive-glossaries-english texlive-glossaries-finnish

Preamble setup

Before \begin{document}, set up glossaries:

\usepackage[toc,acronyms,nonumberlist]{glossaries}
\makeglossaries

Configure the list of options to your liking. Here’s a cheat sheet for some of those:

Option	Description
`acronyms`	Allow using acronyms
`nonumberlist`	Do not include a list of page numbers where the item is referenced after each glossary entry
`nopostdot`	Remove the dot after each entry in the glossary and acronym lists
`toc`	Include the headings (“Glossary” and “Acronyms” by default) to the Table of Contents

Configure `latexmk`

This is the step that I had the most trouble with. I use VimTeX for adding some LaTeX support to Neovim, which in turn uses latexmk to compile my LaTeX documents on each save. Naturally, since the compilation has always “just worked”, I assumed it handles glossaries without issues. However, as of the time of writing, latexmk doesn’t take the necessary steps to compile the glossaries. When I ran makeglossaries main, the glossaries were updated. However, what’s the point of automatic compilation if it only compiles some parts of the document? I came across this wonderful answer and added the following to my ~/.latexmkrc:

# https://tex.stackexchange.com/a/541990
# License: CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>
add_cus_dep( 'acn', 'acr', 0, 'makeglossaries' );
add_cus_dep( 'glo', 'gls', 0, 'makeglossaries' );
$clean_ext .= " acr acn alg glo gls glg";
sub makeglossaries {
     my ($base_name, $path) = fileparse( $_[0] );
     my @args = ( "-d", $path, $base_name );
     if ($silent) { unshift @args, "-q"; }
     return system "makeglossaries", @args;
}

Now, the whole document, including glossaries, is updated after saving.

Define acronyms

% defining an acronym
% Format: \newacronym{label}{ABBREVIATION}{long-form of the term}
% Example:
\newacronym{cli}{CLI}{command-line interface}

Define terms

% defining a glossary item
% Format: \newglossaryentry{label}{name={term name},description={term description}}
% Example:
\newglossaryentry{cmd}{name={command line},description={a type of text interface for inputting commands for a system}}

Use the acronyms and terms

The primary way of referencing the defined acronyms and terms is \gls{label}. When an acronym is first referenced with \gls, the long form is printed, and the acronym itself is added in (parenthesis). Now that we’ve introduced the acronym to the reader, using \gls later only prints out the abbreviation.

Sometimes, \gls is not enough, for example, when we need the term in plural form or with a capital letter. Here’s a small cheat sheet for different commands that can be used for both acronyms and terms:

Command	Explanation
`\gls{label}`	Print the entry
`\Gls{label}`	Print the entry with a capital first letter
`\glspl{label}`	Print the entry in plural
`\Glspl{label}`	Print the entry in plural with a capital first letter
`\glslink{label}{text}`	Reference the term, but use `text` instead of the usual text value
`\glslink{label}{text}`	Reference the term, but use `text` instead of the usual text value

And with acronyms, you can use these too:

Command	Explanation
`\acrlong{label}`	Print the long-form
`\acrshort{label}`	Print the abbreviation only
`\acrfull{label}`	Print both (as it’s printed in the first time referenced with `\gls{label}`)
`\glsreset{label}`	Reset the “first use” for label
`\glsresetall`	Reset the “first use” for all
`\glsunset{label}`	No “first use” for label, use abbreviation from the first reference
`\glsunsetall`	No “first use” for any acronyms

If you don’t want the term hyperlinked to the glossary, a star * can be appended after the command name: \gls*{label}.

Print the glossary and acronyms

Only acronyms and terms appropriately referenced, such as \gls{label}, are included in the lists by default. However, one can combine \glsaddall with \printglossaries to include all defined acronyms and terms, regardless of whether they are referenced in the document.

To print both entries separately and with custom titles:

% print the acronym list with a custom title
\printglossary[type=\acronymtype,title={My Acronym List},toctitle={Acronyms}]
% print the (default) glossary list with custom title
\printglossary[title={My Glossary},toctitle={Glossary}]

The title argument’s value is displayed in the text, while toctitle is used in the Table of Contents.

Example

\documentclass[english]{article}
\usepackage[toc,acronyms,nonumberlist]{glossaries}
\makeglossaries

\newacronym{cli}{CLI}{command-line interface}
\newacronym{zsh}{Zsh}{Z shell}
\newglossaryentry{cmd}{name={command line},description={a type of text interface for inputting commands for a system}}

\begin{document}

\tableofcontents

\printglossary[type=\acronymtype,title={My Acronym List},toctitle={Special Acronyms}]
\printglossary[title={My Glossary},toctitle={Special Glossary}]

\section{The \gls{cmd}}
\Gls{zsh} is a popular shell.
It is some systems' default \gls{cli}. For example, Apple's macOS ships the \acrlong{zsh} as the default \gls{cli}.
\Gls{cli} tools are important for developers.
However, \gls{zsh} is not the only shell available, and not all \glspl{cli} are
shells.

\end{document}

$The document produced by above LaTeX code$

Remember to configure latexmk as instructed above, or run makeglossaries manually to update the glossary and acronym list!

Further reference

I found the LaTeX wikibook’s Glossary chapter extremely helpful, and the cheat sheets here are largely based on that resource.

My dotfiles repository includes a template I’ve successfully used as a starting point when writing. It currently doesn’t have glossary support, but using this blog post to extend the template should be a breeze.