Decyphering the Aux File Commands Provided by glossaries.sty and glossaries-extra.sty

This is a guide for document build tool developers who want to be able to detect whether or not the tool chain should include additional steps to create (or recreate) the files needed by glossaries.sty or glossaries-extra.sty to produce an up-to-date document.

If you are a document author interested in trying to add the relevant step to your document build setup, then try Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

The section Note to Front-End and Script Developers of the glossaries user manual describes all relevant commands. This article provides examples that demonstrate them.

In the examples below, substitute latex with pdflatex, xelatex or lualatex, as applicable. The document source code is assumed to be in a file called myDoc.tex (so the job name is myDoc).

No Glossary

This example doesn’t actually have any glossaries. This may be because it’s a work in progress or because the terms are simply defined at the relevant point in the document and the document is short enough not to require a list.

\documentclass{article}

\usepackage[acronym,symbols]{glossaries}

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.
\end{document}

latex myDoc

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}

Any non-ignored glossary is identified in the aux file with:

\@newglossary{glossary-label}{log-ext}{out-ext}{in-ext}

The arguments are the file extensions for makeindex and xindy. (The extensions are only applicable with \makeglossaries.) This line in the aux file is written by the corresponding \newglossary command, so the list will match the order in which the glossaries were defined. (This isn’t necessarily the same order as the order in which package options such as “acronym” and “symbols” are listed.)

The above example can be adapted to use glossaries-extra:

\documentclass{article}

\usepackage[acronym,symbols]{glossaries-extra}

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

\setabbreviationstyle[acronym]{long-short}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.
\end{document}

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\providecommand\@glsxtr@savepreloctag[2]{}

latex myDoc

\printunsrtglossary

The simplest way of producing a glossary in the document is with \printunsrtglossary, which is provided by glossaries-extra. If you are familiar with bib2gls, you will probably recognise this command, but although it was provided for use with bib2gls, it can be used without it.

The “unsrt” part of \printunsrtglossary is a reference to the fact that this command simply iterates over the glossary’s internal list of entry labels. Whenever an entry is defined, its label is appended to the internal list. This means that \printunsrtglossary will always be in order of definition and will iterate over every label in the glossary, regardless of whether or not it has been indexed in the document.

(The way that bib2gls works is that bib2gls sorts the data obtained from the bib files and then writes the (LaTeX) definitions in the .glstex file in the appropriate order to ensure that the (glossaries[-extra].sty) order of definition matches the desired sort method.)

The previous example can be adapted to include \printunsrtglossaries, which does \printunsrtglossary for each defined (non-ignored) glossary:

\documentclass{article}

\usepackage[acronym,symbols,style=tree]{glossaries-extra}

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

\setabbreviationstyle[acronym]{long-short}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printunsrtglossaries
\end{document}

latex myDoc

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\providecommand\@glsxtr@savepreloctag[2]{}
\@writefile{toc}{\contentsline {section}{Glossary}{1}{}\protected@file@percent }
\@writefile{toc}{\contentsline {section}{Acronyms}{1}{}\protected@file@percent }
\@writefile{toc}{\contentsline {section}{Symbols}{1}{}\protected@file@percent }

\printnoidxglossary

The \printnoidxglossary command is similar to \printunsrtglossary in that it iterates over an internal list, but this method uses the aux file to determine whether or not an entry was referenced in the previous run and, if so, on what pages. The use of \makenoidxglossaries changes the behaviour of commands like \gls and \glsadd so that they write this information in the aux file. The “noidx” part of the command names is because this method doesn’t require an external indexing tool.

The sort=def setting will make \printnoidxglossary iterate over the glossary’s internal label list (like \printunsrtglossary) but it will skip any entries that didn’t have a reference in the aux file. The sort=use setting will instead use another internal list that’s built up while the aux file is read. This means that the list will be in order of use. The other sort settings will sort that internal list (using LaTeX code applicable to the setting) before iterating over it.

The first example can be adapted to use \printnoidxglossary to display the glossary lists.

\documentclass{article}

\usepackage[acronym,symbols,style=tree]{glossaries}

\makenoidxglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printnoidxglossary
\printnoidxglossary[type=acronym]
\printnoidxglossary[type=symbols,sort=use]
\end{document}

latex myDoc
latex myDoc

Package glossaries Warning: Empty glossary for \printnoidxglossary[type={main}]. Rerun may be required (or you may have forgotten to use commands like \gls) on input line 33. Package glossaries Warning: Empty glossary for \printnoidxglossary[type={acronym}]. Rerun may be required (or you may have forgotten to use commands like \gls) on input line 33. Package glossaries Warning: Empty glossary for \printnoidxglossary[type={symbols}]. Rerun may be required (or you may have forgotten to use commands like \gls) on input line 34.

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\providecommand\@gls@reference[3]{}
\@gls@reference{main}{sample}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{ex}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{symbols}{dfx}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{abbr}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{ex}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{abbr}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

\@gls@reference{type}{label}{location}

A \gls{sample} document with an \gls{ex} derivative \gls{dfx} of \gls{fx}.

So, searching for \@gls@reference in the aux file is an indication that at least two LaTeX runs are required, but you need to take into account the hybrid option provided by glossaries-extra, which allows both \printnoidxglossary and \printglossary to appear in the same document.

\printglossary (makeindex)

