glossaries-extra package FAQ
This is the FAQ for the glossaries-extra package. The glossaries-extra package implicitly loads the glossaries package, so also check the glossaries package as some queries or issues may stem from the base package. Related: bib2gls application.
See also the bug tracker (glossaries-extra category), the glossaries-extra user manual, and glossaries-extra and bib2gls: An Introductory Guide. Example documents can be found in the gallery, and articles are available on this site to help integrate indexing tools into the document build process.
- Problems related to selection and indexing with bib2gls
\glsxtrshort,\glsxtrlongand\glsxtrfull(and their case variants) aren’t indexing\glsaddalland\glsaddallunuseddon’t work with bib2gls- The abbreviation style isn’t correct
\printglossarydoesn’t work with bib2gls- The glossary listing order is incorrect
- My document only contains
\printunsrtglossarywith no section header and no PDF is created.
- Glossary Styles
- Cross-Referencing
Problems related to selection and indexing with bib2gls
This bug was fixed in version 1.30. For older versions you will need at least one instance of \gls.
Regardless of version, if you’re not using any instances of \gls for that abbreviation then you should consider using one of the long-noshort or short-nolong or long-only-short-only styles for that entry’s category. This is better from a coding point of view, as it will make it easier to change the style later if necessary, and, from a typing point of view, \gls is also shorter than \glsxtrshort etc (and \ac is shorter than \acl etc, if you are using shortcuts). If you need the full form for an instance other than first use but the short form elsewhere, then use the short-nolong style and use \glsxtrfull for the specific instance (unless it’s in a caption or section title, in which case use \glsfmtfull)
2020-07-02 11:24:51
If you need to include all entries provided in the .bib file(s), regardless of whether they’ve been indexed in the document, then you must use the selection=all resource option not \glsaddall or \glsaddallunused. These iterative commands can’t work with bib2gls because they iterate over all defined entries but the entries can’t be defined until they’ve been selected. The selection=all option works better than either of those commands as it doesn’t cause an unwanted location.
2020-07-02 11:35:12
Make sure you set the abbreviation style before the relevant \GlsXtrLoadResources. Also check the abbreviation definition in the .glstex file. Has the category field been set? Does the helper command provided to define the abbreviation (such as \bibglsnewabbreviation) set the category field? Check that the category matches the optional argument of \setabbreviationstyle. Remember that spaces are significant (including those created by the end of line character) and should be stripped from the category label.
2020-07-02 11:27:27
\printglossary (and the iterative \printglossaries) is designed to work with makeindex and xindy. If you’re using bib2gls you need to use \printunsrtglossary (or the iterative \printunsrtglossaries) instead.
In the rare event that you need to use bib2gls to select entries from the .bib files but need to use xindy to sort and collate (because of some custom xindy rule that can’t be implemented by bib2gls) then you need to use the record=alsoindex package option which should allow \printglossary to work.
2020-07-02 11:29:21
Open the .glstex file in a text editor and check the value of the sort field. This is the value used for the sort comparisons. (Special characters are marked up using commands like \glspercentchar. These were the actual character when bib2gls sorted the entries, but were replaced in order to write the sort value to the .glstex file without causing a syntax error when LaTeX parses it.)
- Has content been stripped? If the missing content is non-alphabetic, you may need to change the
break-atsetting. If the missing content consisted of LaTeX code, run bib2gls in verbose mode (bib2gls --verbose) and check the transcript file (.glg) for messages from the interpreter. - Has the sort value been obtained from the wrong field? Check the
sort-fieldand the various fallback settings, such assymbol-sort-fallbackandabbreviation-sort-fallback. See also Why doesn’tsymbol-sort-fallbackwork? and Gallery: sorting. - Have the sort values been replaced with 0? Then you’ve most likely used a numeric sort method on non-numeric values or the numeric pattern used by the parser is incorrect. Run bib2gls with the verbose mode on and check the transcript file (.glg) for messages.
- If the sort values are correct then check the sort method and, if
sort=custom, the sort rule.
If you have multiple .glstex files, these will form sorted sub-blocks.
2020-07-02 11:38:43
\printunsrtglossary with no section header and no PDF is created. 🔗Suppose you have a document that looks like:
\documentclass{article}
\usepackage[record]{glossaries-extra}
\GlsXtrLoadResources[src=example-glossaries-brief,
selection=all]
\begin{document}
\printunsrtglossary
\end{document}
On the first LaTeX run this will just create a single-paged document with the glossary section header but no glossary content. This is sufficient for the complete document build (LaTeX+bib2gls+LaTeX). A problem occurs if you suppress the section heading by redefining \glossarysection to do nothing:
\renewcommand{\glossarysection}[2][]{}
Now there’s no text on the first LaTeX run (before the .glstex file has been created). This means that no PDF file can be created and the .aux file simply contains \relax. There’s no information for bib2gls so the document build fails.
The analogous \printglossary inserts \null if the glossary file isn’t present to prevent this situation. (Why does \printglossary use \null when the glossary file is missing?) In this case, the section heading is inside the glossary file so there’s no text at all to display if the document simply contains \printglossary. This makes it far more problematic and there’s a greater need for the workaround that uses \null.
In the case of \printunsrtglossary, the only time this becomes a problem is when the document consists solely of a headerless glossary. This is far less likely to occur so adding \null to \printunsrtglossary doesn’t have a sufficient benefit to outweigh the possible problems it might cause.
If you require this particular situation, you will need to insert something (such as \null or \mbox{}) to ensure a page is output.
2020-07-14 19:33:08
Glossary Styles
\glslongextraNameFmt 🔗This bug was in glossary-longextra.sty v1.37 and is fixed in v1.38. If you have v1.37, it can be patched with:
\renewcommand{\glslongextraNameFmt}[1]{%
\glsentryitem{#1}\glstarget{#1}{\glossentryname{#1}}%
}
2020-07-02 11:39:34
Cross-Referencing
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
See Why does the see key automatically index the entry?
2022-02-09 16:05:13