glossaries-extra package FAQ
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