1. Introduction

The glossaries package is provided to assist generating lists of terms, symbols or abbreviations. (For convenience, these lists are all referred to as glossaries in this manual. The terms, symbols and abbreviations are collectively referred to as 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^1.1 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 abbreviations, or you may prefer to have descriptions scattered about the document and be able to easily link to the relevant description (Option 6).

The simplest document is one without a glossary:

(This is a trivial example. For a real document I recommend you use siunitx for units.)

glossaries-extraThe glossaries-extra package, which is distributed as a separate bundle, extends the capabilities of the glossaries package. The simplest document with a glossary can be created with glossaries-extra (which internally loads the 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 package. 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 “xindy” you’ll be taken to the entry in the glossary where there’s a brief description of the term “xindy”. This is the way the glossaries mechanism works. An indexing application is used to generated the sorted list of terms. The indexing applications are command line interface (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.

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.1 Indexing Options lists the available indexing options.
• §19 Sample Documents lists the sample documents provided with this package.
• §1.2 Dummy Entries for Testing lists the dummy glossary files that may be used for testing.
• §1.3 Multi-Lingual Support provides information for users who wish to write in a language other than English.
• §1.4 Generating the Associated Glossary Files describes how to use an indexing application to create the sorted glossaries for your document (Options 2 or 3).

Top

1.1 Indexing Options

The basic idea behind the glossaries package is that you first define your entries (terms, symbols or abbreviations). Then you can reference these within your document (like \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.

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.

🔗Option 1 (TeX)

Example 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 {\’e}lite then the sort value will default to elite if sanitizesort=false is used and will default to \’elite if sanitizesort=true is used. If you have any other kinds of commands that don’t expand to ASCII characters, such as \alpha or \si, 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. For example:

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 number lists. If you really can’t use an indexing application consider using Option 5 instead.

1. Add
   \makenoidxglossaries

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

2. Put
   \printnoidxglossary

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

   \printnoidxglossaries

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.

🔗Option 2 (makeindex)

Example 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. (So you should be able to use the automake 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.

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 made in the preamble.

2. Add
   \makeglossaries

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

3. Put
   \printglossary

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

   \printglossaries

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. 🔗 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. If you have access to a terminal or a command prompt (for example, the MSDOS command prompt for Windows users or the bash console for Unix-like users) then you need to run the command:

   
        
   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 $ symbol indicates the command prompt and should be omitted.)
   The file extensions vary according to the glossary type. See §1.4.4 Using makeindex explicitly (Option 2) 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.4.4 Using makeindex explicitly (Option 2) 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. 🔗 Once you have successfully completed the previous step, you can now run LaTeX on your document again.

You’ll need to repeat the last step if you have used the toc option (unless you’re using glossaries-extra) to ensure the section heading is added to the table of contents. You’ll also need to repeat steps 5 and 6 if you have any cross-references which can’t be indexed until the glossary file has been created.

🔗Option 3 (xindy)

Example 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 §11 Xindy (Option 3)). 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.

In these problematic cases, you must set the sort field explicitly. For example:

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

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 §11 Xindy (Option 3)).

2. Add \makeglossaries to your preamble (before you start defining your entries, as described in §4 Defining Glossary Entries).
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. 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. If you have access to a terminal or a command prompt (for example, the MSDOS command prompt for Windows users or the bash console for Unix-like users) then you need to run the command (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.4.3 Using xindy explicitly (Option 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.4.3 Using xindy explicitly (Option 3) for further details on using xindy explicitly.

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.

🔗Option 4 (bib2gls)

glossaries-extraThis option is only available with the glossaries-extra extension package. This method uses bib2gls to both fetch entry definitions from bib files and to hierarchically sort and collate.

Example document:

All entries must be provided in one or more bib files. See the bib2gls user manual for the required format.

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

(It’s possible to use a hybrid of this method and Options 2 or 3 with record=alsoindex but in general there is little need for this and it complicates the build process.)

Each resource set is loaded with \GlsXtrLoadResources[⟨options⟩]. For example:

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:

   
pdflatex myDoc
   
bib2gls myDoc
   
pdflatex myDoc
   

   
bib2gls --group myDoc
   

   
pdflatex myDoc
   

   
pdflatex myDoc
   
pdflatex myDoc
   

   
pdflatex myDoc
   
pdflatex myDoc
   

   
pdflatex myDoc
   
bib2gls myDoc
   
pdflatex myDoc
   
pdflatex myDoc
   

   
bib2gls --group myDoc
   

   
pdflatex myDoc
   
makeglossaries myDoc
   
pdflatex myDoc
   
makeglossaries myDoc
   
pdflatex myDoc
   

   
pdflatex myDoc
   
makeglossaries myDoc
   
pdflatex myDoc
   

   
perl makeglossaries myDoc
   

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

   
makeglossaries-lite.lua myDoc
   

   
makeglossaries-lite myDoc
   

   
makeglossaries-lite.lua --help
   

   
xindy -L ⟨language⟩ -C ⟨encoding⟩ -I xindy -M ⟨style⟩ -t ⟨base⟩.glg -o ⟨base⟩.gls ⟨base⟩.glo
   

   
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.alg -o myDoc.acr myDoc.acn
   

   
makeglossaries myDoc
   

   
makeindex -s ⟨style⟩.ist -t ⟨base⟩.glg -o ⟨base⟩.gls ⟨base⟩.glo
   

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

   
makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
   

   
makeglossaries myDoc
   

2. Package Options

This section describes the available glossaries package options. You may omit the =true for boolean options. (For example, acronym is equivalent to acronym=true).

Top

2.1 General Options

nowarn

This suppresses all warnings generated by the glossaries package. Don’t use this option if you’re new to using glossaries as the warnings are designed to help detect common mistakes (such as forgetting to use \makeglossaries). Note that if you use debug with any value other than false it will override this option.

nolangwarn

This suppresses the warning generated by a missing language module.

noredefwarn

If you load glossaries with a class or another package that already defines glossary related commands, by default glossaries will warn you that it’s redefining those commands. If you are aware of the consequences of using glossaries with that class or package and you don’t want to be warned about it, use this option to suppress those warnings. Other warnings will still be issued unless you use the nowarn option described above. (This option is automatically switched on by glossaries-extra.)

debug={⟨value⟩}

Introduced in version 4.24. The default setting is debug=false. The following values are available: false, true, showtargets (v4.32+) and showaccsupp (v4.45+). If no value is given, debug=true is assumed.

All values other than debug=false switch on the debug mode (and will automatically cancel the nowarn option). The debug=showtargets option will additionally use:

to show the hypertarget or hyperlink name when \glsdohypertarget is used by commands like \glstarget and when \glsdohyperlink is used by commands like \gls. In math mode or inner mode, this puts the target name in square brackets just before the link or anchor. In outer mode it uses:

which by default places the target name in the margin. The font is given by:

The default definition is \ttfamily\small. This command is included in the definition of \glsshowtargetouter, so if you want to redefine that command remember to include the font. For example:

Similarly, the debug=showaccsupp will add the accessibility support information using:

This internally uses \glsshowtarget. This option is provided for use with glossaries-accsupp.

The purpose of the debug mode can be demonstrated with the following example document:

Without \makeglossaries the indexing is suppressed with Options 2 and 3 but, other than that, commands like \gls behave as usual.

This situation doesn’t cause any errors or warnings as it’s perfectly legitimate for a user to want to use glossaries to format the entries (e.g. abbreviation expansion) but not display any lists of terms, abbreviations, symbols etc (or the user may prefer to use the unsorted Options 5 or 6). It’s also possible that the user may want to temporarily comment out \makeglossaries in order to suppress the indexing while working on a draft version to speed compilation, or the user may prefer to use Options 1 or 4 for indexing, which don’t use \makeglossaries.

Therefore \makeglossaries can’t be used to enable \newglossaryentry and commands like \gls and \glsadd. These commands must be enabled by default. (It does, however, enable the see key as that’s a more common problem. See below.)

The debug mode, enabled with the debug option,

will write information to the log file when the indexing can’t occur because the associated file isn’t open. The message is written in the form

where ⟨type⟩ is the glossary label and ⟨text⟩ is the line of text that would’ve been written to the associated file if it had been open. So if any entries haven’t appeared in the glossary but you’re sure you used commands like \glsadd or \glsaddall, try switching on the debug option and see if any information has been written to the log file.

savewrites={⟨boolean⟩}

This is a boolean option to minimise the number of write registers used by the glossaries package. The default is savewrites=false. With Options 2 and 3, one write register is required per (non-ignored) glossary and one for the style file.

With all options except Options 1 and 4, another write register is required if the docdefs file is needed to save document definitions. With both Options 1 and 4, no write registers are required (document definitions aren’t permitted and indexing information is written to the aux file). If you really need document definitions but you want to minimise the number of write registers then consider using docdef=restricted with glossaries-extra.

There are only a limited number of write registers, and if you have a large number of glossaries or if you are using a class or other packages that create a lot of external files, you may exceed the maximum number of available registers. If savewrites is set, the glossary information will be stored in token registers until the end of the document when they will be written to the external files.

By way of comparison, sample-multi2.tex provided with bib2gls has a total of 15 glossaries. With Options 2 or 3, this would require 46 associated files and 16 write registers.^2.1 With bib2gls, no write registers are required and there are only 10 associated files for that particular document (9 resource files and 1 transcript file).

⚠ If you want to use TeX’s \write18 mechanism to call makeindex or xindy from your document and use savewrites, you must create the external files with \glswritefiles before you call makeindex/xindy. Also set \glswritefiles to nothing or \relax before the end of the document to avoid rewriting the files. For example:

In general, this package option is best avoided.

translate={⟨value⟩}

This can take the following values:

true

If babel has been loaded and the translator package is installed, translator will be loaded and the translations will be provided by the translator package interface. You can modify the translations by providing your own dictionary. If the translator package isn’t installed and babel is loaded, the glossaries-babel package will be loaded and the translations will be provided using babel’s \addto\caption⟨language⟩ mechanism. If polyglossia has been loaded, glossaries-polyglossia will be loaded.

false

Don’t provide translations, even if babel or polyglossia has been loaded. (Note that babel provides the command \glossaryname so that will still be translated if you have loaded babel.)

babel

Don’t load the translator package. Instead load glossaries-babel.

I recommend you use translate=babel if you have any problems with the translations or with PDF bookmarks, but to maintain backward compatibility, if babel has been loaded the default is translate=true.

If translate is specified without a value, translate=true is assumed. If translate isn’t specified, translate=true is assumed if babel, polyglossia or translator have been loaded. Otherwise translate=false is assumed.

See §1.3.1 Changing the Fixed Names for further details.

notranslate

This is equivalent to translate=false and may be passed via the document class options.

hyperfirst={⟨boolean⟩}

This is a boolean option that specifies whether each term has a hyperlink on first use. The default is hyperfirst=true (terms on first use have a hyperlink, unless explicitly suppressed using starred versions of commands such as \gls* or by identifying the glossary with nohypertypes, described above). Note that nohypertypes overrides hyperfirst=true. This option only affects commands that check the first use flag, such as the \gls-like commands (for example, \gls or \glsdisp), but not the \glstext-like commands (for example, \glslink or \glstext).

The hyperfirst setting applies to all glossary types (unless identified by nohypertypes or defined with \newignoredglossary). It can be overridden on an individual basis by explicitly setting the hyper key when referencing an entry (or by using the plus or starred version of the referencing command).

It may be that you only want to apply this to just the acronyms (where the first use explains the meaning of the acronym) but not for ordinary glossary entries (where the first use is identical to subsequent uses). In this case, you can use hyperfirst=false and apply \glsunsetall to all the regular (non-acronym) glossaries. For example:

Alternatively you can redefine the hook

which is used by the commands that check the first use flag, such as \gls. Within the definition of this command, you can use \glslabel to reference the entry label and \glstype to reference the glossary type. You can also use \ifglsused to determine if the entry has been used. You can test if an entry is an acronym by checking if it has the long key set using \ifglshaslong. For example, to switch off the hyperlink on first use just for acronyms:

Note that this hook isn’t used by the commands that don’t check the first use flag, such as \glstext. (You can, instead, redefine \glslinkpostsetkeys, which is used by both the \gls-like and \glstext-like commands.)

The glossaries-extra package provides a method of disabling the first use hyperlink according to the entry’s associated category. For example, if you only to switch off the first use hyperlink for abbreviations and acronyms then you simply need to set the nohyperfirst attribute for the abbreviation and acronym categories. (Instead of using the nohyperfirst package option.) See the glossaries-extra manual for further details.

writeglslabels

This is a valueless option that will create a file called \jobname.glslabels at the end of the document. This file simply contains a list of all defined entry labels (including those in any ignored glossaries). It’s provided for the benefit of text editors that need to know labels for auto-completion. (See also glossaries-extra’s docdef=atom package option.)

undefaction={⟨value⟩} (glossaries-extra.sty)

The value may be one of:

error

generate an error if a referenced entry is undefined (default, and only available setting with just glossaries);

warn

only warn if a referenced entry is undefined (automatically activated with Option 4).

docdef={⟨value⟩} (glossaries-extra.sty)

This option governs the use of \newglossaryentry. Available values:

false

\newglossaryentry is not permitted in the document environment (default with glossaries-extra and for Option 1 with just the base glossaries package);

restricted

\newglossaryentry is only permitted in the document environment if it occurs before \printglossary (not available for some indexing options);

atom

as restricted but creates the docdefs file for use by atom (without the limitations of docdef=true);

true

\newglossaryentry is permitted in the document environment where it would normally be permitted by the base glossaries package. This will create the docdefs file if \newglossaryentry is found in the document environment.

Top

2.2 Sectioning, Headings and TOC Options

toc={⟨boolean⟩}

Add the glossaries to the table of contents. Note that an extra LaTeX run is required with this option. Alternatively, you can switch this function on and off using

and

The default value is toc=false for the base glossaries package and toc=true for glossaries-extra.

numberline={⟨boolean⟩}

When used with the above toc=true option, this will add \numberline{} in the final argument of \addcontentsline. This will align the table of contents entry with the numbered section titles. Note that this option has no effect if the toc option is omitted. If toc is used without numberline, the title will be aligned with the section numbers rather than the section titles.

section={⟨value⟩}

This option indicates the sectional unit to use for the glossary. The value should be the control sequence name without the leading backslash or following star (e.g. just chapter not \chapter or chapter*).

The default behaviour is for the glossary heading to use \chapter, if that command exists, or \section otherwise. The starred or unstarred form is determined by the numberedsection option.

Example:

You can omit the value if you want to use \section, i.e. 

is equivalent to

You can change this value later in the document using

where ⟨name⟩ is the sectional unit.

The start of each glossary adds information to the page header via

By default this uses \@mkboth^2.2 but you may need to redefine it. For example, to only change the right header:

or to prevent it from changing the headers:

If you want \glsglossarymark to use \MakeUppercase in the header, use the ucmark option described below.

Occasionally you may find that another package defines \cleardoublepage when it is not required. This may cause an unwanted blank page to appear before each glossary. This can be fixed by redefining \glsclearpage:

ucmark={⟨boolean⟩}

This is a boolean option. The default is ucmark=false, unless memoir has been loaded, in which case the default is ucmark=true.

If set, \glsglossarymark uses \MakeTextUppercase^2.3. You can test whether this option has been set or not using

For example:

If memoir has been loaded and ucmark is set, then memoir’s \memUChead is used.

numberedsection={⟨value⟩}

The glossaries are placed in unnumbered sectional units by default, but this can be changed using numberedsection. This option can take one of the following values:

• false: no number, i.e. use starred form of sectioning command (e.g. \chapter* or \section*);
• nolabel: use a numbered section, i.e. the unstarred form of sectioning command (e.g. \chapter or \section), but the section not labelled;
• autolabel: numbered with automatic labelling. Each glossary uses the unstarred form of a sectioning command (e.g. \chapter or \section) and is assigned a label (via \label). The label is formed from

  ---

  \glsautoprefix ⟨type⟩

  ---

  where ⟨type⟩ is the label identifying that glossary. The default value of \glsautoprefix is empty. For example, if you load glossaries using:

  \usepackage[section,numberedsection=autolabel]  
    {glossaries}

  then each glossary will appear in a numbered section, and can be referenced using something like:

  The main glossary is in section~\ref{main} and  
  the list of acronyms is in section~\ref{acronym}.

  If you can’t decide whether to have the acronyms in the main glossary or a separate list of acronyms, you can use \acronymtype which is set to main if the acronym option is not used and is set to acronym if the acronym option is used. For example:

  The list of acronyms is in section~\ref{\acronymtype}.

  You can redefine the prefix if the default label clashes with another label in your document. For example:

  \renewcommand*{\glsautoprefix}{glo:}

  will add glo: to the automatically generated label, so you can then, for example, refer to the list of acronyms as follows:

  The list of acronyms is in  
  section~\ref{glo:\acronymtype}.

  Or, if you are undecided on a prefix:

  The list of acronyms is in  
  section~\ref{\glsautoprefix\acronymtype}.

• nameref: this is like autolabel but uses an unnumbered sectioning command (e.g. \chapter* or \section*). It’s designed for use with the nameref package. For example:
  \usepackage{nameref}  
  \usepackage[numberedsection=nameref]{glossaries}

  Now \nameref{main} will display the (TOC) section title associated with the main glossary. As above, you can redefine \glsautoprefix to provide a prefix for the label.

Top

2.3 Glossary Appearance Options

savenumberlist={⟨boolean⟩}

This is a boolean option that specifies whether or not to gather and store the number list for each entry. The default is savenumberlist=false. (See \glsentrynumberlist and \glsdisplaynumberlist in §9 Using Glossary Terms Without Links.) This is always true if you use Option 1.

entrycounter={⟨boolean⟩}

This is a boolean option. (Default is entrycounter=false.) If set, each main (level 0) glossary entry will be numbered when using the standard glossary styles. This option creates the counter glossaryentry.

If you use this option, you can reference the entry number within the document using

where ⟨label⟩ is the label associated with that glossary entry. The labelling systems uses ⟨prefix⟩⟨label⟩, where ⟨label⟩ is the entry’s label and ⟨prefix⟩ is given by

(which defaults to glsentry-).

counterwithin={⟨value⟩}

This is a ⟨key⟩=⟨value⟩ option where ⟨value⟩ is the name of a counter. If used, this option will automatically set entrycounter=true and the glossaryentry counter will be reset every time ⟨value⟩ is incremented.

If you want the counter reset at the start of each glossary, you can modify the glossary preamble (\glossarypreamble) to use

which sets glossaryentry to zero:

or if you are using \setglossarypreamble, add it to each glossary preamble, as required. For example:

subentrycounter={⟨boolean⟩}

This is a boolean option. (Default is subentrycounter=false.) If set, each level 1 glossary entry will be numbered when using the standard glossary styles. This option creates the counter glossarysubentry. The counter is reset with each main (level 0) entry. Note that this package option is independent of entrycounter. You can reference the number within the document using \glsrefentry{⟨label⟩} where ⟨label⟩ is the label associated with the sub-entry.

style={⟨value⟩}

This is a ⟨key⟩=⟨value⟩ option. (Default is style=list, unless classicthesis has been loaded, in which case the default is style=index.) Its value should be the name of the glossary style to use. This key may only be used for styles defined in glossary-list, glossary-long, glossary-super or glossary-tree. Alternatively, you can set the style using

(See §15 Glossary Styles for further details.)

nolong

This prevents the glossaries package from automatically loading glossary-long (which means that the longtable package also won’t be loaded). This reduces overhead by not defining unwanted styles and commands. Note that if you use this option, you won’t be able to use any of the glossary styles defined in the glossary-long package (unless you explicitly load glossary-long).

nosuper

This prevents the glossaries package from automatically loading glossary-super (which means that the supertabular package also won’t be loaded). This reduces overhead by not defining unwanted styles and commands. Note that if you use this option, you won’t be able to use any of the glossary styles defined in the glossary-super package (unless you explicitly load glossary-super).

nolist

This prevents the glossaries package from automatically loading glossary-list. This reduces overhead by not defining unwanted styles. Note that if you use this option, you won’t be able to use any of the glossary styles defined in the glossary-list package (unless you explicitly load glossary-list). Note that since the default style is list (unless classicthesis has been loaded), you will also need to use the style option to set the style to something else.

notree

This prevents the glossaries package from automatically loading glossary-tree. This reduces overhead by not defining unwanted styles. Note that if you use this option, you won’t be able to use any of the glossary styles defined in the glossary-tree package (unless you explicitly load glossary-tree). Note that if classicthesis has been loaded, the default style is index, which is provided by glossary-tree.

nostyles

This prevents all the predefined styles from being loaded. If you use this option, you need to load a glossary style package (such as glossary-mcols). Also if you use this option, you can’t use the style package option. Instead you must either use \setglossarystyle{⟨style⟩} or the style key in the optional argument to \printglossary. Example:

nonumberlist

This option will suppress the associated number lists in the glossaries (see also §5 Number lists). Note that if you use Options 2 or 3 (makeindex or xindy) then the locations must still be valid. This package option merely prevents the number list from being displayed, but both makeindex and xindy still require a location or cross-reference for each term that’s indexed. Remember that number list includes any cross-references, so suppressing the number list will also hide the cross-references (see below).

seeautonumberlist

If you suppress the number lists with nonumberlist, described above, this will also suppress any cross-referencing information supplied by the see key in \newglossaryentry or \glssee. If you use seeautonumberlist, the see key will automatically implement nonumberlist=false for that entry. (Note this doesn’t affect \glssee.) For further details see §8 Cross-Referencing Entries.

counter={⟨value⟩}

This is a ⟨key⟩=⟨value⟩ option. (Default is counter=page.) The value should be the name of the default counter to use in the number lists (see §5 Number lists).

nopostdot={⟨boolean⟩}

This is a boolean option. If no value is specified, true is assumed. When set to true, this option suppresses the default post description dot used by some of the predefined styles.

The default setting is nopostdot=false for the base glossaries package and nopostdot=true for glossaries-extra.

nogroupskip={⟨boolean⟩}

This is a boolean option. If no value is specified, true is assumed. When set to true, this option suppresses the default vertical gap between letter groups used by some of the predefined styles. The default setting is nogroupskip=false.

stylemods={⟨list⟩} (glossaries-extra.sty)

Load the glossaries-extra-stylemods package and patch the predefined styles. The ⟨list⟩ argument is optional. If present, this will also load glossary-⟨element⟩.sty for each ⟨element⟩ in the comma-separated ⟨list⟩.

Top

2.4 Indexing Options

seenoindex={⟨value⟩}

Introduced in version 4.24, this option may take one of three values: error, warn or ignore. The see key automatically indexes the cross-referenced entry using \glsadd. This means that if this key is used in an entry definition before the relevant glossary file has been opened, the indexing can’t be performed. Since this is easy to miss, the glossaries package by default issues an error message if the see key is used before \makeglossaries. This option allows you to change the error into just a warning (seenoindex=warn) or ignore it (seenoindex=ignore) if, for example, you want to temporarily comment out \makeglossaries to speed up the compilation of a draft document by omitting the indexing.

esclocations={⟨boolean⟩}

This is a boolean option. The default is esclocations=true, which is needed for Options 2 and 3. With Option 1 \makenoidxglossaries changes it to esclocations=false. With Option 4 (bib2gls), this setting is ignored.

Both makeindex and xindy are fussy about the location formats (makeindex more so than xindy) so the glossaries package tries to ensure that special characters are escaped and allows for the location to be substituted for a format that’s more acceptable to the indexing application. This requires a bit of trickery to circumvent the problem posed by TeX’s asynchronous output routine, which can go wrong and also adds to the complexity of the document build.

If you’re sure that your locations will always expand to an acceptable format (or you’re prepared to post-process the glossary file before passing it to the relevant indexing application) then use esclocations=false to avoid the complex escaping of location values. (See “Writing information to associated files” in the documented code for further details.)

This isn’t an issue for Options 1 or 4 as the locations are written to the aux file so no syntax conversion is required.

indexonlyfirst={⟨boolean⟩}

This is a boolean option that specifies whether to only add information to the external glossary file on first use. The default is indexonlyfirst=false, which will add a line to the file every time one of the \gls-like or \glstext-like commands are used. Note that \glsadd will always add information to the external glossary file^2.4 (since that’s the purpose of that command).

You can customise this by redefining

where ⟨label⟩ is the entry’s label and ⟨wr-code⟩ is the code that writes the entry’s information to the external file. The default definition of \glswriteentry is:

This checks the indexonlyfirst package option (using \ifglsindexonlyfirst) and does ⟨wr-code⟩ if this is false otherwise it only does ⟨wr-code⟩ of the entry hasn’t been used.

For example, suppose you only want to index the first use for entries in the acronym glossary and not in the main (or any other) glossary:

Here I’ve used \ifthenelse to ensure the arguments of \equal are fully expanded before the comparison is made.

With the glossaries-extra package it’s possible to only index first use for particular categories. For example, if you only want this enabled for abbreviations and acronyms then you can set the indexonlyfirst attribute for the abbreviation and acronym categories. (Instead of using the indexonlyfirst package option.) See the glossaries-extra manual for further details.

indexcrossrefs={⟨boolean⟩} (glossaries-extra.sty)

If true, this will automatically index any cross-referenced entries that haven’t been marked as used at the end of the document. Increases document build time. See glossaries-extra manual for further details.

autoseeindex={⟨boolean⟩} (glossaries-extra.sty)

If true, makes the see and seealso keys automatically index the cross-reference when the entry is defined (default, and the only option with just the base glossaries package).

record={⟨value⟩} (glossaries-extra.sty)

If not off, this option indicates that bib2gls is required. If the value is omitted, only is assumed. Permitted values:

off

bib2gls isn’t being used;

only

bib2gls is being used to fetch entries from a bib file, to sort the entries and collate the number lists, where the location information is the same as for Options 1–3;

nameref

like only but provides extra information that allows the associated title to be used instead of the location number;

alsoindex

a hybrid approach where bib2gls is begin used to fetch entries from a bib file but makeindex or xindy are used for the indexing. This requires a more complicated document build and isn’t recommended.

See glossaries-extra manual for further details.

equations={⟨boolean⟩} (glossaries-extra.sty)

If true, this option will cause the default location counter to automatically switch to equation when inside a numbered equation environment.

floats={⟨boolean⟩} (glossaries-extra.sty)

If true, this option will cause the default location counter to automatically switch to the corresponding counter when inside a float. (Remember that with floats it’s the \caption command that increments the counter so the location will be incorrect if an entry is indexed within the float before the caption.)

indexcounter (glossaries-extra.sty)

This valueless option is primarily intended for use with bib2gls and hyperref allowing the page location hyperlink to the relevant point in the page (rather than the top of the page). Unexpected results will occur with other indexing methods. See glossaries-extra manual for further details.

Top

2.5 Sorting Options

This section is mostly for Options 2 and 3. Only the sort and order options are applicable for Option 1.

sanitizesort={⟨boolean⟩}

This is a boolean option that determines whether or not to sanitize the sort value when writing to the external glossary file. For example, suppose you define an entry as follows:

The sort value (#) must be sanitized before writing it to the glossary file, otherwise LaTeX will try to interpret it as a parameter reference. If, on the other hand, you want the sort value expanded, you need to switch off the sanitization. For example, suppose you do:

and you actually want \mysortvalue expanded, so that the entry is sorted according to AAA, then use the package option sanitizesort=false.

The default for Options 2 and 3 is sanitizesort=true, and the default for Option 1 is sanitizesort=false.

sort={⟨value⟩}

If you use Options 2 or 3, this package option is the only way of specifying how to sort the glossaries. Only Option 1 allows you to specify sort methods for individual glossaries via the sort key in the optional argument of \printnoidxglossary. If you have multiple glossaries in your document and you are using Option 1, only use the package options sort=def or sort=use if you want to set this sort method for all your glossaries.

This is a ⟨key⟩=⟨value⟩ option where ⟨value⟩ may be one of the following:

• standard : entries are sorted according to the value of the sort key used in \newglossaryentry (if present) or the name key (if sort key is missing);
• def : entries are sorted in the order in which they were defined (the sort key in \newglossaryentry is ignored);
• use : entries are sorted according to the order in which they are used in the document (the sort key in \newglossaryentry is ignored).

  Both sort=def and sort=use set the sort key to a six digit number via

  ---

  \glssortnumberfmt{⟨number⟩}

  ---

  (padded with leading zeros, where necessary). This can be redefined, if required, before the entries are defined (in the case of sort=def) or before the entries are used (in the case of sort=use).

• none : this setting is new to version 4.30 and is only for documents that don’t use \makeglossaries (Options 2 or 3) or \makenoidxglossaries (Option 1). It omits the code used to sanitize or escape the sort value, since it’s not required. This can help to improve the document build speed, especially if there are a large number of entries.

  This option can’t be used with \printglossary or \printnoidxglossary (or the iterative versions \printglossaries or \printnoidxglossaries). It may be used with glossaries-extra’s \printunsrtglossary (Option 5).

Note that the group styles (such as listgroup) are incompatible with the sort=use and sort=def options.

The default is sort=standard. When the standard sort option is in use, you can hook into the sort mechanism by redefining:

where ⟨sort cs⟩ is a temporary control sequence that stores the sort value (which was either explicitly set via the sort key or implicitly set via the name key) before any escaping of the makeindex/xindy special characters is performed. By default \glsprestandardsort just does:

which sanitizes ⟨sort cs⟩ if the sanitizesort package option is set (or does nothing if the package option sanitizesort=false is used).

The other arguments, ⟨type⟩ and ⟨label⟩, are the glossary type and the entry label for the current entry. Note that ⟨type⟩ will always be a control sequence, but ⟨label⟩ will be in the form used in the first argument of \newglossaryentry.

Example 1 (Mixing Alphabetical and Order of Definition Sorting)

Suppose I have three glossaries: main, acronym and notation, and let’s suppose I want the main and acronym glossaries to be sorted alphabetically, but the notation type should be sorted in order of definition.

For Option 1, the sort option can be used in \printnoidxglossary:

For Options 2 or 3, I can set the sort to standard (which is the default, but can be explicitly set via the package option sort=standard), and I can either define all my main and acronym entries, then redefine \glsprestandardsort to set ⟨sort cs⟩ to an incremented integer, and then define all my notation entries. Alternatively, I can redefine \glsprestandardsort to check for the glossary type and only modify ⟨sort cs⟩ if ⟨type⟩ is notation.

The first option can be achieved as follows:

The second option can be achieved as follows:

(\ifdefstring is defined by the etoolbox package.) For a complete document, see the sample file sampleSort.tex.

Example 2 (Customizing Standard Sort (Options 2 or 3))

Suppose you want a glossary of people and you want the names listed as ⟨first-name⟩ ⟨surname⟩ in the glossary, but you want the names sorted by ⟨surname⟩, ⟨first-name⟩. You can do this by defining a command called, say, \name{⟨first-name⟩}{⟨surname⟩} that you can use in the name key when you define the entry, but hook into the standard sort mechanism to temporarily redefine \name while the sort value is being set.

First, define two commands to set the person’s name:

and \name needs to be initialised to \textname:

Now redefine \glsprestandardsort so that it temporarily sets \name to \sortname and expands the sort value, then sets \name to \textname so that the person’s name appears as ⟨first-name⟩ ⟨surname⟩ in the text:

(The somewhat complicate use of \expandafter etc helps to protect fragile commands, but care is still needed.)

Now the entries can be defined:

For a complete document, see the sample file samplePeople.tex.

order={⟨value⟩}

This may take two values: word or letter. The default is word ordering.

If you use Option 1, this setting will be used if you use sort=standard in the optional argument of \printnoidxglossary:

Alternatively, you can specify the order for individual glossaries: