Latest news 2021-09-06: new blog post "Legacy Documents and TeX Live Docker Images".

glossaries-extra package FAQ

Why doesn’t indexcrossrefs=true work? 🔗

The indexcrossrefs setting starts out as false but is automatically switched to true if an entry is defined with the see or seealso key set, unless indexcrossrefs has explicitly been set to false. This means that there’s usually little point in actually setting indexcrossrefs=true. The option is provided as a way of switching off the normal behaviour (indexcrossrefs=false).

The purpose of indexcrossrefs=true is to ensure that the targets are automatically indexed at the end of the document, if they haven’t been used.

Consider the following example with just the base glossaries package:

\documentclass{article}

\usepackage{glossaries}

\makeglossaries

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

\newglossaryentry{vector-product}{name={vector product},
 description={...},see=[see also]{dot-product}}

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

\printglossaries
\end{document}

After a complete build (LaTeX+makeglossaries+LaTeX), the glossary consists of a single entry:

vector product .... 1, see also dot product

The “1” is due to the indexing on page 1 (\gls{vector-product}). The “see also dot product” was created by the see key. (Why does the see key automatically index the entry?) The reference (dot product) hasn’t been indexed and so doesn’t appear in the glossary. This means that there’s a cross-reference to a non-existent item. If you were to add the hyperref package, you would get the following warning:

name{glo:dot-product} has been referenced but does not exist

In this situation you need to ask yourself why you want to cross-reference a term that’s not being used in the document. However, there are some situations where it is justified. For example, this document could be part of a series of articles about vector calculus and perhaps the previous article covered dot products. It then may be useful to the reader to include the term in the glossary as a reminder.

Now let’s use glossaries-extra:

\documentclass{article}

\usepackage{glossaries-extra}

\makeglossaries

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

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

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

\printglossaries
\end{document}

Now the glossary contains two items:

dot product ...

vector product ... 1, see also dot product

The indexcrossrefs option starts out as false, but when the “vector-product” entry is defined, the seealso key automatically switches this option on. This means that at the end of the document, a block of code is implemented that iterates over all defined entries: if any entry has been marked as used and has the see or seealso key set then, if the target (or targets) hasn’t been used in the document, it will then be indexed using the special glsxtrunusedformat encap (format). This is why “dot product” appears in the glossary without a location.

This end-of-document code that’s triggered by indexcrossrefs in an 𝒪(𝑛) operation, where 𝑛 is the total number of defined entries. This means that if you have a large number of entries, it can noticeably slow the document build. If you know that all cross-reference targets will be used in the document or you are working on an incomplete draft or if you want to be alerted to unused targets (through hyperref’s warning) then you can speed up the document build with indexcrossrefs=false.

It may be that what you actually want is to index any entry that cross-references an entry that’s been used in the document. Suppose I want to use “vector product” in the document but include “cross product” in the glossary as a synonym:

\documentclass{article}

\usepackage{glossaries-extra}

\makeglossaries

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

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

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

\printglossaries
\end{document}

The glossary now contains both entries:

cross product ... see vector product

vector product ... 1

This is because the see key was designed as a shortcut for \glssee, which means that the cross-reference is automatically added to the glossary. (Why does the see key automatically index the entry?) If you decide to disable this behaviour with autoseeindex=false:

\usepackage[autoseeindex=false]{glossaries-extra}

Then the glossary will only contain one item:

vector product ... 1

If you want “cross product” to also be indexed, then you will need to index it explicitly:

The \gls{vector-product}\glssee{cross-product}{vector-product}...

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}.

2020-07-02 12:23:39


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

Category: glossaries-extra package
Topic: Cross-Referencing