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.
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.
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
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 |
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.
% defining an acronym
% Format: \newacronym{label}{ABBREVIATION}{long-form of the term}
% Example:
\newacronym{cli}{CLI}{command-line interface}
% 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}}
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}
.
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.
\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}
Remember to configure latexmk
as instructed above, or run makeglossaries
manually to update the glossary and acronym list!
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.
Join my blog's Telegram channel to get updates on new posts. I only publish one message to notify you about each new post. That's it. Nice and clean, distraction-free communication.
See my blog's front page to read my other posts.