### Supporters and Partners

Sponsored by DANTE e.V.: The German speaking TeX Users Group

 Glossaries, Nomenclature, Lists of Symbols and Acronyms
(93 votes, average: 4.04 out of 5)
LaTeX - General
Written by Nicola Talbot
Wednesday, 18 March 2009 16:58

The glossaries package can be used to define terms, symbols and abbreviations that can be used throughout a document. You can then use an indexing application to collate and sort the entries that have been used in the document. It is a highly versatile package, but because of this it has a large manual that some beginners find daunting. This article is an introductory guide to help you get started. (Updated to include the glossaries-extra package.)

# What do I need installed?

The glossaries package principally requires:

Some of the features described here are only available in more recent releases. If you get any “undefined control sequence” errors or unknown options, check that you have the latest version.

If you use a language package, such as babel or polyglossia, you’ll also need to install the appropriate glossaries language module. For example, glossaries-french or glossaries-german.

If you want to use glossaries-extra you’ll need both glossaries and glossaries-extra installed. (The glossaries-extra package is an extension to not a replacement for glossaries.)

If you want to use any of the glossary styles that use the longtable environment, you will also need to have the longtable package installed, and if you want to use any of the glossary styles that use the supertabular environment, you will also need to have the supertabular package installed.

The above packages, including glossaries and glossaries-extra, are all distributed with MikTeX and TeX Live. (If you have MikTeX or TeX Live, you can install or update packages using the MikTeX Package Manager or the TeX Live Package Manager, respectively.)

Before you get started, check that you have all the required packages installed using the following test document:

\documentclass{article}\usepackage{glossaries}\begin{document}Test.\end{document}
\documentclass{article}\usepackage[T1]{fontenc}\usepackage[french]{babel}\usepackage{glossaries}\begin{document}Test \entryname.\end{document}

The English definition of \entryname is “Notation”. If the appropriate language module is installed, then this should be translated into the relevant language. (Not all languages are supported.)

If you want to use the glossaries-extra package, replace glossaries with glossaries-extra in the above examples. If the test document compiles without error, the packages are correctly installed. If you have any errors, such as mfirstuc.sty’ not found, then use your TeX package manager to install the missing packages.

The version number for the packages will be listed in the log file. For example, my log file contains the line:
Package: glossaries 2016/04/19 v4.22 (NLCT)

and also (for documents that use glossaries-extra):

Package: glossaries-extra 2016/04/25 v1.02 (NLCT)
You can compare this version information in your log file against the latest version listed on CTAN for glossaries and glossaries-extra.

In addition to the above LaTeX packages, if you want a sorted glossary (list of terms or abbreviations) you’ll also need to have an indexing application installed to collate and sort the entries (unless you want TeX to do this, which is possible but has limitations). The glossaries package is configured to work with makeindex or xindy. Makeindex is distributed with most TeX distributions, including MikTeX and TeX Live, so it should be readily available on your system. Xindy is distributed with TeX Live and (more recently) with MikTeX, but it requires Perl.

There is a common misconception that you must have Perl installed to use the glossaries package. You need Perl for xindy, but you can use makeindex instead. The glossaries package comes with a Perl script called makeglossaries that acts as a convenient interface to makeindex or xindy, but it is not essential. If you don’t want to install Perl, there are alternatives, which are discussed below.

# Getting Started

The first thing that you need to do in your document is indicate that you want to use the glossaries package:
\usepackage{glossaries}
Note that if you want to use xindy instead of makeindex, you must add the xindy package option:
\usepackage[xindy]{glossaries}

However you will need to have xindy and Perl installed if you want to use this option.

If you want to use glossaries-extra, then replace this with

\usepackage{glossaries-extra}

or

\usepackage[xindy]{glossaries-extra}
If you are also using the hyperref package, you must load the glossaries or glossaries-extra package after the hyperref package:
\usepackage[colorlinks]{hyperref}\usepackage{glossaries}
or
\usepackage[colorlinks]{hyperref}\usepackage{glossaries-extra}
This is an exception to the general rule that the hyperref package should be loaded last.

If you want your glossaries (list of terms, abbreviations, symbols, etc) to appear in the document’s table of contents, you also need to use the toc package option:

\usepackage[toc]{glossaries}

