Latest news 2021-06-05: New blog post: Dickimaw Books Site Account.

glossaries package FAQ

Why don’t commands like \gls and \glslink use implicit grouping? 🔗

The glossaries and glossaries-extra manuals warn against using nested links. One of the associated problems is caused by a lack of scope. This can be illustrated in the following:




\newacronym{html}{HTML}{hypertext markup language}
\newacronym{xhtml}{XHTML}{extensible \acrlong{html}}

Instead of displaying the expected “extensible hypertext markup language (XHTML)” it displays “extensible hypertext markup language (HTML)”. The short form in parentheses is incorrect. The problem is caused by the nested link text (\acrlong{html} is inside the link text for \gls{xhtml}). The problem appears to be fixed if grouping is added:
\newacronym{xhtml}{XHTML}{extensible {\acrlong{html}}}
So why doesn’t the glossaries package automatically include grouping?

The problem is the post-link hook, which is always used right at the end of all the \gls-like and \glstext-like commands. This hook needs to be able to both look ahead and look behind. For example, the postfootnote abbreviation style needs to look ahead to see if there’s a punctuation character, but it also needs to know which abbreviation has just been referenced and if it was the first use. If grouping is added internally, it will break either the look ahead or the look behind function. If the hook is inside the group, it can’t look ahead beyond the group, but if the hook is outside the group, it can no longer find out the information about the entry that’s just been referenced. Since the user is free to redefine the hook to whatever they want, they can’t really be expected to remember to close a group that they haven’t opened, and suddenly requiring this would break older documents.

Although this lack of scope causes the most common and visible problem, it’s not the only problem resulting from nested links. There are other, more subtle, problems that can cause inconsistent behaviour, odd warnings and obscure error messages that are difficult to diagnose and are unrelated to the lack of scope. So even if there was a way to add implicit grouping that didn’t break the post-link hook, it still wouldn’t fix all the other problems.

Note that the glossaries-extra package provides alternative commands that may be used in the link text that avoid some of these problems (but there are still some caveats to be aware of).

2020-06-28 15:39:26

Alternative link:

Category: glossaries package
Topic: Referencing Terms