Latest news 2020-05-02: new blog post "Book Samples."

glossaries package FAQ

FAQ Search Tips

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

(See also Why shouldn't I use commands like \gls in \section, \chapter, \caption etc?)

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:
  1. 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.)
  2. 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.
  3. 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}}

Last modified: 2016-03-22 04:28:58.


Category: glossaries package
Topic: Error Messages