This is the default for glossaries-extra, so you just need

\usepackage{glossaries-extra}

If you want to use this extension package and you don’t want the glossaries to appear in the table of contents, then use the toc=false package option:

\usepackage[toc=false]{glossaries-extra}

## Defining a Term or Symbol

Terms and symbols are defined using
\newglossaryentry{label}{definition}
The first argument is a label that uniquely defines this entry.
It is best to use only non-special characters in the label. Avoid special characters such as ^ or _ and active characters like ~ or any of the babel shortcuts. For regular LaTeX or PDFLaTeX, also avoid extended Latin or non-Latin characters, but those may be used with XeLaTeX or LuaLaTeX.

The second argument is a comma-separated list of key=value pairs. The most important keys are name and description. These are used to assign the term and a brief description to appear in the glossary, list of symbols or list of abbreviations.

This article only covers the commonly used keys. See the section "Defining Glossary Entries" in the manual for a complete list.

For example:

\newglossaryentry{culdesac}{name=cul-de-sac,description={passageor street closed at one end}}
The above defines an entry whose label is culdesac.
It is generally best to define the terms in the preamble as problems can occur if you define them in the document environment. You can put all your definitions in a separate file and input it in the preamble using \loadglsentries{filename}, which you may find more convenient. You may also use \input but don’t use \include.

## Referencing Terms

Once a term has been defined using \newglossaryentry, it can be referenced in the document using:
\gls{label}
Returning to the example above, I can reference it using:
\gls{culdesac}
If I want the first letter to be converted to upper case, I can do:
\Gls{culdesac}
or if I want the whole term to appear in capitals, I can do:
\GLS{culdesac}
The above commands also have optional arguments that aren’t discussed in this article. For further information, see the section "Links to Glossary Entries" in the manual.
Don’t use these commands in chapter or section headings or captions as they can cause unexpected problems.

If you use glossaries-extra, you can use

\glsfmttext{label}

in sectioning headings or captions instead. This isn’t available for the base glossaries package.

Let’s put it together to make a simple document:

\documentclass{article}\usepackage{glossaries}\newglossaryentry{culdesac}{name=cul-de-sac,description={passageor street closed at one end},plural=culs-de-sac}\begin{document}I used to live in a \gls{culdesac}. \Gls{culdesac} is another namefor a no-through road.\end{document}

This produces a document that contains the following sentences:

I used to live in a cul-de-sac. Cul-de-sac is another name for a no-through road.

You can replace glossaries with glossaries-extra in the above example. There will be no difference in the PDF, but there will be a difference if we make a slight modification:

\documentclass{article}
\usepackage{glossaries-extra}
\begin{document}
\newglossaryentry{culdesac}{name=cul-de-sac,description={passage
or street closed at one end},plural=culs-de-sac}

I used to live in a \gls{culdesac}. \Gls{culdesac} is another name
\end{document}

This now produces an error message:

! Package glossaries-extra Error: Glossary entries must be
(glossaries-extra)                defined in the preamble with
(glossaries-extra)                package option docdef=false'.

This error doesn’t occur with just glossaries, so what’s gone wrong?

The glossaries package allows entries to be defined within the document environment, but, as mentioned above, there are problems associated with this. These issues are described in section 4.10 of the user guide, but a lot of users prefer to learn from examples rather than reading the manual (which is understandable given how large it is, but this is necessary since it has to cover every available user command). This means that a lot of users don’t realise the pitfalls of document definitions until things behave strangely and they ask for help.

Therefore, glossaries-extra by default disallows document definitions to raise user awareness. If you really need to define terms within your document, you can enable it, but first consider whether the need outweighs the drawbacks.

Consider the docdef option a form of “I understand and accept the risks” check box.

### First Letter Case-Changing

The commands that convert the first letter to upper case (such as \Gls) internally use \makefirstuc provided by the mfirstuc package. This tries to be intuitive in the event that the text to be modified starts with formatting commands, such as \emph, but there are cases where it fails, so take care if you use them.

Common pitfalls:

