Smile for the Camera: a new cybercrime short story ebook.

Gallery: Abbreviations with Footnotes Sample

image of sample document showing abbreviations in text with footnote markers and a glossary
This example compares the footnote and postfootnote abbreviation styles provided by the glossaries-extra package. (I’ve used the -sc variant that sets the abbreviation in small-caps for illustrative purposes. Remove the -sc part of the style name for the basic version.)

In order to compare the two styles, I’ve created two glossaries (fn for the footnote style and postfn for the postfootnote style) and two categories that happen to have the same labels as the glossaries (fn and postfn) although this isn’t a requirement. When I set the style using \setabbreviationstyle, I need to use the category label in the optional argument, and when I define the abbreviations I need to use type to identify the glossary and category to identify the category. Since I’ve defined custom glossaries, I don’t need the default main glossary, so I’ve suppressed its creation using nomain.

I’ve decided to give my abbreviations a description in addition to the long form for illustrative purposes. There’s no -desc variant of the footnote styles, so the explicit use of the description key will suppress the appearance of the long form in the glossary, but I can use the post-description hook \glsxtrpostdesccategory to automatically insert the long form after the description: 

\newcommand*{\glsxtrpostdescfn}{ (\glsentrylong{\glscurrententrylabel})}
\newcommand*{\glsxtrpostdescpostfn}{ (\glsentrylong{\glscurrententrylabel})}

The footnote abbreviation style inserts \footnote{long} into the link text on first use. 

\documentclass{article}

\usepackage{hyperref}

\begin{document}
\hyperlink{A}{TargetA \hyperlink{B}{TargetB}}.

\newpage
\hypertarget{A}{A}

\newpage
\hypertarget{B}{B}
\end{document}

This nesting means that the text “TargetB” is trying to point to both target A (on page 2) and target B (on page 3). How does the PDF viewer deal with this conflict?

If I compile this document using pdflatex or lualatex and then:

If I compile this document using xelatex then:

If I compile this document using latex, dvips and ps2pdf, then the outer link is discarded and only the inner link (to target B) remains.

This unpredictable behaviour and the general ambiguity of nested links means that it’s best to avoid the problem by removing one of the links.

The postfootnote abbreviation style avoids the problem by deferring the \footnote{long} to the post-link hook so that it occurs outside the link text. Since it’s now in the post-link hook, it can also look ahead to determine if it’s followed by a known punctuation character. If it is, the footnote marker is placed after the punctuation to make the line a little neater.

With the postfootnote style, since there are no nested hyperlinks, I can be confident that if I click on the term (html or css in this example), I’ll be directed to the entry in the glossary, and if I click on the footnote marker, I’ll be directed to the footnote.

There is one minor drawback here. With the default boxed link style, it’s obvious where one link ends and the next link starts, but with hyperref’s colorlinks option, it’s less obvious. If you want to use the postfootnote style for its ability to check for following punctuation but you don’t want the abbreviation hyperlinked to the glossary on first use, you can set the nohyperfirst attribute. For example: 

\glssetcategoryattribute{postfn}{nohyperfirst}{true}

The initial comment lines below are arara directives. You can remove them if you don’t use arara. 

% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage[colorlinks]{hyperref}
\usepackage
 [nomain,% don't create main glossary (custom glossaries defined)
  nopostdot=false % don't suppress the post description period
 ]
 {glossaries-extra}

% Define glossaries for this document:
\newglossary*{fn}{Glossary (short-sc-footnote)}
\newglossary*{postfn}{Glossary (short-sc-postfootnote)}

\makeglossaries

% Set the abbreviation styles for the "fn" and "postfn" categories:
\setabbreviationstyle[fn]{short-sc-footnote}
\setabbreviationstyle[postfn]{short-sc-postfootnote}

% Append the long form after the description in the glossary
% for the "fn" and "postfn" categories.

\newcommand*{\glsxtrpostdescfn}{ (\glsentrylong{\glscurrententrylabel})}
\newcommand*{\glsxtrpostdescpostfn}{ (\glsentrylong{\glscurrententrylabel})}

% Define the abbreviations for the category "fn" and glossary
% type "fn"

\newabbreviation[category=fn,type=fn,
 description={standard system for tagging files used in web pages}]
 {html1}{html}{hypertext markup language}
\newabbreviation[category=fn,type=fn,
 description={style sheet language describing the document presentation}]
 {css1}{css}{cascading style sheets}

% Define the abbreviations for the category "postfn" and glossary
% type "postfn"

\newabbreviation[category=postfn,type=postfn,
 description={standard system for tagging files used in web pages}]
{html2}{html}{hypertext markup language}
\newabbreviation[category=postfn,type=postfn,
 description={style sheet language describing the document presentation}]
{css2}{css}{cascading style sheets}

\begin{document}
\section{short-sc-footnote style}

Websites use \gls{html1}, often in combination with \gls{css1}, to
markup the page content.

\section{short-sc-postfootnote style}

Websites use \gls{html2}, often in combination with \gls{css2}, to
markup the page content.

\printglossaries

\end{document}

If you don’t use arara, you need to run the following commands: 

pdflatex abbrv-footnote
makeglossaries abbrv-footnote
pdflatex abbrv-footnote

(See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.)

Download: PDF (98.95K), source code (1.92K).