Latest news 2020-07-03: SmashWords sale (ends 31st July 2020): 50% off crime/SF novel The Private Enemy and 100% off (free!) I’ve Heard the Mermaid Sing.

glossaries package FAQ

Categories:

FAQ Search Tips

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 extension package to provide additional functions. The glossaries-extra package implicitly loads glossaries.sty so it’s not necessary to load both. Related: glossaries-extra package FAQ and bib2gls application FAQ.

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

Error Messages

(La)TeX Errors

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.

Last modified: 2020-07-01 10:59:36.

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.

Last modified: 2020-07-01 10:59:45.

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.

Last modified: 2020-07-01 10:59:57.

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}}

Last modified: 2020-07-01 11:00:04.

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).

Last modified: 2020-07-01 11:10:41.

Top

I get an error saying that \glspagewidthlist is undefined 🔗

This was fixed in v1.18.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 2020-07-01 11:00:42.

Top

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

Upgrade the datatool package.

Last modified: 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.

Last modified: 2020-07-04 11:10:32.

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.

Last modified: 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.

Last modified: 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.)

Last modified: 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).

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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 FAQ and Localisation with tracklang.tex.

Last modified: 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.

Last modified: 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}.

Last modified: 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}.

Last modified: 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.

Last modified: 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}}

Last modified: 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).

Last modified: 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?).

Last modified: 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.

Last modified: 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.

Last modified: 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 extensionmakeglossaries 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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}

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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?

Last modified: 2020-07-01 14:09:28.

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.

Last modified: 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.

Last modified: 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)”.

Last modified: 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?

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

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.

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.

  2. The glossaries-extra package provides the boolean package option autoseeindex. If true, the see (and seealso) 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. 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.

Last modified: 2020-07-01 12:53:59.

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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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).

Last modified: 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.

Last modified: 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.

Last modified: 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]

Last modified: 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

Last modified: 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.)

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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).

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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?

Last modified: 2020-06-29 12:20:58.

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.

Last modified: 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.

Last modified: 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).

Last modified: 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.

Last modified: 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.

Last modified: 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?.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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).

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 2020-06-28 15:29:33.

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).

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 2020-07-01 14:31:58.

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.

Last modified: 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.

Last modified: 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.

Last modified: 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.

Last modified: 2020-07-01 14:29:53.

Top