glossaries package FAQ

How do I change the way the text appears when I use commands like \gls? 🔗

As from version 4.0, commands like \gls and \glspl use \glsentryfmt to display the relevant information. Within the definition of this commands, you may use \glslabel to access the entry’s label, \ifglsused to determine if the entry has been used, \glsifplural to determine if the plural form is required, \glscapscase to determine if a case change is required, \glsinsert to access the additional text provided by the final optional argument of commands like \gls, and \glscustomtext to access the text provided by \glsdisp. If you want different glossaries to have different formats, you can use \defglsentryfmt instead of redefining \glsentryfmt. See the section Changing the format of the link text in the user manual for further information.

If you simply want to append information you might want to consider using the post-link hook. With glossaries-extra, this can be done on a per-category basis. See Gallery: Units (glossaries-extra.sty) for an example.

Versions prior to glossaries v4.0:

Commands like \gls and \glspl use \glsdisplayfirst and \glsdisplay to display the relevant information. The former command is used on first use and the latter command is used subsequently. Both commands take four arguments: the first is either the singular or plural form given by the text, plural, first or firstplural keys (used when the term was defined) depending on context. The second argument is the term’s description (as supplied by the description key), the third argument is the symbol associated with the term (as supplied by the symbol key) and the fourth argument is the additional text supplied in the final optional argument to \gls or \glspl (or their uppercase variants). The default simply prints the first argument immediately followed by the fourth argument and ignores the remaining arguments.

For example, suppose you want a glossary of measurements and units, you can use the symbol key to store the unit:

\newglossaryentry{distance}{name=distance,
description={The length between two points},
symbol={km}}
and now suppose you want \gls{distance} to produce “distance (km)” on first use, then you can redefine \glsdisplayfirst as follows:
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
Note that the additional text is placed after #1, so \gls{distance}['s] will produce “distance’s (km)” rather than “distance (km)’s” which looks a bit odd (even though it may be in the context of “the distance (km) is measured between the two points” — but in this instance it may be better not to use a contraction).

Caveat: care needs to be taken if you want to use the symbol within the text as the symbol key is sanitized by default (pre-v4.0). This means that any commands within the symbol will not be interpreted which can lead to strange results. If you do want to redefine \glsdisplay or \glsdisplayfirst so that the symbol is used, you need to use the package option sanitize={symbol=false} and protect fragile commands within the symbol key.

Remember that you need to use a glossary style that displays the symbol if you use the symbol key as many of the styles ignore it.

2020-07-01 14:15:03


Permalink: https://www.dickimaw-books.com/faq.php?id=53
Alternative link: https://www.dickimaw-books.com/faq.php?itemlabel=glsdisplay

Category: glossaries package
Topic: Referencing Terms