List of Tables

[link]

List of Examples

[link]

If an example shows the icon 📥^🖹 then you can click on that icon to try downloading the example source code from a location relative to this document. You can also try using:

〉_
texdoc -l glossaries-user-example〈nnn〉

1. Introduction

[link]

The glossaries package is provided to assist generating lists of terms, symbols or acronyms. For convenience, these lists are all referred to as glossaries in this manual. The terms, symbols and acronyms are collectively referred to as glossary entries.

The package has a certain amount of flexibility, allowing the user to customize the format of the glossary and define multiple glossaries. It also supports glossary styles that include an associated symbol (in addition to a name and description) for each glossary entry.

There is provision for loading a database of glossary entries. Only those entries indexed in the document will be displayed in the glossary. (Unless you use Option 5, which doesn’t use any indexing but will instead list all defined entries in order of definition.)

It’s not necessary to actually have a glossary in the document. You may be interested in using this package just as means to consistently format certain types of terms, such as acronyms, or you may prefer to have descriptions scattered about the document and be able to easily link to the relevant description (Option 6).

🖹
\documentclass{article}
\usepackage[
  sort=none % no sorting or indexing required
]
{glossaries}

\newglossaryentry
 {cafe}% label
 {% definition:
   name={café},
   description={small restaurant selling refreshments}
 }

\setacronymstyle{long-short}
\newacronym
 {html}% label
 {HTML}% short form
 {hypertext markup language}% long form

\newglossaryentry
 {pi}% label
 {% definition:
   name={\ensuremath{\pi}},
   description={Archimedes' Constant}
 }

\newglossaryentry
 {distance}% label
 {% definition:
   name={distance},
   description={the length between two points},
   symbol={m}
 }

\begin{document}
First use: \gls{cafe}, \gls{html}, \gls{pi}.
Next use: \gls{cafe}, \gls{html}, \gls{pi}.

\Gls{distance} (\glsentrydesc{distance}) is measured in
\glssymbol{distance}.
\end{document}

🖹
\documentclass{article}
\usepackage[
 sort=none,% no sorting or indexing required
 abbreviations,% create list of abbreviations
 symbols,% create list of symbols
 postdot, % append a full stop after the descriptions
 stylemods,style=index % set the default glossary style
]{glossaries-extra}

\newglossaryentry % glossaries.sty
 {cafe}% label
 {% definition:
   name={café},
   description={small restaurant selling refreshments}
 }

\setabbreviationstyle{long-short}% glossaries-extra.sty

\newabbreviation % glossaries-extra.sty
 {html}% label
 {HTML}% short form
 {hypertext markup language}% long form

% requires glossaries-extra.sty 'symbols' option

\glsxtrnewsymbol 
 [description={Archimedes' constant}]% options
 {pi}% label
 {\ensuremath{\pi}}% symbol

\newglossaryentry % glossaries.sty
 {distance}% label
 {% definition:
   name={distance},
   description={the length between two points},
   symbol={m}
 }

\begin{document}
First use: \gls{cafe}, \gls{html}, \gls{pi}.
Next use: \gls{cafe}, \gls{html}, \gls{pi}.

\Gls{distance} is measured in \glssymbol{distance}.
\printunsrtglossaries % list all defined entries
\end{document}

Note the difference in the way the abbreviation (HTML) and symbol (\(\pi \)) are defined in the two above examples. The abbreviations, postdot and stylemods options are specific to glossaries-extra. Other options are passed to the base glossaries package.

One of the strengths of the glossaries package is its flexibility, however the drawback of this is the necessity of having a large manual that covers all the various settings. If you are daunted by the size of the manual, try starting off with the much shorter guide for beginners.

This document uses the glossaries-extra package with bib2gls (Option 4). For example, when viewing the PDF version of this document in a hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if you click on the word “indexing” you’ll be taken to the entry in the main glossary where there’s a brief description of the term. This is the way the glossaries mechanism works. An indexing application (bib2gls in this case) is used to generate the sorted list of terms. The indexing applications are CLI tools, which means they can be run directly from a command prompt or terminal, or can be integrated into some text editors, or you can use a build tool such as arara to run them.

In addition to standard glossaries, this document has “standalone” definitions (Option 6). For example, if you click on the command \gls, the hyperlink will take you to main part of the document where the command is described. The index and summaries are also glossaries. The technique used is too complicated to describe in this manual, but an example can be found in “bib2gls: Standalone entries and repeated lists (a little book of poisons)” TUGboat, Volume 43 (2022), No. 1.

Neither of the above two examples require an indexing application. The first is just using the glossaries package for consistent formatting, and there is no list. The second has lists but they are unsorted (see Option 5).

The remainder of this introductory section covers the following:

• •§1.3 lists the available indexing options.

• •§1.4 lists the files provided that contain dummy glossary entries which may be used for testing.

• •§1.5 provides information for users who wish to write in a language other than English.

• •§1.6 describes how to use an indexing application to create the sorted glossaries for your document (Options 2 or 3).

In addition to the examples provided in this document, there are some sample documents provided with the glossaries package. They are described in §18.

The glossaries package comes with a number of sample documents that illustrate the various functions. These are listed in §18.

1.1. Rollback

[link]

The following rollback releases are available:

• •Version 4.52 (2022-11-03):

  🖹
  \usepackage{glossaries}[=v4.52]
  

  This is the last version that uses an internal comma-separated list for the hyper group information in glossary-hypernav. Version 4.53 has switched to using a sequence.

• •Version 4.49 (2021-11-01):

  🖹
  \usepackage{glossaries}[=v4.49]
  

  Note that this should also rollback mfirstuc to version 2.07 if you have a later version installed.

• •Version 4.46 (2020-03-19):

  🖹
  \usepackage{glossaries}[=v4.46]
  

If you rollback using latexrelease to an earlier date, then you will need to specify v4.46 for glossaries as there are no earlier rollback versions available. You may want to consider using one of the historic TeX Live Docker images instead. See, for example, Legacy Documents and TeX Live Docker Images.

1.2. Integrating Other Packages and Known Issues

[link]

If you use hyperref and glossaries, you must load hyperref first (although, in general, hyperref should be loaded after other packages).

Occasionally you may find that certain packages need to be loaded after packages that are required by glossaries but need to also be loaded before glossaries. For example, a package 〈X〉 might need to be loaded after amsgen but before hyperref (which needs to be loaded before glossaries). In which case, load the required package first (for example, amsgen), then 〈X〉, and finally load glossaries.

\usepackage{amsgen}% load before 〈X〉
\usepackage{〈X〉}% must be loaded after amsgen
\usepackage{hyperref}% load after 〈X〉
\usepackage{glossaries}% load after hyperref

Some packages don’t work with some glossary styles. For example, classicthesis doesn’t work with the styles that use the description environment, such as the list style. Since this is the default style, the glossaries package checks for classicthesis and will change the default to the index style if it has been loaded.

Some packages conflict with a package that’s required by a glossary style style package. For example, xtab conflicts with supertabular, which is required by glossary-super. In this case, ensure the problematic glossary style package isn’t loaded. For example, use the nosuper option and (with glossaries-extra) don’t use stylemods=super or stylemods=all. The glossaries package now (v4.50+) checks for xtab and will automatically implement nosuper if it has been loaded.

The language-support is implemented using tracklang. This needs to know the document languages that have to be supported. It currently (version 1.6 at the time of writing) can’t detect the use of \babelprovide. The tracklang package is able to pick up known language labels from the document class options, for example:

🖹
\documentclass[german]{article}
\usepackage[translate=true]{glossaries}

The tracklang package is also able to pick up languages passed as package options to babel or translator, provided they were loaded before tracklang. For example,

🖹
\usepackage[french]{babel}
\usepackage[translate=babel]{glossaries}

In the event that tracklang can’t pick up the required languages, it’s also possible to identify them with the languages option. For example:

🖹
\usepackage[nil]{babel}
\babelprovide{french}
\usepackage[languages=french]{glossaries}

1.3. Indexing Options

[link]

The basic idea behind the glossaries package is that you first define your entries (terms, symbols or acronyms). Then you can reference these within your document (analogous to \cite or \ref). You can also, optionally, display a list of the entries you have referenced in your document (the glossary). This last part, displaying the glossary, is the part that most new users find difficult. There are three options available with the base glossaries package (Options 1–3). The glossaries-extra extension package provides two extra options for lists (Options 4 and 5) as well as an option for standalone descriptions within the document body (Option 6).

An overview of Options 1–5 is given in Table 1.1. Option 6 is omitted from the table as it doesn’t produce a list. For a more detailed comparison of the various methods, see the glossaries performance page. If, for some reason, you want to know what indexing option is in effect, you can test the value of:

\ifglsxindy xindy\else makeindex\fi

Strictly speaking, Options 5 and 6 aren’t actually indexing options as no indexing is performed. In the case of Option 5, all defined entries are listed in order of definition. In the case of Option 6, the entry hypertargets and descriptions are manually inserted at appropriate points in the document. These two options are included here for completeness and for comparison with the actual indexing options.

1.3.1. Option 1 (“noidx”)

[link]

This option isn’t generally recommended for reasons given below. It’s best used with sort=use (order of use) or sort=def (order of definition).

🖹
\documentclass{article}
\usepackage[style=indexgroup]{glossaries}
\makenoidxglossaries % use TeX to sort
\newglossaryentry{parrot}{name={parrot}, 
  description={a brightly coloured tropical bird}}
\newglossaryentry{duck}{name={duck}, 
  description={a waterbird}}
\newglossaryentry{puffin}{name={puffin},
  description={a seabird with a brightly coloured bill}}
\newglossaryentry{penguin}{name={penguin}, 
  description={a flightless black and white seabird}}
% a symbol:
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 sort={alpha},description={a variable}}
% an acronym:
\setacronymstyle{short-long}
\newacronym{arpanet}{ARPANET}{Advanced Research Projects Agency Network}
\begin{document}
\Gls{puffin}, \gls{duck} and \gls{parrot}.
\gls{arpanet} and \gls{alpha}.
Next use: \gls{arpanet}.
\printnoidxglossary
\end{document}

This option doesn’t require an external indexing application but, with the default alphabetic sorting, it’s very slow with severe limitations. If you want a sorted list, it doesn’t work well for extended Latin alphabets or non-Latin alphabets. However, if you use the sanitizesort=false package option (the default for Option 1) then the standard LaTeX accent commands will be ignored, so if an entry’s name is set to \'elite then the sort value will default to elite if sanitizesort=false is used and will default to the literal string \’elite if sanitizesort=true is used.

If you have any other kinds of commands that don’t expand to ASCII characters, such as \alpha, then you must use sanitizesort=true or change the sort method (sort=use or sort=def) in the package options or explicitly set the sort key when you define the relevant entries, as shown in the above example which has:

🖹
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 sort={alpha},description={a variable}
}

This option works best with the sort=def or sort=use setting. For any other setting, be prepared for a long document build time, especially if you have a lot of entries defined. This option is intended as a last resort for alphabetical sorting. This option allows a mixture of sort methods. (For example, sorting by word order for one glossary and order of use for another.) This option is not suitable for hierarchical glossaries and does not form ranges in the location lists. If you really can’t use an indexing application consider using Option 5 instead.

Summary:

1. 1.Add

   🖹
   \makenoidxglossaries
   

   to your preamble (before you start defining your entries, as described in §4).

2. 2.Put

   🖹
   \printnoidxglossary
   

   where you want your list of entries to appear (described in §8). Alternatively, to display all glossaries use the iterative command:

   🖹
   \printnoidxglossaries
   

3. 3.Run LaTeX twice on your document. (As you would do to make a table of contents appear.) For example, click twice on the “typeset” or “build” or “pdfLaTeX” button in your editor.

1.3.2. Option 2 (makeindex)

[link]

🖹
\documentclass{article}
\usepackage[style=indexgroup]{glossaries}
\makeglossaries % open indexing files
\newglossaryentry{parrot}{name={parrot}, 
  description={a brightly coloured tropical bird}}
\newglossaryentry{duck}{name={duck}, 
  description={a waterbird}}
\newglossaryentry{puffin}{name={puffin},
  description={a seabird with a brightly coloured bill}}
\newglossaryentry{penguin}{name={penguin}, 
  description={a flightless black and white seabird}}
% a symbol:
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 sort={alpha},description={a variable}}
% an acronym:
\setacronymstyle{short-long}
\newacronym{arpanet}{ARPANET}{Advanced Research Projects Agency Network}
\begin{document}
\Gls{puffin}, \gls{duck} and \gls{parrot}.
\gls{arpanet} and \gls{alpha}.
Next use: \gls{arpanet}.
\printglossary
\end{document}

