LaTeX/Glossary

Many technical documents use terms or acronyms unknown to the general population. It is common practice to add a glossary to make such documents more accessible.

The glossaries package can be used to create glossaries. It supports multiple glossaries, acronyms, and symbols. This package replaces the glossary package and can be used instead of the nomencl package. Users requiring a simpler solution should consider hand-coding their entries by using the description environment, or the longtabu environment provided by the tabu package.

Jump start

Place \usepackage{glossaries} and \makeglossaries in your preamble (after \usepackage{hyperref} if present). Then define any number of \newglossaryentry and \newacronym glossary and acronym entries in your preamble (recommended) or before first use in your document proper. Finally add a \printglossaries call to locate the glossaries list within your document structure. Then pepper your writing with \gls{mylabel} macros (and similar) to simultaneously insert your predefined text and build the associated glossary. File processing must now include a call to makeglossaries document_name_without_extension followed by at least one further invocation of latex or pdflatex.

Using glossaries

To use the glossaries package, you have to load it explicitly:

\usepackage{glossaries}

if you wish to use xindy (superior indexing tool) for the indexing phase, as opposed to makeindex (the default), you need to specify the xindy option:

\usepackage[xindy]{glossaries}

For the glossary to show up in your Table of Contents, you need to specify the toc option:

\usepackage[toc]{glossaries}

See also Custom Name at the bottom of this page.

Finally, place the following command in your document preamble in order to generate the glossary:

\makeglossaries

Any links in resulting glossary will not be "clickable" unless you load the glossaries package after the hyperref package.

In addition, users who wish to make use of makeglossaries will need to have Perl installed — this is not normally present by default on Microsoft Windows platforms. That said, makeglossaries simply provides a convenient interface to makeindex and xindy and is not essential.

Defining glossary entries

To use an entry from a glossary you first need to define it. There are few ways to define an entry depending on what you define and how it is going to be used.

Note that a defined entry won't be included in the printed glossary unless it is used in the document. This enables you to create a glossary of general terms and just \include it in all your documents.

Defining terms

To define a term in glossary you use the \newglossaryentry macro:

\newglossaryentry{<label>}{<settings>}

<label> is a unique label used to identify an entry in glossary, <settings> are comma separated key=value pairs used to define an entry.

For example, to define a computer entry:

\newglossaryentry{computer} { name=computer, description={is a programmable machine that receives input, stores and manipulates data, and provides output in a useful format} }

The above example defines an entry that has the same label and entry name. This is not always the case as the next entry will show:

