glossaries package FAQ

Why shouldn’t I use commands like \gls in \section, \chapter, \caption etc? 🔗

The user manual cautions against using commands like \gls in the argument of sectioning commands (\chapter, \section, etc) or in \caption. The reason for this warning is that there are multiple issues, some more serious than others, that can occur if you ignore this warning.

If your document uses hyperref you will have nested hyperlinks. This can have serious implications, although it may not appear to when you view your PDF. Commands like \gls internally use \hyperlink (when hyperlinks are enabled) where the destination/target in the glossary is created using \hypertarget so the following example document illustrates a simplistic representation of what the glossaries package does:
```
\documentclass{report}

\usepackage[colorlinks]{hyperref}

\DeclareRobustCommand{\link}[1]{\hyperlink{#1}{#1}}

\begin{document}
\tableofcontents

\chapter{Test \link{target1}}

Test chapter.

\chapter{Test \link{target2}}

Test chapter.

\chapter*{List of Targets}

\begin{itemize}
\item \hypertarget{target1}{target1}
\item \hypertarget{target2}{target2}
\end{itemize}
\end{document}
```
Since this has a table of contents, two pdflatex calls are required. The second run causes a load of warnings from hyperref such as:
Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding): (hyperref) removing `\<let>-command' on input line 13.
This is because the PDF bookmarks aren’t typeset. They should merely be text that can be understood by the PDF viewer. In this case \hyperlink can’t be expanded to a simple string (piece of text) which is what’s causing all the problems. This can be overcome using \texorpdfstring:
```
\chapter{Test \texorpdfstring{\link{target1}}{target1}}
```
However a more serious issue still remains and that’s the nested hyperlinks in the table of contents. If you build the above example using pdflatex the table of contents will look a bit like:
1. Test target1 2
2. Test target2 3
where “Test target1” is a hyperlink to chapter 1 on page 2, but within that “target1” is a hyperlink to the “target1” entry on page 4. Similarly “Test target2” is a hyperlink to chapter 2 on page 3, but within that “target2” is a hyperlink to the “target2” entry on page 4.
So, if you click on “target1” where do you expect the PDF viewer to send you? Should it take you to page 2 or page 4? This is ambiguous and PDF viewers treat the nested link in different ways. For example, if I view the PDF in okular the link will take me to page 2 but if I view the same PDF in evince the link will take me to page 4. Another PDF viewer may have different behaviour, perhaps even produce an error. If you plan to distribute your PDF, people won’t be particularly impressed if you say “but you have to use xxx application to view it”, especially if they don’t have that application installed.
The first use flag is unset the first time commands like \gls are used. If any of these commands are placed in the argument of \caption or \chapter, \section etc then they will be first used in the list of figures/tables or table of contents. This may not make a difference for a general entry where the first/firstplural and text/plural values are identical but for abbreviations this means that the term will be fully expanded in the front matter but not in the main matter.
Each time a command like \gls is used, a line is written to the corresponding glossary file (which is later input by makeindex or xindy). If any of these commands appear in the front matter then that front matter location will also be added to the location list for that entry, which isn’t particularly helpful for the reader, especially if you’re only indexing the first use.

So what should you do if you want to use a term in a caption or sectioning command? It’s best to do as the user guide suggests and use one of the expandable commands such as \glsentrytext or \glsentrylong or \glsentryfull. Alternatively, have a look at the extension package glossaries-extra, which provides commands specifically for use in chapter or section headings.

2023-05-02 19:21:36

Permalink: https://www.dickimaw-books.com/faq.php?id=183
Alternative link: https://www.dickimaw-books.com/faq.php?itemlabel=whynoglsinsection

Category: glossaries package
Topic: Referencing Terms