This option uses a CLI application called makeindex to sort the entries. This application comes with all modern TeX distributions, but it’s hard-coded for the non-extended Latin alphabet. It can’t correctly sort accent commands (such as \' or \c) and fails with UTF-8 characters, especially for any sort values that start with a UTF-8 character (as it separates the octets resulting in an invalid file encoding). This process involves making LaTeX write the glossary information to a temporary file which makeindex reads. Then makeindex writes a new file containing the code to typeset the glossary. Then \printglossary reads this file in on the next run.

This option works best if you want to sort entries according to the English alphabet and you don’t want to install Perl or Java. This method can also work with the restricted shell escape since makeindex is considered a trusted application, which means you should be able to use the automake=immediate or automake=true package option provided the shell escape hasn’t been completely disabled.

This method can form ranges in the number list but only accepts limited number formats: \arabic, \roman, \Roman, \alph and \Alph.

This option does not allow a mixture of sort methods. All glossaries must be sorted according to the same method: word/letter ordering or order of use or order of definition. If you need word ordering for one glossary and letter ordering for another you’ll have to explicitly call makeindex for each glossary type.

Summary:

1. 1.If you want to use makeindex’s -g option you must change the quote character using \GlsSetQuote. For example:

   🖹
   \GlsSetQuote{+}
   

   This must be used before \makeglossaries. Note that if you are using babel, the shorthands aren’t enabled until the start of the document, so you won’t be able to use the shorthands in definitions that occur in the preamble.

2. 2.Add

   🖹
   \makeglossaries
   

   to your preamble (before you start defining your entries, as described in §4).

3. 3.Put

   🖹
   \printglossary
   

   where you want your list of entries to appear (described in §8). Alternatively, to display all glossaries use the iterative command:

   🖹
   \printglossaries
   

4. 4.Run LaTeX on your document. This creates files with the extensions glo and ist (for example, if your LaTeX document is called myDoc.tex, then you’ll have two extra files called myDoc.glo and myDoc.ist). If you look at your document at this point, you won’t see the glossary as it hasn’t been created yet. (If you use glossaries-extra you’ll see the section heading and some boilerplate text.)

   If you have used package options such as symbols there will also be other sets of files corresponding to the extra glossaries that were created by those options.

5. 5. Run makeindex with the glo file as the input file and the ist file as the style so that it creates an output file with the extension gls:

   〉_
   makeindex -s myDoc.ist -o myDoc.gls myDoc.glo
   

   (Replace myDoc with the base name of your LaTeX document file. Avoid spaces in the file name if possible.)
   ℹ

   The file extensions vary according to the glossary type. See §1.6.4 for further details. makeindex must be called for each set of files.

   If you don’t know how to use the command prompt, then you can probably access makeindex via your text editor, but each editor has a different method of doing this. See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build for some examples.

   Alternatively, run makeindex indirectly via the makeglossaries script:

   〉_
   makeglossaries myDoc
   

   Note that the file extension isn’t supplied in this case. (Replace makeglossaries with makeglossaries-lite if you don’t have Perl installed.) This will pick up all the file extensions from the aux file and run makeindex the appropriate number of times with all the necessary switches.

   The simplest approach is to use arara and add the following comment lines to the start of your document:

   🖹
   % arara: pdflatex
   % arara: makeglossaries
   % arara: pdflatex
   

   (Replace makeglossaries with makeglossarieslite in the second line above if you don’t have Perl installed. Note that there’s no hyphen in this case.)

   The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to add the -l switch:

   〉_
   makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo
   

   (See §1.6.4 for further details on using makeindex explicitly.) If you use makeglossaries or makeglossaries-lite then use the order=letter package option and the -l option will be added automatically.

6. 6. Once you have successfully completed the previous step, you can now run LaTeX on your document again.

1.3.3. Option 3 (xindy)

[link]

🖹
\documentclass{article}
\usepackage[xindy,style=indexgroup]{glossaries}
\makeglossaries % open indexing files
\newglossaryentry{parrot}{name={parrot}, 
  description={a brightly coloured tropical bird}}
\newglossaryentry{duck}{name={duck}, 
  description={a waterbird}}
\newglossaryentry{puffin}{name={puffin},
  description={a seabird with a brightly coloured bill}}
\newglossaryentry{penguin}{name={penguin}, 
  description={a flightless black and white seabird}}
% a symbol:
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 sort={alpha},description={a variable}}
% an acronym:
\setacronymstyle{short-long}
\newacronym{arpanet}{ARPANET}{Advanced Research Projects Agency Network}
\begin{document}
\Gls{puffin}, \gls{duck} and \gls{parrot}.
\gls{arpanet} and \gls{alpha}.
Next use: \gls{arpanet}.
\printglossary
\end{document}

