# glossaries package FAQ

The page numbers in my location lists are in an unexpected order 🔗

Both makeindex and xindy have a page precedence order. This means that the different types of location (lowercase Roman, uppercase Roman, numeric/arabic etc) will be ordered according to their type.

The default order of precedence for makeindex is rnaRA, which means lowercase Roman (r), numeric (n), lowercase alphabetic (a), uppercase Roman (R), uppercase alphabetic (A). However, there does seem to be some discrepancy between different versions of makeindex.

For example, consider the following document that uses makeindex to create the glossary:

\documentclass{report}
\usepackage{glossaries}

\makeglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printglossaries
\end{document}

According to makeindex's default page precedence this should result in the list: i, 1, I, which is the case with TeX Live 2022. However, with TeX Live 2021, the result is i, I, 1.

You can change the order of precedence by adding the page_precedence setting to the .ist file (which is created by \makeglossaries). If you directly edit the .ist file, you will need to add \noist before \makeglossaries to ensure that your modifications aren't lost. A simpler method is to use \GlsSetWriteIstHook before \makeglossaries. For example:

\documentclass{report}
\usepackage{glossaries}

\GlsSetWriteIstHook{%
\write\glswrite{page_precedence "RrnaA"}%
}

\makeglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printglossaries
\end{document}
This produces the list: I, i, 1.

Xindy also has an order of precedence. The original document can be modified to use xindy instead of makeindex:

\documentclass{report}
\usepackage[xindy]{glossaries}

\makeglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printglossaries
\end{document}
This produces the list: i, 1, I, which matches makeindex's default order. The order is given in the .xdy file, which is created by \makeglossaries. If you try the above example and open the .xdy file in your text editor, you should find the following lines:
; define the order of the location classes
(define-location-class-order (
"roman-page-numbers"
"arabic-page-numbers"
"arabic-section-numbers"
"alpha-page-numbers"
"Roman-page-numbers"
"Alpha-page-numbers"
"Appendix-page-numbers"
"see" ))
This is where the order of precedence is established. As with modifying the .ist file, if you directly modify the .xdy file, you need to add \noist before \makeglossaries to prevent the file from being overwritten. Alternatively, you can use \GlsSetXdyLocationClassOrder (before \makeglossaries) to specify a new order. For example:
\documentclass{report}
\usepackage[xindy]{glossaries}

\GlsSetXdyLocationClassOrder{
"Roman-page-numbers"
"roman-page-numbers"
"arabic-page-numbers"
"arabic-section-numbers"
"alpha-page-numbers"
"Alpha-page-numbers"
"Appendix-page-numbers"
"see"
}

\makeglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printglossaries
\end{document}
This will now produce the list: I, i, 1.

Note that both makeindex and xindy may have a problem determining whether a location is Roman and alphabetical. For example, "c" may be Roman 100 or it may be the third letter of the alphabet.

Neither bib2gls nor \makenoidxglossaries have an order of precedence, but instead use the order in which the entries are indexed. For example:

\documentclass{report}
\usepackage{glossaries}

\makenoidxglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printnoidxglossaries
\end{document}
This will produce the list: I, 1, i. Similarly for bib2gls:
\documentclass{report}
\begin{filecontents*}{\jobname.bib}
@index{sample,description={an example}}
\end{filecontents*}
\usepackage[record]{glossaries-extra}

\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printunsrtglossaries
\end{document}

Strange results can also occur if you are using multiple indexing counters. The following example uses the page counter by default, but uses the equation counter when indexing inside the equation environment. (The file example-glossaries-symbolnames.tex is provided with the glossaries package.) I've added the hyperref package, which means that the page locations will link to the top of the relevant page and the equation locations will link to the relevant equation.

\documentclass{article}
\usepackage{hyperref}
\usepackage{glossaries}

\makeglossaries

\begin{document}
\pagenumbering{Roman}\gls{sym.alpha}

\newpage
\pagenumbering{arabic}\gls{sym.alpha}

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

\newpage
\gls{sym.alpha}

\newpage
\pagenumbering{roman}\gls{sym.alpha}
\printglossaries
\end{document}
If this file is called test.tex and the document is built using:
pdflatex test
makeglossaries test
pdflatex test
Then you the following messages will be written to the terminal/prompt makeglossaries:
makeindex  -s "test.ist" -t "test.glg" -o "test.gls" "test.glo"
This is makeindex, version 2.16 [TeX Live 2022] (kpathsea + Thai support).
Scanning style file ./test.ist.............................done (29 attributes redefined, 0 ignored).
Scanning input file test.glo....done (7 entries accepted, 0 rejected).
Sorting entries....done (20 comparisons).
Generating output file test.gls....done (12 lines written, 2 warnings).
Output written in test.gls.
Transcript written in test.glg.
## Warning (input = test.glo, line = 2; output = test.gls, line = 6):
-- Conflicting entries: multiple encaps for the same page under same key.
## Warning (input = test.glo, line = 6; output = test.gls, line = 8):
-- Conflicting entries: multiple encaps for the same page under same key.
Multiple encaps detected. Attempting to remedy.
Writing test.glo...
Retrying
makeindex  -s "test.ist" -t "test.glg" -o "test.gls" "test.glo"
This is makeindex, version 2.16 [TeX Live 2022] (kpathsea + Thai support).
Scanning style file ./test.ist.............................done (29 attributes redefined, 0 ignored).
Scanning input file test.glo....done (5 entries accepted, 0 rejected).
Sorting entries....done (11 comparisons).
Generating output file test.gls....done (10 lines written, 0 warnings).
Output written in test.gls.

