Latest news 2024-04-12: new blog post "Smile for the Camera: a cybercrime story".

glossaries package FAQ

This is the FAQ for the glossaries package. See also the glossaries user manual, the guide for beginners, Glossaries and Lists and the bug tracker (glossaries category). Example documents can be found in the gallery.

The glossaries package may be extended with the glossaries-extra package to provide additional functions. The glossaries-extra package implicitly loads glossaries.sty so it’s not necessary to load both. Related FAQs: glossaries-extra package and bib2gls application.

The glossaries package uses the tracklang package to detect document languages. Related: tracklang package and Localisation with tracklang.tex.

Error Messages

(La)TeX Errors

After updating to glossaries v4.50 I'm getting undefined commands or options errors (e.g. \glossaryentryfield) 🔗

The glossaries v4.50 release (2022-10-14) includes new LaTeX3 commands that have only been introduced over the past few years. (The new commands overcome long standing issues, particular with UTF-8.)

There have been many changes to the LaTeX kernel over the past few years, some of which have broken existing packages, which means that old documents may have issues if they are recompiled with the new kernel or with packages that have been updated to use the new kernel commands. (See also Legacy Documents and TeX Live Docker Images.)

Therefore glossaries v4.50 was distributed with rollback to v4.49 and all commands and options that were deprecated over 6 years ago have been removed on the grounds that if you have a document that old, it's probably going to have other issues anyway, and it has helped to clean up the code. (Using them should've triggered deprecated warnings with pre 4.50 versions over the past few years, but it seems that in some cases the warnings didn't occur.)

If you still need to use them, you will have to use rollback: 

\usepackage{glossaries}[=v4.49]
but be aware that you may encounter other problems more generally if you mix new releases with old code. It's better to switch to the newer commands.

For example, \glossaryentryfield and \glossarysubentryfield were deprecated in v3.08a (2013-09-28) because it simplifies the content written to the indexing files if only the sort value and label are written to the file in the form sort?\glossentry{label} or sort?\subglossentry{level}{label} rather than including the name, symbol and description (which may be lengthy and may contain special characters that require replacing).

As from v3.08a, 

\glossaryentryfield{label}{name}{symbol}{description}{numberlist}
should be replaced with 
\glossentry{label}{numberlist}
The name can be obtained with \glossentryname{label}, the symbol can be obtained with \glossentrysymbol{label}, and the description can be obtained with \glossentrydesc{label}.

Similarly, 

\glossarysubentryfield{level}{label}{name}{symbol}{description}{numberlist}
should be replaced with 
\subglossentry{level}{label}{numberlist}

2022-10-26 14:12:36

Top

After updating to glossaries v4.50 I'm getting undefined control sequence \MakeTextUppercase 🔗

The textcase package is obsolete as of 2022 and now simply defines \MakeTextUppercase and \MakeTextLowercase to \MakeUppercase and \MakeLowercase. Therefore the glossaries package, as from version 4.50, no longer automatically loads textcase, unless an old (pre 2.08) version of mfirstuc has been detected. Instead, the glossaries package uses its own \glsuppercase command for all-caps and mfirstuc's commands for sentence case.

If you want to continue using \MakeTextUppercase then simply load textcase explicitly.

2022-11-02 11:16:43

Top

I get an error when using a fragile command in my glossary entry 🔗

As from version 4.0, use \glssetnoexpandfield to suppress expansion for a particular field. For older versions, use \protect. See also Why must I protect fragile commands in the name key when the documentation says the name key is sanitized? (Pre version 4.0). Remember that the new \makenoidxglossaries method of creating glossaries makes the default sanitizesort option false so you may need to set the sort key manually if the name contains a fragile command.

2022-11-02 11:16:02

Top

I get an error when using one of the commands that convert the first letter to upper case 🔗

As from version 4.0, commands such as \Glsentryname are robust. (Although, as they aren't expandable, they can’t be used in PDF bookmarks.) For earlier versions of glossaries commands like \Glsentryname were fragile and therefore need to be protected when used in a moving argument.

As from v4.50, these commands can now expand in PDF bookmarks.

2022-11-02 11:15:31

Top

I get the message: “! pdfTeX warning (dest): name{...} has been referenced but does not exist” 🔗

This is not an error, but a warning. This just means that PDFLaTeX can't find the given target. Since all the targets defined by the glossaries package will be placed in the files created when you use makeglossaries, you will always get these messages the first time you LaTeX your document. Once you have successfully run makeglossaries, these warnings should go away. If you still get them, then it’s possible that one or more of your glossary entries had an error which prevented them from being written to the .glo (or equivalent) file. Check the makeindex transcript file (.glg or equivalent) for errors.

2022-11-02 11:13:59

Top

I get an error when using a glossary entry in a chapter/section heading or caption 🔗

(See also Why shouldn’t I use commands like \gls in \section, \chapter, \caption etc?)

With older versions of glossaries this occurs when you try to do something like: 

\section{\gls{sample}}
If you are not using the hyperref package, you can fix this with \protect: 
\section{\protect\gls{sample}}
With newer versions, \gls is now robust. However, it’s generally not a good idea to use commands like \gls or \glslink (or \acrshort etc) in chapter or section titles:
  1. If you have a table of contents, the relevant line in the TOC will also have a link to the glossary, and the entry’s page list will include the table of contents page. (Same applies for \caption and the list of figures/tables.)
  2. If you are using a page style that adds the chapter/section title to the page header, then each page header for that section will generate a link to the glossary.
  3. If you are using the hyperref package, you will have a nested link in the table of contents and you will also cause a problem for the bookmarks.
It is therefore better to use the non-link creating commands, such as \glsentryname instead of \gls. For example: 
\section{\glsentryname{sample}}
Alternatively, if you extend the glossaries package with glossaries-extra then you can use one of the commands listed in the section Entries in Sectioning Titles, Headers and Contents of the glossaries-extra user manual. For example: 
\section{\glsfmttext{sample}}
but check the advisory notes in the manual.

If you don’t want to use glossaries-extra and you really want \gls in your chapter/section title, then use the optional argument to supply an alternative for the table of contents and page headers: 

\section[\glsentryname{sample}]{\gls{sample}}
The same applies for captions. For versions prior to v4.0, if you get unexpected output in your page headers (e.g. something like ACRONYMNAME SAMPLE), then use the package option sanitize=none and protect fragile commands.

Note that prior to version 4.0, the commands that convert the first letter to upper case were all fragile and so required \protect: 

\section{\protect\Glsentryname{sample}}
If you use the hyperref package, you’ll need to use \texorpdfstring: 
\section{\texorpdfstring{\protect\Glsentryname{sample}}{Sample}}
For version 4.0 and above, you don’t need \protect, but you still need to provide an alternative for the PDF bookmarks: 
\section{\texorpdfstring{\Glsentryname{sample}}{Sample}}

2022-11-02 11:13:42

Top

I get the message “Token not allowed in a PDF string (PDFDocEncoding)” 🔗

Example warning:

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding): (hyperref) removing `\Glsentrytext'
This is a warning from the hyperref package not an error. As mentioned in Using Glossary Terms Without Links, you can’t use non-expandable commands in PDF bookmarks. The command is ignored (hyperref tells you this in the “removing `\Glsentrytext'” part of the warning) so you end up with just the expandable part (the label) in the bookmark. Remember that, as stated in the user manual, the commands that convert the first letter to upper case are non-expandable and therefore can’t be used in the bookmarks. Use \texorpdfstring to provide alternative text for the bookmark or you can use hyperref’s \pdfstringdefDisableCommands to temporarily disable the command while the bookmark is written. (See the hyperref manual for further details.)

Note that the glossaries-extra package provides commands designed for use within chapter or section headings. (See the section New Commands Designed for Chapter/Section Headings in the user manual.) These commands use \texorpdfstring for the PDF bookmarks (but no case-changing will be applied for the PDF text).

2022-11-02 11:13:28

Top

I get an error saying that \glspagewidthlist is undefined 🔗

This was fixed in v1.18.

2020-07-01 11:10:17

Top

I get an error saying that \glossarymark is already defined 🔗

As from version 2.03, the glossaries package checks to see if \glossarymark is already defined, and now just prints a warning message that \glossarymark is being redefined.

As from version 4.0, \glossarymark has been replaced by \glsglossarymark to avoid conflict with memoir.

2020-07-01 11:09:41

Top

I get the error: “no room for a new \write” 🔗

TeX has a limited number of write registers. If you exceed this number, you will get this error. The glossaries package by default assigns a new write register for the .ist / .xdy file and one new register per glossary. Other packages also assign new write registers, so if you load a lot of packages that write to external files, you may end up with this error.

You can reduced the number of write registers by one if you ensure you define all your entries in the preamble instead of in the document environment. You can also reduce the write registers if you use the savewrites package option. However this will slow down the document build and the locations can be incorrect.

As from version 4.04, the write register used for the .ist / .xdy is only defined if \makeglossaries is used. If you use \makenoidxglossaries no write registers will be created by glossaries. (However, this is a much slower approach than using \makeglossaries.)

If the above doesn’t help, the simplest solution is to use the scrwfile package (comes with the KOMA-Script bundle). 

\usepackage{scrwfile}
Alternative solutions and a more detailed explanation of the problem are given in my answer on TeX.SX.

Note that if you switch to glossaries-extra and bib2gls, no new write registers are required as all indexing information is written to the .aux file.

2020-07-01 11:11:13

Top

When I use savewrites I get an error that \glswritefiles is undefined 🔗

This has been fixed in version 4.03.

2020-07-01 11:11:30

Top

! LaTeX Error: Something's wrong--perhaps a missing \item 🔗

Check if your log file contains the message:

Package glossaries Warning: Deprecated use of \glossaryentryfield. I recommend you change to \glossentry. If you've just upgraded, try removing your gls auxiliary files and recompile
If so, follow the above instructions, remove all the temporary glossary files (.gls etc) and try recompiling.

2020-07-01 11:12:11

Top

glossaries “noidx” commands break with datatool-base v2.26 🔗

Upgrade to at least v2.27 (2016-07-28) of datatool.

2020-07-01 11:12:29

Top

I get a “missing }” error with v1.17 when using babel with the glossaries package 🔗

This was fixed in v1.18.

2020-07-01 11:00:13

Top

I get an error using glossaries with a new version of babel 🔗

Please upgrade to the latest versions of glossaries and tracklang.

2020-07-01 11:08:57

Top

I get an error when using glossaries with fancyhdr 🔗

This is a problem with xfor v1.04. You need to upgrade to at least xfor v1.05.

2020-07-01 11:00:30

Top

I get the error “! Argument of \hyper@link has an extra }”. 🔗

This was a problem with hyperref rather than glossaries. It was fixed in hyperref 6.83g.

2020-07-01 11:00:42

Top

