Note that glossaries-extra provides an extra indexing option (bib2gls) which isn’t available with just the base glossaries package.
If you require multilingual support you must also install the relevant language module. Each language module is called glossaries-, where is the root language name. For example, glossaries-french or glossaries-german. If a language module is required, the glossaries package will automatically try to load it and will give a warning if the module isn’t found. See §1.5 for further details. If there isn’t any support available for your language, use the nolangwarn package option to suppress the warning and provide your own translations. (For example, use the title key in \printglossary
.)
1f631 If you’re freaking out at the size of this manual, start with “The glossaries package: a guide for beginners”. You should find it in the same directory as this document or try
texdoc glossariesbeginOnce you’ve got to grips with the basics, then come back to this manual to find out how to adjust the settings.
The glossaries bundle includes the following documentation:
- The glossaries package: a guide for beginners
- If you want some brief information and examples to get you going, start with the guide for beginners.
- User Manual for glossaries.sty (glossaries-user.pdf)
- This document is the main user guide for the glossaries package.
- Documented Code for glossaries (glossaries-code.pdf)
- Advanced users wishing to know more about the inner workings of all the packages provided in the glossaries bundle should read “Documented Code for glossaries v4.54”.
- CHANGES
- Change log.
- README.md
- Package summary.
- Depends.txt
- List of all packages unconditionally required by glossaries. Other unlisted packages may be required under certain circumstances. For help on installing packages see, for example, How do I update my TeX distribution? or (for Linux users) Updating TeX on Linux.
- •glossaries-extra and bib2gls: An Introductory Guide.
- •glossaries FAQ
- •glossaries gallery
- •a summary of all glossary styles provided by glossaries and glossaries-extra
- •glossaries performance (comparing document build times for the different options provided by glossaries and glossaries-extra).
- •Using LaTeX to Write a PhD Thesis (chapter 6).
- •Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build
- •The glossaries-extra package
- •bib2gls
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:
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).
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
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:
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.
The following rollback releases are available:
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.
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 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 , and finally load glossaries.
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
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,
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:
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
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:
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.
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).
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
If you have any other kinds of commands that don’t expand to ASCII characters, such as
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:
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
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:
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:
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.
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:
The simplest approach is to use arara and add the following comment lines to the start of your document:
The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to add the -l switch:
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
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:
All glossaries must be sorted according to the same method (word/letter ordering, order of use, or order of definition).
Summary:
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.
It’s much simpler to use makeglossaries instead:
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:
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:
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
The glossaries-extra package needs to be loaded with the record package option:
Each resource set is loaded with
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:
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:
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.
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
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
The glossary is displayed using:
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:
See the glossaries-extra documentation for further details of this method.
You can either define entries in the preamble (or in an external file loaded with
Or you can use bib2gls if you want to manage a large database of terms. For example:
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.)
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:
Remember that for this second case you need to run bib2gls as per Option 4:
For both cases (with or without bib2gls), instead of listing all the entries using
(Instead of using
The symbol (if required) can be displayed with either
In normal document text,
The
If you want to test if the symbol field has been set, you need to use
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:
In the second example, you can instead use bib2gls to apply a case change. For example, to apply sentence case to the name field:
In the first example (without bib2gls) you can do this manually. For example:
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:
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:
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
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
The sample file glossary-lipsum-examples.tex in the doc/latex/glossaries/samples directory uses all these files. See also glossaries gallery.
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:
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.
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
If you have the double-quote character (
In general, it’s best not to use babel’s shorthands in entry definitions. For example:
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:
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:
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
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:
If you are using babel and don’t want to use the translator interface, you can use the package option translate=babel. For example:
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.
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-.ldf and glossaries-dictionary-.dict where is the root language name (for example,
Here’s an example of glossaries-dictionary-English.dict:
Here’s an example of glossaries-english.ldf:
The suffixes used to generate the plural forms when the plural hasn’t been specified are given by
If you want to add a regional variation, create a file called glossaries--.ldf, where is the ISO language code and 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:
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:
There are now two extra files: glossaries-irish-noenc.ldf (no encoding information) and glossaries-irish-utf8.ldf (UTF-8).
These both define
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.
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
The advantages of using makeglossaries:
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:
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.
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:
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.
The multiple encap warning is where different location encap values (location formats) are used on the same location for the same entry. For example:
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.
The Lua alternative to the makeglossaries Perl script requires a Lua interpreter, which should already be available if you have a modern TeX distribution that includes LuaTeX. Lua is a light-weight, cross-platform scripting language, but because it’s light-weight it doesn’t have the full-functionality of heavy-weight scripting languages, such as Perl. The makeglossaries-lite script is therefore limited by this and some of the options available to the makeglossaries Perl script aren’t available here. (In particular the -d option.) Whilst it may be possible to implement those features by requiring Lua packages, this would defeat the purpose of providing this script for those don’t want the inconvenience of learning how to install interpreters or their associated packages.
The makeglossaries-lite script can be invoked in the same way as makeglossaries. For example, if your document is called myDoc.tex, then do
Some of the options are only applicable to makeindex and some are only applicable to xindy.
The following switches may be used to override settings written to the aux file.
xindy comes with TeX Live. It has also been added to MikTeX, but if you don’t have it installed, see How to use Xindy with MikTeX.
If you want to use xindy to process the glossary files, you must make sure you have used the xindy package option:
To run xindy type the following in your terminal (all on one line):
For example, if your document is called myDoc.tex and you are using UTF-8 encoding in English, then type the following in your terminal:
Note that this just creates the
Note that if you use makeglossaries instead, you can replace all those calls to xindy with just one call to makeglossaries:
If you want to use makeindex explicitly, you must make sure that you haven’t used the xindy package option or the glossary entries will be written in the wrong format. To run makeindex, type the following in your terminal:
For example, if your document is called myDoc.tex, then type the following at the terminal:
Note that if you use makeglossaries instead, you can replace all those calls to makeindex with just one call to makeglossaries:
The information needed to determine whether to use xindy, makeindex or bib2gls is stored in the aux file. This information can be gathered by a front-end, editor or script to make the glossaries where appropriate. This section describes how the information is stored in the auxiliary file.
The file extension of the indexing files used for each defined glossary (not including any ignored glossaries) are given by:
The indexing application’s style file is specified by:
For example, with arara you can easily determine whether to run makeglossaries:
Word or letter ordering is specified by:
If xindy should be used, the language for each glossary is specified by:
The codepage (file encoding) for all glossaries is specified by:
If Option 1 has been used, the aux file will contain
If you need to gather labels for auto-completion, the writeglslabels package option will create a file containing the labels of all defined entries (regardless of whether or not the entry has been used in the document). As from v4.47, there is a similar option writeglslabelnames that writes both the label and name (separated by a tab).
For example, with arara you can easily determine whether or not to run bib2gls:
Remember that with bib2gls, the glossary entries will never be defined on the first LaTeX call (because their definitions are contained in the glstex file created by bib2gls). You can also pick up labels from the records in aux file, which will be in the form:
This section describes the available glossaries package options. You may omit the
The debug=showtargets option will additionally use:
The font used by both
The purpose of the debug mode can be demonstrated with the following example document:
Without
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 (for example, to show a different form on first use) but not display any glossaries (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
Therefore
The debug mode, enabled with the debug option,
With all options except Options 1 and 414, another write register is required if the glsdefs 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. (These figures don’t include standard files and registers provided by the kernel or hyperref, such as aux and out.) 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).
See §1.5.1 for further details.
Note that nohypertypes overrides hyperfirst=true. This option only affects commands that check the first use flag, such as the
The hyperfirst setting applies to all glossary types (unless identified by nohypertypes or defined with
It may be that you only want to suppress hyperlinks for 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 use). In this case, you can use hyperfirst=false and apply
Alternatively you can redefine the hook
Note that this hook isn’t used by the commands that don’t check the first use flag, such as
Only available with glossaries-extra, the value for this option may be one of:
Only available with glossaries-extra, this option governs the use of
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 (for example, just
The default behaviour is for the glossary heading to use
Example:
The start of each glossary adds information to the page header via
You can test if this option has been set using:
If you use this option (and are using a glossary style that supports this option) then you can reference the entry number within the document using:
The glossaryentry counter can be reset back to zero with:
The value of the glossaryentry counter can be displayed with:
If you want to test whether or not this option is currently enabled, use the conditional:
If you want the counter reset at the start of each glossary, you can modify the glossary preamble (
As with the entrycounter option, you can reference the number within the document using
The glossarysubentry counter can be reset back to zero with:
The glossarysubentry counter can be simultaneously incremented and labelled (using
The value of the glossarysubentry counter can be displayed with:
If you want to test whether or not this option is currently enabled, use the conditional:
This setting may only be used for styles that are defined when the glossaries package is loaded. This will usually be the styles in the packages glossary-list, glossary-long, glossary-super or glossary-tree, unless they have been suppressed through options such as nostyles. Style packages can also be loaded by the stylemods option provided by glossaries-extra.
Alternatively, you can set the style later using:
Remember that number list includes any cross-references, so suppressing the number list will also hide the cross-references (in which case, you may want to use seeautonumberlist).
This option will redefine:
The default setting is nopostdot=false for the base glossaries package and nopostdot=true for glossaries-extra.
This option is only relevant for glossary styles that use the conditional:
Loads the glossaries-extra-stylemods package, which patches the predefined glossary styles. The argument is optional. If present, this will also load glossary- for each .sty in the comma-separated . See the glossaries-extra manual for further details.
This option may take one of the following values:
For example, if you want to temporarily comment out
Only applicable to makeindex and xindy. As from v4.50, the initial setting is now esclocations=false. Previously it was esclocations=true.
Both makeindex and xindy are fussy about the location syntax (makeindex more so than xindy) so, if esclocations=true, the glossaries package will try to ensure that special characters are escaped, which 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. This is now the default.
If, however, your locations (for example,
This conditional can be switched on with:
If you are using makeindex and your location expands to content in the form
This isn’t an issue for Options 1 or 4 as the locations are written to the aux file and both methods use LaTeX syntax, so no conversion is required.
You can test if this setting is on using the conditional:
You can customise the default behaviour by redefining
For example, suppose you only want to index the first use for entries in the
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 then you can set the indexonlyfirst attribute for the abbreviation and, if appropriate, acronym categories. (Instead of using the indexonlyfirst package option.) See the glossaries-extra manual for further details.
This option is only available with glossaries-extra. If true, this will automatically index (
This option is only available with glossaries-extra. The base glossaries package always implements autoseeindex=true.
If true, this makes the see and seealso keys automatically index the entry (with
This option is only available with glossaries-extra. See glossaries-extra manual for further details. A brief summary of available values:
This option is only available with glossaries-extra. If true, this option will cause the default location counter to automatically switch to equation when inside a numbered equation environment.
This option is only available with glossaries-extra. 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
This option is only available with glossaries-extra. This valueless option is primarily intended for use with bib2gls and hyperref allowing the page location hyperlink target to be set to the relevant point within the page (rather than the top of the page). Unexpected results will occur with other indexing methods. See glossaries-extra manual for further details.
This section is mostly for Options 2 and 3. Only the sort and order options are applicable for Option 1.
The default for Options 2 and 3 is sanitizesort=true, and the default for Option 1 is sanitizesort=false.
Both sort=def and sort=use zero-pad the sort key to a six digit number using:
Note that the group styles (such as listgroup) are incompatible with the sort=use and sort=def options.
When the standard sort option is in use, you can hook into the sort mechanism by redefining:
The other arguments, glossary type and the entry label for the current entry. Note that will always be a control sequence, but will be in the form used in the first argument of
For Option 1, the sort option can be used in
For Options 2 or 3, I can set sort=standard (which is the default), and I can either define all my
The first method can be achieved as follows:
First, define two commands to set the person’s name:
Now the entries can be defined:
If you use Option 1, this setting will be used if you use sort=standard in the optional argument of
You may omit this package option if you are using Option 2 as this is the default. It’s available in case you need to override the effect of an earlier occurrence of xindy in the package option list.
This package option may additionally have a value that is a xindy. See §14 for further details on using xindy with the glossaries package.
You can test if this option has been set using the conditional:
The
The makeglossaries script has a set of mappings of known babel language names to xindy language names, but new babel dialect names may not be included. The makeglossaries-lite script doesn’t have this feature (but there’s no benefit in use makeglossaries-lite instead of makeglossaries when using xindy). The automake=option that calls xindy explicitly also doesn’t use any mapping.
However, even if the appropriate mapping is available,
For example:
If this option doesn’t seem to work, open the log file in your text editor and search for “
If you change the package option to:
If the document is compiled in unrestricted mode, the corresponding line in the log file should now be:
If you are using xindy, then automake=makegloss is a better option that this one. Either way, you will need Perl and the unrestricted mode, but with makeglossaries you get the benefit of the language mappings and diagnostics.
Naturally, if there’s a particular reason why the class or package insists on a specific indexing method, for example, it’s an editorial requirement, then you will need to abide by that decision.
This option may be passed in the standard document class option list or passed using
For example, suppose the class customclass.cls automatically loads glossaries and does
Note that restoring these commands doesn’t necessarily mean that they can be used. It just means that their normal behaviour given the current settings will apply. For example, if you use the record=only or record=nameref options with glossaries-extra then you can’t use
You may also use:
If you don’t use the
If you use Option 1, you need to use:
If you use Option 1, you need to use:
If you use Option 1, you need to use:
Since the index isn’t designed for terms with descriptions, you might also want to disable the hyperlinks for this glossary using the package option nohypertypes=index or the command
The example file sample-index.tex illustrates the use of the index package option.
If you are using Option 1, you need to use
If the acronym package option is used,
Make sure you have at least v1.42 of glossaries-extra if you use the acronym (or acronyms) package option with the extension package to avoid a bug that interferes with the abbreviation style.
This valueless option provided by glossaries-extra creates a new glossary type with the label
By default, if the list is empty when
If you have other lists of acronyms, you can specify them as a comma-separated list in the value of acronymlists. For example, if you use the acronym package option but you also want the
If the list is changed after
You can determine if a glossary has been identified as being a list of acronyms using:
The package options listed in this section were deprecated in version 4.02 (2013-12-05) and have now been removed. You will need to use rollback with them (see §1.1). These options started generating warnings in version 4.47 (2021-09-20) and as from version 4.50 will now generate an error unless you use rollback.
If you want to change the acronym style, use
Other available options that don’t fit any of the above categories are described below.
Only available with glossaries-extra, this option loads the glossaries-accsupp package, which needs to be loaded either before glossaries-extra or while glossaries-extra is loaded to ensure both packages are properly integrated.
Only available with glossaries-extra, this option loads the glossaries-prefix package.
This option may be used to suppress the boilerplate text generated by
The value may be either expanded or unexpanded and performs the same function as mfirstuc’s expanded and unexpanded package options. Note that there’s no value corresponding to mfirstuc’s other package option.
The default is mfirstuc=unexpanded to safeguard against glossary styles that convert the description to sentence case. With older versions of mfirstuc (pre v2.08), fragile commands in the description would not have been affected by the case change, but now, if the entire description is passed to
Compatibility mode for old documents created using version 2.07 or below. This option is now only available with rollback (see §1.1).
The redefinitions of these commands was removed in v4.10, but unfortunately it turned out that some packages had hacked the internal commands provided by glossaries and no longer worked when they were removed, so they were restored in v4.41 with this option to undo the effect with kernelglossredefs=true as the default. As from v4.50, the default is now kernelglossredefs=false.
The only glossary-related commands provided by the LaTeX kernel are
In general, if possible, it’s best to stick with just one package that provides a glossary mechanism. (The glossaries package does check for the doc package and patches
Some of the options described above may also be set after the glossaries package has been loaded using
In the preamble you need to indicate which method you want to use to generate the glossary (or glossaries). The available options with both glossaries and glossaries-extra are summarized in §1.3. This chapter documents Options 1, 2 and 3, which are provided by the base package. See the glossaries-extra and bib2gls manuals for the full documentation of the other options.
If you don’t need to display any glossaries, for example, if you are just using the glossaries package to enable consistent formatting, then skip ahead to §4.
The command
The command
The
The default name for the customised style file is given by
There is a hook near the end of
If you use the
Remember that if you switch to xindy, this will no longer be valid code.
You can suppress the creation of the customised xindy or makeindex style file using:
If you have a custom xdy file created when using glossaries version 2.07 (2010-0710) or below, you will need to use rollback and the compatible-2.07 package option with it. However, that is now so dated and the LaTeX kernel has changed significantly since that time that you may need to use a legacy distribution (see Legacy Documents and TeX Live Docker Images).
Each glossary entry is assigned a number list that lists all the locations in the document where that entry was used. By default, the location refers to the page number but this may be overridden using the counter package option. The default form of the location number assumes a full stop compositor (for example, 1.2), but if your location numbers use a different compositor (for example, 1-2) you need to set this using
An invalid page number will also cause xindy to fail with a “did not match any location-class” warning. This is also something that makeglossaries will check for and will provided diagnostic information, but it won’t attempt to make any correction.
If you use Option 3, you can have a different compositor for page numbers starting with an upper case alphabetical character using:
Acronyms are covered in §6 but they use the same underlying mechanism as all the other glossary entries, so it’s a good idea to read this chapter first. The keys provided for
All glossary entries must be defined before they are used, so it is better to define them in the document preamble to ensure this. In fact, some commands such as
Bear in mind that with docdef=restricted, the entries must be defined before any entries are used, including when they are displayed in the glossary (for example, with
Only those entries that are indexed in the document (using any of the commands described in §5.1, §10 or §11) will appear in the glossary. See §8 to find out how to display the glossary.
New glossary entries are defined using the command:
If you have a long description that needs to span multiple paragraphs, use the following instead:
There are also commands that will only define the entry if it hasn’t already been defined:
For all the above commands, the first argument, entry. This can’t contain any non-expandable or fragile commands. The reason for this restriction is that the label is used to construct internal commands that store the associated information (similarly to commands like
The second argument, description and either name or parent. The description is set in the third argument of
As is typical with
This key is automatically set by
You may prefer to use acronyms (§6) or the abbreviations or the category post-link hook (
Although it is possible to use first in the optional argument of
Although it is possible to use plural in the optional argument of
Although it is possible to use firstplural in the optional argument of
You can also override the sort key by redefining
Option 1 by default strips the standard LaTeX accents (that is, accents generated by core LaTeX commands) from the name key when it sets the sort key. So with Option 1:
With Options 2 and 3, the default value of sort will either be set to the name key (if sanitizesort=true) or it will set it to the expansion of the name key (if sanitizesort=false).
Take care if you use Option 1 and the name contains fragile commands. You will either need to explicitly set the sort key or use the sanitizesort=true package option (unless you use the def or use sort methods).
Six keys are provided for any additional information the user may want to specify. (For example, an associated dimension or an alternative plural or some other grammatical construct.) Alternatively, you can add new keys using
This key works by adding
With Option 1, this key saves the appropriate command in the prenumberlist internal field, which is used by
For example:
Note that while it’s possible to put the cross-reference in the description instead, for example:
The referenced entry should be supplied as the value to this key. If you want to override the “see” tag, you can supply the new tag in square brackets before the label. For example see={[see also]{anotherlabel}}.
You can override this for individual glossary entries using nonumberlist={false}. Alternatively, you can use the seeautonumberlist package option. For further details, see §11.
Since it’s useful to suppress the indexing while working on a draft document, consider using the seenoindex package option to warn about or ignore the see key while
If you use the see key, you may want to consider using the glossaries-extra package which additionally provides a seealso and alias key. If you want to avoid the automatic indexing triggered by the see key, consider using Option 4. See also the FAQ item Why does the see key automatically index the entry?
The following keys are reserved for
The supplementary packages glossaries-prefix (§16) and glossaries-accsupp (§17) provide additional keys.
With older LaTeX kernels and pre-2.08 versions of mfirstuc, if the name starts with non-Latin character, you need to group the character, otherwise it will cause a problem for commands like
Note that in the above UTF-8 examples, you will also need to supply the sort key if you are using Options 1 or 2 whereas xindy (Option 3) is usually able to sort non-Latin characters correctly.
You may have noticed from above that you can specify the plural form when you define an entry. If you omit this, the plural will be obtained by appending:
For example:
If you are writing in a language that supports multiple plurals (for a given term) then use the plural key for one of them and one of the user keys to specify the other plural form. For example:
Alternatively, you can define your own keys using
If you are using a language that usually forms plurals by appending a different letter, or sequence of letters, you can redefine
You can use the six user keys to provide alternatives, such as participles. For example:
Alternatively, you can define your own keys using
You can define your own custom keys using the commands described in this section. There are two types of keys: those for use within the document and those to store information used behind the scenes by other commands.
For example, if you want to add a key that indicates the associated unit for a term, you might want to reference this unit in your document. In this case use
In both cases, a new command
A custom key that can be used in the document is defined using:
These entries can later be used in the document:
A custom key that can be used for simply storing information is defined using:
This is essentially the same as
Here I can define a new key that determines whether the term is actually an acronym rather than some other form of abbreviation. I’m going to call this key abbrtype (since type already exists):
Now I can define a style that looks up the value of this new key to determine how to display the full form:
Since it may be a bit confusing to use
For a complete document, see the sample file sample-storage-abbr.tex.
In the above example, if
The new acronym style has a minor modification that forces the user to specify a description. In the previous example, the line:
Once this new style has been set, the new acronyms can be defined using the optional argument to set the description:
No change is required for the definition of
We can also accommodate contractions in a similar manner to the initialisms:
Since the custom acronym style just checks if abbrtype is “acronym”, the contractions will be treated the same as the initialisms, but the style could be modified by a further test of the abbrtype value if required.
To test regular non-abbreviated entries, I’ve also defined a simple word:
Now for a new glossary style that provides information about the abbreviation (in addition to the description):
If the entry has an short/long value, the full form is supplied in parentheses and
With this style set, the “apple” entry is simply displayed in the glossary as:
For a complete document, see sample-storage-abbr-desc.tex.
When you define new glossary entries expansion is performed by default, except for the name, description, descriptionplural, symbol, symbolplural and sort keys (these keys all have expansion suppressed via
You can switch expansion on or off for individual keys using:
Any keys that haven’t had the expansion explicitly set using
If your entries contain any fragile commands, I recommend you switch off expansion via
A sub-entry is created by setting the parent key. These will normally be sorted so that they are placed immediately after their parent entry. However, some sort methods aren’t suitable when there are sub-entries. In particular, sub-entries are problematic with Option 1, and with Option 5 the sub-entries must be defined immediately after their parent entry (rather than at any point after the parent entry has been defined).
The hierarchical level indicates the sub-entry level. An entry with no parent (a top level entry) is a hierarchical level 0 entry. An entry with a parent has a hierarchical level that’s one more than its parent’s level. The level is calculated when an entry is defined.
There are two different types of sub-entries: those that have the same name as their parent (homographs, see §4.5.2) and those that establish a hierarchy (see §4.5.1). Both types are considered hierarchical entries from the point of view of the glossaries package and the indexing applications, but typically homographs will have the name key obtained from the parent, rather than have it explicitly set, and have a maximum hierarchical level of 1.
Not all glossary styles support hierarchical entries and may display all the entries in a flat format. Of the styles that support sub-entries, some display the sub-entry’s name whilst others don’t. Therefore you need to ensure that you use a suitable style. (See §13 for a list of predefined glossary styles.) If you want level 1 sub-entries automatically numbered (in glossary styles that support it) use the subentrycounter package option (see §2.3 for further details).
Note that the parent entry will automatically be added to the glossary if any of its child entries are used in the document. If the parent entry is not referenced in the document, it will not have a number list. Note also that makeindex has a restriction on the maximum hierarchical depth.
To create a glossary with hierarchical divisions, you need to first define the division, which will be a top level (level 0) entry, and then define the sub-entries using the relevant higher level entry as the value of the parent key. (In a hierarchical context, a higher level indicates a numerically smaller level number, so level 0 is one level higher than level 1.) The top level entry may represent, for example, a topic or classification. A level 1 entry may represent, for example, a sub-topic or sub-classification.
Suppose I want a glossary of mathematical symbols that are divided into Greek letters and Roman letters. Then I can define the divisions as follows:
Note that in this example, the top level entries don’t need a description so I have set the descriptions to
I can now define my sub-entries as follows:
Sub-entries that have the same name as the parent entry don’t need to have the name key explicitly set. For example, the word “glossary” can mean a list of technical words or a collection of glosses. In both cases the plural is “glossaries”. So first define the parent entry:
Now define the two different meanings of the word with the parent key set to the above parent entry label:
In the above example, the plural form for both of the child entries is the same as the parent entry, so the plural key was not required for the child entries. However, if the sub-entries have different plurals, they will need to be specified. For example:
You can store all your glossary entry definitions in another file and use:
This is a preamble-only command. You may also use
Now suppose I have a file myacronyms.tex that contains:
If you want to use
Note that only those entries that have been indexed in the text will appear in the relevant glossaries. Note also that
Remember that you can use
You can move an entry from one glossary to another using:
Note that no check is performed to determine the existence of the target glossary. If you want to move an entry to a glossary that’s skipped by
Originally,
To overcome the first two problems, as from version 4.0 the glossaries package modifies the definition of
There are drawbacks to this mechanism: if you modify an entry definition, you need a second run to see the effect of your modification in
Version 4.47 has introduced changes that have removed some of the issues involved, and there are now warning messages if there is an attempt to multiply define the same entry label.
The glossaries-extra package provides a setting (but not for Options 1 or 4) that allows
§4.8.1 above covers technical issues that can cause your document to have compilation errors or produce incorrect output. This section focuses on good writing practice. The main reason cited by users wanting to define entries within the document environment rather than in the preamble is that they want to write the definition as they type in their document text. This suggests a “stream of consciousness” style of writing that may be acceptable in certain literary genres but is inappropriate for factual documents.
When you write technical documents, regardless of whether it’s a PhD thesis or an article for a journal or proceedings, you must plan what you write in advance. If you plan in advance, you should have a fairly good idea of the type of terminology that your document will contain, so while you are planning, create a new file with all your entry definitions. If, while you’re writing your document, you remember another term you need, then you can switch over to your definition file and add it. Most text editors have the ability to have more than one file open at a time. The other advantage to this approach is that if you forget the label, you can look it up in the definition file rather than searching through your document text to find the definition.
Once you have defined a glossary entry using a command such as
Some of these commands are more complicated than others. Many of them are robust and can’t be used in fully expandable contexts, such as in PDF bookmarks.
The commands are broadly divided into:
The text which appears at the point in the document when using any of the commands described in §5.1.2 or §5.1.3 is referred to as the link text (even if there are no hyperlinks). These commands also add content to an external indexing file that is used to generate the relevant entry line in the glossary. This information includes an associated location that is added to the number list for that entry. By default, the location refers to the page number. For further information on number lists, see §12. These external indexing file need to be post-processed by makeindex or xindy if you have chosen Options 2 or 3. If you don’t use
Note that repeated use of these commands for the same entry can cause the number list to become quite long, which may not be particular helpful to the reader. In this case, you can use the non-indexing commands described in §5.2 or you can use the glossaries-extra package, which provides a means to suppress the automated indexing of the commands listed in this chapter. (For example, in this manual, common terms such as glossary have too many references in the document to list them all in their number list in the index. They have a custom key created with
Aside from problems with expansion issues, PDF bookmarks and possible nested hyperlinks in the table of contents (or list of whatever) any use of the commands described in §5.1.2 will have their first use flag unset when they appear in the table of contents (or list of whatever) which is usually too soon and will not match the actual heading or caption in the document if there is a different first/subsequent use.
The above warning is particularly important if you are using the glossaries package in conjunction with the hyperref package. Instead, use one of the expandable commands listed in §5.2 (such as
If you want the link text to produce a hyperlink to the corresponding entry line in the glossary, you should load the hyperref package before the glossaries package. That’s what I’ve done in this manual, so if you encounter a hyperlinked term, such as link text, you can click on the word or phrase and it will take you to a brief description in this document’s glossary or you can click on a command name, such as
These are limitations of the DVI format not of the glossaries package.
It may be that you only want terms in certain glossaries to have hyperlinks, but not for other glossaries. In this case, you can use the package option nohypertypes to identify the glossary lists that shouldn’t have hyperlinked link text. See §2.1 for further details.
The way the link text is displayed depends on
Each entry has an associated conditional referred to as the first use flag. Some of the commands described in this chapter automatically unset this flag and can also use it to determine what text should be displayed. These types of commands are the
The
The keys listed below are available for the optional first argument of the
This section describes the
Apart from
Don’t use any of the
Take care using these commands within commands or environments that are processed multiple times as this can confuse the first use flag query and state change. This includes frames with overlays in beamer and the tabularx environment provided by tabularx. The glossaries package automatically deals with this issue in amsmath’s align environment. You can apply a patch to tabularx by placing the command
Most of the commands below have case-changing variants to convert the link text to sentence case or all caps. The sentence case conversion is performed by
List of Tables
List of Examples
texdoc -l glossaries-user-example
where is the example number zero-padded to three digits to find out if the example files are installed on your device. 1. Introduction
(This is a trivial example. For a real document I recommend you use siunitx for units.)
\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}
\newabbreviation
and stylemods, are only available with the glossaries-extra package. There are also some commands and options (such as \makeglossaries
and symbols) that are provided by the base glossaries package but are redefined by the glossaries-extra package. See the glossaries-extra user manual for further details of those commands. \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.
1.1. Rollback
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.\usepackage
{glossaries}[=v4.52]
Note that this should also rollback mfirstuc to version 2.07 if you have a later version installed.\usepackage
{glossaries}[=v4.49]
\usepackage
{glossaries}[=v4.46]
1.2. Integrating Other Packages and Known Issues
\usepackage
{amsgen}% load before
\usepackage
{ }% must be loaded after amsgen
\usepackage
{hyperref}% load after
\usepackage
{glossaries}% load after hyperref
\babelprovide
. The tracklang package is able to pick up known language labels from the document class options, for example:
The above doesn’t load babel or polyglossia or translator, but the translate=true setting will ensure that tracklang is loaded and the language-sensitive command provided by glossaries will use the definitions in glossaries-german.ldf (which needs to be installed separately, see §1.5) because tracklang can pick up the german document class option.\documentclass
[german]{article}
\usepackage
[translate=true]{glossaries}
The tracklang package used to be able to detect languages identified by polyglossia’s \usepackage
[french]{babel}
\usepackage
[translate=babel]{glossaries}
\setmainlanguage
and \setotherlanguage
, but tracklang v1.5 can’t with newer versions of polyglossia. You will need to upgrade to tracklang v1.6+ to allow this to work again.\usepackage
[nil]{babel}
\babelprovide
{french}
\usepackage
[languages=french]{glossaries}
1.3. Indexing Options
\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).
If the sort=none or sort=clear options are used, \ifglsxindy
xindy\else
makeindex\fi
\glsindexingsetting
will be redefined to none
. If \makeglossaries
is used \glsindexingsetting
will be updated to either makeindex
or xindy
as appropriate (that is, the conditional will no longer be part of the definition). If \makenoidxglossaries
is used then \glsindexingsetting
will be updated to noidx
. This means that \glsindexingsetting
can’t be fully relied on until the start of the document environment. (If you are using glossaries-extra v1.49+, then this command will also be updated to take the record setting into account.)\makeglossaries
into your class or package code. Aside from forcing the user into a particular indexing method, it means that they’re unable to use any commands that must come before \makeglossaries
(such as \newglossary
) and they can’t switch off the indexing whilst working on a draft document. (If you are using a class or package that has done this, pass the disablemakegloss option to glossaries. For example, via the document class options.)
Option
1
2
3
4
5
Requires glossaries-extra?
✖
✖
✖
✔
✔
Requires an external application?
✖
✔
✔
✔
✖
Requires Perl?
✖
✖
✔
✖
✖
Requires Java?
✖
✖
✖
✔
✖
Can sort extended Latin alphabets or non-Latin alphabets?
✖∗
✖
✔
✔
N/A
Efficient sort algorithm?
✖
✔
✔
✔
N/A
Can use a different sort method for each glossary?
✔
✖†
✖†
✔
N/A
Any problematic sort values?
✔
✔
✔
✖
✖‡
Are entries with identical sort values treated as separate unique entries?
✔
✔
✖§
✔
✔
Can automatically form ranges in the location lists?
✖
✔
✔
✔
✖
Can have non-standard locations in the location lists?
✔
✖
✔⧫
✔
✔¶
Maximum hierarchical depth (style-dependent)
∞#
3
∞
∞
∞
\glsdisplaynumberlist
reliable? ✔
✖
✖
✔
✖
\newglossaryentry
allowed in document environment? (Not recommended.) ✖
✔
✔
✖※
✔⁑
Requires additional write registers?
✖
✔
✔
✖
✖★
Default value of sanitizesort package option
false
true
true
true✾
true✾
\AA
is treated the same as A.1.3.1. Option 1 (“noidx”)
You can place all your entry definitions in a separate file and load it in the document preamble with \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}
\loadglsentries
(after \makenoidxglossaries
). Note that six entries have been defined but only five are referenced (indexed) in the document so only those five appear in the glossary.
This uses the indexgroup style, which puts a heading at the start of each letter group. The letter group is determined by the first character of the sort value. For a preview of all available styles, see Gallery: Predefined Styles. The number 1 after each description is the number list (or location list). This is the list of locations (page numbers, in this case) where the entry was indexed. In this example, all entries were indexed on page 1.
then the sort value will default to \'
eliteelite
if sanitizesort=false is used and will default to the literal string \’elite if sanitizesort=true is used. \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}
}
\glsxtrnewsymbol
, which automatically sets the sort key to the entry label (instead of the name).
to your preamble (before you start defining your entries, as described in §4).\makenoidxglossaries
where you want your list of entries to appear (described in §8). Alternatively, to display all glossaries use the iterative command: \printnoidxglossary
\printnoidxglossaries
1.3.2. Option 2 (makeindex)
Example 4 demonstrates a simple document that requires makeindex:
You can place all your entry definitions in a separate file and load it in the preamble with \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}
\loadglsentries
(after \makeglossaries
). The result is the same as for Example 3.
\'
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.\makeglossaries
) that adjusts the special characters and input keyword and also ensures that the resulting file (which is input by \printglossary
) adheres to the glossary style. If you want to use an alternative, you will need to ensure that it can honour the settings in the ist file. \arabic
, \roman
, \Roman
, \alph
and \Alph
.
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 indexing file has been created.\GlsSetQuote
. For example:
This must be used before \GlsSetQuote
{+}
\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.
to your preamble (before you start defining your entries, as described in §4).\makeglossaries
where you want your list of entries to appear (described in §8). Alternatively, to display all glossaries use the iterative command: \printglossary
\printglossaries
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.)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.% 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.)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.1.3.3. Option 3 (xindy)
Example 5 demonstrates a simple document that requires xindy:
You can place all your entry definitions in a separate file and load it in the preamble with \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}
\loadglsentries
(after \makeglossaries
). The result is the same as for Example 3 and Example 4.
\printglossary
reads this file in on the next run.
In these problematic cases, you must set the sort field explicitly, as in the above example which has: $
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}
}
\glsxtrnewsymbol
, which automatically sets the sort key to the entry label (instead of the name).
If you are using a non-Latin script you’ll also need to either switch off the creation of the number group: \usepackage
[xindy]{glossaries}
or use either \usepackage
[xindy={glsnumbers=false}]{glossaries}
(to indicate the first letter group to follow the digits) or \GlsSetXdyFirstLetterAfterDigits
{ }
to indicate where the number group should be placed (see §14).\GlsSetXdyNumberGroupOrder
{ }\makeglossaries
to your preamble (before you start defining your entries, as described in §4).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
.)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.% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
(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 \usepackage
[xindy,order=letter]{glossaries}
-M ord/letorder
to the options list. See §1.6.3 for further details on using xindy explicitly.1.3.4. Option 4 (bib2gls)
Note that the abbreviation style must be set before \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}
\GlsXtrLoadResources
. The file sample-entries.bib contains:
The result is slightly different from the previous examples. Letter groups aren’t created by default with bib2gls so, even though the glossary style supports letter groups, there’s no group information.
@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}
}
@atentry
, the symbol alpha (\(\alpha \)) is defined using @symbol
and the abbreviation “ARPANET” is defined using @abbreviation
.@entry
, @symbol
, @abbreviation
) has a particular field that’s used for the sort value by default (name, the label, short). You will break this mechanism if you explicitly use the sort key. See bib2gls gallery: sorting for examples.
or (equivalently) \usepackage
[record]{glossaries-extra}
or (with glossaries-extra v1.37+ and bib2gls v1.8+): \usepackage
[record=only]{glossaries-extra}
The record=nameref option is the best method if you are using hyperref.\usepackage
[record=nameref]{glossaries-extra}
\GlsXtrLoadResources
. For example:
The bib files are identified as a comma-separated list in the value of the src key. The sort option identifies the sorting method. This may be a locale identifier for alphabetic sorting, but there are other sort methods available, such as character code or numeric. One resource set may cover multiple glossaries or one glossary may be split across multiple resource sets, forming logical sub-blocks.\GlsXtrLoadResources
[% definitions in entries1.bib and entries2.bib:
src={entries1,entries2},
sort={de-CH-1996}% sort according to this locale
]
Alternatively all glossaries can be displayed using the iterative command: \printunsrtglossary
The document is built using: \printunsrtglossaries
pdflatex myDoc
bib2gls myDoc
pdflatex myDoc
If letter groups are required, you need the --group switch: bib2gls --group myDoc
or with arara: % arara: bib2gls: { group: on }
(You will also need an appropriate glossary style.)
\usepackage
[record]{glossaries-extra}
\GlsXtrLoadResources
to identify the bib file(s) and bib2gls options. The bib extension may be omitted: \GlsXtrLoadResources
[src={terms.bib,abbreviations.bib},sort=en]
where you want your list of entries to appear. Alternatively to display all glossaries use the iterative command: \printunsrtglossary
\printunsrtglossaries
1.3.5. Option 5 (“unsrt”)
You can place all your entry definitions in a separate file and load it in the preamble with \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}
\loadglsentries
. There’s no “activation” command (such as \makeglossaries
for Options 2 and 3). \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.\printunsrtglossary
won’t be listed.
Alternatively all glossaries can be displayed using the iterative command: \printunsrtglossary
\printunsrtglossaries
pdflatex myDoc
unless the glossary needs to appear in the table of contents, in which case a second run is required: pdflatex myDoc
pdflatex myDoc
(Naturally if the document also contains citations, and so on, then additional steps are required. Similarly for all the other options above.)1.3.6. Option 6 (“standalone”)
or \glsentryname
{ }
to display the entry name.) Instead of creating a list, this has standalone definitions throughout the document. The entry name may or may not be in a section heading.\Glsentryname
{ }\loadglsentries
), as with Option 5.
This allows the references to hyperlink to the standalone definitions rather than to a glossary.
\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}
Where the file terms.bib contains: \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}
The advantage in this approach (with @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)}}
}
\loadglsentries
or bib2gls) is that you can use an existing database of entries shared across multiple documents, ensuring consistent notation for all of them.pdflatex myDoc
pdflatex myDoc
This will ensure that any entries indexed in the document (through commands like \GlsXtrLoadResources
[src={terms},sort=none]
\gls
or \glsadd
) will be selected by bib2gls, but it will skip the sorting step. (The chances are you probably also won’t need location lists either. If so, you can add the option save-locations=false.)pdflatex myDoc
bib2gls myDoc
pdflatex myDoc
pdflatex myDoc
\printunsrtglossary
, you use
where you want the name (and anchor with hyperref) to appear in the document. This will allow the link text created by commands like \glsxtrglossentry
{ }\gls
to link to that point in the document. The description can simply be displayed with
or \glsentrydesc
{ }
, as in the above examples. In both examples, I’ve defined a custom command \Glsentrydesc
{label}\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.\glsentrydesc
or \Glsentrydesc
, you can use
, which will obey category attributes such as glossdesc and glossdescfont. See the glossaries-extra manual for further details.)\glossentrydesc
{ }
or \glsentrysymbol
{ }
. In the first example, I’ve used \glossentrysymbol
{ }\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.\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. \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).\ifglshassymbol
outside of the section title. For example: \ifglshassymbol
{#1}%
{\section
{\glsxtrglossentry
{#1} \glossentrysymbol
{#1}}}
{\section
{\glsxtrglossentry
{#1}}}
or (for title-case) \glssetcategoryattribute
{general}{glossname}{firstuc}
However, this won’t apply the case change in the table of contents or bookmarks. Instead you can use helper commands provided by glossaries-extra v1.49+ but make sure you have up-to-date versions of glossaries and mfirstuc.\glssetcategoryattribute
{general}{glossname}{title}
(Or name-case-change=title for title case.) This copies the name value to the text field and then applies a case change to the name field (leaving the text field unchanged). The name in the section titles now starts with a capital but the link text produced by commands like \GlsXtrLoadResources
[src={terms},
sort=none,save-locations=false,
replicate-fields={name=text},
name-case-change=firstuc
]
\gls
is still lowercase.
A more automated solution can be obtained with the standalone helper commands for the PDF bookmark and heading text (glossaries-extra v1.49+).\newglossaryentry
{set}{name={Set},text={set},
description={a collection of any kind of objects},
symbol={\ensuremath
{\mathcal
{S}}}
}
I also need to sort the entries, so the resource command is now: \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}
At the end of the document, I can add the glossary: \GlsXtrLoadResources
[src={terms},% definitions in terms.bib
sort=en-GB,% sort by this locale
replicate-fields={name=text},
name-case-change=firstuc
]
Note that I’ve had to switch off the hypertargets with target=false (otherwise there would be duplicate targets). If you want letter group headings you need to use the --group switch: \printunsrtglossary
[title=Index,target=false]
bib2gls --group myDoc
or if you are using arara: % arara: bib2gls: { group: on }
See the glossaries-extra user manual for further details about this style.\renewcommand
*{\glsxtrbookindexname
}[1]{%
\glossentrynameother
{#1}{text}}
@index
in the bib file. For example:
They can be used in the document as usual: @index
{element}
@index
{member,alias={element}}
The objects that make up a set are the
See glossaries-extra and bib2gls: An Introductory Guide or the bib2gls user manual for further details.\glspl
{element}
or \glspl
{member}.
1.4. Dummy Entries for Testing
\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.}}
There are also some level 1 entries, which may or may not have the symbol and user keys set. For example: \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}}
There are no deeper hierarchical entries. Where set, the user1 key is an uppercase letter (A–Z), the user2 key is an integer, the user3 key is a lowercase Roman numeral, the user4 key is in the form - where is either an upper or lowercase letter (a–z or A–Z) and is either an upper or lowercase Roman numeral. The user5 key is a random number (in the range \((-50,+50)\) for top level (level 0) entries and \((-1,+1)\) for child entries). The user6 key is a random date between 1000-01-01 and 2099-12-31.\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}
\newacronym
is redefined to use \newabbreviation
with the category key set to acronym (rather than the default abbreviation). This means that you need to set the abbreviation style for the acronym category. For example: \setabbreviationstyle
[acronym]{long-short}
\newacronym
[type={\glsdefaulttype
},
description={fringilla a, euismod sodales, sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula}
\newacronym
is redefined to use \newabbreviation
with the category key set to acronym (rather than the default abbreviation). This means that you need to set the abbreviation style for the acronym category. For example: \setabbreviationstyle
[acronym]{long-short-desc}
\newacronym
[type={\glsdefaulttype
},user1={love itself}]
{li}{LI}{lorem ipsum}
\newacronym
is redefined to use \newabbreviation
with the category key set to acronym (rather than the default abbreviation). This means that you need to set the abbreviation style for the acronym category. For example: \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/}}
\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
\babelprovide
. In the event that tracklang can’t detect the language, use the languages package option. See §1.2 and also Localisation with tracklang.tex for further details.
If you are using a non-Latin script, you may need the xindynoglsnumbers=option or use \documentclass
[french]{article}
\usepackage
[utf8]{inputenc}
\usepackage
[T1]{fontenc}
\usepackage
{babel}
\usepackage
[xindy]{glossaries}
\GlsSetXdyFirstLetterAfterDigits
to indicate the first letter group that should follow the number group.\Gls
). For example: % mfirstuc v2.07:
This isn’t necessary with glossaries v4.50+ and mfirstuc v2.08+. \newglossaryentry
{elite}{name={{é}lite},
description={select group or class}}
% mfirstuc v2.08:
\newglossaryentry
{elite}{name={élite},
description={select group or class}}
\makeglossaries
, you may need to specify the encoding using the -C option. Read the xindy manual for further details of this option."
) 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: ?
(question mark), |
(pipe) or !
(exclamation mark). For example:
This must be done before \GlsSetQuote
{+}
\makeglossaries
and any entry definitions. It’s only applicable for makeindex. This option in conjunction with ngerman will also cause makeglossaries to use the -g switch when invoking makeindex.\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
and then use babel’s caption hook mechanism. Note that if you pass the language options directly to babel rather that using the document class options or otherwise passing the same options to translator, then translator won’t pick up the language and no dictionaries will be loaded and babel’s caption hooks will be used instead.\documentclass
[english,french]{article}
\usepackage
{babel}
\usepackage
[translate=babel]{glossaries}
Command Name
Translator Key Word
Purpose
\glossaryname
Glossary
Title of the main glossary.
\acronymname
Acronyms
Title of the list of acronyms (when used with package option acronym).
\entryname
Notation (glossaries)
Header for first column in the glossary (for 2, 3 or 4 column glossaries that support headers).
\descriptionname
Description (glossaries)
Header for second column in the glossary (for 2, 3 or 4 column glossaries that support headers).
\symbolname
Symbol (glossaries)
Header for symbol column in the glossary for glossary styles that support this option.
\pagelistname
Page List (glossaries)
Header for the page list column in the glossary for glossaries that support this option.
\glssymbolsgroupname
Symbols (glossaries)
Header for symbols section of the glossary for glossary styles that support this option.
\glsnumbersgroupname
Numbers (glossaries)
Header for numbers section of the glossary for glossary styles that support this option.
(translator is automatically loaded).\documentclass
[english,french]{article}
\usepackage
{babel}
\usepackage
{glossaries}
(translator isn’t loaded). The glossaries-extra package has translate=babel as the default if babel has been loaded.\documentclass
[english,french]{article}
\usepackage
{babel}
\usepackage
[translate=babel]{glossaries}
\documentclass
{article}
\usepackage
{polyglossia}
\setmainlanguage
{english}
\usepackage
{glossaries}
\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
).\deftranslation
in the preamble. It should be put in your personal dictionary instead (as in the example below). See the translator documentation for further details.
You can now load it using: \ProvidesDictionary
{myinstitute-glossaries-dictionary}{English}
\deftranslation
{Glossary}{Nomenclature}
\deftranslation
{Page List (glossaries)}{Location}
(Make sure that myinstitute-glossaries-dictionary-English.dict can be found by TeX.) If you want to share your custom dictionary, you can upload it to CTAN.\usedictionary
{myinstitute-glossaries-dictionary}
\documentclass
[british]{article}
\usepackage
{babel}
\usepackage
[translate=babel]{glossaries}
\addto
\captionsbritish
{%
\renewcommand
*{\glossaryname
}{List of Terms}%
\renewcommand
*{\acronymname
}{List of Acronyms}%
}
1.5.2. Creating a New Language Module
english
) and is the language name used by translator (for example, English
).
You can use this as a template for your dictionary file. Change \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}
English
to the translator name for your language (so that it matches the file name glossaries-dictionary-.dict) and, for each \providetranslation
, change the second argument to the appropriate translation.
This is a somewhat longer file, but again you can use it as a template. Replace \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
}}
English
with the translator language label used for the dictionary file and replace english
with the root language name . Within the definition of \glossariescaptions
, replace the English text (such as “Glossaries”) with the appropriate translation.\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.\captions
hook as that’s typically not switched used until the start of the document. This means that the suffix in effect will be for the last loaded language that redefined these commands. It’s best to initialise these commands to the most common suffix required in your document and use the plural, longplural, shortplural etc keys to override exceptions. \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
}%
}
(Again you can use this as a template. Replace \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
}
irish
with your root language label and Irish
with the translator dictionary label.)\glossariescaptionsirish
but the *-noenc.ldf file uses LaTeX accent commands:
whereas the *-utf8.ldf file replaces the accent commands with the appropriate UTF-8 characters.\@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
% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
With latexmk you need to set up the required dependencies. \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 first two items also apply to makeglossaries-lite.
and suppose you have \newglossaryentry
{citrusfruit}{name={citrus fruit},
description={fruit of any citrus tree. (See also \gls
{orange})}}
\newglossaryentry
{orange}{name={orange},
description={an orange coloured fruit.}}
in your document but don’t reference the “orange” entry, then the orange entry won’t appear in your glossary until you first create the glossary and then do another run of makeglossaries, makeindex or xindy. For example, if the document is called myDoc.tex, then you must do: \gls
{citrusfruit}pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
(In the case of Option 4, bib2gls will scan the description for instances of commands like \gls
to ensure they are selected but an extra bib2gls call is required to ensure the locations are included, if location lists are required. See the and bib2gls manual for further details.)
Command or Package Option
makeindex
xindy
order=letter
use -l
use
-M ord/letorder
order=word
default
default
xindy=language={lang},codepage={code}
N/A
use
-L -C
\GlsSetXdyLanguage
{ } N/A
use
-L
\GlsSetXdyCodePage
{ } N/A
use
-C
1.6.1. Using the makeglossaries Perl Script
makeglossaries
pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
If you only want one glossary processed (for example, if you are working on a draft of a large document and want to concentrate on one specific glossary) then include the extension supplied to \newglossary
, such as glo for the main
glossary. Note that if you do specify the extension and your document has multiple glossaries defined, then makeglossaries will tell you how many glossaries have been ignored unless the -q has been used.pdflatex -output-directory myTmpDir myDoc
makeglossaries -d myTmpDir myDoc
If you explicitly use makeindex, this will cause a warning and the location list will be “1, 1”. That is, the page number will be repeated with each format. As from v2.18, makeglossaries will check for this warning and, if found, will attempt to correct the problem by removing duplicate locations and retrying. If you actually want the duplicate location, you can prevent makeglossaries from checking and correcting the duplicates with -e.\documentclass
{article}
\usepackage
{glossaries}
\makeglossaries
\newglossaryentry
{sample}{name={sample},description={an example}}
\begin{document}
\gls
{sample}, \gls
[format=textbf]{sample}.
\printglossaries
\end{document}
open()
on the piped redirection 2>&1 |
and parses the processor output to help diagnose problems. If this method fails makeglossaries will print an “Unable to fork” warning and will retry without redirection. Without this redirection, the -q switch doesn’t work as well. Some operating systems don’t support redirection.-p
to makeindex. (Ignored if xindy should be called.)-M ord/letorder
to xindy.-s
to makeindex or -M
to xindy (where is with the xdy extension removed). This will generate an error if the extension is xdy when makeindex should be called, or if the extension isn’t xdy when xindy should be called.\newglossary
).\newglossary
).1.6.2. Using the makeglossaries-lite Lua Script
makeglossaries-lite
makeglossaries-lite myDoc
Note that the arara rule doesn’t contain the hyphen: % arara: makeglossarieslite
-p
to makeindex. (Ignored if xindy should be called.)-M ord/letorder
to xindy.\newglossary
).\newglossary
).1.6.3. Using xindy explicitly (Option 3)
This is required regardless of whether you use xindy explicitly or whether it’s called implicitly via applications such as makeglossaries. This causes the glossary entries to be written in raw xindy format, so you need to use \usepackage
[xindy]{glossaries}
-I xindy
not -I tex
.xindy -L -C -I xindy -M -t .glg -o .gls .glo
where is the required language name, is the encoding, is the name of the document without the tex extension and is the name of the xindy style file without the xdy extension. The default name for this style file is xdy but can be changed via \setStyleFile
. You may need to specify the full path name depending on the current working directory. If any of the file names contain spaces, you must delimit them using double-quotes.xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo
main
glossary. You need to do the same for each of the other glossaries (including the list of acronyms if you have used the acronym package option), substituting glg, gls and glo with the relevant extensions. For example, if you have used the acronym package option, then you would need to do: xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acn
For additional glossaries, the extensions are those supplied when you created the glossary with \newglossary
.makeglossaries myDoc
Note also that some commands and package options have no effect if you use xindy explicitly instead of using makeglossaries. These are listed in Table 1.3.1.6.4. Using makeindex explicitly (Option 2)
makeindex -s .ist -t .glg -o .gls .glo
where is the name of your document without the tex extension and ist is the name of the makeindex style file. By default, this is ist, but may be changed via \setStyleFile
. Note that there are other options, such as -l (letter ordering). See the makeindex manual for further details.makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
Note that this only creates the main
glossary. If you have additional glossaries (for example, if you have used the acronym package option) then you must call makeindex for each glossary, substituting glg, gls and glo with the relevant extensions. For example, if you have used the acronym package option, then you need to type the following in your terminal: makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
For additional glossaries, the extensions are those supplied when you created the glossary with \newglossary
.makeglossaries myDoc
Note also that some commands and package options have no effect if you use makeindex explicitly instead of using makeglossaries. These are listed in Table 1.3.1.7. Note to Front-End and Script Developers
1.7.1. MakeIndex and Xindy
main
glossary is written as:
If glossaries-extra’s hybrid method has been used (with \@newglossary
{main}{glg}{gls}{glo}
\makeglossaries
[ ]), then the sub-list of glossaries that need to be processed will be identified with:
% arara: makeglossaries if found("aux", "@istfilename")
It’s more complicated if you want to explicitly run makeindex or xindy.word
or letter
(obtained from the order package option).english
).utf8
). The above two commands are omitted if makeindex should be used.1.7.2. Entry Labels
1.7.3. Bib2Gls
% arara: bib2gls if found("aux", "glsxtr@resource")
(It gets more complicated if both \glsxtr@resource
and \@istfilename
are present as that indicates the hybrid record=hybrid option.)\glssee
):
{label}{xr list} You can also pick up the commands defined with \glsxtrnewglslike
, which are added to the aux file for bib2gls’s benefit:
If \GlsXtrSetAltModifier
is used, then the modifier is identified with:
Label prefixes (for the \dgls
set of commands) are identified with:
2. Package Options
=true
for boolean options. (For example, acronym is equivalent to acronym=true).2.1. General Options
\makeglossaries
). Note that if you use debug with any value other than false it will override this option.\makeglossaries
: wrglossary(
Note that this setting will also cancel )( )
nowarn.\glsdohypertarget
is used by commands like \glstarget
and when \glsdohyperlink
is used by commands like \gls
. In math mode or inner mode, this uses:
which typesets the target name as: [
just before the link or anchor. This uses the text-block command:
which checks for math-mode before applying the font change. In outer mode \glsshowtargetfonttext
{ }]
\glsshowtarget
uses:
which by default places the target name in the margin with a symbol produced with:
which defaults to a small right facing triangle.\glsshowtargetfonttext
and \glsshowtargetouter
is given by the declaration:
In this case, only the “sample1” entry has been indexed, even though \documentclass
{article}
\usepackage
{glossaries}
\newglossaryentry
{sample1}{name={sample1},description={example}}
\newglossaryentry
{sample2}{name={sample2},description={example}}
\glsadd
{sample2}% <- does nothing here
\makeglossaries
\begin{document}
\gls
{sample1}.
\printglossaries
\end{document}
appears in the source code. This is because \glsadd
{sample2}
has been used before the associated file is opened by \glsadd
{sample2}\makeglossaries
. Since the file isn’t open yet, the information can’t be written to it, which is why the “sample2” entry doesn’t appear in the glossary.\makeglossaries
the indexing is suppressed with Options 2 and 3 but, other than that, commands like \gls
behave as usual.\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
.\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.)
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 \usepackage
[debug]{glossaries}
Package glossaries Info: wrglossary( )( ) on
input line .
where is the glossary label and 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.\addto
\captions
mechanism. If polyglossia has been loaded, glossaries-polyglossia will be loaded.\glossaryname
so that will still be translated if you have loaded babel.)pt-BR
) or one of tracklang’s known language labels (such as british
).
. If false, only subsequent use instances will have a hyperlink (if supported).\gls
*\gls
-like commands (for example, \gls
or \glsdisp
), but not the \glstext
-like commands (for example, \glslink
or \glstext
). \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).\glsunsetall
to all the regular (non-acronym) glossaries. For example: \usepackage
[acronym,hyperfirst=false]{glossaries}
% acronym and glossary entry definitions
% at the end of the preamble
\glsunsetall
[main
]
\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
(or if the short key has been set using \ifglshasshort
). For example, to switch off the hyperlink on first use just for acronyms: \renewcommand
*{\glslinkcheckfirsthyperhook
}{%
\ifglsused
{\glslabel
}{}%
{%
\ifglshaslong
{\glslabel
}{\setkeys
{glslink}{hyper=false}}%
}%
}
\glstext
. (You can, instead, redefine \glslinkpostsetkeys
, which is used by both the \gls
-like and \glstext
-like commands.)
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. If you also want the name, use writeglslabelnames. (See also glossaries-extra’s docdef=atom package option.)\jobname
.glslabels\newglossaryentry
. Available values:\newglossaryentry
is not permitted in the document environment (default with glossaries-extra and for Option 1 with just the base glossaries package).\newglossaryentry
is only permitted in the document environment if it occurs before \printglossary
(not available for some indexing options, such as Option 4).\newglossaryentry
is permitted in the document environment where it would normally be permitted by the base glossaries package. This will create the glsdefs file if \newglossaryentry
is found in the document environment.2.2. Sectioning, Headings and TOC Options
in the final argument of \numberline
{}\addcontentsline
. This will align the table of contents entry with the numbered section titles. Note that this option has no effect with toc=false. If toc=true is used without numberline, the glossary title will be aligned with the section numbers rather than the section titles.chapter
not \chapter
or chapter*
).\chapter
, if that command exists, or \section
otherwise. The starred or unstarred form is determined by the numberedsection option.
You can omit the value if you want to use \usepackage
[section=subsection]{glossaries}
\section
:
is equivalent to \usepackage
[section]{glossaries}
You can change this value later in the document using
where is the sectional unit.\usepackage
[section=section]{glossaries}
\glsglossarymark
(see §8.2).\glsglossarymark
use all caps in the header, otherwise no case change will be applied. The default is ucmark=false, unless memoir has been loaded, in which case the default is ucmark=true.\renewcommand
{\glsglossarymark
}[1]{%
\ifglsucmark
\markright
{\glsuppercase
{#1}}%
\else
\markright
{#1}%
\fi
}
\chapter*
or \section*
).\chapter
or \section
), but no label is automatically added.\chapter
or \section
) and is assigned a label (via \label
). The label is formed from the glossary’s label prefixed with:
The default value of \glsautoprefix
is empty. For example, if you load glossaries using:
then each glossary will appear in a numbered section, and can be referenced using something like: \usepackage
[section,numberedsection=autolabel]
{glossaries}
The main glossary is in section
If you can’t decide whether to have the acronyms in the main glossary or a separate list of acronyms, you can use ~
\ref
{main} and
the list of acronyms is in section~
\ref
{acronym}.
\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
You can redefine the prefix if the default label clashes with another label in your document. For example: ~
\ref
{\acronymtype
}.
will add \renewcommand
*{\glsautoprefix
}{glo:}
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
Or, if you are undecided on a prefix: ~
\ref
{glo:\acronymtype
}.
The list of acronyms is in
section
~
\ref
{\glsautoprefix
\acronymtype
}.
\chapter*
or \section*
). It’s designed for use with the nameref package. For example:
Alternatively, since nameref is automatically loaded by hyperref: \usepackage
{nameref}
\usepackage
[numberedsection=nameref]{glossaries}
Now \usepackage
{hyperref}
\usepackage
[numberedsection=nameref]{glossaries}
will display the (table of contents) section title associated with the \nameref
{main}main
glossary. As above, you can redefine \glsautoprefix
to provide a prefix for the label.2.3. Glossary Appearance Options
\glsentrynumberlist
and \glsdisplaynumberlist
in §5.2.) This setting is always true if you use Option 1 as a by-product of the way that indexing method works.\ref
if either entrycounter=true or subentrycounter=true, with the label , where is the entry’s label and is given by:
If both entrycounter=false and subentrycounter=false,
will be used instead.\gls
{ }\glsrefentry
, you must run LaTeX twice after creating the indexing files using makeglossaries, makeindex or xindy (or after creating the glstex file with bib2gls) to ensure the cross-references are up-to-date. This is because the counter can’t be incremented and labelled until the glossary is typeset. \refstepcounter
and \label
) with:
This command is within the definition of \glsentryitem
, which is typically used in glossary styles at the start of top level (level 0) entries. The argument is the entry label.
if entrycounter=true, otherwise does nothing. This is therefore more generally useful in glossary styles as it will silently do nothing if the setting isn’t on. This command is used within the definition of \theglossaryentry
.\space
\glsentryitem
.\print
option glossary.\glossarypreamble
) to use \glsresetentrycounter
. For example:
or if you are using \renewcommand
{\glossarypreamble
}{%
\glsresetentrycounter
}
\setglossarypreamble
, add it to each glossary preamble, as required. For example: \setglossarypreamble
[acronym
]{%
\glsresetentrycounter
The preamble text here for the list of acronyms.
}
\setglossarypreamble
{%
\glsresetentrycounter
The preamble text here for the main
glossary.
}
\glsentryitem
. If subentrycounter is used before entrycounter then the two counters are independent.\glsrefentry
. There are analogous commands to those for entrycounter.\glsentryitem
if entrycounter=false.\refstepcounter
and \label
) with: \glssubentryitem
if subentrycounter=true, otherwise it does nothing. The argument is the entry label and is passed to \label
is as for \glsrefentry
.
if subentrycounter=true, otherwise does nothing. This is therefore more generally useful in glossary styles as it will silently do nothing if the setting isn’t on. This command is used in \theglossarysubentry
)\space
\glssubentryitem
.\print
option glossary.\print
option glossary. (See §13 for further details.)\setglossarystyle
or the style \print
option glossary. Example:
Alternatively: \usepackage
[nostyles]{glossaries}
\usepackage
{glossary-mcols}
\setglossarystyle
{mcoltree}
\usepackage
[nostyles,stylemods=mcols,style=mcoltree]{glossaries-extra}
\print
options glossary.\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 §11.\newglossary
or the counter key when defining an entry or by the counter option when referencing an entry.\print
options glossary.2.4. Indexing Options
(This option is only relevant with makeindex and xindy.) The see key automatically indexes the cross-referenced entry using \glssee
. This means that if this key is used in an entry definition before the relevant indexing 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
. \makeglossaries
to speed up the compilation of a draft document by omitting the indexing, you can use seenoindex=warn or seenoindex=ignore.\thepage
with the default counter=page) expand to a robust command then you may need to use esclocations=true. You may additionally need to set the following conditional to true: \thepage
. Since this hack may cause some issues and isn’t necessary for the majority of documents, this is off by default., where { } is a command (optionally preceded by
\protect
) and is a location acceptable to makeindex, then you can use makeglossaries to make a suitable adjustment without esclocations=true. See §12.5 for furthe details.\gls
-like or \glstext
-like commands are used. Note that \glsadd
will always add information to the external glossary file (since that’s the purpose of that command).\glsreset
after an entry has been indexed will cause that entry to be indexed multiple times if it’s used again after the reset. Likewise unsetting the first use flag before an entry has been indexed will prevent it from being indexed (unless specifically indexed with \glsadd
). \glswriteentry
is:
This does unless indexonlyfirst=true and the entry identified by has been marked as used\newcommand
*{\glswriteentry
}[2]{%
\ifglsindexonlyfirst
\ifglsused
{#1}{}{#2}%
\else
#2%
\fi
}
acronym
glossary and not in the main
(or any other) glossary:
Here I’ve used \renewcommand
*{\glswriteentry
}[2]{%
\ifthenelse
\equal
{\glsentrytype
{#1}}{acronym}
{\ifglsused
{#1}{}{#2}}%
{#2}%
}
\ifthenelse
to ensure the arguments of \equal
are fully expanded before the comparison is made. There are other methods of performing an expanded string comparison, which you may prefer to use.\glsadd
) any cross-referenced entries that haven’t been marked as used at the end of the document. Note that this increases the document build time. See glossaries-extra manual for further details.\glssee
) when the entry is defined. This means that any entry with the see (or seealso) key will automatically be added to the glossary. See the glossaries-extra manual for further details.\caption
command that increments the counter so the location will be incorrect if an entry is indexed within the float before the caption.)2.5. Sorting Options
\GlsXtrLoadResources
not with the sort package option. There’s no sorting with Options 5 and 6.
The sort value () must be sanitized before writing it to the indexing 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: \newglossaryentry
{hash}{name={\#
},sort={},
description={hash symbol}}
and you actually want \newcommand
{\mysortvalue
}{AAA}
\newglossaryentry
{sample}{%
name={sample},
sort={\mysortvalue
},
description={an example}}
\mysortvalue
expanded, so that the entry is sorted according to AAA
, then use the package option sanitizesortfalse.\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.\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 setting may be used if no glossary is required or if \printunsrtglossary
is used (Option 5). If you want an unsorted glossary with bib2gls, use the resource option sort=none instead. This option will redefine \glsindexingsetting
to none
.\printunsrtglossary
with Option 5. See the glossaries-extra manual for further details. This option will redefine \glsindexingsetting
to none
. The remaining sort options listed below don’t change \glsindexingsetting
.\newglossaryentry
(if present) or the name key (if sort key is missing).\glsprestandardsort
just does:
which sanitizes if sanitizesort=true (or does nothing if sanitizesort=false).\newglossaryentry
.\glsprestandardsort
won’t affect any entries that have already been defined and will have no effect at all if you use another sort setting. 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. \printnoidxglossary
: \printnoidxglossary
[sort=word]
\printnoidxglossary
[type=acronym
,sort=word]
\printnoidxglossary
[type=notation,sort=def]
main
and acronym
entries, then redefine \glsprestandardsort
to set 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 if is notation
.
The second method can be achieved as follows: \newcounter
{sortcount}
\renewcommand
{\glsprestandardsort
}[3]{%
\stepcounter
{sortcount}%
\edef
#1{\glssortnumberfmt
{\arabic
{sortcount}}}%
}
(\newcounter
{sortcount}
\renewcommand
{\glsprestandardsort
}[3]{%
\ifdefstring
{#2}{notation}%
{%
\stepcounter
{sortcount}%
\edef
#1{\glssortnumberfmt
{\arabic
{sortcount}}}%
}%
{%
\glsdosanitizesort
}%
}
\ifdefstring
is defined by the etoolbox package, which is automatically loaded by glossaries.) For a complete document, see the sample file sampleSort.tex. \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.
and \newcommand
{\sortname
}[2]{#2, #1}
\newcommand
{\textname
}[2]{#1 #2}
\name
needs to be initialised to \textname
:
Now redefine \let
\name
\textname
\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 in the text:
(The somewhat complicate use of \renewcommand
{\glsprestandardsort
}[3]{%
\let
\name
\sortname
\edef
#1{\expandafter
\expandonce
\expandafter
{#1}}%
\let
\name
\textname
\glsdosanitizesort
}
\expandafter
etc helps to protect fragile commands, but care is still needed.)
For a complete document, see the sample file samplePeople.tex. \newglossaryentry
{joebloggs}name={\name
{Joe}{Bloggs}},
description={some information about Joe Bloggs}
\newglossaryentry
{johnsmith}{name={\name
{John}{Smith}},
description={some information about John Smith}}
\printnoidxglossary
:
Alternatively, you can specify the order for individual glossaries: \printnoidxglossary
[sort=standard]
\printnoidxglossary
[sort=word]
\printnoidxglossary
[type=acronym
,sort=letter]
\makeglossaries
otherwise the syntax in the glossary files will be incorrect. If this conditional is false, it means that any option other than Option 3 is in effect. (If you need to know which indexing option is in effect, check the definition of \glsindexingsetting
instead.)\languagename
but note that this may not be correct as xindy has a different labelling system to babel and polyglossia. \languagename
may still not expand to the language required for the glossary. In which case, you need to specify the correct xindy language. For example:
If you have multiple glossaries in different languages, use \usepackage
[brazilian,english]{babel}
\usepackage
[xindy=language=portuguese]{glossaries}
\GlsSetXdyLanguage
to set the language for each glossary.\inputencodingname
. As from v4.50, if \inputencodingname
isn’t defined, UTF-8 is assumed (which is identified by the label utf8
). If this is incorrect, you will need to use the codepage option but make sure you use the xindy codepage label (for example, cp1252
or latin9
). See the xindy documentation for further details.ij-as-y-utf8
or din5007-utf8
. See §14.2. \usepackage
[xindy=language=english,codepage=cp1252]
{glossaries}
\GlsSetXdyNumberGroupOrder
.\GlsSetXdyLanguage
and \GlsSetXdyCodePage
if the defaults are inappropriate (see §14.2.)
Then the document build is now: \usepackage
[automake]{glossaries}
\makeglossaries
\newglossaryentry
{sample}{name={sample},description={an example}}
\begin{document}
\gls
{sample}
\printglossaries
\end{document}
pdflatex myDoc
pdflatex myDoc
This will run makeindex on every LaTeX run. If you have a large glossary with a complex document build, this can end up being more time-consuming that simply running makeindex (either explicitly or via makeglossaries) the minimum number of required times.runsystem
”. For example, if the document is in a file called myDoc.tex and it has:
and you run LaTeX in restricted mode, then if call was successful, you should find the following line in the file myDoc.log: \usepackage
[automake]{glossaries}
runsystem(makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo)...executed safely (allowed).
The parentheses immediately after “runsystem
” show how the command was called. The bit after the three dots ...
indicates whether or not the command was run and, if so, whether it was successful. In the above case, it has “executed safely (allowed)”. This means that it was allowed to run in restricted mode because makeindex is on the list of trusted applications.
and rerun LaTeX in restricted mode, then the line in myDoc.log will now be: \usepackage
[automake=makegloss]{glossaries}
runsystem(makeglossaries myDoc)...disabled (restricted).
This indicates that an attempt was made to run makeglossaries (rather than a direct call to makeindex), which isn’t permitted in restricted mode. There will be a similar message with automake=lite or if the xindy option is used. These cases require the unrestricted shell escape. runsystem
” to find out exactly what system calls are being attempted. runsystem(makeglossaries myDoc)...executed.
This means that makeglossaries was run. If it has “failed” instead of “executed”, then it means there was a fatal error. Note that just because the log file has “executed” doesn’t mean that the application ran without a problem as there may have been some warnings or non-fatal errors. If you get any unexpected results, check the indexing application’s transcript file (for example, the glg file, myDoc.glg in the above, for the main
glossary).\thepage
is correct.) Unfortunately, there are situations where the delayed write never occurs, for example, if there are floats on the final page. In those cases, it’s better to use an immediate write (any of the following options).\makeglossaries
using an immediate write. This ensures that the indexing files are read by the indexing application before they are opened (which will clear their content).\makeglossaries
using an immediate write if the aux file exists. On the one hand, it’s better to use makeglossaries as it has some extra diagnostic functions, but on the other hand it both requires Perl and the unrestricted shell escape.\makeglossaries
using an immediate write if the aux file exists. There’s little benefit in this option over automake=immediate and it has the added disadvantage of requiring the unrestricted mode.\makeglossaries
and \makenoidxglossaries
should be disabled. This option is provided in the event that you have to use a class or package that disregards the advice in §1.3 and automatically performs \makeglossaries
or \makenoidxglossaries
but you don’t want this. (For example, you want to use a different indexing method or you want to disable indexing while working on a draft document.)\PassOptionsToPackage
before glossaries is loaded. Note that this does nothing if \makeglossaries
or \makenoidxglossaries
has already been used whilst enabled.\setupglossaries
. It issues a warning if \makeglossaries
or \makenoidxglossaries
has already been used whilst enabled. Note that this option removes the check for \nofiles
, as this option is an indication that the output files are actually required.\makeglossaries
but you need an extra glossary, which has to be defined before \makeglossaries
, then you can do:
or \documentclass
[disablemakegloss]{customclass}
\newglossary*
{functions}{Functions}
\setupglossaries
{restoremakegloss}
\makeglossaries
\PassOptionsToPackage
{disablemakegloss}{glossaries}
\documentclass
{customclass}
\newglossary*
{functions}{Functions}
\setupglossaries
{restoremakegloss}
\makeglossaries
\makeglossaries
or \makenoidxglossaries
regardless of restoremakegloss.2.6. Glossary Type Options
\gls
etc shouldn’t have hyperlinks by default. Make sure you enclose the value in braces if it contains any commas. Example:
As illustrated above, the glossary doesn’t need to exist when you identify it in nohypertypes.\usepackage
[acronym,nohypertypes={acronym
,notation}]
{glossaries}
\newglossary
[nlg]{notation}{not}{ntn}{Notation}
main
glossary and associated glo file, if unrequired. Note that if you use this option, you must create another glossary in which to put all your entries (either via the acronym (or acronyms) package option described in §2.7 or via the symbols, numbers or index options described in §2.9 or via \newglossary
described in §9). Even if you don’t intend to display the glossary, a default glossary is still required.main
glossary and you don’t use this option to suppress its creation, makeglossaries will produce a warning: Warning: File ' .glo' is empty.
Have you used any entries defined in glossary '
If you did actually want to use the main
'?
Remember to use package option 'nomain' if
you don't want to use the main
glossary.
main
glossary and you see this warning, check that you have referenced the entries in that glossary via commands such as \gls
.symbols
via
It also defines
which is a synonym for \newglossary
[slg]{symbols
}{sls}{slo}{\glssymbolsgroupname
}
\printglossary
[type=symbols
, ]
to display the list of symbols.\printnoidxglossary
[type=symbols
, ]
symbols
glossary and don’t intend to use the main
glossary. \glsxtrnewsymbol
as a convenient shortcut method for defining symbols. See the glossaries-extra manual for further details. numbers
via
It also defines
which is a synonym for \newglossary
[nlg]{numbers
}{nls}{nlo}{\glsnumbersgroupname
}
\printglossary
[type=numbers
, ]
to display the list of numbers.\printnoidxglossary
[type=numbers
, ]
numbers
glossary and don’t intend to use the main
glossary. \glsxtrnewnumber
as a convenient shortcut method for defining numbers. See the glossaries-extra manual for further details. index
via
It also defines
which is a synonym for \newglossary
[ilg]{index
}{ind}{idx}{\indexname
}
and
which is a synonym for \newglossaryentry
{ }{type={index
},name={entry-label},
description={\nopostdesc
}, }
\printglossary
[type=index
, ]
to display this glossary.\printnoidxglossary
[type=index
, ]
index
glossary and don’t intend to use the main
glossary. Note that you can’t mix this option with \index
. Either use glossaries for the indexing or use a custom indexing package, such as makeidx, imakeidx. (You can, of course, load one of those packages and load glossaries without the index package option.)
However, it can also be useful to link to the index in order to look up the term’s location list to find other parts of the document where it might be used. For example, this manual will have a hyperlink to the index for general terms, such as “table of contents”, or general commands, such as \GlsDeclareNoHyperList
{index
}
\index
, that aren’t defined anywhere in the document.\setupglossaries
.2.7. Acronym and Abbreviation Options
If true, this creates a new glossary with the label acronym
. This is equivalent to:
It will also provide (if not already defined)
that’s equivalent to \newglossary
[alg]{acronym
}{acr}{acn}{\acronymname
}
\printglossary
[type=acronym
, ]
to display the list of acronyms.\printnoidxglossary
[type=acronym
, ]
\acronymtype
is set to acronym
otherwise it is set to \glsdefaulttype
(which is normally the main
glossary.) Entries that are defined using \newacronym
are placed in the glossary whose label is given by \acronymtype
, unless another glossary is explicitly specified with the type key.acronym
glossary. (That is, you don’t intend to use the main
glossary.) abbreviations
and sets the command \glsxtrabbrvtype
to this. If the acronym option hasn’t also been used, then \acronymtype
will be set to \glsxtrabbrvtype
. This enables both \newacronym
and \newabbreviation
to use the same glossary.abbreviations
using:
The label can be accessed with \newglossary
[glg-abr]{abbreviations
}{gls-abr}{glo-abr}{\abbreviationsname
}
\glsxtrabbrvtype
, which is analogous to \acronymtype
. See glossaries-extra manual for further details.\setacronymstyle
. (It also enables \forallacronyms
to work.)\setacronymstyle
is used then it will automatically add \acronymtype
to the list. main
glossary to also contain a list of acronyms, you can do:
No check is performed to determine if the listed glossaries exist, so you can add glossaries you haven’t defined yet. For example: \usepackage
[acronym,acronymlists=main
]{glossaries}
You can use
instead of or in addition to the acronymlists option. This will add the glossaries given in to the list of glossaries that are identified as lists of acronyms. To replace the list of acronym lists with a new list use:
\usepackage
[acronym,acronymlists={main
,acronym2}]
{glossaries}
\newglossary
[alg2]{acronym2}{acr2}{acn2}%
{Statistical Acronyms}
\setacronymstyle
then it will result in inconsistencies in the formatting. If this does happen, and is for some reason unavoidable (such as \setacronymstyle
occurring in a package that loads glossaries), you will need to set the entry format to match the style: \DeclareAcronymList
{ }
\defglsentryfmt
[ ]{\GlsUseAcrEntryDispStyle
}{ }
2.8. Deprecated Acronym Style Options
\setacronymstyle
instead. See §6 for further details.\newacronym
to allow a description. This option may be replaced by:
or (with smallcaps) \setacronymstyle
{long-short-desc}
or (with smaller) \setacronymstyle
{long-sc-short-desc}
or (with footnote) \setacronymstyle
{long-sm-short-desc}
or (with footnote and smallcaps) \setacronymstyle
{footnote-desc}
or (with footnote and smaller) \setacronymstyle
{footnote-sc-desc}
or (with dua) \setacronymstyle
{footnote-sm-desc}
\setacronymstyle
{dua-desc}
\newacronym
and the way that acronyms are displayed. This option may be replaced by:
or (with description) \setacronymstyle
{long-sc-short}
or (with description and footnote) \setacronymstyle
{long-sc-short-desc}
\setacronymstyle
{footnote-sc-desc}
\newacronym
and the way that acronyms are displayed. This option may be replaced by:
or (with description) \setacronymstyle
{long-sm-short}
or (with description and footnote) \setacronymstyle
{long-sm-short-desc}
\setacronymstyle
{footnote-sm-desc}
\newacronym
and the way that acronyms are displayed. This option may be replaced by:
or (with smallcaps) \setacronymstyle
{footnote}
or (with smaller) \setacronymstyle
{footnote-sc}
or (with description) \setacronymstyle
{footnote-sm}
or (with smallcaps and description) \setacronymstyle
{footnote-desc}
or (with smaller and description) \setacronymstyle
{footnote-sc-desc}
\setacronymstyle
{footnote-sm-desc}
\newacronym
so that acronyms are always expanded. This option may be replaced by:
or (with description) \setacronymstyle
{dua}
\setacronymstyle
{dua-desc}
2.9. Other Options
\printglossary
if the indexing file is missing.\MFUsentencecase
, it will be expanded, which could break existing documents.\makeglossary
and \glossary
) are redefined in terms of the glossaries package’s commands. However, they were never documented in this user manual, and the conversion guide (“Upgrading from the glossary package to the glossaries package”) explicitly discourages their use.\glossary
and \makeglossary
. If they have been previously redefined by kernelglossredefs their original definitions (at the time glossaries was loaded) will be restored.\glossary
and \makeglossary
, but their use will trigger warnings.\glossary
and \makeglossary
without any warnings.\makeglossary
and \glossary
. Other packages or classes may provide additional glossary-related commands or environments that conflict with glossaries (such as \printglossary
and theglossary). These non-kernel commands aren’t affected by this package option, and you will have to find some way to resolve the conflict if you require both glossary mechanisms. (The glossaries package will override the existing definitions of \printglossary
and theglossary.)\PrintChanges
.)2.10. Setting Options After the Package is Loaded
\setupglossaries
: xindy, xindygloss, xindynoglsnumbers, makeindex, nolong, nosuper, nolist, notree, nostyles, nomain, compatible-2.07, translate, notranslate, languages, acronym. These options have to be set while the package is loading, except for the xindy sub-options which can be set using commands like \GlsSetXdyLanguage
(see §14 for further details).3. Setting Up
3.1. Option 1
\makenoidxglossaries
none of the glossaries will be displayed.3.2. Options 2 and 3
\makeglossaries
none of the indexing files will be created.\makeglossaries
has an optional argument that allows you to have a hybrid of Options 1 or 2 or Options 1 or 3. See glossaries-extra manual for further details. \makeglossaries
as they are required when creating the customised style file. If you attempt to use those commands after \makeglossaries
you will generate an error. Similarly, there are some commands that must not be used before \makeglossaries
because they require the associated indexing files to be open, if those files should be created. These may not necessarily generate an error or warning as a different indexing option may be chosen that doesn’t require those files (such as Options 5 or 6). \makeglossaries
command internally uses: \relax
so that it can only be used once. In general, there should be no reason to use or alter this command.
(Option 2) or \jobname
.ist
(Option 3). This name may be changed using: \jobname
.xdy\writeist
that can be set with: \writeist
to prevent an unnecessary write register from being created in the event that neither makeindex nor xindy is required.\GlsSetWriteIstHook
hook to write extra information to the style file, make sure you use the appropriate syntax for the desired indexing application. For example, with makeindex:
This changes the page precedence and the maximum line length used by makeindex.\GlsSetWriteIstHook
{%
\write
\glswrite
{page_precedence "arnAR"}%
\write
\glswrite
{line_max 80}%
}
\writeist
to \relax
(making it do nothing) but will also update the xindy attribute list if applicable.
This command must not be used after \glsSetCompositor
{-}
\makeglossaries
. Note that with makeindex, any locations with the wrong compositor (or one that hasn’t been correctly identified with \glsSetCompositor
) will cause makeindex to reject the location with an invalid number/digit message. As from v4.50, makeglossaries will check for this message and attempt a correction, but this can result in an incorrectly formatted location in the number list. See the information about makeglossaries’s -e switch in §1.6.1 for further details.
See §12 for further information about number lists.\glsSetCompositor
{.}\glsSetAlphaCompositor
{-}
4. Defining Glossary Entries
\newglossaryentry
can also be used in the optional argument of \newacronym
, although some of them, such as first and plural, interfere with the acronym styles.\longnewglossaryentry
may only be used in the preamble. See §4.8 for a discussion of the problems with defining entries within the document instead of in the preamble. (The glossaries-extra package has an option that provides a restricted form of document definitions that avoids some of the issues discussed in §4.8.) \newglossaryentry
. Option 4 requires that definitions are provided in bib format. Options 5 and 6 work best with either preamble-only definitions or the use of the glossaries-extra package option docdef=restricted. \printunsrtglossary
) or where they appear in the table of contents or list of floats. This is essentially the same problem as defining a robust command mid-document and using it in a section title or caption.,
) or equal signs (=
) with braces to hide them from the = list parser.\longnewglossaryentry
will remove trailing spaces in the description (via \unskip
) but won’t remove leading spaces. This command also appends \nopostdesc
to the end of the description, which suppresses the post-description hook (since the terminating punctuation is more likely to be included in a multi-paragraph description). The glossaries-extra package provides a starred version of \longnewglossaryentry
that doesn’t append either \unskip
or \nopostdesc
.\label
) and therefore must be able to expand to a valid control sequence name. With modern LaTeX kernels, you should now be able to use UTF-8 characters in the label.:
) or double-quote ("
), to active characters. \longnewglossaryentry
and \longprovideglossaryentry
. With the other commands it’s set via the description key.,
) or equal sign (=
) must be enclosed in braces. Available fields are listed below. Additional fields are provided by the supplementary packages glossaries-prefix (§16) and glossaries-accsupp (§17) and also by glossaries-extra. You can also define your own custom keys (see §4.3).\nopostdesc
}. If you want a paragraph break in the description use:
or, better, use \longnewglossaryentry
. However, note that not all glossary styles support multi-line descriptions. If you are using one of the tabular-like glossary styles that permit multi-line descriptions and you really need an explicit line break, use \newline
not \\
(but in general, avoid \\
outside of tabular contexts anyway and use a ragged style if you are having problems with line breaks in a narrow column).\glsxtrnopostpunc
instead of \nopostdesc
to suppress the post-description punctuation. \gls
on subsequent use. If this field is omitted, the value of the name key is used.\newacronym
. Although it is possible to override it by using text in the optional argument of \newacronym
, it will interfere with the acronym style and cause unexpected results.\gls
. If this field is omitted, the value of the text key is used. Note that if you use \glspl
, \Glspl
, \GLSpl
, \glsdisp
before using \gls
, the first value won’t be used with \gls
.\glsdefpostlink
) provided by glossaries-extra if you would like to automatically append content on first use in a consistent manner. See, for example, Gallery: Units (glossaries-extra.sty).\newacronym
, it can interfere with the acronym style and cause unexpected results.\glspl
on subsequent use. If this field is omitted, the value is obtained by appending \glspluralsuffix
to the value of the text field.\newacronym
, it can interfere with the acronym style and cause unexpected results. Use shortplural instead, if the default value is inappropriate.\glspl
. If this field is omitted, the value is obtained from the plural key, if the first key is omitted, or by appending \glspluralsuffix
to the value of the first field, if the first field is present. Note that if you use \gls
, \Gls
, \GLS
, \glsdisp
before using \glspl
, the firstplural value won’t be used with \glspl
.\newacronym
, it can interfere with the acronym style and cause unexpected results. Use shortplural and longplural instead, if the default value is inappropriate.\relax
. Note that not all glossary styles display the symbol.
) and with Options 2 and 3, it’s strongly recommended as the indexing may fail if you don’t (see below).\ensuremath
{\alpha}\glsprestandardsort
(see §2.5).
This is equivalent to: \newglossaryentry
{elite}{
name={\'
elite},
description={select group of people}
}
Unless you use the package option sanitizesort=true, in which case it’s equivalent to: \newglossaryentry
{elite}{
name={\'
elite},
description={select group of people}
sort={elite}
}
This will place the entry before the “A” letter group since the sort value starts with a symbol (a literal backslash \newglossaryentry
{elite}{
name={\'
elite},
description={select group of people}
sort={\
'
elite},
}
\
). Note that Option 1 shouldn’t be used with UTF-8 characters. With old LaTeX kernels, it was able to convert a UTF-8 character, such as é
, to an ASCII equivalent but this is no longer possible.\alpha
}).\glsdefaulttype
is assumed unless \newacronym
is used (see §6).\glsaddkey
or \glsaddstoragekey
(see §4.3).\glsnonextpages
(nonumberlist={true}) or \glsnextpages
(nonumberlist={false}) to the indexing information for Options 2 and 3. Note that this means that if the entry is added to the glossary simply because it has an indexed descendent (and has not been indexed itself) then the first indexed sub-entry that follows will have its number list suppressed instead.\glsnoidxprenumberlist
.
after the entry has been defined. (See §11.) It was originally designed for synonyms that may not occur in the document text but needed to be included in the glossary in order to redirect the reader. Note that it doesn’t index the cross-referenced entry (or entries) as that would interfere with their number lists.\glssee
[ ]{ }{ }
This defines two entries (courgette and zucchini) and automatically adds a cross-reference from zucchini to courgette. (That is, it adds “see courgette” to zucchini’s number list.) This doesn’t automatically index courgette since this would create an unwanted location in courgette’s number list. (Page 1, if the definitions occur in the preamble.)\newglossaryentry
{courgette}{name={courgette},
description={variety of small marrow}}
\newglossaryentry
{zucchini}{name={zucchini},
description={(North American)},
see={courgette}}
this won’t index the zucchini entry, so if zucchini isn’t indexed elsewhere (with commands like \newglossaryentry
{zucchini}{name={zucchini},
description={(North American) see \gls
{courgette}}}
\gls
or \glsadd
) then it won’t appear in the glossary even if courgette does.\makeglossaries
must be used before any occurrence of \newglossaryentry
that contains the see key. \makeglossaries
is commented out.\seealsoname
and seealso={xr-list} is essentially like see={[\seealsoname
] } (Options 3 and 4 may treat these differently).\gls
so that they index the entry given by instead of the original entry. (See, for example, Gallery: Aliases.)\newglossary
(if provided) and the counter identified by the counter package option. The location counter can be overridden by the counter option when using the \gls
-like and \glstext
-like commands.\newacronym
(see §6) and also for \newabbreviation
(see the glossaries-extra manual): long, longplural, short and shortplural. You can use longplural and shortplural in the optional argument of \newacronym
(or \newabbreviation
) to override the defaults, but don’t explicitly use the long or short keys as that may interfere with acronym style (or abbreviation style).\gls
-like or \glstext
-like commands within the text, first, short or long keys (or their plural equivalent) or any other key that you plan to access through those commands. (For example, the symbol key if you intend to use \glssymbol
.) Otherwise you can up with nested links, which can cause complications. You can use them within the value of keys that won’t be accessed through those commands. For example, the description key if you don’t use \glsdesc
. Additionally, they’ll confuse the formatting placeholder commands, such as \glslabel
. The glossaries-extra package provides \glsxtrp
for this type of situation. \Gls
and \Glspl
. For example: % mfirstuc v2.07
Note that the same applies with inputenc: \newglossaryentry
{elite}{name={{\'
e}lite},
description={select group or class}}
% mfirstuc v2.07
This doesn’t apply for XeLaTeX or LuaLaTeX documents or with mfirstuc v2.08+. \newglossaryentry
{elite}{name={{é}lite},
description={select group or class}}
% mfirstuc v2.08
See the mfirstuc manual for further details.\newglossaryentry
{elite}{name={élite},
description={select group or class}}
4.1. Plurals
defines a new entry whose singular form is “cow” and plural form is “cows”. However, if you are writing in archaic English, you may want to use “kine” as the plural form, in which case you would have to do: \newglossaryentry
{cow}{name={cow},description={a fully grown female of any bovine animal}}
\newglossaryentry
{cow}{name={cow},plural={kine},
description={a fully grown female of any bovine animal}}
You can then use \newglossaryentry
{cow}{
name={cow},
description={a fully grown female of any bovine animal (plural cows, archaic plural kine)},
user1={kine}}
to produce “cows” and \glspl
{cow}
to produce “kine”. You can, of course, define an easy to remember synonym. For example: \glsuseri
{cow}
Then you don’t have to remember which key you used to store the second plural. (Be careful with using \let
\glsaltpl
\glsuseri
\let
as it doesn’t check if the command already exists.)\glsaddkey
, described in §4.3 (or simply use \glsdisp
or \glslink
with the appropriate text).\glspluralsuffix
as required. However, this must be done before the entries are defined and is unreliable for multilingual documents. For languages that don’t form plurals by simply appending a suffix, all the plural forms must be specified using the plural key (and the firstplural key where necessary). 4.2. Other Grammatical Constructs
With the above definitions, I can now define terms like this: \let
\glsing
\glsuseri
\let
\glsd
\glsuserii
\newcommand
*{\ingkey
}{user1}
\newcommand
*{\edkey
}{user2}
\newcommand
*{\newword
}[3][]{%
\newglossaryentry
{#2}{%
name={#2},%
description={#3},%
\edkey
={#2ed},%
\ingkey
={#2ing},#1%
}}
and use them in the text: \newword
{play}{to take part in activities for enjoyment}
\newword
[\edkey
={ran},\ingkey
={running}]{run}{to move fast using
the legs}
Peter is
\glsing
{play} in the park today.
Jane \glsd
{play} in the park yesterday.
Peter and Jane \glsd
{run} in the park last week.
\glsaddkey
, described below in §4.3. It may, however, be simpler just to use \glslink
or \glsdisp
with the appropriate link text.4.3. Additional Keys
\glsaddkey
described in §4.3.1. If, on the other hand, you want to add a key to indicate to a glossary style or acronym style that this entry should be formatted differently to other entries, then you can use \glsaddstoragekey
described in §4.3.2.\glsentrytext
). This can be used in an expandable context (provided any fragile commands stored in the key have been protected). The new keys must be added using \glsaddkey
or \glsaddstoragekey
before glossary entries are defined.4.3.1. Document Keys
The starred version of is the new key to use in \newglossaryentry
(or similar commands such as \longnewglossaryentry
); is the default value to use if this key isn’t used in an entry definition (this may reference the current entry label via \glslabel
, but you will have to switch on expansion via the starred version of \glsaddkey
and protect fragile commands); is the control sequence to use analogous to commands like \glsentrytext
; is the control sequence to use analogous to commands like \Glsentrytext
; is the control sequence to use analogous to commands like \glstext
; is the control sequence to use analogous to commands like \Glstext
; is the control sequence to use analogous to commands like \GLStext
.
\glsaddkey
switches on expansion for this key. The unstarred version doesn’t override the current expansion setting.% Define "ed" key:
Now I can define some entries: \glsaddkey
*
{ed}% key
{\glsentrytext
{\glslabel
}ed}% default value
{\glsentryed
}% command analogous to \glsentrytext
{\Glsentryed
}% command analogous to \Glsentrytext
{\glsed
}% command analogous to \glstext
{\Glsed
}% command analogous to \Glstext
{\GLSed
}% command analogous to \GLStext
% Define "ing" key:
\glsaddkey
*
{ing}% key
{\glsentrytext
{\glslabel
}ing}% default value
{\glsentrying
}% command analogous to \glsentrytext
{\Glsentrying
}% command analogous to \Glsentrytext
{\glsing
}% command analogous to \glstext
{\Glsing
}% command analogous to \Glstext
{\GLSing
}% command analogous to \GLStext
% No need to override defaults for this entry:
\newglossaryentry
{jump}{name={jump},description={}}
% Need to override defaults on these entries:
\newglossaryentry
{run}{name={run},
ed={ran},
ing={running},
description={}}
\newglossaryentry
{waddle}{name={waddle},
ed={waddled},
ing={waddling},
description={}}
The dog
For a complete document, see the sample file sample-newkeys.tex. \glsed
{jump} over the duck.
The duck was \glsing
{waddle} round the dog.
The dog \glsed
{run} away from the duck.
4.3.2. Storage Keys
\glsaddkey
, described above in §4.3.1.\glsaddkey
except that it doesn’t define the additional commands. You can access or update the value of your new field using the commands described in §15.6.\glsaddstoragekey
{abbrtype}% key/field name
{word}% default value if not explicitly set
{\abbrtype
}% custom command to access the value if required
Remember that the new style needs to be set before defining any terms: \newacronymstyle
{mystyle}% style name
{% Use the generic display
\ifglshaslong
{\glslabel
}{\glsgenacfmt
}{\glsgenentryfmt
}%
}%
{% Put the long form in the description
\renewcommand
*{\GenericAcronymFields
}{%
description={\the
\glslongtok
}}%
% For the full format, test the value of the "abbrtype" key.
% If it's set to "word" put the short form first with
% the long form in brackets.
\renewcommand
*{\genacrfullformat
}[2]{%
\ifglsfieldeq
{##
1}{abbrtype}{word}
{% is a proper acronym
\protect
\firstacronymfont
{\glsentryshort
{##
1}}##
2\space
(\glsentrylong
{##
1})%
}%
{% is another form of abbreviation
\glsentrylong
{##
1}##
2\space
(\protect
\firstacronymfont
{\glsentryshort
{##
1}})%
}%
}%
% sentence case version:
\renewcommand
*{\Genacrfullformat
}[2]{%
\ifglsfieldeq
{##
1}{abbrtype}{word}
{% is a proper acronym
\protect
\firstacronymfont
{\Glsentryshort
{##
1}}##
2\space
(\glsentrylong
{##
1})%
}
{% is another form of abbreviation
\Glsentrylong
{##
1}##
2\space
(\protect
\firstacronymfont
{\glsentryshort
{##
1}})%
}%
}%
% plural
\renewcommand
*{\genplacrfullformat
}[2]{%
\ifglsfieldeq
{##
1}{abbrtype}{word}%
{% is a proper acronym
\protect
\firstacronymfont
{\glsentryshortpl
{##
1}}##
2\space
(\glsentrylong
{##
1})%
}%
{% is another form of abbreviation
\glsentrylongpl
{##
1}##
2\space
(\protect
\firstacronymfont
{\glsentryshortpl
{##
1}})%
}%
}%
% plural and sentence case
\renewcommand
*{\Genplacrfullformat
}[2]{%
\ifglsfieldeq
{##
1}{abbrtype}{word}%
{% is a proper acronym
\protect
\firstacronymfont
{\Glsentryshortpl
{##
1}}##
2\space
(\glsentrylong
{##
1})%
}%
{% is another form of abbreviation
\Glsentrylongpl
{##
1}##
2\space
(\protect
\firstacronymfont
{\glsentryshortpl
{##
1}})%
}%
}%
% Just use the short form as the name part in the glossary:
\renewcommand
*{\acronymentry
}[1]{%
\acronymfont
{\glsentryshort
{##
1}}}%
% Sort by the short form:
\renewcommand
*{\acronymsort
}[2]{##
1}%
% Just use the surrounding font for the short form:
\renewcommand
*{\acronymfont
}[1]{##
1}%
% Same for first use:
\renewcommand
*{\firstacronymfont
}[1]{\acronymfont
{##
1}}%
% Default plural suffix if the plural isn't explicitly set
\renewcommand
*{\acrpluralsuffix
}{\glspluralsuffix
}%
}
\setacronymstyle
{mystyle}
\newacronym
for something that’s not technically an acronym, let’s define a new command for initialisms:
Now the entries can all be defined: \newcommand
*{\newinitialism
}[4][]{%
\newacronym
[abbrtype=initialism,#1]{#2}{#3}{#4}%
}
On first use, \newacronym
{radar}{radar}{radio detecting and ranging}
\newacronym
{laser}{laser}{light amplification by stimulated
emission of radiation}
\newacronym
{scuba}{scuba}{self-contained underwater breathing
apparatus}
\newinitialism
{dsp}{DSP}{digital signal processing}
\newinitialism
{atm}{ATM}{automated teller machine}
will produce “radar (radio detecting and ranging)” but \gls
{radar}
will produce “DSP (digital signal processing)”.\gls
{dsp}\newglossaryentry
is explicitly used (instead of through \newacronym
) the abbrtype key will be set to its default value of “word” but the \ifglshaslong
test in the custom acronym style will be false (since the long key hasn’t been set) so the display style will switch to that given by \glsgenentryfmt
and they’ll be no test performed on the abbrtype field.
This may seem a little odd for non-abbreviated entries that are defined using \glsaddstoragekey
{abbrtype}% key/field name
{acronym}% default value if not explicitly set
{\abbrtype
}% custom command to access the value if required
\newglossaryentry
directly, but \ifglshaslong
can be used to determine whether or not to reference the value of this new abbrtype field.
needs to be changed to: \renewcommand
*{\GenericAcronymFields
}{%
description={\the
\glslongtok
}}%
Additionally, to accommodate the change in the default value of the abbrtype key, all instances of \renewcommand
*{\GenericAcronymFields
}{}%
need to be changed to: \ifglsfieldeq
{##
1}{abbrtype}{word}
\ifglsfieldeq
{##
1}{abbrtype}{acronym}
\newacronym
[description={system for detecting the position and speed of aircraft, ships, etc}]{radar}{radar}{radio detecting
and ranging}
\newinitialism
but again the optional argument is required to set the description: \newinitialism
[description={mathematical manipulation of an information signal}]{dsp}{DSP}{digital signal processing}
The contractions can similarly been defined using this new command: \newcommand
*{\newcontraction
}[4][]{%
\newacronym
[abbrtype=contraction,#1]{#2}{#3}{#4}%
}
\newcontraction
[description={front part of a ship below the deck}]{focsle}{fo'c's'le}{forecastle}
\newglossaryentry
{apple}{name={apple},description={a fruit}}
This uses \newglossarystyle
{mystyle}% style name
{% base it on the "list" style
\setglossarystyle
{list}%
\renewcommand
*{\glossentry
}[2]{%
\item
[\glsentryitem
{##
1}%
\glstarget
{##
1}{\glossentryname
{##
1}}]
\ifglshaslong
{##
1}%
{ (\abbrtype
{##
1}: \glsentrylong
{##
1})\space
}{}%
\glossentrydesc
{##
1}\glspostdescription
\space
##
2}%
}
\ifglshaslong
to determine whether or not the term is an abbreviation. (An alternative is to use \ifglshasshort
. The long and short keys are only set for acronyms/abbreviations.) \abbrtype
(defined by \glsaddstoragekey
earlier) is used to indicate the type of abbreviation.
apple a fruit.
but the abbreviations are displayed in the form
laser (acronym: light amplification by stimulated emission of radiation) device that creates a narrow beam of intense light.
(for acronyms) or
DSP (initialism: digital signal processing) mathematical manipulation of an information signal.
(for initalisms) or
fo’c’s’le (contraction: forecastle) front part of a ship below the deck.
(for contractions).4.4. Expansion
\glssetnoexpandfield
).
Key
Field
sort
sortvalue
firstplural
firstpl
description
desc
descriptionplural
descplural
user1
useri
user2
userii
user3
useriii
user4
useriv
user5
userv
user6
uservi
longplural
longpl
shortplural
shortpl
\glssetexpandfield
or \glssetnoexpandfield
are governed by \glsnoexpandfields
. (This should be used before you define the entries.)\newacronym
and \newabbreviation
partially suppress expansion of some keys regardless of the above expansion settings. 4.5. Sub-Entries
\glsfieldfetch
or (with glossaries-extra) \glsxtrusefield
, but neither the level nor the parent values should be altered as it can cause inconsistencies in the sorting and glossary formatting. The indexing syntax for Options 2 and 3 is generated when the entry is first defined, so it’s too late to change the hierarchy after that, and bib2gls obtains the hierarchical information from the bib files and the resource options. Note, however, that glossaries-extra does allow the ability to locally alter the level with the leveloffset option, which is mainly intended for nested glossary. See the glossaries-extra manual for further details and also Gallery: Inner or Nested Glossaries. 4.5.1. Hierarchy
\newglossaryentry
{greekletter}{name={Greek letters},
description={\nopostdesc
}}
\newglossaryentry
romanletter{name={Roman letters},
description={\nopostdesc
}}
\nopostdesc
. This gives a blank description and suppresses the description terminator.
For a complete document, see the sample file sampletree.tex.\newglossaryentry
{pi}name={\ensuremath
{\pi
}},sort={pi},
description={ratio of the circumference of a circle to the diameter},
parent={greekletter}
\newglossaryentry
{C}{name={\ensuremath
{C}},sort={C},
description={Euler's constant},
parent={romanletter}}
4.5.2. Homographs
As in the previous example, the parent entry has no description, so the description terminator needs to be suppressed using \newglossaryentry
{glossary}{name={glossary},
description={\nopostdesc
},
plural={glossaries}}
\nopostdesc
.
Note that if I reference the parent entry (for example, \newglossaryentry
{glossarylist}{
description={list of technical words},
sort={1},
parent={glossary}}
\newglossaryentry
{glossarycol}{
description={collection of glosses},
sort={2},
parent={glossary}}
), the location will be added to the parent’s number list, whereas if I reference any of the child entries (for example, \gls
{glossary}
), the location will be added to the child entry’s number list. Note also that since the sub-entries have the same name, the sort key is required with Option 3 (xindy) and recommended with Option 2 (makeindex). You can use the subentrycounter package option to automatically number the level 1 child entries in the glossary (if you use a glossary style that supports it). See §2.3 for further details.\gls
{glossarylist}
For a complete document, see the sample file sample.tex.\newglossaryentry
{bravo}{name={bravo},
description={\nopostdesc
}}
\newglossaryentry
{bravocry}{description={cry of approval (pl. bravos)},
sort={1},
plural={bravos},
parent={bravo}}
\newglossaryentry
{bravoruffian}{description={hired ruffian or killer (pl. bravoes)},
sort={2},
plural={bravoes},
parent={bravo}}
4.6. Loading Entries From a File
\newglossaryentry
, \longnewglossaryentry
, \newacronym
etc commands. The optional argument is the name of the glossary to which those entries should belong, for those entries where the type key has been omitted (or, more specifically, for those entries whose type has been set to \glsdefaulttype
, which is what \newglossaryentry
uses by default). See sampleDB.tex for a complete example document.\newacronym
, \newabbreviation
, \newterm
, \glsxtrnewsymbol
and \glsxtrnewnumber
all set the type key to the appropriate glossary. This means that the optional argument won’t apply to those commands, unless they have type={\glsdefaulttype
}. \input
to load the file but don’t use \include
. If you find that your file is becoming unmanageably large, you may want to consider switching to bib2gls and use an application such as JabRef to manage the entry definitions.\AtBeginDocument
to \input
all your entries automatically at the start of the document, add the \AtBeginDocument
command before you load the glossaries package (and babel, if you are also loading that) to avoid the creation of the glsdefs file and any associated problems that are caused by defining commands in the document environment. (See §4.8.) Alternatively, if you are using glossaries-extra, use the docdef=restricted package option.
and suppose in my preamble I use the command: \newglossaryentry
{perl}{type={main
},
name={Perl},
description={A scripting language}}
\newglossaryentry
{tex}{name={\TeX
},
description={A typesetting language},sort={TeX}}
\newglossaryentry
{html}{type={\glsdefaulttype
},
name={html},
description={A mark up language}}
then this will add the entries “tex” and “html” to the glossary whose type is given by languages, but the entry “perl” will be added to the \loadglsentries
[languages]{myentries}
main
glossary, since it explicitly sets the type to main
.
then (supposing I have defined a new glossary type called altacronym) \newacronym
{aca}{aca}{a contrived acronym}
will add “aca” to the glossary type \loadglsentries
[altacronym]{myacronyms}
acronym
, if the package option acronym has been specified, or will add “aca” to the glossary type altacronym, if the package option acronym is not specified. This is because \acronymtype
is set to \glsdefaulttype
if the acronym package option is not used so the optional argument of \loadglsentries
will work in that case, but if the acronym option is used then \acronymtype
will be redefined to acronym
.\loadglsentries
with the acronym package option set, there are two possible solutions to this problem:
and do: \newacronym
[type={\glsdefaulttype
}]{aca}{aca}{a
contrived acronym}
\loadglsentries
[altacronym]{myacronyms}
\acronymtype
to the target glossary: \let
\orgacronymtype
\acronymtype
\renewcommand
{\acronymtype
}{altacronym}
\loadglsentries
myacronyms
\let
\acronymtype
\orgacronymtype
\loadglsentries
may only be used in the preamble.\provideglossaryentry
rather than \newglossaryentry
. Suppose you want to maintain a large database of acronyms or terms that you’re likely to use in your documents, but you may want to use a modified version of some of those entries. (Suppose, for example, one document may require a more detailed description.) Then if you define the entries using \provideglossaryentry
in your database file, you can override the definition by simply using \newglossaryentry
before loading the file. For example, suppose your file (called, say, terms.tex) contains:
but suppose your document requires a more detailed description, you can do: \provideglossaryentry
{mallard}{name={mallard},
description={a type of duck}}
Now the “mallard” definition in the terms.tex file will be ignored.\usepackage
{glossaries}
\makeglossaries
\newglossaryentry
{mallard}{name={mallard},
description={a dabbling duck where the male has a green head}}
\loadglsentries
{terms}
4.7. Moving Entries to Another Glossary
\makeglossaries
.\glsfielddef
won’t correctly move the entry, since the label needs to be removed from the old glossary’s internal list and added to the new glossary’s internal list to allow commands such as \glsaddall
and \glsunsetall
to work. \printglossaries
, then define an ignored glossary with \newignoredglossary
. (See §9.) With Options 4 and 5, it’s also possible to copy an entry to another glossary with \glsxtrcopytoglossary
. See the glossaries-extra manual for further details.4.8. Drawbacks With Defining Entries in the Document Environment
\newglossaryentry
(and \newacronym
) could only be used in the preamble. I reluctantly removed this restriction in version 1.13, but there are issues with defining commands in the document environment instead of the preamble, which is why the restriction is maintained for newer commands. This restriction is also reimposed for \newglossaryentry
by Option 1 because in that case the entries must be defined before the aux file is input. (The glossaries-extra package automatically reimposes the preamble-only restriction but provides the docdef package option to allow document definitions for Options 2 and 3 if necessary.)\GlsXtrLoadResources
, which is a preamble-only command. 4.8.1. Technical Issues
\newcommand
in the middle of the document and then moving things around so that the command is used before it has been defined.\label
and \ref
work)."
(double-quote), !
(exclamation mark), ?
(question mark), and |
(pipe). They must not be active when defining a glossary entry where they occur in the sort key (and they should be avoided in the label if they may be active at any point in the document). Additionally, the comma (,
) character and the equals (=
) character should not be active when using commands that have = arguments.\newglossaryentry
at the beginning of the document environment so that the definitions are written to an external file (\jobname
.glsdefs) which is then read in at the start of the document on the next run. This means that the entry can now be looked up in the glossary, even if the glossary occurs at the beginning of the document.\printglossary
(if it occurs at the start of the document); this method requires an extra \newwrite
, which may exceed TeX’s maximum allocation; unexpected expansion issues could occur.\newglossaryentry
to occur in the document environment but doesn’t create the glsdefs file. This circumvents some problems but it means that you can’t display any of the glossaries before all the entries have been defined (so it’s all right if all the glossaries are at the end of the document but not if any occur in the front matter).4.8.2. Good Practice Issues
5. Referencing Entries in the Document
\newglossaryentry
(§4) or \newacronym
(§6), you can refer to that entry in the document with one of the provided commands that are describe in this manual. (There are some additional commands provided by glossaries-extra.) The text produced at that point in the document (the link text) is determined by the command and can also be governed by whether or not the entry has been marked as used.
There are additional commands specific to entries defined with \gls
-like commands, §5.1.2) and those that don’t (the \glstext
-like commands, §5.1.3).\newacronym
that are described in §6.1.5.1. Links to Glossary Entries
\makeglossaries
these external files won’t be created. (Options 1 and 4 write the information to the aux file instead.)\glsaddstoragekey
that’s used to set their default indexing option.)\chapter
or \caption
.\glsentrytext
). Alternatively, provide an alternative via the optional argument to the sectioning/caption command or use hyperref’s \texorpdfstring
. Examples:
(You can use \chapter
An overview of \glsentrytext
{perl}
\chapter
[An overview of Perl]An overview of \gls
{perl}
\chapter
{An overview of \texorpdfstring
{\gls
{perl}}{Perl}}
\glstexorpdfstring
instead of \texorpdfstring
if you don’t know whether or not hyperref will be needed.) \glsfmttext
, that overcome some of the problems. \gls
, and it will take you to the relevant part of the document where the command is described or you can click on a general word or phrase, such as table of contents, and it will take you to the relevant line in the index where you can find the number list to navigate to other parts of the document that are pertinent. If, however, you click on “number list”, you’ll find it leads you to the location list entry in the index instead. This is because number list has been aliased to location list using the alias key. Whereas if you click on “page list” it will take you to the corresponding page list entry in the glossary that has a cross-reference to location list, because the see key was used instead.
Further customisation can be done via \renewcommand
*{\glstextformat
}[1]{\textsf
{#1}}
\defglsentryfmt
or by redefining \glsentryfmt
. See §5.1.4 for further details.\gls
-like commands and are described in §5.1.2. The commands that don’t reference or change the first use flag are \glstext
-like commands and are described in §5.1.3. See §7 for commands that unset (mark the entry as having been used) or reset (mark the entry as not used) the first use flag without referencing the entries.\gls
-like and \glstext
-like commands all take a first optional argument that is a comma-separated list of = options, described below. They also have a star-variant, which inserts hyper=false at the start of the list of options and a plus-variant, which inserts hyper=true at the start of the list of options. For example
is the same as \gls
*
{sample}
and \gls
[hyper=false]{sample}
is the same as \gls
+
{sample}
, whereas just \gls
[hyper=true]{sample}
will use the default hyperlink setting which depends on a number of factors (such as whether the entry is in a glossary that has been identified in the nohypertypes list). You can override the hyper key in the variant’s optional argument, for example, \gls
{sample}
but this creates redundancy and is best avoided. The glossaries-extra package provides the option to add a third custom variant and commands to override the behaviour of the star and plus variants.\gls
*
[hyper=true]{sample}
as this is likely to cause problems. By implication, this means that you should avoid using any of these commands within the text, first, short or long keys (or their plural equivalent) or any other key that you plan to access through these commands. (For example, the symbol key if you intend to use \glslink
{ }{\gls
{ }}\glssymbol
.) The glossaries-extra package provides \glsxtrp
to use instead, which helps to mitigate against nesting problems. 5.1.1. Options
\gls
-like and \glstext
-like commands. The glossaries-extra package provides additional keys. (See the glossaries-extra manual for further details.)\gls
-like command, if this is the first use and the hyperfirst=false package option has been used, then the default value is hyper=false. The hyperlink can be forced on using hyper=true unless the hyperlinks have been suppressed using \glsdisablehyper
. You must load the hyperref package before the glossaries package to ensure the hyperlinks work.\newglossary
) and the default counter identified by the counter package option. See also §12. The glossaries-extra package has additional options that affect the counter used, such as floats and equations. This manual uses the floats option to automatically switch the counter to table for any entries indexed in tables (such as those in Table 12.1).\gls
-like commands that change the entry’s first use flag. If local=true, the change to the first use flag will be localised to the current scope.\glstextformat
. Only available with glossaries-extra.\glstextformat
. Only available with glossaries-extra.\glolinkprefix
to the given value. Only available with glossaries-extra.5.1.2. The
\gls
-Like Commands (First Use Flag Queried)\gls
-like commands that unset (mark as used) the first use flag after the link text, and in most cases they use the current state of the flag to determine the text to be displayed. As described above, these commands all have a star-variant (hyper=false) and a plus-variant (hyper=true) and have an optional first argument that is a = list. These commands use \glsentryfmt
or the equivalent definition provided by \defglsentryfmt
to determine the automatically generated text and its format (see §5.1.4).\glsdisp
, the commands described in this section also have a final optional argument which may be used to insert material into the automatically generated text.\relax
or an empty set of braces {}
immediately before the opening square bracket to prevent it from being interpreted as the final argument. For example:
Use of a semantic command can also help avoid this problem. For example: \gls
{sample}[] [Editor's comment]
\gls
{sample}{} [Editor's comment]
\gls
{sample} \relax
[Editor's comment]
\newcommand
{\edcom
}[1][#1]
% later:
\gls
{sample} \edcom
{Editor's comment}
\gls
-like or \glstext
-like commands in the argument. \glspatchtabularx
in the preamble. This does nothing if tabularx hasn’t been loaded. There’s no patch available for beamer. See §7 for more details and also §15.5.\glssentencecase
and the all caps is performed by \glsuppercase
. Ensure you have at least version 2.08 of mfirstuc to use the modern LaTeX3 case-changing commands instead of the now deprecated textcase package. See the mfirstuc manual for further details.