# Glossaries and custom section headings broken

I've a document, where I use the glossaries to manage acronyms for me. Sometimes, I use a \gls{} command inside a section heading, and I have defined page headers to have the current section heading. However, when a section heading contains a \gls{} command, the headings for those pages render incorrectly, with what appears to be some code from the glossaries package appearing instead.

MWE:

\documentclass[a4paper, 12pt]{report}
\usepackage[toc,xindy,nonumberlist,acronym,shortcuts]{glossaries}
\usepackage{fancyhdr}
\begin{document}
\pagestyle{plain}
\pagestyle{fancyplain}
\renewcommand{\sectionmark}[1]{\markboth{\thesection #1}{}}
\newacronym{ecg}{ECG}{electrocardiogram}
\chapter{test}
\gls{ecg} is ecg
\pagebreak
\section{\gls{ecg}}
waffle here
\end{document}


I should note, I am compiling this with TL2011, but I have also had a friend with TL2013 test it.

• The user manual warns against using \gls in section headings as does the glossaries FAQ so try replacing \section{\gls{ecg}} with \section{\glsentryshort{ecg}} (also consider moving \newacronym to the preamble). – Nicola Talbot Aug 27 '14 at 11:04
• Is this not something that can be fixed? It presents quite a big usability hurdle for the whole package which is otherwise excellent. As an aside, I have no known issues when using \gls inside captions. – user1207217 Aug 27 '14 at 13:58

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:

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{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.

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}


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.

• Thank you very much. One quick question I have (which I couldn't seem to find the answer to in the documentation) - are the acr* commands expandable or not? – user1207217 Aug 28 '14 at 10:20
• @user1207217 They're not expandable. – Nicola Talbot Aug 28 '14 at 10:24
• Great answer and great package, @NicolaTalbot! Thanks a lot! :) – Kjetil Sonerud Jun 14 '15 at 17:35
• Is there a recommended method for using pluralized versions of acronyms in section headings? – ali_m Dec 3 '15 at 20:28
• Ah, just figured out that I could use \glsentryshortpl{}, Glsentryshort{}` in order to force pluralization, capitalization etc., although these variants don't seem to be mentioned in the official manual. – ali_m Dec 3 '15 at 20:50