I've a document, where I use the glossaries
package 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.
Best Answer
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
: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:
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: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 usepdflatex
the link will take me to\chapter
when I view the document withokular
, but to the definition in the glossary when I useevince
. If I uselatex
+dvips
+ps2pdf
the reverse happens.The PDF bookmarks also fail with this example, and
hyperref
issues the warning: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:
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: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:
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):With v4.10, this now causes an error:
This is because
\MakeUppercase
converts the label to upper case within the action of TeX's\mark
primitive. This issue isn't peculiar toglossaries
but also occurs in other cases. For example:This results in the warning:
and the reference will appear as ??
Summary
With just
glossaries
(withoutglossaries-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: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 withhyperref
, 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:
Alternatively, set up some mappings if your editor provides that facility.