The \printglossary command follows the more conventional LaTeX route of inputting a file that contains the code to typeset the glossary. This file is created by an external application that reads in a file written by LaTeX. This means that LaTeX must first be run to create the file required by the indexing application so that the indexing application can then create the file that needs to be input by \printglossary. The glossaries package supports makeindex and xindy. This example focuses on makeindex.

The input/output terminology can be confusing. The file that LaTeX creates (.glo) is an output file from LaTeX’s point of view, but an input file from the indexing application’s point of view. The file that the indexing application creates (.gls) is an output file from the indexing application’s point of view, but is an input file from LaTeX’s point of view.

(It was this confusion that led to me accidentally switching the .glo and .gls extensions when replacing the old glossary.sty package with the first version of the glossaries.sty package, but it’s too late to change it now.)

The previous example can be modified to use \makeglossaries and \printglossary instead of the “noidx” commands.

\documentclass{article}

\usepackage[acronym,symbols,style=tree]{glossaries}

\makeglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},sort={fx},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},sort={f'x},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossary
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

No file myDoc.aux. No file myDoc.gls. No file myDoc.acr. No file myDoc.sls.

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\providecommand\@glsorder[1]{}
\providecommand\@istfilename[1]{}
\@istfilename{myDoc.ist}
\@glsorder{word}

The “no file” transcript messages aren’t particularly useful for a build tool as they won’t appear once the files have been created, so there’s no indication that they need updating. The information in the aux file provides more information.

In this case, you have two possibilities:

1. If \@istfilename is found in the aux file, then run makeglossaries or makeglossaries-lite.
2. Determine if makeindex or xindy is required, and run the relevant tool with the applicable switches for each glossary identified by \@newglossary.

(See below if you are undecided as to which method you should choose.)

In the first case, makeglossaries is better than makeglossaries-lite because it provides extra diagnostics when things go wrong, does some repair work to overcome any encap clashes, and provides some language mappings for xindy. The drawback is that it requires Perl, but so does xindy.

If you’re interested in comparing file modification dates, remember that \makeglossaries opens each glossary file. The indexing style file (identified by \@istfilename) is also, by default, created by \makeglossaries, although this can be overridden to allow the user to customise it by directly editing the style file.

So, for this example document, if myDoc.gls doesn’t exist or myDoc.ist (identified by \@istfilename) is newer than myDoc.gls, or if myDoc.glo is newer than myDoc.gls, then run makeglossaries (followed by another LaTeX run). The gls and glo extensions are selected from the arguments of the first instance of \@newglossary. (Bear in mind that the nomain package option prevents the creation of the default “main” glossary, so don’t assume these extensions.)

If you prefer the second case (explicitly run makeindex or xindy instead of using makeglossaries), then the extension of the filename argument of \@istfilename identifies whether or not the file is a makeindex style file or a xindy module.

\@istfilename{filename}

If filename ends with .xdy then xindy is required. Otherwise assume makeindex.

Note that while xindy requires a .xdy extension, makeindex doesn’t enforce a .ist extension and the glossaries package does still support the old pre-xindy (now undocumented) method of specifying the full filename (instead of just the basename) for the style file. So test for “ends with .xdy” not “ends with .ist”.

The sort ordering can be either word or letter ordering. The default is word ordering, so that’s what this example has.

\@glsorder{order}

So, for this example, \@istfilename is present, the filename argument doesn’t end with .xdy, and the order argument of \@glsorder isn’t “letter”. Therefore makeindex is required and it needs to be invoked with -s myDoc.ist but should not have the -l (letter) switch. This needs to be done for each set of glossary extensions identified in \@newglossary:

makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo

Another LaTeX run is then required:

latex myDoc

Note that with makeindex, the aux file may also contain:

\@gls@extramakeindexopts{args}

This aux command will only appear if args has been set. It’s detected by both makeglossaries and makeglossaries-lite, so you only need to worry about it if you are explicitly invoking makeindex.

Let’s switch back to glossaries-extra again, but this time use “abbreviation” instead of “acronym”:

\documentclass{article}

\usepackage[abbreviations,symbols,style=tree]{glossaries-extra}

\makeglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'abbreviations' glossary:
\newabbreviation{ex}{EX}{example}
\newabbreviation{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},sort={fx},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},sort={f'x},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossary
\printglossary[type=abbreviations]
\printglossary[type=symbols]
\end{document}

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{symbols}{slg}{sls}{slo}
\@newglossary{abbreviations}{glg-abr}{gls-abr}{glo-abr}
\providecommand\@glsxtr@savepreloctag[2]{}
\providecommand\@glsorder[1]{}
\providecommand\@istfilename[1]{}
\@istfilename{myDoc.ist}
\@glsorder{word}

So now the document build is:

latex myDoc
makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo
makeindex -s myDoc.ist -t myDoc.glg-abr -o myDoc.gls-abr myDoc.glo-abr
latex myDoc

\printglossary (xindy)

Now let’s switch to xindy (with just the base glossaries package):

\documentclass{article}

\usepackage[acronym,symbols,style=tree,xindy]{glossaries}

\makeglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},sort={fx},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},sort={f'x},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossary
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

\@xdylanguage{main}{english}
\@gls@codepage{main}{utf8}
\@xdylanguage{acronym}{english}
\@gls@codepage{acronym}{utf8}
\@xdylanguage{symbols}{english}
\@gls@codepage{symbols}{utf8}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\@istfilename{myDoc.xdy}
\@glsorder{word}

The argument of \@istfilename now ends with .xdy, which indicates that xindy is required, but the other clue is the presence of \@xdylanguage and \@gls@codepage, which indicate the language and encoding required for each glossary. The encoding should typically be the same for each glossary. (It would be very unusual and highly problematic to have a mixture of encodings in the same document.)

The document build is now:

latex myDoc
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.slg -o myDoc.sls myDoc.slo
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acn
latex myDoc

The language for each glossary is identified with:

\@xdylanguage{glossary-label}{language}

\@gls@codepage{code-page}

The codepage will default to the expansion of \inputencodingname, if it’s defined, or utf8, otherwise. Again, the document author can explicitly change this value (via \GlsSetXdyCodePage or xindy={codepage=code-page}).

The codepage and language commands are written to the aux file by \printglossary using \immediate to ensure that they pick up the document language and encoding at the point where the glossary is displayed. The \@newglossary commands are written using a delayed write by \newglossary (because it’s a preamble command and the old aux file must be input before the new one can be created, so the write has to be delayed). The different behaviour between the immediate and delayed write is the reason why the language and codepage commands appear before the other commands for this short example.

For example, the makeglossaries Perl script will map “brazilian” to “portuguese” and “naustrian” to “german”. Additionally, if a known German language label is detected, the code-page will be inspected to determine if “din5007-” should be added. If you want your build tool to explicitly invoke xindy, then you will either need to provide similar checks or you will have to instruct your users to identify the correct xindy language and code-page information. For example:

\usepackage[xindy={language={german},codepage={din5007-utf8}}]{glossaries}

What are the Benefits of Using makeglossaries Over an Explicit makeindex/xindy Call?

If you are undecided whether to use makeglossaries versus makeglossaries-lite versus a direct call to makeindex or xindy, try out the following example (myDoc.tex):

\documentclass{article}

\usepackage{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},description={alpha}}