I get the error “File `datatool-base.sty' not found” after updating glossaries 🔗

Upgrade the datatool package.

2020-07-01 11:00:48

Top

mfirstuc.sty not found 🔗

The mfirstuc package has been split from glossaries so they are now two separate bundles and both need to be installed in order to use glossaries. This needs to be done using your TeX distribution update manager. If you have any problems with your update manager you'll need to contact the support for your TeX distribution.

The reason for the split is that mfirstuc is a useful package in its own right and can be used without glossaries. It’s also much easier to maintain as a standalone package, rather than as part of a much larger bundle. Additionally, mfirstuc has a separate version number from glossaries and already had its own entry in the CTAN catalogue, which caused complications to the CTAN upload.

2020-07-04 11:10:32

Top

Undefined control sequence \DeclareRelease 🔗

You are using a very old LaTeX kernel (2017 or earlier) with a much newer (2021 onwards) version of glossaries that provides rollback. The best solution is to install an up-to-date TeX distribution. If that isn’t possible you can add: 

\providecommand{\DeclareRelease}[3]{}
\providecommand{\DeclareCurrentRelease}[2]{}
to the start of your document. However, bear in mind that if you mix new packages with significantly older TeX distributions you could encounter other incompatibilities.

2021-10-06 09:20:18

Top

Indexing Application Errors

I get the error: “perl not found” or “The Perl interpreter could not be found” when I use makeglossaries on Windows 🔗

You don’t have Perl installed or your path is not set up correctly. Note that TeX Live on Windows comes with its own internal Perl interpreter so makeglossaries.exe should run on TeX Live. If you are using MikTeX have a look at MiKTeX and Perl Scripts.

If the above doesn’t help or for some reason you don’t want to install Perl, you can run makeindex on each of your glossaries. For example, to create the main glossary (assuming your file is called myfile.tex): 

makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo
If you have used the acronym package option, you will need to create the list of acronyms file as follows: 
makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acn
Repeat this procedure for each glossary that you have defined.

Alternatively you could try using the MakeGlossariesGUI Java application. Note that xindy is also a Perl script, so if you don’t have Perl you're stuck with just makeindex.

2020-07-01 11:05:19

Top

makeindex complains that the entry is too long 🔗

As from glossaries version 4.0, this should no longer be an issue. For earlier versions, if you have a very long description, it is possible that you may exceed makeindex’s buffer. In which case, try defining a command that stores the long description, and use that when you define the entry. For example: 

\newcommand{\mylongdescription}{A very long description}
\newglossaryentry{example}{name={example},
description={\mylongdescription}}
For pre v4.0: note that if you’ve used sanitize=description=false (which automatically occurs with certain acronym styles), then you need to use \protect: 
\newcommand{\mylongdescription}{A very long description}
\newglossaryentry{example}{name={example},
description={\protect\mylongdescription}}
Alternative, try using xindy instead of makeindex. See the section on xindy in the glossaries documentation.

2020-07-01 11:05:25

Top

I get the xindy error “PROGN: variable FILENAME.XDY has no value” 🔗

This seems to be a bug that’s appeared in a new release of xindy and is therefore out of my control. (See [tex-live] xindy with "-I xindy" broke with the latest update on linux for a fix.)

2020-07-01 12:21:38

Top

makeglossaries can’t find the style file when file name has spaces 🔗

More detailed description of problem: You are using MiKTeX, your .tex file has spaces in it (for example, “my doc.tex”) and you run 

makeglossaries "my doc"
but makeglossaries reads the style name as my*doc.ist. (That is, the space has been replaced with an asterisk.)

This is caused by MiKTeX bug #2301.

Workarounds:

  1. Remove the spaces in your file name. (Optimal solution.)
  2. Upgrade to at least makeglossaries version 2.13 (glossaries version 4.03 and above).

2020-07-01 12:22:04

Top

What does makeglossaries mean by “Unable to fork [...] Retrying without redirection”? 🔗

When makeglossaries tries to run makeindex or xindy, its preferred method of running the process is to use piped redirection (using 2>&1 | ). This enables makeglossaries to read both the standard output and standard error streams. There are two reasons for doing this:

  1. makeglossaries can pick up messages that don’t get written to the transcript file;
  2. the -q option works correctly.
Unfortunately not all operating systems support this method of running a process. In which case, makeglossaries prints this warning and retries using a platform independent method instead. This means the -q switch won’t be as effective and, if something goes wrong, makeglossaries has less information available to determine the cause.

If all goes well and you’re not bothered about the -q setting, then you don’t need to worry about it. As from makeglossaries version 2.14 (distributed with glossaries version 4.04), you can suppress this warning using the -Q switch. Alternatively you can use the new -k switch to prevent makeglossaries from attempting the piped redirection and it will just use the platform-independent method.

2020-07-01 12:22:36

Top

What does the xindy error “CHAR: index 0 should be less than the length of the string” mean? 🔗

xindy discards all commands and braces from the sort string. If your sort string (either specified explicitly by the sort key or implicitly by the name key) only consists of commands, this will be treated by xindy as an empty sort string, which produces an error message in newer versions of xindy. For example, the following will cause a problem: 

\newglossaryentry{alpha}{name={\ensuremath{\alpha}},  
  description={...}}
Either use a different sort key for the entry, for example: 
\newglossaryentry{alpha}{sort=alpha,  
  name={\ensuremath{\alpha}},  
  description={...}}
or, if all entries are like this, you may prefer to use the sort=use or sort=def package options. See the Sorting Options section of the user manual for further details of the sort option.

If you are using glossaries-extra, the symbols package option will provide the command \glsxtrnewsymbol[options]{label}{symbol}. The definition is simply: 

\newglossaryentry{label}{name={symbol},
 sort={label},type=symbols,category=symbol,options}

This assigns the sort key to the label (unless explicitly overridden in options). This will avoid the problem (although you need to consider whether or not the label is an appropriate sort value). There is a similar command associated with the numbers package option.

You might also want to consider switching to bib2gls, which has a limited understanding of some LaTeX commands. For example, if the entry is defined as: 

@entry{alpha,
  name={\ensuremath{\alpha}},
  description={...}
}

Then the default sort value will be 𝛼 (mathematical alpha, Unicode value U+1D6FC). Alternatively, if the entry is defined as: 

@symbol{alpha,
  name={\ensuremath{\alpha}},
  description={...}
}

Then the sort value will default to the label (analogous to \glsxtrnewsymbol). See also Gallery (bib2gls): sorting.

2020-07-01 12:23:02

Top

Perl error “Unescaped left brace in regex is illegal here in regex” 🔗

If you get this message from the Perl interpreter when you run makeglossaries you have an out of date version of makeglossaries. Update your glossaries installation.

2020-07-01 12:23:51

Top

Translating Fixed Names

I’ve used the babel/polyglossia package, but the fixed names haven’t been translated. 🔗

As from version 4.12, the language support has been split off into separate independently-maintained modules. For example, glossaries-french. The required language module needs to be installed in addition to installing/updating glossaries. Note that not all languages are supported. See the section “Creating a New Language Module” in the user manual for guidance if you want to create a new language module.

2020-07-01 12:28:23

Top

How do I change the default translations provided by the glossaries package? 🔗

The glossaries package uses tracklang to detect the document languages. If you want to have the fixed names (such as “Glossary” and “Acronyms”) translated, you will need to install the associated glossaries language package, such as glossaries-french.

If you load the babel package before, by default the translator package will be loaded by the glossaries package. You then need to use the translator package’s interface to change the fixed names. Alternatively, use the glossaries package option translate=babel which will load glossaries-babel.sty instead. You can then use babel’s interface to change the fixed names. If you are using polyglossia, the glossaries will load glossaries-polyglossia.sty and you need to use polyglossia’s interface to change the fixed names. See the section Multi-Lingual Support in the glossaries user manual for further details.

Note that glossaries-extra automatically implements translate=babel if babel has been loaded. (That is, it doesn’t use the translator package by default.)

If you have any queries regarding the babel, polyglossia or translator packages, please address them to the authors of those packages (after first checking the TeX FAQ and comp.text.tex archives).

Related: tracklang package and Localisation with tracklang.tex.

2020-07-01 12:30:50

Top

Unexpected Output

Unexpected Output in the Main Document Text

When I display an entry’s description using \glsentrydesc it doesn’t come out right 🔗

This should no longer be an issue with glossaries version 4.0. For older versions, if your description contains commands, you will have to switch off the sanitization for the description, using the package option sanitize={description=false}. You must then protect any fragile commands using \protect.

2020-06-28 16:12:03

Top

When I display an entry’s symbol using \glsentrysymbol it doesn’t come out right 🔗

This should no longer be an issue with glossaries version 4.0. For earlier versions, you will have to switch off the sanitization for the symbol, using the package option sanitize={symbol=false}. You must then protect any fragile commands using \protect.

If you need to do the same for the description, you will need to use the package option sanitize={description=false,symbol=false}.

2020-07-01 12:31:16

Top

I’ve used the smallcaps/smaller option but the long form in the list of acronyms is always the long form of the last defined acronym 🔗

This has been fixed in version 1.15. Earlier versions can fix this by using the package option sanitize={description=false}.

2020-07-01 12:31:40

Top

\Gls doesn’t work with the smaller option (everything is converted to uppercase) 🔗

Redefine \acronymfont to use \textsmaller instead of \smaller: 

\renewcommand{\acronymfont}[1]{\textsmaller{#1}}
This has been fixed in version 1.19.

Note that if your acronym starts with a capital letter, \Gls will produce the same text as \gls.

2020-07-01 12:32:04

Top

\Gls doesn’t work when \acronymfont uses a declaration 🔗

This is similar to \Gls doesn’t work with the smaller option (everything is converted to uppercase) . Using a declaration instead of a text block command confuses \makefirstuc. So use a text block command instead. If there is no text block equivalent, you will have to define one. For example: 

\newcommand{\textlarge}[1]{{\large #1}}
\renewcommand{\acronymfont}[1]{\textlarge{#1}}

2020-06-29 10:53:53

Top

I’ve used the smallcaps option, but the acronyms are displayed in normal sized upper case letters. 🔗

The smallcaps package option (or the sc acronym styles, such as long-sc-short) uses \textsc to typeset the acronyms. This command converts lower case letters to small capitals, while upper case letters remain their usual size. Therefore you need to specify the acronym in lower case letters.

If you prefer to keep upper case letters in your entry definitions, you could redefine \acronymfont so that it converts the letters to lower case. For example: 

\renewcommand{\acronymfont}[1]{\textsc{\MakeLowercase{#1}}}

Alternatively, consider using the “smaller” (sm) styles instead.

Note that if you are using glossaries-extra, the \acronymfont command isn’t used by the abbreviation styles. In this case, the sc styles use \glsxtrscfont, so that’s the command that will need changing. Note that if you are using bib2gls, you can instruct bib2gls to perform the case-conversion instead (see the short-case-change resource option).

2020-07-01 13:21:54

Top

The long form of acronyms won’t break across a line 🔗

This can occur when you are using hyperref and [DVI]latex (rather than pdflatex) which won’t break a hyperlink across a line. Either use pdflatex or you can suppress the hyperlink on first use (see How do I suppress the hyperlink for the first use just for acronyms?).

2020-07-01 13:23:04

Top

Acronyms are displayed as “acronymfont” followed by the label in certain situations (such as page headers) 🔗

This should no longer be an issue with glossaries version 4.0. For earlier versions, use the package option sanitize=none and protect fragile commands in acronym and glossary definitions.

2020-07-01 13:22:46

Top

I changed the definition of an entry, but it’s still using the old definition 🔗

This can occur if you define your entries in the document environment instead of in the preamble. (See the section Technical Issues in the user guide.) Try removing the .glsdefs file and rerun.

2020-07-01 13:22:35

Top

Unexpected Output in the Glossaries

One or more of my glossaries haven’t appeared 🔗

Check the following:

  1. You have used \makeglossaries in the preamble.
  2. You have used either \printglossaries or \printglossary at the point in the document where you want the glossary to appear. Remember that if you have multiple glossaries and you use \printglossary, you must specify the glossary name in the optional argument for the additional glossaries (this includes the list of acronyms when you have used the acronym option). The name is not required for the main glossary.
  3. Make sure you have used one or more of: \glslink, \glsdisp, \glsadd, \glsaddall, \gls or \glspl (or the uppercase variants).
  4. Remember that once you have saved your .tex file, you must follow the three step process:
    1. latex filename

      This creates the .glo file that contains the glossary information for makeindex to collate, but there is no glossary in the document yet. Any hyperlinks to glossary entries will be undefined because the glossary doesn’t exist yet.

    2. makeglossaries filename

      Note there is no extension — makeglossaries reads filename.aux to determine the relevant glossary information, but passes filename.glo to makeindex, which in turn creates filename.gls which contains the glossary.

    3. latex filename

      This reads filename.gls (created in the previous step). The document should now contain the glossary, and the hyperlinks to glossary entries should now be defined. If not, check the makeindex transcript file (filename.glg) for errors.

    If you don’t have Perl installed or are otherwise unable to run makeglossaries, you can run makeindex on each of your glossaries. (See Do I have to use makeglossaries?) For example, to create the main glossary (assuming your file is called myfile.tex): 
    makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo
    If you have used the acronym package option, you will need to create the list of acronyms file as follows: 
    makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acn
    Repeat this procedure for each glossary that you have defined.

See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

2020-06-28 15:58:15

Top

All my glossary entries have appeared in the same glossary instead of in separate glossaries 🔗

If you are using makeindex directly instead of via makeglossaries, you must remember to call makeindex separately for each glossary. For example, if you have both a main glossary and a list of acronyms you will need to do (assuming your file is called myfile.tex): 

makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo
makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acn
If you have Perl installed, I would strongly recommend that you use makeglossaries instead, as then all you need do is: 
makeglossaries myfile
which significantly reduces the chance of errors.

Also try checking the makeindex transcript files to see if there were any errors in the makeindex run.

See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

2020-06-27 14:20:26

Top

Entries that appear in the first paragraph of a page have the wrong page number in the glossary 🔗

If you’re not using savewrites, this problem has been fixed in version 1.07.

If you are using savewrites, this issue is an unfortunate shortcoming of the method employed by this setting due to TeX’s asynchronous output routine. If you need a number list in your glossary and this issue is causing a problem, remove the savewrites option. If you have a problem of too many write registers, consider switching to bib2gls, which doesn’t require any write registers (since it uses the .aux file for the indexing information and doesn’t require an associated style file). See also: I get the error: “no room for a new \write”.

2020-07-01 12:40:34

Top

Why have numbers appeared after my glossary entries? 🔗

These are the page numbers on which that glossary entry has been used. You can suppress the number list using the package option nonumberlist.

2013-12-08 16:39:19

Top

Why have my glossary terms appeared in bold in the glossary? 🔗

The most likely reason is that you are using one of the list-type glossary styles which put the term in the optional argument of \item which sets its argument in bold. The tree-like glossary styles also make the term bold. You can override this by redefining \glsnamefont. For example: 

\renewcommand{\glsnamefont}[1]{\mdseries #1}

2020-06-27 14:21:41

Top

I have used the smallcaps option, but the entry names appear in lowercase bold in the glossary 🔗

See Why have my glossary terms appeared in bold in the glossary? for the reason why the entry is in bold. It is most likely in lowercase because you are using a set of fonts that don’t support bold small caps, so the closest match has been used instead. Try using a different font encoding. For example: 

\usepackage[T1]{fontenc}
Or change \glsnamefont to use a medium weight font instead of bold.

2020-06-28 16:17:27

Top

Why is there a larger vertical gap between some glossary entries? 🔗

When using makeindex, the glossary is divided into 28 groups corresponding to the initial character: symbols, digits, a, …, z. When using xindy, the groups may be different if you’re using an extended Latin alphabet (which may have additional groups) or a non-Latin alphabet (which won’t have the Latin letters). With xindy, the digit group can be omitted with xindy={glsnumbers=false}.

Each group is separated by \glsgroupskip which is set to \indexspace when using one of the list styles or is set to a blank row when using one of the tabular styles. This can be suppressed by using the package option nogroupskip or by redefining \glsgroupskip to do nothing: 

\renewcommand{\glsgroupskip}{}
However note that \glsgroupskip is redefined each time the glossary style is changed, so make sure you either redefine it after you set the glossary style or define your own custom glossary style.

Note that the tabular-like styles (such as long and super) need to test the nogroupskip option while defining \glsgroupskip (rather than having the test within \glsgroupskip). This is due to the problems caused by conditionals within tabular-like contexts.

2020-06-27 14:36:38

Top

When I use the hyperlink to take me to an entry in the glossary, the relevant line is just above the top edge of the viewer. 🔗

As from glossaries v1.16, this shouldn’t occur. For earlier versions use: 

\newlength\mylen
\makeatletter
\renewcommand{\@glstarget}[2]{%
\settoheight{\mylen}{#2}\raisebox{\mylen}{\hypertarget{#1}{}}#2}
\makeatother
(\@glstarget is an internal command, so it should go between \makeatletter and \makeatother in the .tex file. If you put the above code into a style file, remember to remove the \makeatletter and \makeatother commands.)

Note that this pre-v1.16 fix is only required for the glossary styles that use lists.

2020-06-27 14:38:49

Top

I redefined one or more of the commands governing the glossary style, but it hasn’t had an effect 🔗

Remember that these commands are overridden whenever \setglossarystyle is used (or \glossarystyle for versions prior to v4.0), so make sure the new definitions are placed after \setglossarystyle. In particular, remember that if you use the style key in the optional argument of \printglossary, it will override any previous definitions.

In general, it’s best to define a custom style that’s based on the required one with the necessary modifications. Alternatively, consider using glossaries-extra with the stylemods option (which automatically loads glossaries-extra-stylemods.sty), which provides additional hooks to make it easier to customise the styles. With the glossaries-extra package, you can also use hooks, such as the post-description category hook, to make minor adjustments, and there are additional styles, which may suit your requirements.

2020-06-27 14:44:12

Top

I’ve redefined \acronymfont but the acronyms are still displayed in the surrounding font. 🔗

For v4.02 onwards: set the acronym style to one of the predefined styles via \setacronymstyle and then redefine \acronymfont as required.

For pre version 4.02: \acronymfont is only used by the package options that redefine \newacronym (e.g. description, smallcaps, footnote). Try using the smaller package option and redefine \acronymfont in the preamble.

If you are using glossaries-extra, the abbreviation styles don’t use \acronymfont. You will need to adjust the command provided by the particular style instead. For example, the sc styles all use \glsxtrscfont to format the short form.

2020-06-28 16:19:11

Top

Glossary terms at the start of a cell in tabularx don’t align properly on the row 🔗

This has been fixed in version 2.03.

2020-06-28 16:19:54

Top

I deleted an entry but it’s still showing up in the glossary 🔗

Try removing the associated .gls etc files (including .glsdefs, if present) and then rebuild your document.

2020-06-28 12:45:16

Top

Page break occurs after a group title 🔗

The base glossaries package provides fairly simple glossary styles. With these it is possible for page breaks to occur after group headings. If you are using the glossaries-extra extension then make sure you use the glossaries-extra-stylemods package identifying the style package (or packages) that needs patching. The simplest way of doing this is to use the stylemods package option. The following test document uses the testidx package to generate a dummy document: 

\documentclass{article}

\usepackage[a4paper,margin=1in]{geometry}
\usepackage[T1]{fontenc}
\usepackage{glossaries}
\usepackage{glossary-mcols}% provides the 'mcol' styles
\usepackage[notestencaps,ascii]{testidx-glossaries}

\tstidxmakegloss % uses \makeglossaries and loads definition files

\begin{document}
\tstidxprintglossary[style=mcolindexgroup]

\testidx
\end{document}
This demonstrates the problem with the mcolindexgroup style when just using the base glossaries package. There's a page break between the title for the “G“ group and the first item in that group. Similarly for the “L” and “V” letter groups. Switching to the glossaries-extra package and using the glossaries-extra-stylemods package to patch the styles provided by the base package solves the problem: 
\documentclass{article}

\usepackage[a4paper,margin=1in]{geometry}
\usepackage[T1]{fontenc}
\usepackage[stylemods=mcols]{glossaries-extra}
\usepackage[notestencaps,ascii]{testidx-glossaries}

\tstidxmakegloss

\begin{document}
\tstidxprintglossary[style=mcolindexgroup]

\testidx
\end{document}
Note that the style package must be either loaded through the glossaries-extra-stylemods package or loaded before glossaries-extra-stylemods. For example, any of the following will work: Loading implicitly through the stylemods option: 
\usepackage[stylemods=mcols]{glossaries-extra}
Loading the glossaries-extra-stylemods package explicitly and identifying any supplementary style packages that need to be loaded: 
\usepackage{glossaries-extra}
\usepackage[mcols]{glossaries-extra-stylemods}
Loading the required style package before loading glossaries-extra-stylemods: 
\usepackage{glossaries-extra}
\usepackage{glossary-mcols}
\usepackage{glossaries-extra-stylemods}
The base glossaries package automatically loads the long, super, list and tree style packages. If these are the only styles you require then you can simply do: 
\usepackage[stylemods]{glossaries-extra}
If you want to prevent any unnecessary style packages from being loaded and only load required ones, then use nostyles in combination with stylemods. For example: 
\usepackage[nostyles,stylemods={mcols,longextra}]{glossaries-extra}
Any styles loaded after glossaries-extra-stylemods won't be patched. If you don't want to switch to the extension package but prefer to stick with just the base package, then you can provide your own patch. For example, to patch the treegroup style (which will affect any style that uses it, such as mcoltreegroup): 
\renewglossarystyle{treegroup}{%
  \setglossarystyle{tree}%
  \renewcommand{\glsgroupheading}[1]{\par
    \noindent\glstreegroupheaderfmt{\glsgetgrouptitle{##1}}\par
    \nopagebreak\indexspace\nobreak\@afterheader}%
}
If you patch a style remember to remove the patch if you switch over to glossaries-extra and glossaries-extra-stylemods otherwise you'll lose the benefit of the style modifications provided by the extension package.

2020-02-07 14:36:29

Top

A spurious comma appears in the number list 🔗

This usually occurs because there’s a location in the list with a format (such as glsignore or, with glossaries-extra, glsxtrunusedformat) that doesn’t display anything. From makeindex and xindy’s point of view, this is just another formatted location.

The glsignore format is used by \glsaddallunused which iterates over all entries and, for any entry that is marked as unused, it will do \gls[format=glsignore]{label}. This ensures that the entry is indexed (and therefore is listed in the glossary) but the page number is typically not wanted. If this is the only time the given entry is indexed, then it will have a location list that consists of a single, invisible location.

The spurious comma in the location list is usually the result of placing \glsaddallunused too early or after a reset (e.g. \glsresetall) or when an entry has only been used by commands that don’t unset the first use flag. If your document contains \glsaddallunused:

Note that bib2gls recognises glsignore as indicating an “ignored location”. This means the entry will be selected but that location will be discarded, which avoids this problem. (However, you can’t use \glsaddallunused with bib2gls. Use the selection=all resource option instead.) For example, at the start of your back matter, you can do (with glossaries-extra): 

\GlsXtrSetDefaultNumberFormat{glsignore}

This will ensure that any entries in the back matter are selected by bib2gls but their locations won’t be added to the location lists. This approach can’t be used with makeindex or xindy as it will result in the location list including invisible locations separated by visible commas or dashes.

2020-07-02 12:25:11

Top

Table of contents pages have appeared in the locations lists for one or more glossary entries 🔗

This is typically caused by using a command such as \gls in a chapter/section command. The command is copied to the table of contents, which causes the entry to be indexed in the contents. See Why shouldn’t I use commands like \gls in \section, \chapter, \caption etc?

2020-07-01 14:09:28

Top

\glssee at the end of the document doesn’t work if there’s no text on the final page. 🔗

For example: 

\documentclass{article}

\usepackage{glossaries}

\makeglossaries
\newglossaryentry{sample1}{name={sample1},description={a test}}
\newglossaryentry{sample2}{name={sample2},description={a test}}

\begin{document}
\gls{sample2}
\printglossaries
\newpage
\glssee{sample1}{sample2}
\end{document}
This is due to the delayed write, which is lost because there’s no content on the final page. The delayed write (rather than an immediate write) is necessary to ensure that the page number is correct. The same problem occurs with \label and \index (and anything else that similarly uses a delayed write without producing any content on the page). For example: 
\documentclass{article}

\begin{document}
Test\newpage
\label{test-label}
\end{document}
Note that (as from v4.12) this doesn’t occur with \glsadd, which additionally inserts empty content, so if the document is changed to: 
\documentclass{article}

\usepackage{glossaries}

\makeglossaries
\newglossaryentry{sample1}{name={sample1},description={a test}}
\newglossaryentry{sample2}{name={sample2},description={a test}}

\begin{document}
\gls{sample2}
\printglossaries
\newpage
\glsadd{sample1}
\end{document}
Then the indexing does work and you will end up with a two-paged document.

This example is a bit contrived as there’s no benefit in the \newpage. If you actually want a blank page 2 then you’d need some empty content following the page break and the problem would go away. However a similar situation can occur if the final page of a document consists solely of floating content. (It was for this reason that \glsadd was modified in v4.12 to switch to horizontal mode unless it occurs in the preamble.)

Since \glssee doesn’t depend on the page number, the simplest solution is to move it to the preamble.

2021-09-20 20:57:59

Top

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

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

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

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

\documentclass{report}
\usepackage{glossaries}

\makeglossaries
\newglossaryentry{sample}{name={sample},description={an example}}
\begin{document}
\pagenumbering{Roman}\gls{sample}
\newpage
\pagenumbering{arabic}\gls{sample}
\newpage
\pagenumbering{roman}\gls{sample}
\printglossaries
\end{document}
According to makeindex's default page precedence this should result in the list: i, 1, I, which is the case with TeX Live 2022. However, with TeX Live 2021, the result is i, I, 1.

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

\documentclass{report}
\usepackage{glossaries}

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

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

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

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

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

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

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

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

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

\documentclass{report}
\usepackage{glossaries}

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

\GlsXtrLoadResources

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

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

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

\makeglossaries
\loadglsentries{example-glossaries-symbolnames}

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

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

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

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

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

\newpage
\gls{sym.alpha}

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

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

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

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

If you use makeindex directly: 

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

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

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

\GlsAddXdyCounters{equation}

\makeglossaries
\loadglsentries{example-glossaries-symbolnames}

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

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

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

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

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

\newpage
\gls{sym.alpha}

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

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

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

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

\makenoidxglossaries
\loadglsentries{example-glossaries-symbolnames}

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

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

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

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

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

\newpage
\gls{sym.alpha}

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

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

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

\GlsXtrLoadResources[src=example-glossaries-symbolnames]

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

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

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

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

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

\newpage
\gls{sym.alpha}

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

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

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

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

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

2022-08-01 20:53:27

Top

Unexpected Output in Table of Contents

The glossary entry in the TOC is not aligned with the numbered chapter/section titles 🔗

By default, the glossary entry in the table of contents is aligned with the chapter/section numbers. As from version 1.1, you can use the package option numberline (in addition to the toc option) to align the title with the other TOC titles.

If you are using an older version, you can achieve the same effect by redefining \@gls@toc: 

\renewcommand*{\@gls@toc}[2]{%
\ifglstoc\addcontentsline{toc}{#2}{\numberline{}#1}\fi}
Note that this contains internal commands (commands that have an @ character in the name) so it either needs to go in a style file or it must be placed within \makeatletter and \makeatother in a .tex file.

2020-06-27 14:59:44

Top

The glossaries haven’t appeared in the table of contents 🔗

Remember to use the toc package option and to re-run LaTeX. Note that this option is the default for glossaries-extra but not for just the base glossaries package.

2020-06-28 16:20:29

Top

Commands such as \Glsentrytext only display their label in the PDF bookmark 🔗

See I get the message “Token not allowed in a PDF string (PDFDocEncoding)”.

2020-06-28 16:20:58

Top

The full form of an acronym is showing in the table of contents but not on first use or the corresponding chapter/section title 🔗

This is typically caused by using a command such as \gls in a chapter/section command. The command is copied to the table of contents, which means that the first use of the entry is in the contents not in the main matter. Why shouldn’t I use commands like \gls in \section, \chapter, \caption etc?

2020-07-01 14:12:21

Top

General Queries

Defining Terms

Is it possible for an entry to have a name and an associated symbol? 🔗

Yes, just use the name key for the term and the symbol key for the symbol. See Gallery: Units (glossaries.sty) for an example. If you want the symbol to also appear in the text when you use commands such as \gls, then you can redefine \glsentryfmt or use \defglsentryfmt (those two commands are new to version 4.0).

With glossaries-extra, it’s possible to use the post-link hook to automatically append the symbol, which is simpler than redefining \glsentryfmt. See Gallery: Units (glossaries-extra.sty) for an example.

2020-06-27 15:25:24

Top

My term has multiple plural forms, how can I deal with this? 🔗

Use the plural key for the plural term you are most likely to use, and use one of the user keys for the other plurals. For example: 

\newglossaryentry{cow}{name=cow,
  description={a fully grown female of any bovine animal (plural
cows, archaic plural kine)},
  user1={kine}}

\let\glsaltpl\glsuseri
You can now use \glspl for the first plural and \glsaltpl for the second plural. There are six user keys, so this method can be used for other grammatical constructs as well. As from version 4.0, you can also define your own keys via \glsaddkey. See the section Additional Keys in the user manual for further details.

2020-06-27 15:27:58

Top

How do I define different grammatical parts for an entry? 🔗

As with My term has multiple plural forms, how can I deal with this? you can use one of the user keys (such as user1) or you can define your own key. However, this can lead to a large number of extra keys. You may find it easier to simply use \glsdisp or \glslink. For example, with the following definition: 

\newglossaryentry{run}{name=run,description={...}}

Then you can do: 

I \glsdisp{run}{ran} to the shops. They are \glsdisp{ran}{running} to catch the bus.

2020-07-01 12:55:07

Top

How do I cross-reference entries? 🔗

As from v1.17, you can use \glssee or use the see key when you define the entry. Note that the see key is just a convenient shortcut that implements \glssee. For example: 

\newglossaryentry{cross-product}{name={cross product},description={\nopostdesc},see={vector-product}}

is equivalent to 

\newglossaryentry{cross-product}{name={cross product},description={\nopostdesc}}
\glssee{cross-product}{vector-product}

See the section Cross-Referencing Entries in the manual for further details.

2020-07-01 12:54:15

Top

Why does the see key automatically index the entry? 🔗

As mentioned in the user manual, the see key automatically implements \glssee because the see key was added as a simple shortcut for \glssee. With the base glossaries package, that’s all this key does. The value isn’t even saved. With the glossaries-extra package, the value is saved but its intended purpose is still a shortcut for \glssee.

The same feature applies to the seealso and alias cross-referencing keys provided by glossaries-extra. In the case of the alias key, this both indexes and adjusts the hyperlink target. The indexing for seealso is implemented with \glsxtrindexseealso instead of \glssee, but these commands work in a similar way.

For example, suppose you have a document about (mathematical) vectors and you want the glossary to contain the term “vector product”. This can be defined as follows:

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

Let’s suppose that in the document you only want to use this particular term for this kind of product, so you use \gls{vector-product}. However, this type of product is also known as a “cross product”, and it’s possible that your reader may try looking up the term by that name in the glossary, so it’s useful to provide a redirect:

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}
\glssee{cross-product}{vector-product}

This term isn’t used anywhere else in the document. It’s simply provided as a redirect. This is quite cumbersome, so when \glssee was added to glossaries.sty version 1.17 (2008-12-26), the see key was also provided at the same time as a convenient shortcut:

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc},
 see={vector-product}}

This catches out users who define an entry with the see key set but don’t actually want the entry in the document.

Note that this need to index the entry in order to add the cross-reference to the glossary is a quirk of the indexing applications. Makeindex treats “see” style references in the same way as normal indexing. The location formatting command (encap) simply discards the location number and inserts the “see …” text. Xindy has a slightly different syntax for cross-references but code still needs to be added to the file parsed by xindy which will add the entry to the output file (the glossary file input by \printglossary in this case).

So what do you do if you want a large database of terms that’s shared across multiple documents? The best solution is to switch to using bib2gls. This is the most efficient method in terms of overall document build time (see the 3. Alphabetical Order (Subset) section of the glossaries performance page). It’s also the best method in terms of managing the database (since a .bib management system, such as JabRef, can be used). The bib2gls resource option selection criteria can be used to determine whether or not to select cross-referenced entries.

If you don’t want to switch to bib2gls then there are other options:

  1. Don’t use the see key. Use \glssee explicitly where required. For example, if the following terms have been defined: 
    \newglossaryentry{dot-product}{name={dot product},
 description={...}}

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}
    then later in the document: 
    The \gls{vector-product}\glssee{cross-product}{vector-product}\glssee[see also]{vector-product}{dot-product} is...

...

The \gls{dot-product}\glssee[see also]{dot-product}{vector-product}...

    This gives you greater control over exactly which cross-references are used on a per-document basis.

    In the case of the alias key provided by glossaries-extra, you can set the alias field after defining the entry to enable the hyperlink target substitution without triggering the automatic indexing: 

    \newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc}}
\GlsXtrSetField{cross-product}{alias}{dot-product}
  2. The glossaries-extra package provides the boolean package option autoseeindex. If true, the see key will automatically index the entry with \glssee (as per the base glossaries package). With glossaries-extra, this option may be set to false to prevent the automatic indexing. If you use this setting, you will need to find some other way of using \glssee if you actually want the cross-reference to appear in the glossary. This option also governs the automatic indexing of seealso and alias. For example, consider the following document: 
    \documentclass{article}
\usepackage[autoseeindex=false]{glossaries-extra}

\makeglossaries

\newglossaryentry{dot-product}{name={dot product},
 description={...}}

\newglossaryentry{vector-product}{name={vector product},
 description={...}}

\newglossaryentry{cross-product}{name={cross product},
 description={\nopostdesc},see={vector-product}}

\begin{document}
The \gls{dot-product}...

\printglossaries
\end{document}

    In this case the glossary will only contain the “dot product” entry. Again, you need to explicitly use \glssee to add the cross-reference. If you want to programmatically apply \glssee to any entries that cross-reference an entry that has been used, then (at the end of the document) you will need to iterate over all entries and, for those that have the see or seealso key set, find out if the targets have been used. If so, use \glssee[tag]{label}{target}.

  3. If your intention is to have every entry in one glossary cross-reference a corresponding related entry in another glossary then a better approach is to use a hook (either a category hook or a more general glossary style hook) that automatically adds the cross-reference in the glossary. This is most easily achieved if the target entries in the second glossary have a labelling system that can be created by appending a prefix or suffix to the corresponding entry label in the first glossary.

2022-02-09 16:29:35

Top

Why does glossaries create a file with the extension .glsdefs? 🔗

When the glossary is displayed with \printglossary the entry information (such as the name, description and symbol) has to be accessed in order for it to be shown. If you have a glossary at the start of your document, but only define the entries later then the information isn’t available when the glossary is displayed. In order to make the information available at the start of the document, the information has to be saved at the end of the document (in the .glsdefs file) so it can be read in at the start of the document on the next LaTeX run.

If you define all your entries in the preamble then the information will be available for the entire document, so there’s no need to save it. Therefore the creation of the .glsdefs file is only triggered if you define an entry within the document environment.

If at all possible, it’s best to avoid defining entries within the document environment. Not all information can be saved to the .glsdefs file. In particular, with just the base glossaries the see field isn’t saved. It can also interfere with both the base acronym styles and the glossaries-extra abbreviation styles (since the entry information is written using the generic \newglossaryentry command).

If all your \printglossary commands (or \printglossaries) are at the end of the document, you may want to consider using glossaries-extra with the docdef=restricted option.

See the section Drawbacks With Defining Entries in the Document Environment in the user manual for further details.

Note that if you want to put \loadglsentries (or \input) in the begin document hook in order to load a file containing glossary definitions at the start of the document, then this will trigger the creation of the .glsdefs file unless you append to the hook before loading glossaries. Alternatively use glossaries-extra with docdef=restricted.

2020-07-01 13:16:12

Top

Why shouldn’t I use \include to include my glossary definitions? 🔗

Suppose you’ve defined all your glossary entries in a file called glossary-defs.tex and you want to use some or all of these entries in your document. The glossaries user guide says that you can use: 

\loadglsentries[type]{filename}

to load the file. For example: 

\loadglsentries{glossary-defs}
You can also use \input{filename} (e.g., \input{glossary-defs}) but you shouldn’t use \include{filename}, despite the number of web pages that suggest you can or should.

Although both \input and \include make TeX read the named file, these two commands aren’t equivalent. The first, \input, acts as though the contents of the file were written directly in your document in place of the \input command. The other one, \include, does a lot more than this. The command \include{file}:

Therefore, if you want to just input the contents of a file, \include is far less efficient than \input, can cause a spurious page break and creates a redundant extra file. So always use either \input or \loadglsentries to load your glossary definitions and only do this in the preamble.

2020-07-01 12:45:42

Top

What’s the best way of managing a file containing many entry definitions? 🔗

The best solution is to switch to using glossaries-extra and bib2gls. The terms can then all be defined in one or more .bib files and managed in an application such as JabRef.

2020-07-01 12:45:28

Top

Why must I protect fragile commands in the name key when the documentation says the name key is sanitized? (Pre version 4.0) 🔗

Pre version 4.0: by default, the glossaries package sanitizes the values of the name, description, symbol and sort keys, but none of the other keys. This means that you can use fragile commands within name, description and symbol, but they must be protected within the other keys. If you don’t specify the text key, its value will be obtained from the name key (before it is sanitized), so if you have only specified the name key and not the text key, you must protect fragile commands using \protect.

As from version 4.0, only the sort value is sanitized (unless sanitizesort=false). This is because v4.0 redesigned the way information is passed to the indexing applications. Now only the label and sort value are written to the glossary files (not the name, description or symbol). To ensure backward-compatibility with pre-v4.0, by default when an entry is defined the name, description and symbol keys don’t have their values expanded and other fields do. See the Expansion section of the glossaries user manual for further details.

2020-07-01 12:45:11

Top

Glossary Formatting

How do I get rid of the full stop after the description in the glossary? 🔗

If you are using version 3.03 or above, use the package option nopostdot. Alternatively (version 1.03 or above) just redefine \glspostdescription to do nothing: 

\renewcommand{\glspostdescription}{}
As from v1.17, if you want to remove it for a particular entry, use \nopostdesc in that entry’s description.

Note that with glossaries-extra, the nopostdot setting is the default. You can switch it on with postdot and use \nopostpunc as an alternative to \nopostdesc (which removes the punctuation without removing the post-description hook).

2020-06-27 11:25:05

Top

Can I suppress the page lists in the glossary? 🔗

Yes. Use the nonumberlist package option or as an option in \printglossary.

As from v1.17, you can suppress the number list for a particular entry using the nonumberlist option when defining the entry.

If you are using bib2gls with glossaries-extra then you can also use the save-locations=false resource option to suppress the numbering for that particular resource set and you can use \glsadd[format=glsignore]{label} to ensure an entry is selected without adding to that entry’s location list.

2020-06-27 15:36:40

Top

How do I make my glossaries appear in numbered chapters/sections? 🔗

As from version 1.1, you can use the package option numberedsection. This option takes one of the following values: false (unnumbered), nolabel (glossaries are numbered but not labelled) and autolabel (glossaries are numbered and automatically labelled). As from v4.02 there is also: nameref (glossaries are unnumbered but labelled so they can be reference via \nameref defined by the nameref package, which is automatically loaded by hyperref).

If numbersection=autolabel (or numberedsection=nameref), the labels are taken from the glossary type, so the main (default) glossary is given the label main, the list of acronyms (when using the acronym option) is given the label acronym and additional glossaries are given the same label as used in the first argument to \newglossary. So you can refer to each glossary in the text using \ref. For example: 

See chapter~\ref{main} for the main glossary and
chapter~\ref{acronym} for a list of acronyms.
Note that with the package option numbersection=nolabel, you will need to add your own label to the glossary preamble if you want to reference it. For example: 
\renewcommand{\glossarypreamble}{\label{glossary}}
\printglossary
However take care if you have multiple glossaries. For example: 
\renewcommand{\glossarypreamble}{\label{glossary}}
\printglossary
\renewcommand{\glossarypreamble}{\label{acronyms}}
\printglossary[type=acronym]
Alternatively, upgrade to v4.02 and use numberedsection=nameref instead.

2020-06-27 15:41:56

Top

How do I have some of my glossaries in numbered sections and some in unnumbered sections? 🔗

As from version 1.14, you can use the numberedsection key in the optional argument to \printglossary. For example, to put the main glossary in an unnumbered section and the list of acronyms in a numbered section: 

\printglossary[numberedsection=false]
\printglossary[type=acronym,numberedsection]

2020-06-27 15:42:51

Top

How do I make my glossaries appear in different sectional units? 🔗

Suppose you want the main glossary to appear in a chapter, but you want the list of acronyms to appear in a section, then use the package option section=chapter (which is actually the default if your document class defines chapters) and then change the document sectioning unit to section at the place where you want the change to occur. Version 1.1 introduced an easy interface to do this: \setglossarysection{<section name>}, where <section name> is the name of a sectional unit. For example: 

\printglossary % print the main glossary
% change the glossary sectional unit to section
\setglossarysection{section}
\printglossary[type=acronym] % print the list of acronyms

For earlier versions, you need to redefine \@@glossarysec, but remember that this is an internal command so it needs to be placed inside \makeatletter and \makeatother. For example: 

\printglossary % print the main glossary
\makeatletter
% change the glossary sectional unit to section
\renewcommand*{\@@glossarysec}{section}
\makeatother
\printglossary[type=acronym] % print the list of acronyms

2020-06-27 15:44:14

Top

How do I prevent my glossaries from starting a new section/chapter? 🔗

Redefine \glossarysection to ignore its arguments: 

\renewcommand{\glossarysection}[2][]{}
(Remember to do this before using \printglossaries or \printglossary.)

2020-06-27 15:45:03

Top

Can I have sub-entries? 🔗

As from v1.17, hierarchical glossaries are supported. See the section Sub-Entries in the user guide for further details.

2018-08-21 09:59:11

Top

Is it possible to automatically move a lonely entry up a hierarchical level? 🔗

This is only possible with bib2gls. See Is it possible to automatically move a lonely entry up a hierarchical level? in the bib2gls FAQ.

2020-06-29 12:24:56

Top

How do I define my own glossary style? 🔗

See section Defining your own glossary style in the user manual.

2020-06-29 12:22:24

Top

Is it possible to prevent the glossaries package from loading longtable/supertabular? 🔗

As from v1.18, you can use the package options nolong or nosuper to prevent the glossaries package from automatically loading the glossary-long or glossary-super packages. (You can also use nostyles to prevent all the default styles from being loaded.) Note, however, that if you use these options, you won’t be able to use any of the glossary styles defined in those packages (unless you explicitly load them later).

2020-07-01 13:19:27

Top

Is it possible to make the long/super styles use ragged right formatting? 🔗

As from v2.01, you can use the styles defined in glossary-longragged or glossary-superragged, but note that these packages have to be loaded explicitly after loading the glossaries package so you can’t use the style package option. There are also additional ragged styles available with the glossary-longbooktabs package.

If you are using glossaries-extra, you can also use the glossary-longextra styles.

2020-06-29 12:21:56

Top

How do I apply a different font to a particular page in a number list? 🔗

The location encapsulator (encap) is given by the format key in the optional argument of commands like \gls. The value should be the name of the associated command (which should only take a single argument) without the initial backslash. For example, \gls[format={textbf}]{sample}.

Note that if your document has hyperlinks, then the formatting command will cause the hyperlink to be lost unless it uses \glshypernumber. So format=textbf or format=emph will format the location in bold or italic but the location won't have a hyperlink. For convenience, the glossaries package provides alternatives that internally use \glshypernumber. For example, format=hyperbf or format=hyperem.

For a complete list of available location formats that support hyperlinks, see Table 6.1 of the glossaries user manual.

2020-06-29 12:21:36

Top

How do I make each letter group start with a title? 🔗

You need to use a glossary style that supports this. For the predefined styles provided with the base glossaries package, these are the styles whose name ends with "group". For example, listgroup or treegroup. The glossaries-extra package provides an additional style bookindex in the accompanying glossary-bookindex package that also supports letter group titles. See the gallery of all predefined styles for examples.

If you are using glossaries-extra with bib2gls, you additionally need to remember to call bib2gls with the --group (or -g) switch.

2020-06-29 12:21:23

Top

Why does \printglossary use \null when the glossary file is missing? 🔗

When the document build is incomplete (before the associated files have been created by makeindex or xindy), \printglossary will do \null, which creates (empty) content on the page. This can lead to a blank page mid-build. Once the associated files have been created, \printglossary will input the file and not use \null. This shouldn’t normally cause a problem since the PDF is never complete mid-build anyway. (References and citations appear as a double question mark ??, the table of contents, list of floats aren’t present etc.)

The reason for \null is to deal with dictionary-style documents where the document environment simply consists of the glossary. For example: 

\documentclass{book}
\usepackage[nonumberlist]{glossaries}
\makeglossaries
\input{definitions}\glsaddall
\begin{document}
\printglossary
\end{document}

Without the \null, there would be no content and the document build would fail. The \null ensures that the PDF file is actually created albeit with a single empty page (with header/footer).

Note that with glossaries-extra, the behaviour of \printglossary is modified to print the chapter/section title and helpful text instead of simply \null. This again ensures that the document contains at least one page but also adds the glossary to the table of contents earlier (which can reduce the total number of LaTeX calls) and provides help to new users who haven’t worked out how to create the associated files.

\printglossary is designed to print content to the page. The fact that it produces different content mid-build shouldn’t be a problem as long as the correct content is present at the end of the build. The only time it causes a problem is when users try to modify the behaviour of \printglossary (through a custom style) so that it doesn’t actually produce any output. This is usually done in an attempt to gather information from the associated file, but there are more efficient ways of gathering this information. The best way is to switch to bib2gls. The location field then provides the formatted location list and the loclist field provides the locations in an internal list that can be iterated over. The group field contains the letter group label, and various resource settings can provide additional information such as child count and sibling count. This is far simpler than trying to write a glossary style that parses the code that makeindex or xindy writes to the glossary files, particularly since they use different commands within the location lists.

See also Is it possible to reference the locations outside of the glossary?

2020-06-29 12:20:58

Top

How do I change the page numbers to another type of number in the glossary page lists? 🔗

The location list shown after each entry in the glossary defaults to the list of page numbers where the entry was indexed in the document. The location counter determines those numbers. By default, the location counter is the page counter. You can change the default location counter with the counter package option. For example, to use the section counter instead: 

\usepackage[counter=section]{glossaries}
You can also change it later in the document with \setupglossaries. For example: 
\setupglossaries{counter=section}
This will change the location counter from that point onwards. Any indexing that has already occurred, won’t be affected.

It’s also possible to change the location counter for a specific instance using the counter option in the optional argument of commands like \gls. For example: 

\gls[counter=section]{label}

You can set the default counter for a specific glossary when you define the glossary. For example, the following will set the default location counter to the equation counter for all entries in this new glossary: 

\newglossary*{notation}{Notation}[equation]

Obviously, if you use a counter such as equation, you need to take care if you try indexing an entry outside of the context of that counter. Such as in text mode where the counter is equation.

The glossaries-extra package additionally provides the package options: equations, which automatically switches the location counter to equation when in a numbered equation environment, and floats, which will automatically switch to the corresponding counter, such as figure or table, when indexing occurs in a float. (Bear in mind that the float counter is incremented by \caption so any indexing within a float before the caption will have an incorrect location if the corresponding float counter is used.)

With glossaries-extra, it’s also possible to redefine the hook \glslinkpresetkeys to set the counter according to some condition, such as for a particular value of the category field.

2023-07-08 13:56:08

Top

Referencing Terms

How do I change the way the glossary term is formatted in the document (when using \gls etc)? 🔗

The font can be changed by redefining \glstextformat which takes one argument (the text to be displayed). For example, if you want all your glossary terms to appear in bold, you can do: 

\renewcommand{\glstextformat}[1]{\textbf{#1}}

(See also How do I change the way the text appears when I use commands like \gls?.)

If you are using glossaries-extra, you can also make adjustments using category attributes. See Gallery: Mixing Styles for an example.

2020-07-01 14:14:41

Top

How do I change the way the text appears when I use commands like \gls? 🔗

As from version 4.0, commands like \gls and \glspl use \glsentryfmt to display the relevant information. Within the definition of this commands, you may use \glslabel to access the entry’s label, \ifglsused to determine if the entry has been used, \glsifplural to determine if the plural form is required, \glscapscase to determine if a case change is required, \glsinsert to access the additional text provided by the final optional argument of commands like \gls, and \glscustomtext to access the text provided by \glsdisp. If you want different glossaries to have different formats, you can use \defglsentryfmt instead of redefining \glsentryfmt. See the section Changing the format of the link text in the user manual for further information.

If you simply want to append information you might want to consider using the post-link hook. With glossaries-extra, this can be done on a per-category basis. See Gallery: Units (glossaries-extra.sty) for an example.

Versions prior to glossaries v4.0:

Commands like \gls and \glspl use \glsdisplayfirst and \glsdisplay to display the relevant information. The former command is used on first use and the latter command is used subsequently. Both commands take four arguments: the first is either the singular or plural form given by the text, plural, first or firstplural keys (used when the term was defined) depending on context. The second argument is the term’s description (as supplied by the description key), the third argument is the symbol associated with the term (as supplied by the symbol key) and the fourth argument is the additional text supplied in the final optional argument to \gls or \glspl (or their uppercase variants). The default simply prints the first argument immediately followed by the fourth argument and ignores the remaining arguments.

For example, suppose you want a glossary of measurements and units, you can use the symbol key to store the unit: 

\newglossaryentry{distance}{name=distance,
description={The length between two points},
symbol={km}}
and now suppose you want \gls{distance} to produce “distance (km)” on first use, then you can redefine \glsdisplayfirst as follows: 
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
Note that the additional text is placed after #1, so \gls{distance}['s] will produce “distance’s (km)” rather than “distance (km)’s” which looks a bit odd (even though it may be in the context of “the distance (km) is measured between the two points” — but in this instance it may be better not to use a contraction).

Caveat: care needs to be taken if you want to use the symbol within the text as the symbol key is sanitized by default (pre-v4.0). This means that any commands within the symbol will not be interpreted which can lead to strange results. If you do want to redefine \glsdisplay or \glsdisplayfirst so that the symbol is used, you need to use the package option sanitize={symbol=false} and protect fragile commands within the symbol key.

Remember that you need to use a glossary style that displays the symbol if you use the symbol key as many of the styles ignore it.

2020-07-01 14:15:03

Top

How do I change the way the text appears when I use commands like \gls for a given glossary? 🔗

As from version 4.0, you can use \defglsentryfmt (see How do I change the way the text appears when I use commands like \gls?) to change the way glossary entries appear when using commands like \gls or \glsdisp. See the section Changing the format of the link text in the user manual for further information.

Versions prior to v4.0:

If you have multiple glossaries, changing \glsdisplayfirst and \glsdisplay (see How do I change the way the text appears when I use commands like \gls?) will change the way all glossary entries appear when using commands like \gls. If you only want the change to affect entries for a given glossary, then you need to use \defglsdisplay and \defglsdisplayfirst instead of redefining \glsdisplay and \glsdisplayfirst.

Both \defglsdisplay and \defglsdisplayfirst take two arguments: the first is the glossary name and the second is how the term should be displayed when it is invoked using commands like \gls and \glspl. This is similar to the way \glsdisplayfirst was redefined in How do I change the way the text appears when I use commands like \gls? except that you must use ##1, ##2, ##3 and ##4 instead of #1, #2, #3 and #4.

For example, suppose you have created a new glossary called notation and you want to change the way the entry is displayed on first use so that it includes the symbol, you can do: 

\defglsdisplayfirst{notation}{##1##4 (denoted ##3)}
Now suppose you have defined an entry as follows: 
\newglossaryentry{set}{type=notation,
name=set,
description={A collection of objects},
symbol={$S$},
}
The first time you reference this entry using \gls it will be displayed as: “set (denoted S)” (similarly for \glspl and the other variants).

2020-07-01 14:15:28

Top

How do I define my own custom acronym style? 🔗

As from version 4.02, you can define your own acronym style using \newacronymstyle. For example, suppose you want the long form to appear in the margin on first use. You could define the style from scratch, but you might find it easier to base the new style on an existing style. For example, let’s define a new style called “margin” that’s based on the short-long style: 

\newacronymstyle{margin}
{%
  \GlsUseAcrEntryDispStyle{short-long}%
}%
{%
  \GlsUseAcrStyleDefs{short-long}%  
  \renewcommand*{\genacrfullformat}[2]{%
   \protect\firstacronymfont{\glsentryshort{##1}}##2%
   \protect\marginpar{\glsentrylong{##1}}%
  }%
  \renewcommand*{\Genacrfullformat}[2]{%
   \firstacronymfont{\Glsentryshort{##1}}##2%
   \protect\marginpar{\glsentrylong{##1}}%
  }%
  \renewcommand*{\genplacrfullformat}[2]{%
   \protect\firstacronymfont{\glsentryshortpl{##1}}##2%
   \protect\marginpar{\glsentrylongpl{##1}}%
  }%
  \renewcommand*{\Genplacrfullformat}[2]{%
   \protect\firstacronymfont{\Glsentryshortpl{##1}}##2%
   \protect\marginpar{\glsentrylongpl{##1}}%
  }%
}
Now you can set the style: 
\setacronymstyle{margin}

Note that if you are using glossaries-extra, it uses a completely different abbreviation mechanism. The above is only for cases where the base glossaries package is being used without the glossaries-extra extension package.

Pre glossaries version 4.02:

A new style can be set by redefining \CustomAcronymFields and using \SetCustomStyle. 

\DeclareRobustCommand{\MARGINPAR}[1]{\marginpar{#1}}

\renewcommand*{\CustomAcronymFields}{%
  name={\the\glsshorttok},% name is abbreviated form
  description={\the\glslongtok},% description is long form
  first={\the\glsshorttok\MARGINPAR{\the\glslongtok}},%
  firstplural={\the\glsshorttok\noexpand\acrpluralsuffix\MARGINPAR{\the\glslongtok}},%
  text={\the\glsshorttok},%
  plural={\the\glsshorttok\noexpand\acrpluralsuffix}%
}

\SetCustomStyle % Switch to custom style
Note that this method gets more complicated if the plural forms can’t be derived by appending the singular form with the plural suffix (“s” by default). If you find this a problem, then upgrade to the latest version and use \newacronymstyle as described above.

2020-06-27 16:13:08

Top

How do I set the font for just the long form when using \newacronym? 🔗

As from version 4.02 you can define your own custom acronym style (see How do I define my own custom acronym style?). For example, suppose you want the long form in italic followed by the short form in parentheses on first use, then you can define a new style called, say, em-long-short that’s based on the long-short style: 

\newacronymstyle{em-long-short}
{%
  \GlsUseAcrEntryDispStyle{long-short}%
}%
{%
  \GlsUseAcrStyleDefs{long-short}%  
  \renewcommand*{\genacrfullformat}[2]{%
   \emph{\glsentrylong{##1}}##2\space
   (\firstacronymfont{\glsentryshort{##1}})%
  }%
  \renewcommand*{\Genacrfullformat}[2]{%
   \emph{\Glsentrylong{##1}}##2\space
   (\firstacronymfont{\glsentryshort{##1}})%
  }%
  \renewcommand*{\genplacrfullformat}[2]{%
   \emph{\glsentrylongpl{##1}}##2\space
   (\firstacronymfont{\glsentryshortpl{##1}})%
  }%
  \renewcommand*{\Genplacrfullformat}[2]{%
   \emph{\Glsentrylongpl{##1}}##2\space
   (\firstacronymfont{\Glsentryshortpl{##1}})%
  }%
}
Now you can set the style: 
\setacronymstyle{em-long-short}
You may prefer to move the insert part (##2) into the \emph argument: 
\newacronymstyle{em-long-short}
{%
  \GlsUseAcrEntryDispStyle{long-short}%
}%
{%
  \GlsUseAcrStyleDefs{long-short}%  
  \renewcommand*{\genacrfullformat}[2]{%
   \emph{\glsentrylong{##1}##2}\space
   (\firstacronymfont{\glsentryshort{##1}})%
  }%
  \renewcommand*{\Genacrfullformat}[2]{%
   \emph{\Glsentrylong{##1}##2}\space
   (\firstacronymfont{\glsentryshort{##1}})%
  }%
  \renewcommand*{\genplacrfullformat}[2]{%
   \emph{\glsentrylongpl{##1}##2}\space
   (\firstacronymfont{\glsentryshortpl{##1}})%
  }%
  \renewcommand*{\Genplacrfullformat}[2]{%
   \emph{\Glsentrylongpl{##1}##2}\space
   (\firstacronymfont{\Glsentryshortpl{##1}})%
  }%
}

Note that if you are using glossaries-extra, it uses a completely different abbreviation mechanism so the above won’t work.

Pre version 4.02:

You can use the custom acronym format, as described in How do I define my own custom acronym style?. For example, suppose you want the long form to be emphasized using \emph, you can do the following: 

\renewcommand*{\CustomAcronymFields}{%
  name={\the\glsshorttok},% name is abbreviated form
  description={\the\glslongtok},% description is long form
  first={\noexpand\emph{\the\glslongtok}\space(\the\glsshorttok)},%
  firstplural={\noexpand\emph{\the\glslongtok\noexpand\acrpluralsuffix}\space(\the\glsshorttok)},%
  text={\the\glsshorttok},%
  plural={\the\glsshorttok\noexpand\acrpluralsuffix}%
}

\SetCustomStyle
This displays long (short). You can swap, add or remove \glslongtok and \glsshorttok, as required. Remember to use \SetCustomStyle to switch to this acronym style. (If you get an error saying that \CustomAcronymFields can’t be redefined as it doesn’t exist or an “Undefined control sequence” error for \SetCustomStyle, then you need to update your version of glossaries.)

Note, however, that this solution doesn’t work for plurals that aren’t formed by simply prefixing the singular term with \acrpluralsuffix. If this causes a problem, upgrade to the latest version and use \newacronymstyle as described above.

2020-07-01 14:16:00

Top

How do I make the acronym on first use display the short form followed by the long form in brackets? 🔗

As from version 4.02, use one of the predefined acronym styles short-long, sc-short-long or sm-short-long. For example: 

\setacronymstyle{short-long}

Note that if you are using glossaries-extra, it uses a completely different abbreviation mechanism and some of the corresponding style names are slightly different. For example, short-sc-long rather than sc-short-long.

Pre glossaries version 4.02:

  1. If you are using the default definition of \newacronym, you can change the definition of \acrfullformat: 
    \renewcommand{\acrfullformat}[2]{#2\space(#1)}
  2. If you are using the description, smaller or smallcaps options (but neither the dua or footnote options) you can do: 
    \defglsdisplayfirst[\acronymtype]{\firstacronymfont{#3}#4 (#1)}
  3. Use the custom acronym format described in How do I define my own custom acronym style?.

2020-06-27 16:28:40

Top

How do I make acronyms appear in a different font (but not the long form)? 🔗

As from version 4.02, use one of the predefined acronym formats and redefine \acronymfont as required. For example, if you want the short form displayed in sans-serif using the long-short format: 

\setacronymstyle{long-short}
\renewcommand*{\acronymfont}[1]{\textsf{#1}}
or you can define you own custom style called, say, long-sf-short: 
\newacronymstyle{long-sf-short}%
{%
  \GlsUseAcrEntryDispStyle{long-short}%
}%
{%
  \GlsUseAcrStyleDefs{long-short}%
  \renewcommand{\acronymfont}[1]{\textsf{##1}}%
}
and use that: 
\setacronymstyle{long-sf-short}

Note that if you are using glossaries-extra, it uses a completely different abbreviation mechanism so the above won’t work.

Pre glossaries version 4.02:

If you are just using the default definition of \newacronym, then use the package option smaller and redefine \acronymfont to use the required font.

If you are using any of the package options that redefine \newacronym (such as description), then just redefine \acronymfont to use the required font.

2020-06-27 16:27:57

Top

How do I make the short form of the acronyms appear in a different font for the first use? 🔗

As from version 1.14, follow the instructions for How do I make acronyms appear in a different font (but not the long form)?, but redefine \firstacronymfont instead of \acronymfont.

2020-06-27 16:29:33

Top

As from version 2.03, you can also use the package option hyperfirst=false to suppress the first use link for all terms (including acronyms). If you also have non-acronym glossaries where the term on first use is identical to that used subsequently (that is, where the first and text keys have identical values), you can use \glsunsetall for just those glossaries to counteract the effect of hyperfirst=false. However, be careful about using \glsunsetall if you don’t intend using all defined entries in the document as there are situations where it can break other commands that rely on knowing whether or not an entry has been used in the document (such as \glsaddallunused).

With glossaries, you suppress the first-use hyperlink on a per-category basis with the nohyperfirst category attribute.

Pre glossaries version 2.03:

Use the footnote package option and do: 

\defglsdisplayfirst[\acronymtype]{#2#4 (\firstacronymfont{#1})}
Note that this won’t work for acronyms that belong to a glossary not given by \acronymtype.

2020-06-27 16:36:10

Top

Is it possible to reset acronyms so that they can be fully expanded again? 🔗

Yes. To reset an acronym you can use \glsreset{label} or \glslocalreset{label} where label is the label identifying the acronym. (These commands also work with glossary entries in general, but you will only see a difference if you set different values for first and subsequent use.)

To reset all entries for a given glossary type use \glsresetall[glossary list] or \glslocalresetall[glossary list]. If the optional argument is omitted, all entries for all defined glossaries will be reset.

Be careful about using \glsresetall as there are situations where it can break other commands that rely on knowing whether or not an entry has been used in the document (such as \glsaddallunused).

2020-06-27 16:38:26

Top

Is it possible to set an acronym so that it uses the short form on first use? 🔗

Yes, this is basically the reverse of Is it possible to reset acronyms so that they can be fully expanded again? To unset an acronym you can use \glsunset{label} or \glslocalunset{label} where label is the label identifying the acronym. (These commands also work with glossary entries in general, but you will only see a difference if you set different values for first and subsequent use.)

To unset all entries for a given glossary type use \glsunsetall[glossary list] or \glslocalunsetall[glossary list]. If the optional argument is omitted, all entries for all defined glossaries will be unset.

Be careful about using \glsunsetall as there are situations where it can break other commands that rely on knowing whether or not an entry has been used in the document (such as \glsaddallunused).

With glossaries-extra, it’s safer to use an abbreviation style that doesn’t show the full form on first use, such as the short-nolong (or short) style.

2020-06-27 16:41:04

Top

How can I make just the short form a hyperlink? 🔗

If you switch off the hyperlink on first use (using the hyperfirst=false package option), you can create a custom acronym style that inserts the link around just the short form: 

\documentclass{article}

\usepackage[colorlinks]{hyperref}
\usepackage[hyperfirst=false]{glossaries}

\makeglossaries

\newacronymstyle{linkshort}
{%
  % use the "long-short" display style:
  \GlsUseAcrEntryDispStyle{long-short}%
}
{%
  % use the "long-short" style definitions:
  \GlsUseAcrStyleDefs{long-short}%
  % adjust the full form so that it has a hyperlink for the short part:
  \renewcommand*{\genacrfullformat}[2]{%
    \glsentrylong{##1}##2\space
    (\glshyperlink[\protect\firstacronymfont{\glsentryshort{##1}}]{##1})%
  }%
  % same for the plural form:
  \renewcommand*{\genplacrfullformat}[2]{%
    \glsentrylongpl{##1}##2\space
    (\glshyperlink[\protect\firstacronymfont{\glsentryshortpl{##1}}]{##1})%
  }%
}

% apply this new style
\setacronymstyle{linkshort}

% now define the acronyms
\newacronym{gnu}{GNU}{Gnu is Not Unix}

\begin{document}

First use: \gls{gnu}. Next use: \gls{gnu}.

Full form: \acrfull*{gnu}.

\printglossaries
\end{document}

Note that if you are using glossaries-extra, it uses a completely different abbreviation mechanism so the above won’t work. However, you can simply use an abbreviation style such as short-postlong-user.

2020-06-27 16:45:13

Top

Why shouldn’t I use commands like \gls in \section, \chapter, \caption etc? 🔗

The user manual cautions against using commands like \gls in the argument of sectioning commands (\chapter, \section, etc) or in \caption. The reason for this warning is that there are multiple issues, some more serious than others, that can occur if you ignore this warning.

So what should you do if you want to use a term in a caption or sectioning command? It’s best to do as the user guide suggests and use one of the expandable commands such as \glsentrytext or \glsentrylong or \glsentryfull. Alternatively, have a look at the extension package glossaries-extra, which provides commands specifically for use in chapter or section headings.

2023-05-02 19:21:36

Top

Why don’t commands like \gls and \glslink use implicit grouping? 🔗

The glossaries and glossaries-extra manuals warn against using nested links. One of the associated problems is caused by a lack of scope. This can be illustrated in the following: 

\documentclass{article}

\usepackage{glossaries}

\setacronymstyle{long-short}

\newacronym{html}{HTML}{hypertext markup language}
\newacronym{xhtml}{XHTML}{extensible \acrlong{html}}

\begin{document}
\gls{xhtml}.
\end{document}
Instead of displaying the expected “extensible hypertext markup language (XHTML)” it displays “extensible hypertext markup language (HTML)”. The short form in parentheses is incorrect. The problem is caused by the nested link text (\acrlong{html} is inside the link text for \gls{xhtml}). The problem appears to be fixed if grouping is added: 
\newacronym{xhtml}{XHTML}{extensible {\acrlong{html}}}
So why doesn’t the glossaries package automatically include grouping?

The problem is the post-link hook, which is always used right at the end of all the \gls-like and \glstext-like commands. This hook needs to be able to both look ahead and look behind. For example, the postfootnote abbreviation style needs to look ahead to see if there’s a punctuation character, but it also needs to know which abbreviation has just been referenced and if it was the first use. If grouping is added internally, it will break either the look ahead or the look behind function. If the hook is inside the group, it can’t look ahead beyond the group, but if the hook is outside the group, it can no longer find out the information about the entry that’s just been referenced. Since the user is free to redefine the hook to whatever they want, they can’t really be expected to remember to close a group that they haven’t opened, and suddenly requiring this would break older documents.

Although this lack of scope causes the most common and visible problem, it’s not the only problem resulting from nested links. There are other, more subtle, problems that can cause inconsistent behaviour, odd warnings and obscure error messages that are difficult to diagnose and are unrelated to the lack of scope. So even if there was a way to add implicit grouping that didn’t break the post-link hook, it still wouldn’t fix all the other problems.

Note that the glossaries-extra package provides alternative commands that may be used in the link text that avoid some of these problems (but there are still some caveats to be aware of).

2020-06-28 15:39:26

Top

Is it possible to reference the locations outside of the glossary? 🔗

Yes, but how well it works depends on the indexing method.

With \makenoidxglossaries, the locations are stored in the loclist field using the syntax of an etoolbox internal list (see Iteration With etoolbox’s Internal Lists) where each element is in a particular location format. Note that this method can’t compress consecutive locations into a compact range.

Example document (uses the example-glossaries-brief.tex file provided with glossaries that contains dummy entries for testing): 

\documentclass{report}

\usepackage{glossaries}

\makenoidxglossaries

\loadglsentries{example-glossaries-brief}

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}
Test locations: \glsentrynumberlist{lorem}
or \glsdisplaynumberlist{lorem}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls{lorem}

\chapter{Sample E}
\gls{lorem}

\printnoidxglossary
\end{document}

This produces the following text on page 2:

Test locations: 1, 3, 4, 5 or 1, 3, 4 & 5.

Note that there are no ranges and note the difference in output between \glsentrynumberlist and \glsdisplaynumberlist. (In the second list, the last two items are separated by & instead of a comma.) If you use hyperref: 

\usepackage[colorlinks]{hyperref}
\usepackage{glossaries}

Then the locations will be hyperlinks (as long as the location format supports them).

If you use \makeglossaries instead of \makenoidxglossaries then it isn’t quite so straight-forward as it’s necessary to gather the information when the glossary is displayed with \printglossary. Now you need the savenumberlist package option because it’s extra work to gather this information, which needlessly adds to the build time if it’s not required. 

\documentclass{report}

\usepackage[savenumberlist]{glossaries}

\makeglossaries

\loadglsentries{example-glossaries-brief}

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}
Test locations: \glsentrynumberlist{lorem}
or \glsdisplaynumberlist{lorem}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls{lorem}

\chapter{Sample E}
\gls{lorem}

\printglossary
\end{document}

Since the information can only be gathered when the glossary file is input by \printglossary, an extra LaTeX call is required. If the document is called myDoc.tex then the build process is now: 

pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
pdflatex myDoc

The result is now:

Test locations: 1, 3–5 or 1 & 3–5.

Note that the ranges are now present. Unfortunately, \glsdisplaynumberlist doesn’t work with hyperref. If you add hyperref you will find the following message in the transcript:

Package glossaries Warning: \glsdisplaynumberlist doesn't work with hyperref. Using \glsentrynumberlist instead

Compare this now with bib2gls (the following document uses example-glossaries-brief.bib provided with glossaries-extra): 

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[record]{glossaries-extra}

\GlsXtrLoadResources[src={example-glossaries-brief}]

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}
Test locations: \glsentrynumberlist{lorem}
or \glsdisplaynumberlist{lorem}.

Directly accessing the location field:
\glsxtrifhasfield{location}{lorem}{\glscurrentfieldvalue}{??}.
Iterating over the loclist field:
\glsxtrifhasfield{loclist}{lorem}{\glsnoidxloclist{\glscurrentfieldvalue}}{??}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls{lorem}

\chapter{Sample E}
\gls{lorem}

\printunsrtglossary
\end{document}

This now produces:

Test locations: 1, 3–5 or 1, 3–5.

Directly accessing the location field: 1, 3–5. Iterating over the loclist field: 1, 3, 4, 5.

So there are now extra ways of accessing the location lists, but note that \glsdisplaynumberlist now produces the same result as \glsentrynumberlist.

The formatted location list is stored in the location field and the individual locations are stored in the loclist field (the same as for the \makenoidxglossaries method). Note that with the hyperref package the locations are all hyperlinks.

With bib2gls, the entries aren’t defined on the first LaTeX call, so I’ve used \glsxtrifhasfield to test if the field has been set and put ?? in the false part so it’s easier to detect when the field hasn’t been set. (This also helps to check that the entry label and field label have been typed correctly.)

Note that this method also works without \printunsrtglossary, unlike the \makeglossaries method (which can’t work without \printglossary) or the \makenoidxglossaries method (which can work without \printnoidxglossary but issues a warning).

You can also instruct bib2gls to save primary locations (identified by designated formats) to a special field, which is useful if you don’t require the entire list. For example: 

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[record]{glossaries-extra}

\GlsXtrLoadResources[src={example-glossaries-brief},
 save-primary-locations={default format},
 primary-location-formats={primary}]

\newcommand{\primary}[1]{\hyperbf{#1}}

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}

Full location list: 
\glsxtrifhasfield{location}{lorem}{\glscurrentfieldvalue}{??}.

Primary location(s):
\glsxtrifhasfield{primarylocations}{lorem}{\glsnoidxloclist{\glscurrentfieldvalue}}{}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls[format=primary]{lorem}

\chapter{Sample E}
\gls{lorem}

\printunsrtglossary
\end{document}

This now produces:

Full location list: 1, 3–5.

Primary location(s): 4.

The primary location can be saved and removed from the location field by changing the resource settings: 

\GlsXtrLoadResources[src={example-glossaries-brief},
 save-primary-locations={remove},
 primary-location-formats={primary}]

The result is now:

Full location list: 1, 3, 5.

Primary location(s): 4.

With a combination of hyperref and record=nameref with the chapter counter as the location, it’s also possible to hyperlink to the chapter where the hyperlink text is the chapter title (rather than the chapter number): 

\documentclass{report}

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

\GlsXtrLoadResources[src={example-glossaries-brief},
 save-primary-locations={default format},
 primary-location-formats={primary}]

\newcommand{\primary}[1]{\hyperbf{#1}}

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}

Full location list: 
\glsxtrifhasfield{location}{lorem}{\glscurrentfieldvalue}{??}.

Primary location(s):
\glsxtrifhasfield{primarylocations}{lorem}{\glsnoidxloclist{\glscurrentfieldvalue}}{}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls[format=primary,counter=chapter]{lorem}

\chapter{Sample E}
\gls{lorem}

\printunsrtglossary
\end{document}

This now produces:

Full location list: 1, 3, Sample D, 5.

Primary location(s): Sample D.

Alternatively: 

\documentclass{report}

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

\GlsXtrLoadResources[src={example-glossaries-brief},
 loc-counters={equation,page},
 save-primary-locations={default format},
 primary-location-formats={primary}]

\newcommand{\primary}[1]{\hyperbf{#1}}

\GlsXtrAutoAddOnFormat{primary}{counter=chapter}

\begin{document}
\chapter{Sample A}
\gls{lorem}

\chapter{Sample B}

Full location list: 
\glsxtrifhasfield{location}{lorem}{\glscurrentfieldvalue}{??}.

Primary location(s):
\glsxtrifhasfield{primarylocations}{lorem}{\glsnoidxloclist{\glscurrentfieldvalue}}{}.

\chapter{Sample C}
\gls{lorem}

\chapter{Sample D}
\gls[format=primary]{lorem}

\chapter{Sample E}
\gls{lorem}

\printunsrtglossary
\end{document}

Which produces:

Full location list: 1, 3–5.

Primary location(s): Sample D, 4.

2020-06-28 22:24:19

Top

Sorting and Collating Entries

How do I get TeXnicCenter to use makeglossaries? 🔗

See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

2020-07-01 14:17:21

Top

How do I get WinEdt to make the glossaries? 🔗

This is explained in a thread on comp.text.tex. See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

2020-06-28 16:02:39

Top

Do I have to use makeglossaries? 🔗

No, you can use makeindex or xindy directly, but you will need to remember to use it for each glossary that has been defined, and you will need to remember all the relevant switches. If you want to use xindy, you must remember to use the xindy option when loading the glossaries package. See Generating the associated glossary files for further details.

Note that makeglossaries doesn’t simply run makeindex or xindy, it also analyses the transcript messages (which can be quite cryptic) and provides additional information when something goes wrong. When used with makeindex (which doesn’t allow the same location to have multiple formats), makeglossaries will detect the multiple encap warning and attempt to fix it.

Consider the following document: 

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

\makeglossaries

\newglossaryentry{alpha}{name={\ensuremath{\alpha}},description={...}}

\begin{document}
\gls{alpha}

\printglossaries
\end{document}

This will cause xindy to fail with the message:

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

This is one of the error messages that makeglossaries looks for and it provides more information (the document is in the file test.tex):

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

Note that this identifies the label of the problematic entry (alpha) and suggests a remedy (add sort={alpha} to the entry’s definition). See also What does the xindy error “CHAR: index 0 should be less than the length of the string” mean?.

Now consider the document: 

\documentclass{article}
\usepackage{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},description={...}}

\begin{document}
\gls{sample}
\gls[format=hyperbf]{sample}

\printglossaries
\end{document}

In this case makeindex will generate a warning (the document is in the file test.tex):

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

The location list will have page 1 appearing twice, first in the normal font and then in bold. If you use makeglossaries it will show the above warning and then the message:

Multiple encaps detected. Attempting to remedy. Reading test.glo... Writing test.glo... Retrying

The location list will now just contain the bold page 1.

So to recap: no, you don’t have to use makeglossaries. You can simple run makeindex or xindy explicitly or you can write your own script that simply runs makeindex or xindy with your preferred switches, but makeglossaries knows what switches are required (from the .aux file) and can help you when things go wrong.

If you don’t want to use makeglossaries because you don’t have Perl installed (and you don’t want to or can’t install it), then you can use makeglossaries-lite instead, which is a Lua script, but it doesn’t have any diagnostics. (Note that in this case, you also won’t be able to use xindy either as that is also a Perl script.) Alternatively, you can use the MakeGlossariesGUI Java application, which has a graphical interface that provides more detailed diagnostics. It can also be run from the command line, but there are no diagnostics available in that mode.

If you don’t want to install Perl (and therefore can’t use xindy) but you require non-Latin or extended Latin support for sorting alphabetically then your only remaining option is to use bib2gls (a Java application) with glossaries-extra.

See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

2020-07-01 14:17:53

Top

How do I change the way entries are sorted? 🔗

There are three package options that change the sort order: sort=standard (default alphabetical sort), sort=def (sort in order of definition) and sort=use (sort in order of use). As from version 4.0, you can also redefine \glsprestandardsort to hook into the standard sort mechanism to modify its behaviour. See the section Sorting Options in the user manual for further details.

Alternatively, if you want to override the sort for an individual entry, then you can use the entry’s sort key to sort it according to a different term. If it’s for the entire alphabet, then you will need to use xindy (instead of makeindex) and use an appropriate xindy language module. I’m sorry, I can’t give any assistance with writing or adapting xindy modules or styles. If you want help, try the xindy mailing list on the Xindy Web Site.

Version 4.04 introduced a new way of generating glossaries that doesn’t use external indexing applications (via \makenoidxglossaries and \printnoidxglossary / \printnoidxglossaries). Although this is a slower method that can’t sort extended-Latin or non-Latin alphabets, it does allow you to use independent sorting methods for each glossary. For example, you might want to sort the main glossary alphabetically, but sort the list of notations in order of use or definition. In general, it’s best to avoid this method if possible.

The glossaries-extra package provides a hybrid of the above methods by adding an optional argument to \makeglossaries so you can use makeindex/xindy for the alphabetical sorting and the \printnoidxglossary approach for order of definition/use. However, for a more flexible approach, consider switching to a combination of glossaries-extra and bib2gls. See, for example, Gallery: Sorting.

2020-07-01 14:31:58

Top

How can automated build tools determine whether or not to run makeglossaries etc? 🔗

The glossaries package writes information to the aux file that can be used for this purpose. This information is described in the section Note to Front-End and Script Developers in the glossaries user manual. These no-op commands were specifically provided for external tools and do nothing in the LaTeX document.

Please provide a method for your tool to search for those commands in the aux file rather than encouraging hacks that could break in future releases.

The existence of the command \@istfilename{basename.ext} indicates that makeindex or xindy is required. If the file extension ext is xdy then xindy is required with -M basename otherwise makeindex is needed with -s basename.ext.

Each non-ignored glossary that has been defined in the document is identified with \@newglossary{glossary-label}{log}{out-ext}{in-ext} where in-ext is the extension of the indexing application’s input file (the output file from the glossaries package’s point of view), such as glo, out-ext is the extension of the indexing application’s output file (the input file from the glossaries package’s point of view), such as gls, and log is the extension of the indexing application’s transcript file, such as glg.

Note that the \@newglossary lines are always written, regardless of the indexing method. The existence of \@newglossary in the aux file is not an indication of whether or not to use makeindex/xindy. Check for the \@istfilename file to determine this. With glossaries-extra there is also the possibility of a hybrid \printnoidxglossary and \printglossary combination. This is indicated by \glsxtr@makeglossaries, which lists the labels of the glossaries that need to have their files created by makeindex/xindy.

Once you have determined that makeindex/xindy is required, you can then test if jobname.out-file doesn’t exist or is older than jobname.in-file which will indicate that the indexing application needs to be run if jobname.in-file exists. If the input file doesn’t exist then there’s no corresponding \printglossary or \nofiles has been used.

Additional information, such as the letter/word order, language and codepage can also be obtained from the aux file from the commands \@glsorder{order}, \@xdylanguage{glossary-label}{language} and \@gls@codepage{code-page}.

If \glsxtr@resource{options}{basename} is found, then bib2gls is required. This is more complicated if you want to find out if the glstex files requiring updating as you’ll need to parse options for src={bib list} to find the list of bib files. The indexing output file in this case is basename.glstex. In general the simplest thing to do is just run bib2gls if \glsxtr@resource is found rather than trying to work out if the indexing information has changed.

2023-04-16 12:59:52

Top

Documentation

The manual is very long, is there an introductory guide? 🔗

There is now a separate beginners guide distributed with the glossaries package. There is also a section on glossaries in Using LaTeX to Write a PhD Thesis and an introductory guide in the LaTeX Community's Know How section.

See also examples in the gallery and glossaries-extra and bib2gls: An Introductory Guide.

2020-06-27 17:11:06

Top

What’s happened to the Quick Guide for the Impatient section in the manual? 🔗

I've replaced it with a separate beginners guide.

2020-07-01 14:28:24

Top

Upgrading from the glossary package

Can you help me upgrade my document from using the old glossary package to the new glossaries package? 🔗

Information is provided in the document Upgrading from the glossary package to the glossaries package.

2020-07-01 14:30:28

Top

Why doesn’t the new glossaries package create command names for the acronyms like the old glossary package? 🔗

There are a number of reasons:

  1. The new way of accessing terms using commands like \gls is more compatible with standard LaTeX syntax.
  2. Each term would require a command for the single as well as plural term, as well as commands to generate the upper case versions. For a large glossary that can amount to a lot of extra commands.
  3. Provision would also be needed to allow for the optional arguments, which is awkward as commands such as \gls have 2 optional arguments, one before and one after the mandatory argument. Without the mandatory argument, you would need to use an empty optional first argument if you want to use the second argument, which is a nuisance.
  4. You need to explicitly add a space after a command name that doesn’t have a mandatory argument. (Don’t rely on xspace, there are issues with that package that have led David Carlisle, the package author, to deprecate its use.)
If you really want to, as from v1.18, you can use \oldacronym which emulates the old glossary package’s syntax, but be aware of the drawbacks. See the section Upgrading From the glossaries Package in the glossaries documentation.

2020-07-01 14:29:53

Top