Glossaries and custom section headings broken

Both the user manual and the glossaries FAQ caution against using commands like gls in chapter or section headings (and also for captions). However, if you're using the extension package glossaries-extra, most of the associated problems can be overcome by using commands like glsfmttext, glsfmtshort, glsfmtlong or glsfmtfull instead of commands like gls:

documentclass{book}

usepackage{hyperref}
usepackage{glossaries-extra}

makeglossaries

setabbreviationstyle[acronym]{long-short}
newglossaryentry{sample}{name={sample},description={an example}}
newacronym{sa}{SA}{sample acronym}

pagestyle{plain}

begin{document}

tableofcontents

chapter{glsfmttext{sample}}

section{Full: glsfmtfull{sa}}

section{Short: glsfmtshort{sa}}

section{Long: glsfmtlong{sa}}

printglossaries

end{document}

With just the glossaries package, you have to use commands like glsentrytext, glsentryshort or glsentrylong, which don't contain any formatting commands.

The problems with using commands like gls in section headings are as follows:

1. Documents with a Table of Contents

Consider the following example:

documentclass{book}

usepackage{glossaries}

makeglossaries

newglossaryentry{sample}{name={sample},description={an example}}

pagestyle{plain}

begin{document}

tableofcontents

chapter{gls{sample}}

printglossaries

end{document}

This results in the table of contents page appearing in the location list for the sample entry. This isn't what most users expect, and it's not helpful for the reader.

Things get even worse when hyperref is added:

documentclass{book}

usepackage[colorlinks]{hyperref}
usepackage{glossaries}

makeglossaries

newglossaryentry{sample}{name={sample},description={an example}}

pagestyle{plain}

begin{document}

tableofcontents

chapter{gls{sample}}

printglossaries

end{document}

The line in the table of contents now has a nested link. The word "sample" is trying to link both to the page where chapter occurs and to the definition of "sample" in the glossary. Which one ends up as the actual target? If I use pdflatex the link will take me to chapter when I view the document with okular, but to the definition in the glossary when I use evince. If I use latex + dvips + ps2pdf the reverse happens.

The PDF bookmarks also fail with this example, and hyperref issues the warning:

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing `gls' on input line 20.

This is because gls is robust and can't be expanded to a simple string, so the command gls is discarded and just the label appears in the bookmark. In this case the label is the same as the text, but this isn't necessarily the case.

Now change the example so that it defines an acronym instead:

documentclass{book}

usepackage{glossaries}

makeglossaries

newacronym{sa}{SA}{sample acronym}

pagestyle{plain}

begin{document}

tableofcontents

chapter{gls{sa}}

printglossaries

end{document}

Here the "first use" occurs in the table of contents, so in the contents gls{sa} is expanded to its full form, but chapter{gls{sa}} now uses the short form. You can get around this by adding glsresetall after tableofcontents but inconsistencies can occur if the acronym is used after the table of contents but before chapter{gls{sa}}. For example:

documentclass{book}

usepackage{glossaries}

makeglossaries

newacronym{sa}{SA}{sample acronym}

pagestyle{plain}

begin{document}

tableofcontents
glsresetall

chapter{Sample}

gls{sa}

chapter{gls{sa}}

printglossaries

end{document}

Now the table of contents uses the full form but the actual chapter uses the short form. While you can specify an alternative chapter title for the TOC using the optional argument of chapter, this kind of discrepancy looks a bit weird as the optional argument is usually used to provide a shortened version of a long chapter title.

2. Documents with Headers

This is the case in your question. One of the changes in glossaries v4.10 makes it work a bit better in this case, but there are still instances when it fails.

First consider this example:

documentclass{book}

usepackage{lipsum}% dummy text
usepackage{glossaries}

makeglossaries

newacronym{sa}{SA}{sample acronym}

renewcommand*{chaptermark}[1]{markboth{chaptername thechapter}{#1}}

begin{document}

tableofcontents
glsresetall

chapter{gls{sa}}

lipsum[1-20]

printglossaries

end{document}

This now works with v4.10, but the headings use the short form as the acronym has already been used, so the headings are inconsistent with the chapter title and the corresponding line in the table of contents. In addition, the location list for this entry is now: 1, 3, 5, 7. The first page is the reference in the table of contents and pages 5 and 7 are caused by the reference in the header. While one author might want to suppress the location list, another might not and may be perplexed as to why the location list has so many entries.

However, even with v4.10 a problem occurs when MakeUppercase is used in the heading (which occurs by default):

documentclass{book}

usepackage{lipsum}% dummy text
usepackage{glossaries}

makeglossaries

newglossaryentry{sample}{name={sample},description={an example}}

renewcommand*{chaptermark}[1]{%
 markboth
  {MakeUppercase{chaptername thechapter}}
  {MakeUppercase{#1}}}

begin{document}

tableofcontents

chapter{gls{sample}}

lipsum[1-20]

printglossaries

end{document}

With v4.10, this now causes an error:

! Package glossaries Error: Glossary entry `SAMPLE' has not been defined.

This is because MakeUppercase converts the label to upper case within the action of TeX's mark primitive. This issue isn't peculiar to glossaries but also occurs in other cases. For example:

documentclass{book}

usepackage{lipsum}
usepackage{hyperref}

begin{document}
chapter{Sample}label{ch:sample}

lipsum

chapter{Following on from ref{ch:sample}}

lipsum

end{document}

This results in the warning:

LaTeX Warning: Reference `CH:SAMPLE' on page 4 undefined on input line 15.

and the reference will appear as ??

Summary

With just glossaries (without glossaries-extra), the only way to avoid all these issues is to use one of the expandable commands instead of the robust gls. For example glsentrytext for regular entries and one of glsentrylong, glsentryshort or glsentryfull for acronyms. For example:

documentclass{book}

usepackage{lipsum}% dummy text
usepackage{glossaries}

makeglossaries

newglossaryentry{sample}{name={sample},description={an example}}
newacronym{sa}{SA}{sample acronym}

renewcommand*{chaptermark}[1]{%
 markboth
  {MakeUppercase{chaptername thechapter}}
  {MakeUppercase{#1}}}

begin{document}

tableofcontents

chapter{glsentrytext{sample}}

lipsum[1-20]

chapter{glsentryfull{sa}}

lipsum[21-40]

printglossaries

end{document}

This works with MakeUppercase because the expansion is now performed before the case change is applied inside mark. There are also no discrepancies with the chapter title, the header and the table of contents entry and, if used with hyperref, this works with the PDF bookmarks and doesn't cause nested links.

If the thing that puts you off using those commands is merely the amount of typing, remember that you can define your own shortcut commands to use instead. For example:

newcommand*{gtxt}{glsentrytext}
newcommand*{glng}{glsentrylong}
newcommand*{gsht}{glsentryshort}

Alternatively, set up some mappings if your editor provides that facility.