This indicates that makeglossaries has detected that makeindex has warned that two identical locations have different encaps (formats). This results from the page 1 location and the equation 1 location, both of which have the same location value (1), but they have different encaps. Similarly for page 2 and equation 2. The normal behaviour is to merge duplicate locations, but makeindex doesn't merge them if they have different encaps. Since it's more usual to merge, makeglossaries will attempt to remedy the situation and remove the conflict.

(From the point of view of the glossaries package, the format is the value of the format key, which defaults to glsnumberformat, but as there's no other way of incorporating the counter information in both makeindex and xindy syntax, the actual encap includes the counter name. This is necessary to support location hyperlinks).

This means that if the document is built using makeglossaries, the resulting location list will be: i, 1, 2, 3, I. In this case, "1" is page 1 but "2" and "3" are equations 2 and 3. Equation 1 has been dropped and there's no range formation as "1" has a different encap to "2" and "3".

If you use makeindex directly:

pdflatex test
makeindex -s test.ist -t test.glg -o test.gls test.glo
pdflatex test
then the location list will be: i, 1, 1, 2, 2, 3, I. This corresponds to page i, equation 1, page 1, equation 2, page 2, equation 3, page I. This ordering is because makeindex will order the conflicting locations according to their encap ("e" comes before "p").

With xindy, you need to identify the addition location counter with \GlsAddXdyCounters:

\documentclass{article}
\usepackage{hyperref}
\usepackage[xindy]{glossaries}

\makeglossaries

\begin{document}
\pagenumbering{Roman}\gls{sym.alpha}

\newpage
\pagenumbering{arabic}\gls{sym.alpha}

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

\newpage
\gls{sym.alpha}

\newpage
\pagenumbering{roman}\gls{sym.alpha}
\printglossaries
\end{document}
(Unfortunately there's a bug in \GlsAddXdyCounters with glossaries v4.49 and lower that will cause "ignoring redefinition of attribute" warnings from xindy.)

The location list is now: i, 1, 2, 3, I. This corresponds to page i, page 1, page 2, equation 3 and page I. Note that equations 1 and 2 have been dropped. This is because xindy merges duplicate locations with different encaps and gives priority according to the order of attribute definition.

The "noidx" method saves the indexing information in the .aux file and uses a syntax that separates the counter from the format. (Note that this method never forms ranges.) The example document can be changed to use this method as follows:

\documentclass{article}
\usepackage{hyperref}
\usepackage{glossaries}

\makenoidxglossaries

\begin{document}
\pagenumbering{Roman}\gls{sym.alpha}

\newpage
\pagenumbering{arabic}\gls{sym.alpha}

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

\newpage
\gls{sym.alpha}

\newpage
\pagenumbering{roman}\gls{sym.alpha}
\printnoidxglossaries
\end{document}
The resulting location list is: I, 1, 1, 2, 3, 2, i. This corresponds to page I, page 1, equation 1, equation 2, equation 3, page 2 and page i. As noted earlier, this method always uses the order of indexing.

Since bib2gls was specifically designed for use with glossaries-extra, it also uses a syntax that separates the counter from the format. The example document can be modified to use bib2gls as follows:

\documentclass{article}
\usepackage{hyperref}
\usepackage[record]{glossaries-extra}

\begin{document}
\pagenumbering{Roman}\gls{sym.alpha}

\newpage
\pagenumbering{arabic}\gls{sym.alpha}

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

$$\gls[counter=equation]{sym.alpha}$$

\newpage
\gls{sym.alpha}

\newpage
\pagenumbering{roman}\gls{sym.alpha}
\printunsrtglossaries
\end{document}
This produces the location list: I, 1, 1–3, 2, i. This corresponds to page I, page 1, equations 1–3, page 2 and page i. As with the "noidx" method, this is the order of indexing.

If the record package option is changed to record=nameref then the location list will be: I, 1, (1)–(3), 2, i. See the glossaries-extra package for further details about customizing the location formatting according to the counter with the nameref setting.

You can separate the location list into different sub-groups corresponding to each counter using the loc-counters resource option. For example:

\GlsXtrLoadResources[src=example-glossaries-symbolnames,loc-counters={page,equation}]
This puts the page numbers first and then the equation numbers: I, 1, 2, i, 1–3. If you want the equation numbers first, you need: loc-counters={equation,page}.

The separator between the sub-groups is given by \bibglslocationgroupsep and each sub-group is encapsulated with \bibglslocationgroup{n}{counter}{locations}, so you can customize the formatting for the different sub-groups. See the bib2gls manual for further details.

2022-08-01 20:53:27