This option uses a CLI application called xindy to sort the entries. This application is more flexible than makeindex and is able to sort extended Latin alphabets or non-Latin alphabets, however it does still have some limitations.

The xindy application comes with both TeX Live and MikTeX, but since xindy is a Perl script, you will also need to install Perl, if you don’t already have it. In a similar way to Option 2, this option involves making LaTeX write the glossary information to a temporary file which xindy reads. Then xindy writes a new file containing the code to typeset the glossary. Then \printglossary reads this file in on the next run.

This is the best option with just the base glossaries package if you want to sort according to a language other than English or if you want non-standard location lists, but it can require some setting up (see §14). There are some problems with certain sort values:

• •entries with the same sort value are merged by xindy into a single glossary line so you must make sure that each entry has a unique sort value;
• •xindy forbids empty sort values;
• •xindy automatically strips control sequences, the math-shift character $ and braces {} from the sort value, which is usually desired but this can cause the sort value to collapse to an empty string which xindy forbids.

🖹
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 sort={alpha},description={a variable}
}

All glossaries must be sorted according to the same method (word/letter ordering, order of use, or order of definition).

Summary:

1. 1.Add the xindy option to the glossaries package option list:

   🖹
   \usepackage[xindy]{glossaries}
   

   If you are using a non-Latin script you’ll also need to either switch off the creation of the number group:

   🖹
   \usepackage[xindy={glsnumbers=false}]{glossaries}
   

   or use either \GlsSetXdyFirstLetterAfterDigits{〈letter〉} (to indicate the first letter group to follow the digits) or \GlsSetXdyNumberGroupOrder{〈spec〉} to indicate where the number group should be placed (see §14).

2. 2.Add \makeglossaries to your preamble (before you start defining your entries, as described in §4).

3. 3.Run LaTeX on your document. This creates files with the extensions glo and xdy (for example, if your LaTeX document is called myDoc.tex, then you’ll have two extra files called myDoc.glo and myDoc.xdy). If you look at your document at this point, you won’t see the glossary as it hasn’t been created yet. (If you’re using the glossaries-extra extension package, you’ll see the section header and some boilerplate text.)

   If you have used package options such as symbols there will also be other sets of files corresponding to the extra glossaries that were created by those options.

4. 4.Run xindy with the glo file as the input file and the xdy file as a module so that it creates an output file with the extension gls. You also need to set the language name and input encoding, as follows (all on one line):

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

   (Replace myDoc with the base name of your LaTeX document file. Avoid spaces in the file name. If necessary, also replace english with the name of your language and utf8 with your input encoding, for example, -L german -C din5007-utf8.)
   ℹ

   The file extensions vary according to the glossary type. See §1.6.3 for further details. xindy must be called for each set of files.

   It’s much simpler to use makeglossaries instead:

   〉_
   makeglossaries myDoc
   

   Note that the file extension isn’t supplied in this case. This will pick up all the file extensions from the aux file and run xindy the appropriate number of times with all the necessary switches.

   There’s no benefit in using makeglossaries-lite with xindy. (Remember that xindy is a Perl script so if you can use xindy then you can also use makeglossaries, and if you don’t want to use makeglossaries because you don’t want to install Perl, then you can’t use xindy either.) If you don’t know how to use the command prompt, then you can probably access xindy or makeglossaries via your text editor, but each editor has a different method of doing this. See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build for some examples.

   Again, a convenient method is to use arara and add the follow comment lines to the start of your document:

   🖹
   % arara: pdflatex
   % arara: makeglossaries
   % arara: pdflatex
   

   The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to add the order=letter package option:

   🖹
   \usepackage[xindy,order=letter]{glossaries}
   

   (and return to the previous step). This option is picked up by makeglossaries. If you are explicitly using xindy then you’ll need to add -M ord/letorder to the options list. See §1.6.3 for further details on using xindy explicitly.

5. 5.Once you have successfully completed the previous step, you can now run LaTeX on your document again. As with makeindex (Option 2), you may need to repeat the previous step and this step to ensure the table of contents and cross-references are resolved.

1.3.4. Option 4 (bib2gls)

[link]

🖹
\documentclass{article}
\usepackage[record,style=indexgroup]{glossaries-extra}
\setabbreviationstyle{short-long}
% data in sample-entries.bib:
\GlsXtrLoadResources[src={sample-entries}]
\begin{document}
\Gls{puffin}, \gls{duck} and \gls{parrot}.
\gls{arpanet} and \gls{alpha}.
Next use: \gls{arpanet}.
\printunsrtglossary
\end{document}

🖹
@entry{parrot,
 name={parrot}, 
 description={a brightly coloured tropical bird}
}
@entry{duck,
 name={duck}, 
 description={a waterbird}
}
@entry{puffin,
 name={puffin},
 description={a seabird with a brightly coloured bill}
}
@entry{penguin,
 name={penguin}, 
 description={a flightless black and white seabird}
}
@symbol{alpha,
 name={\ensuremath{\alpha}},
 description={a variable}
}
@abbreviation{arpanet,
  short={ARPANET},
  long={Advanced Research Projects Agency Network}
}

