glossaries package FAQ

I get an error when using a glossary entry in a chapter/section heading or caption 🔗

With older versions of glossaries this occurs when you try to do something like:

\section{\gls{sample}}

If you are not using the hyperref package, you can fix this with \protect:

\section{\protect\gls{sample}}

With newer versions, \gls is now robust. However, it’s generally not a good idea to use commands like \gls or \glslink (or \acrshort etc) in chapter or section titles:

If you have a table of contents, the relevant line in the TOC will also have a link to the glossary, and the entry’s page list will include the table of contents page. (Same applies for \caption and the list of figures/tables.)
If you are using a page style that adds the chapter/section title to the page header, then each page header for that section will generate a link to the glossary.
If you are using the hyperref package, you will have a nested link in the table of contents and you will also cause a problem for the bookmarks.

It is therefore better to use the non-link creating commands, such as \glsentryname instead of \gls. For example:

\section{\glsentryname{sample}}

Alternatively, if you extend the glossaries package with glossaries-extra then you can use one of the commands listed in the section Entries in Sectioning Titles, Headers and Contents of the glossaries-extra user manual. For example:

\section{\glsfmttext{sample}}

but check the advisory notes in the manual.

If you don’t want to use glossaries-extra and you really want \gls in your chapter/section title, then use the optional argument to supply an alternative for the table of contents and page headers:

\section[\glsentryname{sample}]{\gls{sample}}

The same applies for captions. For versions prior to v4.0, if you get unexpected output in your page headers (e.g. something like ACRONYMNAME SAMPLE), then use the package option sanitize=none and protect fragile commands.

Note that prior to version 4.0, the commands that convert the first letter to upper case were all fragile and so required \protect:

\section{\protect\Glsentryname{sample}}

If you use the hyperref package, you’ll need to use \texorpdfstring:

\section{\texorpdfstring{\protect\Glsentryname{sample}}{Sample}}

For version 4.0 and above, you don’t need \protect, but you still need to provide an alternative for the PDF bookmarks:

\section{\texorpdfstring{\Glsentryname{sample}}{Sample}}

2022-11-02 11:13:42

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

Category: glossaries package
Topic: (La)TeX Errors