\begin{document}
A \gls{sample} and another \gls[format=textbf]{sample} and
\gls{alpha}.

\printglossary
\end{document}

pdflatex myDoc
makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
pdflatex myDoc

## Warning (input = myDoc.glo, line = 2; output = myDoc.gls, line = 8): -- Conflicting entries: multiple encaps for the same page under same key.

Now try:

pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc

## Warning (input = myDoc.glo, line = 2; output = myDoc.gls, line = 8): -- Conflicting entries: multiple encaps for the same page under same key. Multiple encaps detected. Attempting to remedy. Reading myDoc.glo... Writing myDoc.glo... Retrying

Now switch to xindy:

\usepackage[xindy]{glossaries}

pdflatex myDoc
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo

ERROR: CHAR: index 0 should be less than the length of the string

Now try makeglossaries:

makeglossaries myDoc

***Call to xindy failed*** Possible cause of problem: Sort key required for entries only containing command names. Attempting to determine which entries have problem sort keys. Parsing 'myDoc.glo' 1 problematic entry found: Label: 'alpha'. Sort value : '\\ensuremath {\\alpha }' (Try adding sort={alpha} to the definition.)

So makeglossaries detects the error, provides a more informative message, finds the problematic entry, and suggests a remedy.

Note that makeglossaries-lite doesn’t make these corrections or provide diagnostic information. It’s only benefit is that it can parse the aux file to determine whether to call makeindex or xindy and what command line options should be used.

If you want your build tool to bypass makeglossaries, are you prepared to provide similar diagnostics and corrections?

The advantage in directly calling makeindex or xindy is that it’s slightly faster and has one less sub-process.

Can an Alternative to MakeIndex be Used?

Only if the alternative can understand the makeindex style file created by \makeglossaries or if you can convert the style file into an equivalent set of instructions for the alternative indexing application.

• The “actual” character is ? not MakeIndex’s default @ (this was because the early versions of the glossaries package included the name, description and symbol in the indexing file, which increased the chances of internal commands causing interference).
• The quote character may have been changed (via \GlsSetQuote).
• The keyword is \glossaryentry (not \indexentry).
• The preamble should be:

  \glossarysection[\glossarytoctitle]{\glossarytitle}\glossarypreamble
  \begin{theglossary}\glossaryheader
  

• The postamble should be:

  \end{theglossary}\glossarypostamble
  

• The group headings should be encapsulated with:

  \glsgroupheading{heading}\glsresetentrylist 
  

  where the heading should be “glssymbols” for symbols, “glsnumbers” for numbers or the initial letter(s) otherwise.
• The group skip should be \glsgroupskip
• The page compositor defaults to “.” but may have been changed with \glsSetCompositor.
• The location list should be encapsulated with:

  \glsresetentrylist
  \glossaryentrynumbers{locations}
  

• If an entry doesn’t have a location list (for example, a parent entry) then it needs to end with

  \glsresetentrylist
  

• The location range and separator symbols should be \delimN and \delimR, respectively.

The glossary styles won’t work if the output doesn’t match this format, and location hyperlinks won’t work correctly if the location range and separator symbols aren’t the expected commands.

Hybrid \printglossary and \printnoidxglossary

The glossaries-extra package provides a hybrid option that allows the use of both \printglossary (which requires makeindex or xindy) and \printnoidxglossary (which simply requires a second LaTeX run). The advantage with this method is that it allows different sort methods for different glossaries. In particular, it means that the superior alphabetical sorting and collation performed by external indexing tools can be used for glossaries with natural language terms (which is harder to do in LaTeX) but a glossary that contains symbolic or pictographic names can simply be ordered by use or by definition (which is easy to do in LaTeX).