• The word starts with an accented or UTF-8 character but (PDF)LaTeX is being used. (Not a problem with XeLaTeX.) You need to enclose the character in braces. For example:
name={é}lite
or
name={\'e}lite
(More on this below.)
• The word starts with a command that has arguments, but the first argument doesn’t contain the text to modify, then a suitable replacement needs to be found. For example, the following won’t work:
name={\textcolor{red}{word}}
Instead you need to do, something like:
\newcommand*{\strong}[1]{\textcolor{red}{#1}}
and then use
name={\strong{word}}
Similarly for commands like \foreignlanguage.
• The word starts with a math-shift. Note that mathematical content shouldn’t be capitalised at the start of a sentence. Lower case and upper case variables usually have different meanings. Insert an empty brace at the start to prevent any modification if you happen to use commands like \Gls. For example:
name={{}$x$}
Similarly for any other content that shouldn’t be altered. For example:
name={{}\si{\ohm}}
• The word starts with a command that takes a label, such as \gls or \cite. The text that requires modifying can’t be obtained, and the label will end up with the case-change, which will prevent it from being recognised.
In general, don’t use commands like \gls inside the value of any key that may result in nested use of \gls (or similar commands).

### Plural Forms

The plural of a term can be obtained using
\glspl{label}
The default behaviour is to append the letter “s” to the name to create the plural. In the above example, that would produce “cul-de-sacs” which is incorrect. The correct plural is “culs-de-sac”. To fix this, I need to modify the definition:
\newglossaryentry{culdesac}{name=cul-de-sac,description={passageor street closed at one end},plural=culs-de-sac}
As with the singular, I can also make the first letter of the plural form upper case:
\Glspl{culdesac}
or I can make the entire plural form appear in capitals:
\GLSpl{culdesac}

### Alternative plurals or other grammatical constructs

There are six keys provided that you can use to store additional information, such as alternative plurals or other constructs. For example, you could store alternative plurals in user1 and gerunds in user2:

\newglossaryentry{cow}{name=cow,  description={a fully grown female of any bovine animal (plural cows, archaic plural kine)},  user1={kine}}\newglossaryentry{low}{name=low,  description={long, deep sound made by a cow},  user2={lowing}}

You can access the value of the user keys using \glsuseri{label} and \glsuserii{label}, but it’s better to define easy to remember synonyms. For example:

\let\glsaltpl\glsuseri\let\glsing\glsuserii

You can now use \glsaltpl to produce the alternative plural and \glsing to produce the gerund:

\documentclass{article}\usepackage{glossaries}\newglossaryentry{cow}{name=cow,  description={a fully grown female of any bovine animal (pluralcows, archaic plural kine)},  user1={kine}}\newglossaryentry{low}{name=low,  description={long, deep sound made by a cow},  user2={lowing}}\let\glsaltpl\glsuseri\let\glsing\glsuserii\begin{document}The \glsing{low} was so loud it could be heard a mile away from the\glsaltpl{cow}.\end{document}

Another possibility is to add your own custom key using \glsaddkey, but that’s too complicated for this introductory article. See Additional Keys for further details.

### The sort key

Later on in this article, I will cover sorting the entries using an indexing application, but when you define an entry, you need to bear in mind that the indexing application won’t know how to sort terms that contain LaTeX commands. Consider the following example:
\newglossaryentry{pi}{name={\ensuremath{\pi}},description={ratio of circumference of circle to its diameter}}
This entry should ideally belong to the “p” group (that is, the group of terms whose first letter is a “p”) however neither makeindex nor xindy will be able to sort this entry correctly as they can’t interpret LaTeX code. Therefore, we need to tell the indexing application that this entry should be sorted according to “pi”:
\newglossaryentry{pi}{name={\ensuremath{\pi}},sort=pi,description={ratio of circumference of circle to its diameter}}


Click on "OK" and you should now see MakeGlossaries present in the drop-down tool list:

Select "MakeGlossaries" and click on the green run button. You won’t see anything different in the PDF yet. Use the drop-down box to select pdfLaTeX again and click on the green run button. Your document should now be updated and the glossaries should be present. (Click on image to view larger version.)

Note that the glossary (page 1), list of acronyms (page 1) and list of symbols (page 2) haven’t appeared in the table of contents. Another run (click the green button) is required.

The numbers after each glossary entry indicate the page number on which that entry was used. The numbers are red because the hyperref package has been used, and they link to the corresponding page. You can use the glossaries package option nonumberlist to suppress the number list.

The list of symbols doesn’t show the corresponding symbol for each entry. This is because the default style ignores the symbol. Try changing the package options to:

\usepackage[acronym,toc,style=tree]{glossaries}
See the section "Glossary Styles" in the manual for a list of predefined styles.

In general, you need to perform at least three steps to ensure the glossaries are up-to-date:

1. Run (pdf)latex
2. Run makeglossaries (or MakeGlossariesGUI described below)
3. Run (pdf)latex

Sometimes (as above) step 3 needs to be repeated. If your glossaries contain cross-references, you may need five steps:

1. Run (pdf)latex
2. Run makeglossaries (or MakeGlossariesGUI described below)
3. Run (pdf)latex
4. Run makeglossaries (or MakeGlossariesGUI described below)
5. Run (pdf)latex

## MakeGlossariesGUI

There is a Java alternative to makeglossaries called MakeGlossariesGUI. This doesn’t come with MikTeX or TeXLive, but can be downloaded from CTAN. (Make sure you first have an up-to-date version of the Java Runtime Environment installed.) Windows users should download and run makeglossariesgui-setup.exe. Users of other operating systems need to download makeglossariesgui.zip and follow the installation instructions in the README file. When you run MakeGlossariesGUI for the first time, you will be prompted for the paths to makeindex and xindy. (If you don’t want to use xindy, you can leave that box blank. Similarly, if you only intend to use xindy, you can leave the makeindex box blank.) After that you should see the following window:

Use the open button or the File → Open menu item to load the auxiliary file created when you latexed your document. For example, my document was called "sample2.tex", so I need to load "sample2.aux":

Once you load the file, the application will automatically call makeindex or xindy for each defined glossary. The glossaries information will be displayed in the window:

If any problems occur, you can check the "Diagnostics" tab for help. For example, suppose I forgot to add \makeglossaries, then I’ll get an error message saying "Can’t determine indexer" and the diagnostics tab will display the message:

Your document doesn’t seem to have used \makeglossaries.

If you modify your document, run latex as usual and then reload the auxiliary file in MakeGlossariesGUI using the reload button or the File → Reload menu item.

## Using makeindex explicitly

If you don’t have Perl (or Java and MakeGlossariesGUI) installed you can run makeindex explicitly. Let’s suppose that your document is called myDoc.tex. If you are using makeindex (that is, you haven’t used the xindy package option) then you need to use makeindex for each defined glossary. This includes the list of acronyms if you have used the acronym package option. The above example document has three glossaries: the main one, the list of acronyms and the list of symbols. The main glossary is created using:

makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
The list of acronyms is created with:
makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
The list of symbols is created with:
makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sym myDoc.sbl

This means that you need to set up three separate tools in your editor. For TeXWorks, you need to go to the "Edit Preferences" window and create a new tool called, say "make main glossary", select the path to makeindex and add the appropriate arguments:

Similarly for the list of acronyms:

and for the list of symbols:

Now, everytime you modify your document, you need to:

1. Select the pdfLaTeX tool and click run button
2. Switch to the Make Main Glossary tool and click run button
3. Switch to the Make Acronyms tool and click run button
4. Switch to the Make Symbols tool and click run button
5. Switch to the pdfLaTeX tool and click run button

You may find it simpler to just use the automake option:

\usepackage[automake]{glossaries}

## TeXnicCenter

You can add makeglossaries to the build profile of TeXnicCenter as follows:
1. Install Perl (you will need to quit TeXnicCenter and restart it after installing Perl)
2. Select the menu item Build → Output Profiles...
3. Select the desired output profile from the box on the left (e.g. LaTeX=>PDF)
4. Select the "Postprocessor" tab from the box on the right
5. Click on the "New (insert)" icon. (This looks like a dashed rectangle to the left of the red cross.)
6. Type in makeglossaries
7. Type in the full path name of makeglossaries.bat into the executable box or use the ellipsis button on the right to browse the filing system. (On my Windows partition, the file can be found in the folder C:\Program Files\MiKTeX 2.7\scripts\glossaries but it may be somewhere else on your system.)
The full path name must be surrounded by double quotes if it contains spaces.
8. Type "%bm" in the Arguments box
9. Repeat for each output profile as desired.
10. Click on okay

## WinEdt

There is a thread on comp.text.tex that discusses how to use makeglossaries with WinEdt.

foxtrott
+12

Really nice.. Tank you very much
Milagros
0

Here's some atoadidnil Lewisian symbols:\DeclareMathSymb ol{\boxRight}{\mathrel}{symbolsC}{136}% Lewis's stronger 'would' counterfactual\DeclareMathSymb ol{\diamondRight}{\mathrel}{symbolsC}{140}% Lewis's stronger 'might' counterfactual\DeclareMathSymb ol{\diamonddot}{\mathord}{symbolsC}{144}% Lewis's inner necessity (\boxright should work already)Note that these also requires \DeclareSymbolFo nt{symbolsC}{U}{txsyc}{m}{n}.
Korosh
0

I really like this idea - it would be very usuefl to so many people. I wish I could do the same but my system really discourages listing/naming particular items and I figure they would really hit the roof if I used pictures.
zroutik
+2

Dear Nicola, dear Latex users,

is there a command, please, to show the glossary entry in text (as with \gls{} command), point it to the Glossary (when created), but do not create a new page number and a new back-referencin g link? Page numbers and back-referencin g links (in the Glossary list) would be created and pointed only for the first use of \gls{} or the appropriate command.

Thank you very much for listening,
Zroutik
zroutik
+2

(note on previous)

links in the text pointing to the Glossary list are very good. But many page numbers back-referencin g from the Glossary list to the text are a nice mess, IMO.

Thank you,
Zroutik
spkmn
-1

Hi... first, I love the package. I have a problem that I'm looking for advice on. I have a glossary entry that contains a reference to another glossary entry.

\newglossaryentr y{Hi}{description={This is an \gls{entry}},name={Hi}}
\newglossaryentr y{There}{description={There is a whole world out there.},name={Hi}}

Inside of a table cell, I want to use \gls{Hi}.

When it prints, I get "This is an gls --There''" inside of the table...

This entry appears fine in the \printglossaries and if I use it outside of a table.

Thanks
James
spkmn
-1

sorry.... it should be

\newglossaryentr y{Hi}{description={This is an \gls{There}},name={Hi}}
\newglossaryentr y{There}{description={There is a whole world out there.},name={Hi}}

Thanks
James
nlct
-1

Hi,

it's better to post requests for help in the forum as you'll get a quicker response and more people are likely to see it. It's also helpful to provide a http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/" rel="nofollow" target="_blank">minimal working example that illustrates the problem.

Regards
Nicola Talbot
nlct
-1

Sorry, that link got a bit mangled.
horacv
-1

Hi,
i am having a couple of problems with the definition of several glossaries. In particular, i have two separate input files. Where do i indicate this to the
\newglossary command?
i defined it this way:
 \include{./acr/acr.tex} \include{./acr/not.tex} \newglossary{notacion}{gls}{glo}{Notaci\'on} 
inside acr.tex i defined each entry, this way:
 \newglossaryentr y{rz}{ type=\acronymtype, 
and, inside not.tex, exactly the same way, except i didn't defined the type.
The output pdflates produces the same list (the one in acr.tex) two times. Any ideas what i am doing wrong?
thanks for the help
nlct
+1

If you have problems with the glossaries package, please post your query to the forum rather than as a comment here. Other people are more likely to search the forum than the comments if they have a similar problem.

### Latest Forum Posts

﻿

Metafile to EPS converter: should it work from within LYX?
22/10/2016 16:14, Stef Pillaert

Re: Force to print table
22/10/2016 15:22, Stefan Kottwitz

Re: Force to print table
22/10/2016 15:10, Wooldridge1

Re: Force to print table
22/10/2016 14:49, Stefan Kottwitz

Re: Broken Line in Table
22/10/2016 14:32, Wooldridge1

Force to print table
22/10/2016 14:32, Wooldridge1

Re: Broken Line in Table
22/10/2016 13:28, rais

Re: Broken Line in Table
22/10/2016 11:02, Wooldridge1

Re: Titlepage in latex
21/10/2016 21:24, sindy

Re: A orientalibus liminibus Italiæ septentrionalis
21/10/2016 14:49, Stefan Kottwitz