Latest news 2021-09-06: new blog post "Legacy Documents and TeX Live Docker Images".

# 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:
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}}
```

2020-07-01 11:00:04