Note that bib2gls can use different sort methods for different glossaries. This hybrid method is only applicable with \makeglossaries.

This method can be demonstrated in the following example document:

\documentclass{article}

\usepackage[abbreviations,symbols,style=tree]{glossaries-extra}

\makeglossaries[main,abbreviations]

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'abbreviations' glossary:
\newabbreviation{ex}{EX}{example}
\newabbreviation{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},sort={fx},
 description={a function of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},sort={f'x},
 description={a derivative of the function $f(x)$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossary
\printglossary[type=abbreviations]
\printnoidxglossary[type=symbols,sort=def]
\end{document}

On the first LaTeX run, a warning appears in the transcript:

Package glossaries Warning: Empty glossary for \printnoidxglossary[type={symbols}]. Rerun may be required (or you may have forgotten to use commands like \gls) on input line 34.

This is the same as for the earlier example that used \printnoidxglossary, but there’s now only one warning.

After the first LaTeX run, the aux file now contains:

\providecommand\@newglossary[4]{}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{symbols}{slg}{sls}{slo}
\@newglossary{abbreviations}{glg-abr}{gls-abr}{glo-abr}
\providecommand\@glsxtr@savepreloctag[2]{}
\providecommand\@glsorder[1]{}
\providecommand\@istfilename[1]{}
\@istfilename{myDoc.ist}
\@glsorder{word}
\glsxtr@makeglossaries{main,abbreviations}
\providecommand\@gls@reference[3]{}
\@gls@reference{symbols}{dfx}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

This contains \@istfilename and \@glsorder (which indicates \makeglossaries was used), but it also contains \@gls@reference, which indicates that the document is expected to contain \printnoidxglossary. However, there’s an additional command that hasn’t yet been mentioned:

\glsxtr@makeglossaries{label-list}

If you have chosen to use the simpler option of just checking for \@istfilename and then running the makeglossaries Perl script (or makeglossaries-lite Lua script), then you don’t need to make a special case, as both scripts check for this command. (Although, if you are also checking for \@gls@reference, make sure you check for \@istfilename first).

If you have chosen to explicitly run makeindex or xindy, then perform the same checks as before, but only run the required indexing application for the glossaries whose labels are listed in label-list. For this example document, the build process is:

latex myDoc
makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
makeindex -s myDoc.ist -t myDoc.glg-abr -o myDoc.gls-abr myDoc.glo-abr
latex myDoc

bib2gls

The glossaries-extra package provides an alternative method of indexing, and that’s with the bib2gls application, which has two functions:

1. fetch data relevant to the document from associated bib files;
2. sort the data so that \printunsrtglossary will list the data in the required order (with the relevant locations, if applicable).

The example document below does require a sorted list. It’s actually very similar to the earlier \printunsrtglossary example, but the definitions have been removed from the preamble:

\documentclass{article}

\usepackage[record,acronym,symbols,style=tree]{glossaries-extra}

\setabbreviationstyle[acronym]{long-short}

\GlsXtrLoadResources

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printunsrtglossaries
\end{document}

The corresponding bib file (which was simply created from the earlier example document using convertgls2bib, provided with bib2gls) contains the following:

% Encoding: UTF-8
@entry{sample,
  name = {sample},
  description = {an example}
}

@entry{function,
  symbol = {\ensuremath{f}},
  name = {function},
  description = {a function}
}

@acronym{ex,
  short = {EX},
  long = {example}
}

@acronym{abbr,
  short = {abbr},
  long = {abbreviation}
}

@entry{fx,
  name = {\ensuremath{f(x)}},
  description = {a function of $x$},
  type = {symbols}
}

@entry{dfx,
  name = {\ensuremath{f'(x)}},
  description = {a derivative of the function $f(x)$},
  type = {symbols}
}

The aux file is now considerably larger as most of the document information is supplied to bib2gls via aux file commands. As before, the non-ignored glossaries are identified with \@newglossary, but there are other commands as well. Most of these aren’t relevant to a document build tool. The primary one of interest is:

\glsxtr@resource{options}{basename}

There will be one instance of \glsxtr@resource for each \GlsXtrLoadResources that occurs in the document preamble. The options argument corresponds to the optional argument of \GlsXtrLoadResources and basename is the basename of the .glstex file that’s input by \GlsXtrLoadResources (and needs to be created by bib2gls).

If you want to check file existence or modification times, then, for each \glsxtr@resource, check that basename.glstex exists and compare its timestamp with the document source file. Unfortunately it becomes a bit more difficult if the document source is split across multiple files. (Comparing with the aux file’s timestamp can cause an infinite loop in a bib2gls+LaTeX cycle.)

You may also want to check if the relevant bib files have been changed. The bib files can be identified in the src option. If no src is provided, then src={basename.bib} is assumed. The first instance of \GlsXtrLoadResources has a basename that matches \jobname. Subsequence instances of \GlsXtrLoadResources have a basename in the form \jobname-n.

In this example, there’s only one \GlsXtrLoadResources and it has no options, so the corresponding line in the aux file is:

\glsxtr@resource{}{myDoc}

latex myDoc
bib2gls myDoc
latex myDoc

On the first LaTeX run, commands like \gls will produce a double question mark ??, similar to \ref and \cite. The bib2gls run creates a .glstex file which includes the following lines:

\providecommand{\bibglsnewacronym}[4]{%
  \newacronym[#2]{#1}{#3}{#4}%
}

\bibglsnewacronym{abbr}%
{location={\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}},
sort={abbr|}}%
{abbr}%
{abbreviation}
\glsxtrfieldlistadd{abbr}{loclist}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

\bibglsnewacronym{ex}%
{location={\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}},
sort={EX|}}%
{EX}%
{example}
\glsxtrfieldlistadd{ex}{loclist}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

\providecommand{\bibglsnewentry}[4]{%
 \longnewglossaryentry*{#1}{name={#3},#2}{#4}%
}

\bibglsnewentry{dfx}%
{location={\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}},
sort={f|x|},
type={symbols}}%
{\ensuremath{f'(x)}}%
{a derivative of the function $f(x)$}
\glsxtrfieldlistadd{dfx}{loclist}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

\bibglsnewentry{sample}%
{location={\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}},
sort={sample|}}%
{sample}%
{an example}
\glsxtrfieldlistadd{sample}{loclist}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

\newacronym{abbr}{abbr}{abbreviation}
\newacronym{ex}{EX}{example}

\newglossaryentry{dfx}{
 name={\ensuremath{f'(x)}},
 description={a derivative of the function $f(x)$},
 type={symbols}
}

\newglossaryentry{sample}{
  name={sample},
  description={an example}
}

The next LaTeX run inputs this .glstex file and now the references are resolved. If the link text (that replaces the double question mark) is quite long, this can cause the page numbers to shift in which case another bib2gls+LaTeX run will be required.

You might have noticed that there’s a slight difference in the resulting document, compared with the earlier examples. They all use the “tree” glossary style, but previously there has been a vertical gap between “abbr” and “EX” in the list of acronyms/abbreviations. That gap isn’t present here.

The gap is the “group skip” that’s inserted between different letter groups. The “tree” style doesn’t show the group heading (switch to “treegroup” for that) but it does still include the group skip. The reason for the lack of a group skip in this example is that bib2gls defaults to --no-group, which inhibits the letter group formation. (So even with the “treegroup” style, there will be no group headings.)

You can have your build tool automatically add --group. The group skip gap can be suppressed in the document with nogroupskip, as per the other indexing options, or with groups=false (which is only available with \printunsrtglossary). It will, however, increase the complexity of the bib2gls process.

Other aux commands that bib2gls searches for include the following, which provide the indexing information:

\glsxtr@record{label}{h-prefix}{counter}{format}{loc}

\glsxtr@record@nameref{label}{href-prefix}{counter}{format}{location}{title}{href-anchor}{href-value}

\glsxtr@recordsee{label}{xr-list}

This next example is a slight modification that has two resource sets, as different sort methods are required:

\documentclass{article}

\usepackage[record,abbreviations,symbols,style=tree]{glossaries-extra}

\GlsXtrLoadResources[src={entries,abbreviations},sort=en]
\GlsXtrLoadResources[src=symbols,type=symbols,sort=use]

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printunsrtglossaries
\end{document}

This depends on three .bib files. General entries are in entries.bib:

% Encoding: UTF-8
@entry{sample,
  name = {sample},
  description = {an example}
}

@entry{function,
  symbol = {\ensuremath{f}},
  name = {function},
  description = {a function}
}

% Encoding: UTF-8
@abbreviation{ex,
  short = {EX},
  long = {example}
}

@abbreviation{abbr,
  short = {abbr},
  long = {abbreviation}
}

% Encoding: UTF-8
@symbol{fx,
  name = {\ensuremath{f(x)}},
  description = {a function of $x$}
}

@symbol{dfx,
  name = {\ensuremath{f'(x)}},
  description = {a derivative of the function $f(x)$}
}

The aux file now contains two instances of \glsxtr@resource:

\glsxtr@resource{src={entries,abbreviations},sort=en}{myDoc}
\glsxtr@resource{src=symbols,type=symbols,sort=use}{myDoc-1}

In this case, the required .bib files are identified in the src argument. Again, only one call to bib2gls is required:

latex myDoc
bib2gls myDoc
latex myDoc

bib2gls and record=hybrid

This example demonstrates a rare setting that’s for esoteric use. It’s provided for cases where a document author has a highly customized xindy style that can’t be reproduced with bib2gls resource options but the author would like the convenience of storing all the glossary information in bib files.

\documentclass{article}

\usepackage[xindy,record=hybrid,abbreviations,symbols,style=tree]{glossaries-extra}

\makeglossaries

\GlsXtrLoadResources[src={entries,abbreviations},sort=none,save-locations=false]
\GlsXtrLoadResources[src=symbols,type=symbols,sort=none,save-locations=false]

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossaries
\end{document}

The aux file now has both the xindy commands and the bib2gls commands.

\@xdylanguage{main}{english}
\@gls@codepage{main}{utf8}
\@xdylanguage{symbols}{english}
\@gls@codepage{symbols}{utf8}
\@xdylanguage{abbreviations}{english}
\@gls@codepage{abbreviations}{utf8}
\@newglossary{main}{glg}{gls}{glo}
\@newglossary{symbols}{slg}{sls}{slo}
\@newglossary{abbreviations}{glg-abr}{gls-abr}{glo-abr}
\@istfilename{myDoc.xdy}
\@glsorder{word}
[...]
\glsxtr@resource{src={entries,abbreviations},sort=none,save-locations=false}{myDoc}
\glsxtr@resource{src=symbols,type=symbols,sort=none,save-locations=false}{myDoc-1}

latex myDoc

On the first LaTeX run, no entries are defined, which means that the indexing information required for xindy is unavailable, so the .glo etc files will be empty.

This means that if you try running makeglossaries at this point you will get warnings about empty files and if you explicitly use xindy instead, you’ll end up with empty glossaries that will trigger a “missing item” error with any of the “list” glossary styles.

However, the aux file does contain information that bib2gls needs in order to select the required entries, so that their definitions can be written to the .glstex file. Therefore the next step is:

bib2gls myDoc

At this point (that is, after the initial LaTeX+bib2gls), the indexing files myDoc.glo, myDoc.slo and myDoc.glo-abr exist but are empty. However, the .glstex files now exist.

The first file myDoc.glstex contains:

\providecommand{\bibglsnewentry}[4]{%
 \longnewglossaryentry*{#1}{name={#3},#2}{#4}%
}

\bibglsnewentry{sample}%
{}%
{sample}%
{an example}

\providecommand{\bibglsnewabbreviation}[4]{%
  \newabbreviation[#2]{#1}{#3}{#4}%
}

\bibglsnewabbreviation{ex}%
{}%
{EX}%
{example}


\bibglsnewabbreviation{abbr}%
{}%
{abbr}%
{abbreviation}

Note that the entries haven’t been sorted and there are no associated locations. This is because the hybrid method defers sorting and collating locations to the indexing application (xindy).

The second file myDoc-1.glstex includes the lines:

\providecommand{\bibglsnewsymbol}[4]{%
 \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}}

\bibglsnewsymbol{dfx}%
{type={symbols}}%
{\ensuremath{f'(x)}}%
{a derivative of the function $f(x)$}

The myDoc.glstex file will be input by the first \GlsXtrLoadResources and the myDoc-1.glstex file will be input by the second \GlsXtrLoadResources on the next LaTeX run, and now that the entries have been defined, they can be indexed using xindy syntax:

latex myDoc

Note that the provided definition of \bibglsnewsymbol sets the sort value to the label by default. This definition is only picked up by LaTeX (and is not used by bib2gls or affected by the “symbol-sort-fallback” setting). The command may be defined before \GlsXtrLoadResources to omit that sort assignment or to supply a different assignment. In this example, no alternative definition has been provided, so the above lines in the myDoc-1.glstex file are equivalent to:

\newglossaryentry{dfx}{
 name={\ensuremath{f'(x)}},
 sort={dfx},
 category={symbol},
 type={symbols},
 description={a derivative of the function $f(x)$}
}

(indexentry :tkey (("dfx" "\\glossentry{dfx}") ) :locref "{}{1}" :attr "pageglsnumberformat" )

Now that the indexing files finally have some content, xindy can be run (either explicitly or via makeglossaries):

xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.slg -o myDoc.sls myDoc.slo
xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg-abr -o myDoc.gls-abr myDoc.glo-abr

latex myDoc

After this point, bib2gls isn’t needed until the resource options change (that is, the argument of the \GlsXtrLoadResources commands changes) or a new entry is required in the document (which needs to be fetched from the bib file). However, there should be no need to check for the “selection” resource option. If “selection=all” is set, bib2gls will fetch all entries, but \printglossary will still only list the entries that were indexed. So, you can simply check the LaTeX log file for “Package glossaries-extra Warning: Glossary entry `[...]' has not been defined” to decided whether or not to run bib2gls (and you may also want to check if the bib file has changed).

What happens if the sort=none, save-locations=false resource options are omitted? This will cause bib2gls to use its default settings, which is to sort according to the document language (or the default language if not specified) and collate the locations. This in turn means that the .glstex files will have the sort and location fields set, and so xindy will be supplied the sort values that bib2gls used. This means that not only is the document build more complex but it also involves duplication of effort.

The only advantage that makeindex and xindy have over bib2gls is that the indexing applications categorise the locations by class (decimal, lowercase Roman, uppercase Roman, alphabetic) and each class is a subset of the location list and those subsets can be reordered. With bib2gls, the location list can only be sub-divided and reordered according to the counter used for the location (page, equation, section, etc).

Dependencies with \printnoidxglossary

This example is a modification of the earlier \printnoidxglossary example. The document text hasn’t changed, but the symbol entry descriptions have been changed so that they reference another entry:

\documentclass{article}

\usepackage[acronym,symbols,style=tree]{glossaries}

\makenoidxglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a \gls{function} of $x$},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of \gls{fx}},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printnoidxglossary
\printnoidxglossary[type=acronym]
\printnoidxglossary[type=symbols,sort=use]
\end{document}

As before, start with:

latex myDoc

This first LaTeX run creates an aux file that contains:

\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\@gls@reference{main}{sample}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{ex}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{symbols}{dfx}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{abbr}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{ex}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}
\@gls@reference{acronym}{abbr}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

Note that this doesn’t include any references for the two entries (“fx” and “function”) that haven’t been referenced in the main body of the document. Another LaTeX run is required for the glossaries to appear:

latex myDoc

Within the symbol glossary, the description of the “dfx” entry is now typeset, which includes a reference to the “fx” entry, so the aux file has another line:

\@gls@reference{symbols}{fx}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

latex myDoc

\@gls@reference{main}{function}{\glsnoidxdisplayloc{}{page}{glsnumberformat}{1}}

latex myDoc

In total, four LaTeX runs are required:

latex myDoc
latex myDoc
latex myDoc
latex myDoc

Dependencies with \printglossary

This example modifies the previous example to switch from \printnoidxglossary to \printglossary. Note that it’s now not possible to apply different sorting methods. (Actually, it is possible — sort of — but it’s complicated.)

\documentclass{article}

\usepackage[acronym,symbols,style=tree]{glossaries}

\makeglossaries

% entries in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}
\newglossaryentry{function}{name={function},
 symbol={\ensuremath{f}},
 description={a function}}

% entries in 'acronym' glossary:
\newacronym{ex}{EX}{example}
\newacronym{abbr}{abbr}{abbreviation}

% entries in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a \gls{function} of $x$},sort={fx},
 type=symbols
}

\newglossaryentry{dfx}{name={\ensuremath{f'(x)}},
 description={a derivative of \gls{fx}},sort={f'x},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printglossary
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

As with the earlier \printglossary examples, start with a LaTeX run:

latex myDoc

\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}
\@istfilename{myDoc.ist}
\@glsorder{word}

\glossaryentry{sample?\glossentry{sample}|setentrycounter[]{page}"\glsnumberformat}{1}

\glossaryentry{EX?\glossentry{ex}|setentrycounter[]{page}"\glsnumberformat}{1}
\glossaryentry{abbr?\glossentry{abbr}|setentrycounter[]{page}"\glsnumberformat}{1}
\glossaryentry{EX?\glossentry{ex}|setentrycounter[]{page}"\glsnumberformat}{1}
\glossaryentry{abbr?\glossentry{abbr}|setentrycounter[]{page}"\glsnumberformat}{1}

\glossaryentry{f'x?\glossentry{dfx}|setentrycounter[]{page}"\glsnumberformat}{1}

So the next step is:

makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo

makeglossaries myDoc

Note that the myDoc.glo file didn’t contain any indexing information about the “function” entry, so it’s not included in the corresponding myDoc.gls file. Likewise, the myDoc.slo file didn’t contain any indexing information about the “fx” entry, so that’s not included in the corresponding myDoc.sls file.

LaTeX needs a rerun to ensure that the files created by makeindex are input by the applicable \printglossary command.

latex myDoc

\glossaryentry{fx?\glossentry{fx}|setentrycounter[]{page}"\glsnumberformat}{1}

makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo

Another LaTeX run is required to take this update into account:

latex myDoc

\glossaryentry{function?\glossentry{function}|setentrycounter[]{page}"\glsnumberformat}{1}

makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo

latex myDoc

latex myDoc
makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo
latex myDoc
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sls myDoc.slo
latex myDoc
makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
latex myDoc

Dependencies with bib2gls

This example modifies the previous example to switch to using bib2gls:

\documentclass{article}

\usepackage[record,abbreviations,symbols,style=tree]{glossaries-extra}

\GlsXtrLoadResources[
 assign-fields={
  type = "symbols" [ entrytype -> original = "symbol" ]
 }
]

\begin{document}
A \gls{sample} document with an \gls{ex} derivative \gls{dfx}.
There are two \glspl{abbr}: \gls{ex} and \gls{abbr}.

\printunsrtglossary
\printunsrtglossary[type=abbreviations]
\printunsrtglossary[type=symbols]
\end{document}

% Encoding: UTF-8
@entry{sample,
  name = {sample},
  description = {an example}
}

@entry{function,
  symbol = {\ensuremath{f}},
  name = {function},
  description = {a function}
}

@abbreviation{ex,
  short = {EX},
  long = {example}
}

@abbreviation{abbr,
  short = {abbr},
  long = {abbreviation}
}

@symbol{fx,
  name = {\ensuremath{f(x)}},
  description = {a \gls{function} of $x$}
}

@symbol{dfx,
  name = {\ensuremath{f'(x)}},
  description = {a derivative of \gls{fx}}
}

Unlike the single bib file example earlier, this doesn’t have the “type” field set for the symbol entries, which are now defined with @symbol rather than @entry. This means that the sort value for the symbols will default to the label rather than the name (since the sort field hasn’t explicitly been set).

Note that this example only has a single resource set, so all entries will be sorted alphabetically. (Dependencies across multiple resource sets can be problematic.)

Since the type field hasn’t been set, the resource set includes an option to set the type field to “symbols” for all entries that have been defined with @symbol. The @abbreviation entries will automatically be added to the “abbreviations” glossary, since they will be defined with \newabbreviation in the .glstex file. The other entries will be placed in the default “main” glossary.

As usual, start with a LaTeX run:

latex myDoc

\@newglossary{main}{glg}{gls}{glo}
\@newglossary{symbols}{slg}{sls}{slo}
\@newglossary{abbreviations}{glg-abr}{gls-abr}{glo-abr}
[...]
\glsxtr@resource{ assign-fields={ type = "symbols" [ entrytype -> original = "symbol" ] } }{myDoc}

There is no need for your build tool to search for the extra commands described below, but they explain how bib2gls is better able to deal with dependencies.

\glsxtr@fields{field-map list}

\@glsxtr@mglslike{list}

If any commands have been defined with \glsxtrnewglslike, then the aux file will also include:

\@glsxtr@newglslike{label-prefix}{cs}

If \GlsXtrSetAltModifier has been used, the modifier is identified with:

\@glsxtr@altmodifier{character}

Any label prefixes provided for use with the \dgls set of commands are identified with:

\@glsxtr@prefixlabellist{list}

All this information makes it possible for bib2gls to scan the values of fields, such as the description field, for commands such as \gls in order to discover dependencies. With the default selection={recorded and deps} setting, these dependencies will be included in the selection, even though they have no records in the aux file.

So the next steps in the build process are simply:

bib2gls myDoc
latex myDoc

The document now has all required entries appearing in the glossaries. However, if you try this out, you may notice that the dependencies (“fx” and “function”) don’t have associated locations at this point. Even though bib2gls can detect the dependencies, it can’t know what page number they may then be referenced on when the glossaries are typeset.

The simplest situation occurs when no locations are required (for example, with the resource option save-locations=false or the package option nonumberlist) or where indexing is switched off before the glossaries are displayed. Whilst you can detect the save-locations setting in the aux file, you can’t detect the other possibilities.

If the locations do need updating, then another bib2gls and LaTeX run are required.

Therefore, in order to ensure the locations are correct, the example document requires:

latex myDoc
bib2gls myDoc
latex myDoc
bib2gls myDoc
latex myDoc

If you want to check the hash of the aux file, bear in mind that a document with \include will have multiple aux files. These can be detected by bib2gls and are parsed as they may contain indexing records.

Alternatively, the bibglsaux package option may have been passed to glossaries-extra or the corresponding command \glsxtrsetbibglsaux may have been used. This will create a supplementary aux file that glossaries-extra will write all the records to. The file is identified in the main aux file with:

\@bibgls@input{filename}

How Do I Get a List of Entry Labels?

If your build tool is part of an IDE, you might want a list of entry labels for autocompletion. The glossaries package provides the options writeglslabels and writeglslabelnames. These both create a file with the name given by expanding \jobname.glslabels which will contain a list of all defined entry labels, with one label per line. In the case of writeglslabelnames, the label will be followed by a tab character and then the value of entry’s name field.

With bib2gls, this information won’t be available until the .glstex file has been updated. You could try picking out the names of the bib files from the \glsxtr@resource commands, and find the information from the bib files instead.

Summary

You may need to repeat some steps in order to resolve dependencies and allow for changing page numbers.

• If \glsxtr@resource is present in the aux file (but not \@istfilename), then bib2gls is required. Minimum build steps:

  latex myDoc
  bib2gls myDoc
  latex myDoc
  

  Or, to ensure letter groups are supported:

  latex myDoc
  bib2gls --group myDoc
  latex myDoc
  

  (Use bib2gls --help for a list of all available switches.)
• If \@istfilename{style-filename} is present in the aux file (but not \glsxtr@resource), then makeindex or xindy is required. The applicable indexing application can either be invoked explicitly by your build tool or implicitly with makeglossaries or makeglossaries-lite. (What’s the Difference?)
  • If you want to use makeglossaries the minimum build steps are:

    latex myDoc
    makeglossaries myDoc
    latex myDoc
    

  • If you want to use makeglossaries-lite the minimum build steps are:

    latex myDoc
    makeglossaries-lite myDoc
    latex myDoc
    

  • If you want to explicitly invoke makeindex or xindy:
    1. If the style-filename argument of \@istfilename ends with .xdy, then xindy is required, otherwise use makeindex;
    2. If \glsxtr@makeglossaries{glossary-label list} is present, iterate over each glossary label listed in the argument, otherwise iterate over all glossaries identified by \@newglossary and invoke makeindex or xindy as applicable:
       • Fetch the data from the corresponding instance of \@newglossary{glossary-label}{log-ext}{out-ext}{in-ext} that matches the current glossary label and add the appropriate command line arguments:
       • -t basename.log-ext (the makeindex/xindy transcript file);
       • -o basename.out-ext (the makeindex/xindy output file);
       • If \@glsorder{letter} is present in the aux file then, if makeindex, add -l or, if xindy, add -M ord/letorder (letter order);
       • If makeindex, add -s style-filename (where style-filename is the argument of \@istfilename), and also, if \@gls@extramakeindexopts{args} is present, add args;
       • If xindy, add -M style-basename (where style-basename is the style-filename without the .xdy suffix), -C codepage and -L language (where codepage and language are determined from the corresponding \@gls@codepage{glossary-label}{codepage} and \@xdylanguage{glossary-label}{language} for the current glossary).
       • Finally, add (no preceding switch) basename.in-ext (the makeindex/xindy input file).
• If both \glsxtr@resource and \@istfilename are present in the aux file, then both bib2gls and makeindex/xindy are required. Minimum build steps:
  1. Run LaTeX:

     latex myDoc
     

  2. If the LaTeX transcript file contains one or more instances of “Package glossaries-extra Warning: Glossary entry `[...]' has not been defined” or if the bib files have changed then run bib2gls followed by LaTeX:

     bib2gls myDoc
     latex myDoc
     

     In this case bib2gls should not form letter groups (as it’s not expected to do any sorting) so don’t include the --group switch.
  3. Run makeglossaries followed by another LaTeX run.

     makeglossaries myDoc
     latex myDoc
     

  Note that there must be a LaTeX run between the bib2gls call and makeglossaries, and they must be in this order.

  Since this hybrid method is provided for custom xindy modules and there’s no benefit in using it with makeindex, there’s no advantage in substituting makeglossaries for makeglossaries-lite.

  If you prefer to call xindy directly, then follow the steps detailed above.

• If the aux file contains \@gls@reference but does not contain \@istfilename then the minimum build is:

  latex myDoc
  latex myDoc
  

• If the aux file contains \@newglossary but does not contain \@istfilename or \glsxtr@resource or \@gls@reference then there’s either no glossary or \printunsrtglossary has been used. Treat the document as any other document that might contain sections.