\newglossaryentry{naiive} { name=na\"{\i}ve, description={is a French loanword (adjective, form of naïf) indicating having or showing a lack of experience, understanding or sophistication} }

When you define terms, you need to remember that they will be sorted by makeindex or xindy. While xindy is a bit more LaTeX aware, it does it by omitting latex macros (\"{\i}) thus incorrectly sorting the above example as nave. makeindex won't fare much better, because it doesn't understand TeX macros, it will interpret the word exactly as it was defined, putting it inside symbol class, before words beginning with naa. Therefore it's needed to extend our example and specify how to sort the word:

\newglossaryentry{naiive} { name=na\"{\i}ve, description={is a French loanword (adjective, form of naïf) indicating having or showing a lack of experience, understanding or sophistication}, sort=naiive }

You can also specify plural forms, if they are not formed by adding “s” (we will learn how to use them in next section):

\newglossaryentry{Linux} { name=Linux, description={is a generic term referring to the family of Unix-like computer operating systems that use the Linux kernel}, plural=Linuces }

Or, for acronyms:

\newacronym[longplural={Frames per Second}]{fpsLabel}{FPS}{Frame per Second}

This will avoid the wrong long plural: Frame per Seconds.

So far, the glossary entries have been defined as key-value lists. Sometimes, a description is more complex than just a paragraph. For example, you may want to have multiple paragraphs, itemized lists, figures, tables, etc. For such glossary entries use the command longnewglossaryentry in which the description follows the key-value list. The computer entry then looks like this:

\longnewglossaryentry{computer} { name=computer } {is a programmable machine that receives input, stores and manipulates data, and provides output in a useful format}

Defining symbols

Defined entries can also be symbols:

\newglossaryentry{pi} { name={\ensuremath{\pi}}, description={ratio of circumference of circle to its diameter}, sort=pi }

You can also define both a name and a symbol:

\newglossaryentry{real number} { name={real number}, description={include both rational numbers, such as $42$ and $\frac{-23}{129}$, and irrational numbers, such as $\pi$ and the square root of two; or, a real number can be given by an infinite decimal representation, such as $2.4871773339\ldots$ where the digits continue in some way; or, the real numbers may be thought of as points on an infinitely long number line}, symbol={\ensuremath{\mathbb{R}}} }

Note that not all glossary styles show defined symbols.

Defining acronyms

To define a new acronym you use the \newacronym macro:

\newacronym{<label>}{<abbrv>}{<full>}

where <label> is the unique label identifying the acronym, <abbrv> is the abbreviated form of the acronym and <full> is the expanded text. For example:

\newacronym{lvm}{LVM}{Logical Volume Manager}

Defined acronyms can be put in separate list if you use acronym package option:

\usepackage[acronym]{glossaries}

Using defined terms

When you have defined a term, you can use it in a document. There are many different commands used to refer to glossary terms.

General references

A general reference is used with \gls command. If, for example, you have glossary entries defined as those above, you might use it in this way:

\Gls{naiive} people don't know about alternative \gls{computer} operating systems: \glspl{Linux}, BSDs and GNU/Hurd.

Naïve people don't know about alternative computer opera- ting systems: Linuces, BSDs and GNU/Hurd.

Description of commands used in above example:

\gls{<label>}

This command prints the term associated with <label> passed as its argument. If the hyperref package was loaded before glossaries it will also be hyperlinked to the entry in glossary.

\glspl{<label>}

This command prints the plural of the defined term, other than that it behaves in the same way as gls.

\Gls{<label>}

This command prints the singular form of the term with the first character converted to upper case.

\Glspl{<label>}

This command prints the plural form with first letter of the term converted to upper case.

\glslink{<label>}{<alternate text>}

This command creates the link as usual, but typesets the alternate text instead. It can also take several options which changes its default behavior (see the documentation).

\glssymbol{<label>}

This command prints what ever is defined in \newglossaryentry{<label>}{symbol={Output of glssymbol}, ...}

\glsdesc{<label>}

This command prints what ever is defined in \newglossaryentry{<label>}{description={Output of glsdesc}, ...}

Referring acronyms

Acronyms behave a bit differently to normal glossary terms. On first use the \gls command will display "<full> (<abbrv>)". On subsequent uses only the abbreviation will be displayed. If this isn't happening, setting \setacronymstyle{long-short} is required.

To reset the first use of an acronym, use the command:

\glsreset{<label>}

or, if you want to reset the use status of all acronyms:

\glsresetall

Similarly, to unset the first use of an acronym so that only the abbreviation will be displayed, use:

\glsunset{<label>}

or, for all acronyms:

\glsunsetall

If you just want to print the long version of an acronym without the abbreviation "<full>", use :

\acrlong{<label>}

If you just want to print the long version of an acronym with the abbreviation "<full> (<abbrv>)", use :

\acrfull{<label>}

If you just want to print the abbreviation "<abbrv>", use :

\acrshort{<label>}

Displaying the Glossary

To display the sorted list of terms you need to add:

\printglossaries

at the place you want the glossary and the list of acronyms to appear.

If all entries are to be printed the command

\glsaddall

can be inserted before \printglossaries. You may also want to use \usepackage[nonumberlist]{glossaries} to suppress the location list within the glossary.

Separate Glossary and List of Acronyms

\printglossaries will display all the glossaries in the order in which they were defined. If no custom glossaries are defined, the default glossary and the list of acronyms will be displayed.

The glossary and the list of acronyms can be displayed separately in different places:

\usepackage[acronyms]{glossaries} \printglossary[type=\acronymtype] % prints just the list of acronyms Some text between the list of acronyms and the glossary. \printglossary % if no option is supplied the default glossary is printed.

Dual entries with reference to a glossary entry from an acronym

It may be useful to have both an acronym and a glossary entry for the same term. To link these two, define the acronym with a reference to the glossary entry like this:

\newglossaryentry{gls-OWD} { name={One-Way Delay}, description={The time a packet uses through a network from one host to another}, } \newacronym[see={[Glossary:]{gls-OWD}}]{OWD}{OWD}{One-Way Delay\glsadd{gls-OWD}}

Refer to acronym with \gls{OWD} and the glossary with \gls{gls-OWD}

To make this easier, we can use this command (modified from example in the official docs):

Syntax: \newdualentry[glossary options][acronym options]{label}{abbrv}{long}{description}

\usepackage{xparse} \DeclareDocumentCommand{\newdualentry}{ O{} O{} m m m m } { \newglossaryentry{gls-#3}{name={#5},text={#5\glsadd{#3}}, description={#6},#1 } \makeglossaries \newacronym[see={[Glossary:]{gls-#3}},#2]{#3}{#4}{#5\glsadd{gls-#3}} }

then, define new (dual) entries for glossary and acronym list like this:

\newdualentry{OWD} % label {OWD} % abbreviation {One-Way Delay} % long form {The time a packet uses through a network from one host to another} % description

Custom Name

The name of the glossary section can be replaced with a custom name or translated to a different language. Add the option title to \printglossary to specify the glossary's title. Add the option toctitle to specify a the title used in the table of content (if not used, title is used as default).

\printglossary[title=List of Terms,toctitle=Terms and abbreviations]

Remove the point

To omit the dot at the end of each description, use this code:

\usepackage[nopostdot]{glossaries}

Changing Glossary Entry Presentation Using Glossary Styles

A number of pre-built styles are available, and can be changed easily using

% Must be issued before \printglossaries \setglossarystyle{<newstyle>}

Commonly used styles include

• list

My Term Has some long description 7, 9

• altlist (inserts newline after term and indents description)

My Term 
   Has some long description 7, 9

• altlistgroup or listgroup (group adds grouping based on the first letters of the terms)

M
My First Term 
   Has some long description 7, 9
My Second Term 
   Has some long description 7, 9

• altlisthypergroup or listhypergroup (hyper adds an hyperlinked 'index' at the top of each glossary to jump to a group)

A|B|C|D|F|G|I|M|O|R|S|C|D|G|M|P
A
A First term 
   Has some long description 7, 9
B
Barely missed first 
   Has some long description 7, 9

Building your document

To add glossary into your final document requires:

1. build your LaTeX document — this will also generate the aux file/s required by the makeglossaries
2. invoke makeglossaries — a script which selects the correct character encodings and language settings and which will also run xindy or makeindex if these are specified in your document file
3. build your LaTeX document again — to produce a document with glossary entries

Thus:

latex doc
makeglossaries doc
latex doc

where latex is your usual build call, perhaps pdflatex, lualatex and doc is the name of your LaTeX master file without file extention. Option -d out can be used topoint where aux and other intermediate files are. If your entries are interlinked (entries themselves link to other entries with \gls calls), you will need to run steps 1 and 2 twice, that is, in the following order: 1, 2, 1, 2, 3.

Any issues will be reported in doc.log and doc.glg files.

Example for use in windows with Texmaker

Compile glossary with xindy - In Windows with Texmaker

In TeX Live and since June 2015 in MikTeX xindy is already included.

There is only one issue with path of the install directory of MikTeX containing spaces. It can be solved via the following edit: http://tex.stackexchange.com/questions/251221/miktex-and-xindy-problems/251801#251801

You need to restart Texmaker after installation of xindy, to update PATH references to xindy and Perl binaries.

Then, in Texmaker, go to User -> User Commands -> Edit User Commands.
Choose command 1

1. Menuitem = makeglossaries
2. Command = makeglossaries %

Now push Alt+Shift+F1and then ->F1

Note, for use with the "use build directory" option of Texmaker: makeglossaries needs to find the aux file. Thankfully, while Texmaker does not help there, the option -d <dir> of makeglossaries provides for the subdirectory case. Hence the Command in this case should be:
Command = makeglossaries -d build % instead.

Document preamble

In preamble should be included (note, hyperref should be loaded before the glossaries):

\usepackage[nomain,acronym,xindy,toc]{glossaries} % nomain, if you define glossaries in a file, and you use \include{INP-00-glossary}
\makeglossaries
\usepackage[xindy]{imakeidx}
\makeindex

Glossary definitions

Write all your glossaries/acronyms in a file: Ex: INP-00-glossary.tex

\newacronym{ddye}{D$_{\text{dye}}$}{donor dye, ex. Alexa 488}
\newacronym[description={\glslink{r0}{F\"{o}rster distance}}]{R0}{$R_{0}$}{F\"{o}rster distance}
\newglossaryentry{r0}{name=\glslink{R0}{\ensuremath{R_{0}}},text=F\"{o}rster distance,description={F\"{o}rster distance, where 50\% ...}, sort=R}
\newglossaryentry{kdeac}{name=\glslink{R0}{\ensuremath{k_{DEAC}}},text=$k_{DEAC}$, description={is the rate of deactivation from ... and emission)}, sort=k}

Include glossary definitions and print glossary

Include glossary definitions in the preamble (Before "\begin{document}")

\loadglsentries[main]{INP-00-glossary}
% or using \input:
%\input{INP-00-glossary}

\begin{document}

Print glossaries, near end

\appendix
\bibliographystyle{plainnat}
\bibliography{bibtex}
\printindex
\printglossaries
\end{document}

References

• The glossaries documentation, http://tug.ctan.org/tex-archive/macros/latex/contrib/glossaries/

• Using LaTeX to Write a PhD Thesis, Nicola L.C. Talbot, [1]

• glossaries FAQ, Nicola L. C. Talbot, glossaries FAQ

• Glossaries, Nomenclature, Lists of Symbols and Acronyms, Nicola L. C. Talbot, link