All entries must be provided in one or more bib files. (See the bib2gls user manual for the required format.) In this example, the terms “parrot”, “duck”, “puffin” and “penguin” are defined using @atentry, the symbol alpha (\(\alpha \)) is defined using @symbol and the abbreviation “ARPANET” is defined using @abbreviation.

The glossaries-extra package needs to be loaded with the record package option:

🖹
\usepackage[record]{glossaries-extra}

🖹
\usepackage[record=only]{glossaries-extra}

🖹
\usepackage[record=nameref]{glossaries-extra}

Each resource set is loaded with \GlsXtrLoadResources. For example:

🖹
\GlsXtrLoadResources
[% definitions in entries1.bib and entries2.bib:
 src={entries1,entries2},
 sort={de-CH-1996}% sort according to this locale
]

If you want to ensure that all entries are selected, even if they haven’t been referenced in the document, then add the option selection=all. (There are also ways of filtering the selection or you can even have a random selection by shuffling and truncating the list. See the bib2gls user manual for further details.)

The glossary is displayed using:

🖹
\printunsrtglossary

🖹
\printunsrtglossaries

〉_
pdflatex myDoc
bib2gls myDoc
pdflatex myDoc

〉_
bib2gls --group myDoc

🖹
% arara: bib2gls: { group: on }

Unlike Options 2 and 3, this method doesn’t create a file containing the typeset glossary but simply determines which entries are needed for the document, their associated locations and (if required) their associated letter group. This option allows a mixture of sort methods. For example, sorting by word order for one glossary and order of use for another or even sorting one block of the glossary differently to another block in the same glossary. See bib2gls gallery: sorting.

This method supports Unicode and uses the Common Locale Data Repository, which provides more extensive language support than xindy. (Except for Klingon, which is supported by xindy, but not by the CLDR.) The locations in the number list may be in any format. If bib2gls can deduce a numerical value it will attempt to form ranges otherwise it will simply list the locations.

Summary:

1. 1.Use glossaries-extra with the record package option:

   🖹
   \usepackage[record]{glossaries-extra}
   

2. 2.Use \GlsXtrLoadResources to identify the bib file(s) and bib2gls options. The bib extension may be omitted:

   🖹
   \GlsXtrLoadResources[src={terms.bib,abbreviations.bib},sort=en]
   

3. 3.Put

   🖹
   \printunsrtglossary
   

   where you want your list of entries to appear. Alternatively to display all glossaries use the iterative command:

   🖹
   \printunsrtglossaries
   

4. 4.Run LaTeX on your document.

5. 5.Run bib2gls with just the document base name.

6. 6.Run LaTeX on your document.

See glossaries-extra and bib2gls: An Introductory Guide or the bib2gls user manual for further details of this method, and also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

1.3.5. Option 5 (“unsrt”)

[link]

🖹
\documentclass{article}
\usepackage[style=indexgroup]{glossaries-extra}
\newglossaryentry{parrot}{name={parrot}, 
  description={a brightly coloured tropical bird}}
\newglossaryentry{duck}{name={duck}, 
  description={a waterbird}}
\newglossaryentry{puffin}{name={puffin},
  description={a seabird with a brightly coloured bill}}
\newglossaryentry{penguin}{name={penguin}, 
  description={a flightless black and white seabird}}
% a symbol:
\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 description={a variable}}
% an abbreviation:
\setabbreviationstyle{short-long}
\newabbreviation{arpanet}{ARPANET}{Advanced Research Projects Agency Network}
\begin{document}
\Gls{puffin}, \gls{duck} and \gls{parrot}.
\gls{arpanet} and \gls{alpha}.
Next use: \gls{arpanet}.
\printunsrtglossary
\end{document}

The result is different from the previous examples. Now all entries are listed in the glossary, including “penguin” which hasn’t been referenced in the document, and the list is in the order that the entries were defined. There are no number lists.

The \printunsrtglossary command simply iterates over the set of all defined entries associated with the given glossary and lists them in the order of definition. This means that child entries must be defined immediately after their parent entry if they must be kept together in the glossary. Some glossary styles indent entries that have a parent but it’s the indexing application that ensures the child entries are listed immediately after the parent. If you’re opting to use this manual approach then it’s your responsibility to define the entries in the correct order.

The glossaries-extra package requires entries to be defined in the preamble by default. It’s possible to remove this restriction, but bear in mind that any entries defined after \printunsrtglossary won’t be listed.

The glossary is displayed using:

🖹
\printunsrtglossary

🖹
\printunsrtglossaries

This method will display all defined entries, regardless of whether or not they have been used in the document. Note that this uses the same command for displaying the glossary as Option 4. This is because bib2gls takes advantage of this method by defining the wanted entries in the required order and setting the locations (and letter group information, if required). See the glossaries-extra manual for further details.

Therefore, the above example document has a glossary containing the entries: parrot, duck, puffin, penguin, \(\alpha \) and ARPANET (in that order). Note that the “penguin” entry has been included even though it wasn’t referenced in the document.

This just requires a single LaTeX call:

〉_
pdflatex myDoc

〉_
pdflatex myDoc
pdflatex myDoc

See the glossaries-extra documentation for further details of this method.

1.3.6. Option 6 (“standalone”)

[link]

You can either define entries in the preamble (or in an external file loaded with \loadglsentries), as with Option 5.

🖹
\documentclass{article}

\usepackage[colorlinks]{hyperref}
\usepackage[sort=none,
   nostyles% <- no glossary styles are required
 ]{glossaries-extra}

\newglossaryentry{set}{name={set},
  description={a collection of any kind of objects},
  symbol={\ensuremath{\mathcal{S}}}
}

