glossaries package FAQ

Why does the see key automatically index the entry? 🔗

As mentioned in the user manual, the see key automatically implements \glssee because the see key was added as a simple shortcut for \glssee. With the base glossaries package, that’s all this key does. The value isn’t even saved. With the glossaries-extra package, the value is saved but its intended purpose is still a shortcut for \glssee.

The same feature applies to the seealso and alias cross-referencing keys provided by glossaries-extra. In the case of the alias key, this both indexes and adjusts the hyperlink target. The indexing for seealso is implemented with \glsxtrindexseealso instead of \glssee, but these commands work in a similar way.

For example, suppose you have a document about (mathematical) vectors and you want the glossary to contain the term “vector product”. This can be defined as follows:

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

Let’s suppose that in the document you only want to use this particular term for this kind of product, so you use \gls{vector-product}. However, this type of product is also known as a “cross product”, and it’s possible that your reader may try looking up the term by that name in the glossary, so it’s useful to provide a redirect:

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}
\glssee{cross-product}{vector-product}

This term isn’t used anywhere else in the document. It’s simply provided as a redirect. This is quite cumbersome, so when \glssee was added to glossaries.sty version 1.17 (2008-12-26), the see key was also provided at the same time as a convenient shortcut:

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc},
 see={vector-product}}

This catches out users who define an entry with the see key set but don’t actually want the entry in the document.

Note that this need to index the entry in order to add the cross-reference to the glossary is a quirk of the indexing applications. Makeindex treats “see” style references in the same way as normal indexing. The location formatting command (encap) simply discards the location number and inserts the “see …” text. Xindy has a slightly different syntax for cross-references but code still needs to be added to the file parsed by xindy which will add the entry to the output file (the glossary file input by \printglossary in this case).

So what do you do if you want a large database of terms that’s shared across multiple documents? The best solution is to switch to using bib2gls. This is the most efficient method in terms of overall document build time (see the 3. Alphabetical Order (Subset) section of the glossaries performance page). It’s also the best method in terms of managing the database (since a .bib management system, such as JabRef, can be used). The bib2gls resource option selection criteria can be used to determine whether or not to select cross-referenced entries.

If you don’t want to switch to bib2gls then there are other options:

Don’t use the see key. Use \glssee explicitly where required. For example, if the following terms have been defined:

\newglossaryentry{dot-product}{name={dot product},
 description={...}}

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}

then later in the document:

The \gls{vector-product}\glssee{cross-product}{vector-product}\glssee[see also]{vector-product}{dot-product} is...

...

The \gls{dot-product}\glssee[see also]{dot-product}{vector-product}...

This gives you greater control over exactly which cross-references are used on a per-document basis.

In the case of the alias key provided by glossaries-extra, you can set the alias field after defining the entry to enable the hyperlink target substitution without triggering the automatic indexing:

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}
\GlsXtrSetField{cross-product}{alias}{dot-product}

The glossaries-extra package provides the boolean package option autoseeindex. If true, the see key will automatically index the entry with \glssee (as per the base glossaries package). With glossaries-extra, this option may be set to false to prevent the automatic indexing. If you use this setting, you will need to find some other way of using \glssee if you actually want the cross-reference to appear in the glossary. This option also governs the automatic indexing of seealso and alias. For example, consider the following document:
```
\documentclass{article}
\usepackage[autoseeindex=false]{glossaries-extra}

\makeglossaries

\newglossaryentry{dot-product}{name={dot product},
 description={...}}

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc},see={vector-product}}

\begin{document}
The \gls{dot-product}...

\printglossaries
\end{document}
```
In this case the glossary will only contain the “dot product” entry. Again, you need to explicitly use \glssee to add the cross-reference. If you want to programmatically apply \glssee to any entries that cross-reference an entry that has been used, then (at the end of the document) you will need to iterate over all entries and, for those that have the see or seealso key set, find out if the targets have been used. If so, use \glssee[tag]{label}{target}.
If your intention is to have every entry in one glossary cross-reference a corresponding related entry in another glossary then a better approach is to use a hook (either a category hook or a more general glossary style hook) that automatically adds the cross-reference in the glossary. This is most easily achieved if the target entries in the second glossary have a labelling system that can be created by appending a prefix or suffix to the corresponding entry label in the first glossary.

2022-02-09 16:29:35

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

Category: glossaries package
Topic: Defining Terms