\newglossaryentry{function}{name={function},
  description={a rule that assigns every element in the    domain \gls{set} to an element in the range \gls{set}},
  symbol={\ensuremath{f(x)}}
}
\newcommand*{\termdef}[1]{% 
  \section{\glsxtrglossentry{#1} \glsentrysymbol{#1}}% 
  \begin{quote}\em\Glsentrydesc{#1}.\end{quote}% 
}
\begin{document}
\tableofcontents

\section{Introduction}
Sample document about \glspl{function} and \glspl{set}.

\termdef{set}

More detailed information about \glspl{set} with examples.

\termdef{function}

More detailed information about \glspl{function} with examples.

\end{document}

Or you can use bib2gls if you want to manage a large database of terms. For example:

🖹
\documentclass{article}

\usepackage[colorlinks]{hyperref}
\usepackage[record,
   nostyles% <- no glossary styles are required
  ]{glossaries-extra}

\GlsXtrLoadResources[src={terms},sort=none,save-locations=false]

\newcommand*{\termdef}[1]{% 
  \section{\glsxtrglossentry{#1} \glossentrysymbol{#1}}% 
  \glsadd{#1}% <- index this entry
  \begin{quote}\em\Glsentrydesc{#1}.\end{quote}% 
}
\begin{document}
\tableofcontents

\section{Introduction}
Sample document about \glspl{function} and \glspl{set}.

\termdef{set}

More detailed information about \glspl{set} with examples.

\termdef{function}

More detailed information about \glspl{function} with examples.
\end{document}

🖹
@entry{set,
  name={set},
  description={a collection of any kind of objects},
  symbol={\ensuremath{\mathcal{S}}}
}
@entry{function,
  name={function},
  description={a rule that assigns every element in the domain   \gls{set} to an element in the range \gls{set}},
  symbol={\ensuremath{f(x)}}
}

In both cases, there’s no need to load all the glossary styles packages, as they’re not required, so I’ve used the nostyles package option to prevent them from being loaded.

In the first case, you just need to define the terms (preferably in the preamble or in a file that’s input in the preamble). No external tool is required. Just run LaTeX as normal. (Twice to ensure that the table of contents is up to date.)

〉_
pdflatex myDoc
pdflatex myDoc

In the second case, you need the record package option (as in Option 4) since bib2gls is needed to select the required entries, but you don’t need a sorted list:

🖹
\GlsXtrLoadResources[src={terms},sort=none]

Remember that for this second case you need to run bib2gls as per Option 4:

〉_
pdflatex myDoc
bib2gls myDoc
pdflatex myDoc
pdflatex myDoc

For both cases (with or without bib2gls), instead of listing all the entries using \printunsrtglossary, you use \glsxtrglossentry{〈label〉} where you want the name (and anchor with hyperref) to appear in the document. This will allow the link text created by commands like \gls to link to that point in the document. The description can simply be displayed with \glsentrydesc{〈label〉} or \Glsentrydesc{label}, as in the above examples. In both examples, I’ve defined a custom command \termdef to simplify the code and ensure consistency. Extra styling, such as placing the description in a coloured frame, can be added to this custom definition as required.

(Instead of using \glsentrydesc or \Glsentrydesc, you can use \glossentrydesc{〈label〉}, which will obey category attributes such as glossdesc and glossdescfont. See the glossaries-extra manual for further details.)

The symbol (if required) can be displayed with either \glsentrysymbol{〈label〉} or \glossentrysymbol{〈label〉}. In the first example, I’ve used \glsentrysymbol. In the second I’ve used \glossentrysymbol. The latter is necessary with bib2gls if the symbol needs to go in a section title as the entries aren’t defined on the first LaTeX run.

In normal document text, \glsentrysymbol will silently do nothing if the entry hasn’t been defined, but when used in a section heading it will expand to an undefined internal command when written to the aux file, which triggers an error.

The \glossentrysymbol command performs an existence check, which triggers a warning if the entry is undefined. (All entries will be undefined before the first bib2gls call.) You need at least glossaries-extra v1.42 to use this command in a section title. (\glossentrysymbol is defined by the base glossaries package but is redefined by glossaries-extra.) If hyperref has been loaded, this will use \texorpdfstring to allow a simple expansion for the PDF bookmarks (see the glossaries-extra user manual for further details).

If you want to test if the symbol field has been set, you need to use \ifglshassymbol outside of the section title. For example:

🖹
\ifglshassymbol{#1}% 
{\section{\glsxtrglossentry{#1} \glossentrysymbol{#1}}}
{\section{\glsxtrglossentry{#1}}}

In both of the above examples, the section titles start with a lowercase character (because the name value is all lowercase in entry definitions). You can apply automatic case change with the glossname category attribute. For example:

🖹
\glssetcategoryattribute{general}{glossname}{firstuc}

🖹
\glssetcategoryattribute{general}{glossname}{title}

In the second example, you can instead use bib2gls to apply a case change. For example, to apply sentence case to the name field:

🖹
\GlsXtrLoadResources[src={terms},
 sort=none,save-locations=false,
 replicate-fields={name=text},
 name-case-change=firstuc
]

In the first example (without bib2gls) you can do this manually. For example:

🖹
\newglossaryentry{set}{name={Set},text={set},
  description={a collection of any kind of objects},
  symbol={\ensuremath{\mathcal{S}}}
}

Note that if you use the default save-locations=true with bib2gls, it’s possible to combine Options 4 and 6 to have both standalone definitions and an index. In this case, a glossary style is required. In the example below, I’ve use bookindex, which is provided in the glossary-bookindex package (bundled with glossaries-extra). I don’t need any of the other style packages, so I can still keep the nostyles option and just load glossary-bookindex:

🖹
\usepackage[record=nameref,% <- using bib2gls
 nostyles,% <- don't load default style packages
 stylemods=bookindex,% <- load glossary-bookindex.sty
 style=bookindex% <- set the default style to 'bookindex'
]{glossaries-extra}

🖹
\GlsXtrLoadResources[src={terms},% definitions in terms.bib
 sort=en-GB,% sort by this locale
 replicate-fields={name=text},
 name-case-change=firstuc
]

🖹
\printunsrtglossary[title=Index,target=false]

〉_
bib2gls --group myDoc

🖹
% arara: bib2gls: { group: on }

The bookindex style doesn’t show the description, so only the name and location is displayed. Remember that the name has had a case change so it now starts with an initial capital. If you feel this is inappropriate for the index, you can adjust the bookindex style so that it uses the text field instead. For example:

🖹
\renewcommand*{\glsxtrbookindexname}[1]{% 
  \glossentrynameother{#1}{text}}

Note that on the first LaTeX run none of the entries will be defined. Once they are defined, the page numbers may shift due to the increased amount of document text. You may therefore need to repeat the document build to ensure the page numbers are correct.

If there are extra terms that need to be included in the index that don’t have a description, you can define them with @index in the bib file. For example:

🖹
@index{element}
@index{member,alias={element}}

🖹
The objects that make up a set are the \glspl{element}
or \glspl{member}.

1.4. Dummy Entries for Testing

[link]

In addition to the sample files described in §18, glossaries also provides some files containing lorum ipsum dummy entries. These are provided for testing purposes and are on TeX’s path (in tex/latex/glossaries/test-entries) so they can be included via \input or \loadglsentries. The glossaries-extra package provides bib versions of all these files for use with bib2gls. The files are as follows:

🖹
\newglossaryentry{lorem}{name={lorem},description={ipsum}}

🖹
\newglossaryentry{loremipsum}{name={lorem ipsum},
description={dolor sit amet, consectetuer adipiscing  elit. Ut purus elit, vestibulum ut, placerat ac,  adipiscing vitae, felis. Curabitur dictum gravida  mauris.}}

🖹
\longnewglossaryentry{loremi-ii}{name={lorem 1--2}}% 
{% 
Lorem ipsum ...

Nam dui ligula...
}

🖹
\newglossaryentry{alpha}{name={alpha},
symbol={\ensuremath{\alpha}},
description={Quisque ullamcorper placerat ipsum.}}

🖹
\newglossaryentry{sym.alpha}{sort={alpha},
name={\ensuremath{\alpha}},
description={Quisque ullamcorper placerat ipsum.}}

🖹
\newglossaryentry{sample-a}
{name={a name},
description={a description},
symbol={\ensuremath{\alpha}},
user1={A},
user2={1},
user3={i},
user4={A-i},
user5={25.2020788573521},
user6={1585-11-06}}

🖹
\newglossaryentry{sample-b-0}
{parent={sample-b},
name={b/0 name},
description={child 0 of b},
symbol={\ensuremath{\sigma}},
user2={0},
user4={a-i}}

🖹
\longnewglossaryentry{sedfeugiat}{name={sed feugiat},
user1={example-image}}% 
{% 
Cum sociis natoque...

Etiam...
}

🖹
\newacronym[type={\glsdefaulttype}]{lid}{LID}{lorem ipsum 
dolor}

🖹
\setabbreviationstyle[acronym]{long-short}

🖹
\newacronym[type={\glsdefaulttype},
  description={fringilla a, euismod sodales,   sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula}

🖹
\setabbreviationstyle[acronym]{long-short-desc}

🖹
\newacronym[type={\glsdefaulttype},user1={love itself}]
 {li}{LI}{lorem ipsum}

🖹
\setabbreviationstyle[acronym]{long-short-user}

🖹
\newglossaryentry{sedmattis}{name={sed mattis},
description={erat sit amet}}

\newglossaryentry{gravida}{parent={sedmattis},
  name={gravida},description={malesuada}}

🖹
\newglossaryentry{scelerisque}{name={scelerisque},
  description={at}}

\newglossaryentry{vestibulum}{parent={scelerisque},
  description={eu, nulla}}

🖹
\newglossaryentry{longsedmattis}{name={sed mattis},
 description={erat sit amet dolor sit amet, consectetuer adipiscing elit.   Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis.   Curabitur dictum gravida mauris.}}

\newglossaryentry{longgravida}{parent={longsedmattis},name={gravida},
 description={malesuada libero, nonummy eget, consectetuer id, vulputate a,   magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Mauris ut leo.}}

🖹
\newglossaryentry{hiersedmattis}{name={sed mattis},user1={example-image},
 description={Erat sit amet dolor sit amet, consectetuer adipiscing elit.   Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Ut pellentesque augue sed urna. Vestibulum diam eros, fringilla et, consectetuer eu, nonummy id, sapien. Nullam at lectus. In sagittis ultrices mauris. Curabitur malesuada erat sit amet massa. Fusce blandit. Aliquam erat volutpat.}}

\longnewglossaryentry{hierloremi-ii}
{name={lorem 1--2},parent={hiersedmattis}}% 
{% 
Lorem ipsum ...

Nam dui ligula...
}

🖹
\newglossaryentry{fusce}{name={fusce},
description={suscipit cursus sem},user1={article-minimal}}

🖹
\newglossaryentry{aenean-url}{name={aenean},
 description={adipiscing auctor est},
 user1={http://uk.tug.org/}}

The sample file glossary-lipsum-examples.tex in the doc/latex/glossaries/samples directory uses all these files. See also glossaries gallery.

🖹
\newglossaryentry{alias-lorem}{name={alias-lorem},
 description={ipsum},alias={lorem}}

\newglossaryentry{amet}{name={amet},description={consectetuer},
 see={dolor}}

\newglossaryentry{arcu}name={arcu},description={libero},
 seealso={placerat,vitae,curabitur}

1.5. Multi-Lingual Support

[link]

As from version 1.17, the glossaries package can be used with xindy as well as makeindex. If you are writing in a language that uses an extended Latin alphabet or non-Latin alphabet it’s best to use Option 3 (xindy) or Option 4 (bib2gls) as makeindex (Option 2) is hard-coded for the non-extended Latin alphabet and Option 1 can only perform limited ASCII comparisons.

This means that with Options 3 or 4 you are not restricted to the A, …, Z letter groups. If you want to use xindy, remember to use the xindy package option. For example:

🖹
\documentclass[french]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage[xindy]{glossaries}

If you want to use bib2gls, you need to use the record option with glossaries-extra and supply the definitions in bib files. (See the bib2gls user manual for further details.)

With old versions of mfirstuc (pre v2.08), if you use a UTF-8 character at the start of an entry name, you must place it in a group, or it will cause a problem for sentence case commands (e.g. \Gls). For example:

🖹
% mfirstuc v2.07:
\newglossaryentry{elite}{name={{é}lite},
description={select group or class}}

🖹
% mfirstuc v2.08:
\newglossaryentry{elite}{name={élite},
description={select group or class}}

If you are using xindy or bib2gls, the application needs to know the encoding of the tex file. This information is added to the aux file and can be picked up by makeglossaries and bib2gls. If you use xindy explicitly instead of via \makeglossaries, you may need to specify the encoding using the -C option. Read the xindy manual for further details of this option.

If you have the double-quote character (") as an active character (for example, a babel shorthand) and you want to use makeindex’s -g option, you’ll need to change makeindex’s quote character using:

🖹
\GlsSetQuote{+}

In general, it’s best not to use babel’s shorthands in entry definitions. For example:

🖹
\documentclass{article}

\usepackage[ngerman]{babel}
\usepackage{glossaries}

\GlsSetQuote{+}

\makeglossaries

\newglossaryentry{rna}{name=ribonukleinsäure,
  sort={ribonukleins"aure},
  description={eine Nukleinsäure}}

\begin{document}
\gls{rna}

\printglossaries
\end{document}

1.5.1. Changing the Fixed Names

[link]

The fixed names are produced using the commands listed in Table 1.2. If you aren’t using a language package such as babel or polyglossia that uses caption hooks, you can just redefine these commands as appropriate. If you are using babel or polyglossia, you need to use their caption hooks to change the defaults. See changing the words babel uses or read the babel or polyglossia documentation. If you have loaded babel, then glossaries will attempt to load translator, unless you have used the notranslate, translate=false or translate=babel package options. If the translator package is loaded, the translations are provided by dictionary files (for example, glossaries-dictionary-English.dict). See the translator package for advice on changing translations provided by translator dictionaries. If you can’t work out how to modify these dictionary definitions, try switching to babel’s interface using translate=babel:

🖹
\documentclass[english,french]{article}
\usepackage{babel}
\usepackage[translate=babel]{glossaries}

As from version 4.12, multilingual support is provided by separate language modules that need to be installed in addition to installing the glossaries package. You only need to install the modules for the languages that you require. If the language module has an unmaintained status, you can volunteer to take over the maintenance by contacting me at http://www.dickimaw-books.com/contact.html. The translator dictionary files for glossaries are now provided by the appropriate language module. For further details about information specific to a given language, please see the documentation for that language module.

Examples of use:

• •Using babel and translator:

  🖹
  \documentclass[english,french]{article}
  \usepackage{babel}
  \usepackage{glossaries}
  

  (translator is automatically loaded).

• •Using babel:

  🖹
  \documentclass[english,french]{article}
  \usepackage{babel}
  \usepackage[translate=babel]{glossaries}
  

  (translator isn’t loaded). The glossaries-extra package has translate=babel as the default if babel has been loaded.

• •Using polyglossia:

  🖹
  \documentclass{article}
  \usepackage{polyglossia}
  \setmainlanguage{english}
  \usepackage{glossaries}
  

Due to the varied nature of glossaries, it’s likely that the predefined translations may not be appropriate. If you are using the babel package and the glossaries package option translate=babel, you need to be familiar with the advice given in changing the words babel uses. If you are using the translator package, then you can provide your own dictionary with the necessary modifications (using \deftranslation) and load it using \usedictionary. If you simply want to change the title of a glossary, you can use the title key in commands like \printglossary (but not the iterative commands like \printglossaries).

Your custom dictionary doesn’t have to be just a translation from English to another language. You may prefer to have a dictionary for a particular type of document. For example, suppose your institution’s in-house reports have to have the glossary labelled as “Nomenclature” and the location list should be labelled “Location”, then you can create a file called, say, myinstitute-glossaries-dictionary-English.dict that contains the following:

🖹
\ProvidesDictionary{myinstitute-glossaries-dictionary}{English}
\deftranslation{Glossary}{Nomenclature}
\deftranslation{Page List (glossaries)}{Location}

🖹
\usedictionary{myinstitute-glossaries-dictionary}

If you are using babel and don’t want to use the translator interface, you can use the package option translate=babel. For example:

🖹
\documentclass[british]{article}

\usepackage{babel}
\usepackage[translate=babel]{glossaries}

\addto\captionsbritish{% 
  \renewcommand*{\glossaryname}{List of Terms}% 
  \renewcommand*{\acronymname}{List of Acronyms}% 
}

Note that xindy and bib2gls provide much better multi-lingual support than makeindex, so I recommend that you use Options 2 or 3 if you have glossary entries that contain non-Latin characters. See §14 for further details on xindy, and see the bib2gls user manual for further details of that application.

1.5.2. Creating a New Language Module

[link]

The glossaries package now uses the tracklang package to determine which language modules need to be loaded. If you want to create a new language module, you should first read the tracklang documentation.

To create a new language module, you need to at least create two files called: glossaries-〈lang〉.ldf and glossaries-dictionary-〈Lang〉.dict where 〈lang〉 is the root language name (for example, english) and 〈Lang〉 is the language name used by translator (for example, English).

Here’s an example of glossaries-dictionary-English.dict:

🖹
\ProvidesDictionary{glossaries-dictionary}{English}

\providetranslation{Glossary}{Glossary}
\providetranslation{Acronyms}{Acronyms}
\providetranslation{Notation (glossaries)}{Notation}
\providetranslation{Description (glossaries)}{Description}
\providetranslation{Symbol (glossaries)}{Symbol}
\providetranslation{Page List (glossaries)}{Page List}
\providetranslation{Symbols (glossaries)}{Symbols}
\providetranslation{Numbers (glossaries)}{Numbers}

Here’s an example of glossaries-english.ldf:

🖹
\ProvidesGlossariesLang{english}

\glsifusedtranslatordict{English}
{% 
  \addglossarytocaptions{\CurrentTrackedLanguage}% 
  \addglossarytocaptions{\CurrentTrackedDialect}% 
}
{% 
  \@ifpackageloaded{polyglossia}% 
  {% 
    \newcommand*{\glossariescaptionsenglish}{% 
      \renewcommand*{\glossaryname}{\textenglish{Glossary}}% 
      \renewcommand*{\acronymname}{\textenglish{Acronyms}}% 
      \renewcommand*{\entryname}{\textenglish{Notation}}% 
      \renewcommand*{\descriptionname}{\textenglish{Description}}% 
      \renewcommand*{\symbolname}{\textenglish{Symbol}}% 
      \renewcommand*{\pagelistname}{\textenglish{Page List}}% 
      \renewcommand*{\glssymbolsgroupname}{\textenglish{Symbols}}% 
      \renewcommand*{\glsnumbersgroupname}{\textenglish{Numbers}}% 
    }% 
  }% 
  {% 
    \newcommand*{\glossariescaptionsenglish}{% 
      \renewcommand*{\glossaryname}{Glossary}% 
      \renewcommand*{\acronymname}{Acronyms}% 
      \renewcommand*{\entryname}{Notation}% 
      \renewcommand*{\descriptionname}{Description}% 
      \renewcommand*{\symbolname}{Symbol}% 
      \renewcommand*{\pagelistname}{Page List}% 
      \renewcommand*{\glssymbolsgroupname}{Symbols}% 
      \renewcommand*{\glsnumbersgroupname}{Numbers}% 
    }% 
  }% 
  \ifcsdef{captions\CurrentTrackedDialect}
  {% 
    \csappto{captions\CurrentTrackedDialect}% 
    {% 
      \glossariescaptionsenglish
    }% 
  }% 
  {% 
    \ifcsdef{captions\CurrentTrackedLanguage}
    {% 
      \csappto{captions\CurrentTrackedLanguage}% 
      {% 
        \glossariescaptionsenglish
      }% 
    }% 
    % 
    % 
  }% 
  \glossariescaptionsenglish
}
\renewcommand*{\glspluralsuffix}{s}
\renewcommand*{\glsacrpluralsuffix}{\glspluralsuffix}
\renewcommand*{\glsupacrpluralsuffix}{\glstextup{\glspluralsuffix}}

The suffixes used to generate the plural forms when the plural hasn’t been specified are given by \glspluralsuffix (for general entries). For acronyms defined with the base \newacronym, \glsupacrpluralsuffix is used for the small caps acronym styles where the suffix needs to be set using \glstextup to counteract the effects of \textsc and \glsacrpluralsuffix for other acronym styles. There’s no guarantee when these commands will be expanded. They may be expanded on definition or they may be expanded on use, depending on the glossaries configuration.

If you want to add a regional variation, create a file called glossaries-〈iso-lang〉-〈iso-region〉.ldf, where 〈iso-lang〉 is the ISO language code and 〈iso-region〉 is the ISO country code. For example, glossaries-en-GB.ldf. This file can load the root language file and make the appropriate changes, for example:

🖹
\ProvidesGlossariesLang{en-GB}
 \RequireGlossariesLang{english}
 \glsifusedtranslatordict{British}
 {% 
   \addglossarytocaptions{\CurrentTrackedLanguage}% 
   \addglossarytocaptions{\CurrentTrackedDialect}% 
 }
 {% 
   \@ifpackageloaded{polyglossia}% 
   {% 
     % Modify \glossariescaptionsenglish as appropriate for
     % polyglossia
   }% 
   {% 
     % Modify \glossariescaptionsenglish as appropriate for
     % non-polyglossia
   }% 
 }

If the translations includes non-Latin characters, it’s a good idea to provide code that’s independent of the input encoding. Remember that while some users may use UTF-8 (and it’s now the default encoding with modern LaTeX kernels), others may use Latin-1 or any other supported encoding, but while users won’t appreciate you enforcing your preference on them, it’s useful to provide a UTF-8 version.

The glossaries-irish.ldf file provides this as follows:

🖹
\ProvidesGlossariesLang{irish}

\glsifusedtranslatordict{Irish}
{% 
  \addglossarytocaptions{\CurrentTrackedLanguage}% 
  \addglossarytocaptions{\CurrentTrackedDialect}% 
}
{% 
  \ifdefstring{\inputencodingname}{utf8}
  {\input{glossaries-irish-utf8.ldf}}% 
  {% 
    \ifdef\XeTeXinputencoding% XeTeX defaults to UTF-8
    {\input{glossaries-irish-utf8.ldf}}% 
    {\input{glossaries-irish-noenc.ldf}}
  }
  \ifcsdef{captions\CurrentTrackedDialect}
  {% 
    \csappto{captions\CurrentTrackedDialect}% 
    {% 
      \glossariescaptionsirish
    }% 
  }% 
  {% 
    \ifcsdef{captions\CurrentTrackedLanguage}
    {
      \csappto{captions\CurrentTrackedLanguage}% 
      {% 
        \glossariescaptionsirish
      }% 
    }% 
    {% 
    }% 
  }% 
  \glossariescaptionsirish
}

There are now two extra files: glossaries-irish-noenc.ldf (no encoding information) and glossaries-irish-utf8.ldf (UTF-8).

These both define \glossariescaptionsirish but the *-noenc.ldf file uses LaTeX accent commands:

🖹
\@ifpackageloaded{polyglossia}% 
{% 
  \newcommand*{\glossariescaptionsirish}{% 
    \renewcommand*{\glossaryname}{\textirish{Gluais}}% 
    \renewcommand*{\acronymname}{\textirish{Acrainmneacha}}% 
    \renewcommand*{\entryname}{\textirish{Ciall}}% 
    \renewcommand*{\descriptionname}{\textirish{Tuairisc}}% 
    \renewcommand*{\symbolname}{\textirish{Comhartha}}% 
    \renewcommand*{\glssymbolsgroupname}{\textirish{Comhartha\'\i}}% 
    \renewcommand*{\pagelistname}{\textirish{Leathanaigh}}% 
    \renewcommand*{\glsnumbersgroupname}{\textirish{Uimhreacha}}% 
  }% 
}% 
{% 
  \newcommand*{\glossariescaptionsirish}{% 
    \renewcommand*{\glossaryname}{Gluais}% 
    \renewcommand*{\acronymname}{Acrainmneacha}% 
    \renewcommand*{\entryname}{Ciall}% 
    \renewcommand*{\descriptionname}{Tuairisc}% 
    \renewcommand*{\symbolname}{Comhartha}% 
    \renewcommand*{\glssymbolsgroupname}{Comhartha\'\i}% 
    \renewcommand*{\pagelistname}{Leathanaigh}% 
    \renewcommand*{\glsnumbersgroupname}{Uimhreacha}% 
  }% 
}

1.6. Generating the Associated Glossary Files

[link]

If this section seriously confuses you, and you can’t work out how to run external tools like makeglossaries or makeindex, you can try using the automake package option, described in §2.5, but you will need TeX’s shell escape enabled. See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

In order to generate a sorted glossary with compact number lists, it is necessary to use an external indexing application as an intermediate step (unless you have chosen Option 1, which uses TeX to do the sorting or Option 5, which doesn’t perform any sorting). It is this application that creates the file containing the code required to typeset the glossary. If this step is omitted, the glossaries will not appear in your document. The two indexing applications that are most commonly used with LaTeX are makeindex and xindy. As from version 1.17, the glossaries package can be used with either of these applications. Previous versions were designed to be used with makeindex only. With the glossaries-extra package, you can also use bib2gls as the indexing application. (See the glossaries-extra and bib2gls user manuals for further details.) Note that xindy and bib2gls have much better multi-lingual support than makeindex, so xindy or bib2gls are recommended if you’re not writing in English. Commands that only have an effect when xindy is used are described in §14.

🖹
% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex

The glossaries package comes with the Perl script makeglossaries which will run makeindex or xindy on all the indexing files using a customized style file (which is created by \makeglossaries). See §1.6.1 for further details. Perl is stable, cross-platform, open source software that is used by a number of TeX-related applications (including xindy and latexmk). Most Unix-like operating systems come with a Perl interpreter. TeX Live also comes with a Perl interpreter. As far as I know, MikTeX doesn’t come with a Perl interpreter so if you are a Windows MikTeX user you will need to install Perl if you want to use makeglossaries or xindy. Further information is available at http://www.perl.org/about.html and MikTeX and Perl scripts (and one Python script).

The advantages of using makeglossaries:

• •It automatically detects whether to use makeindex or xindy and sets the relevant application switches.

• •One call of makeglossaries will run makeindex/xindy for each glossary type.

• •If things go wrong, makeglossaries will scan the messages from makeindex or xindy and attempt to diagnose the problem in relation to the glossaries package. This will hopefully provide more helpful messages in some cases. If it can’t diagnose the problem, you will have to read the relevant transcript file and see if you can work it out from the makeindex or xindy messages.

• •If makeindex warns about multiple encap values, makeglossaries v2.18+ will detect this and attempt to correct the problem. This correction is only provided by makeglossaries when makeindex is used since xindy uses the order of the attributes list to determine which format should take precedence. (see §14.3.) This correction can be switched off with the -e switch.

• •If makeindex warns about invalid or empty locations, makeglossaries v4.50+ will detect this and attempt to alter the location to fit makeindex’s syntax. This may or may not cause unexpected results in the location list, but it’s useful if the nonumberlist option is used.

• •If makeindex has a warning that could be the result of a command occurring within the location, makeglossaries v4.50+ will attempt to repair it by moving the command out of the location and into the encap.

As from version 4.16, the glossaries package also comes with a Lua script called makeglossaries-lite. This is a trimmed-down alternative to the makeglossaries Perl script. It doesn’t have some of the options that the Perl version has and it doesn’t attempt to diagnose any problems, but since modern TeX distributions come with LuaTeX (and therefore have a Lua interpreter) you don’t need to install anything else in order to use makeglossaries-lite so it’s an alternative to makeglossaries if you want to use Option 2 (makeindex).

If things go wrong and you can’t work out why your glossaries aren’t being generated correctly, you can use makeglossariesgui as a diagnostic tool. Once you’ve fixed the problem, you can then go back to using makeglossaries or makeglossaries-lite.

Whilst I strongly recommended that you use the makeglossaries Perl script or the makeglossaries-lite Lua script, it is possible to use the glossaries package without using those applications. However, note that some commands and package options have no effect if you explicitly run makeindex/xindy. These are listed in Table 1.3.

Below, references to makeglossaries can usually be substituted with makeglossaries-lite, except where noted otherwise.

If any of your entries use an entry that is not referenced outside the glossary (for example, the entry is only referenced in the description of another entry), you will need to do an additional makeglossaries, makeindex or xindy run, as appropriate. For example, suppose you have defined the following entries:

🖹
\newglossaryentry{citrusfruit}{name={citrus fruit},
description={fruit of any citrus tree. (See also  \gls{orange})}}

\newglossaryentry{orange}{name={orange},
description={an orange coloured fruit.}}

〉_
pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc

Likewise, an additional makeglossaries and LaTeX run may be required if the document pages shift with re-runs. For example, if the page numbering is not reset after the table of contents, the insertion of the table of contents on the second LaTeX run may push glossary entries across page boundaries, which means that the number lists in the glossary may need updating.

The examples in this document assume that you are accessing makeglossaries, xindy or makeindex via a terminal. Windows users can use the command prompt which is usually accessed via the Start➜All Programs menu or Start➜All Programs➜Accessories menu or Start➜Windows System.

Alternatively, your text editor may have the facility to create a function that will call the required application. See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

If any problems occur, remember to check the transcript files (e.g. glg or alg) for messages.

1.6.1. Using the makeglossaries Perl Script

[link]

〉_
makeglossaries 〈options〉 〈aux-file〉

The makeglossaries script picks up the relevant information from the auxiliary (aux) file and will either call xindy or makeindex, depending on the supplied information. Therefore, you only need to pass the document’s name without the extension to makeglossaries. For example, if your document is called myDoc.tex, type the following in your terminal:

〉_
pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc

Windows users: TeX Live on Windows has its own internal Perl interpreter and provides makeglossaries.exe as a convenient wrapper for the makeglossaries Perl script. MikTeX also provides a wrapper makeglossaries.exe but doesn’t provide a Perl interpreter (as far as I know), which is still required even if you run MikTeX’s makeglossaries.exe, so with MikTeX you’ll need to install Perl. There’s more information about this at MikTeX and Perl scripts (and one Python script).

Some of the options are only applicable to makeindex and some are only applicable to xindy.

〉_
pdflatex -output-directory myTmpDir myDoc
makeglossaries -d myTmpDir myDoc

The multiple encap warning is where different location encap values (location formats) are used on the same location for the same entry. For example:

🖹
\documentclass{article}

\usepackage{glossaries}
\makeglossaries

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

\begin{document}
\gls{sample}, \gls[format=textbf]{sample}.
\printglossaries
\end{document}

There’s no similar check for xindy as xindy won’t produce any warning and will simply discard duplicates.

If you want to use an application that is capable of reading makeindex files (including support for makeindex style files via -s), then you can use -m to specify the alternative application to use instead of makeindex. Note that both xindex and texindy can read makeindex files using the default makeindex syntax but, as of the time of writing this, they don’t support makeindex style files.

The following switches may be used to override settings written to the aux file.