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:

• ifthen
• xkeyval
• xfor
• amsgen (part of amstex)
• etoolbox
• mfirstuc
• datatool-base
• tracklang

Other packages may be required depending on the settings. 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. (The latest version number can be found by checking the glossaries package information on CTAN.)

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.) However, you only need to explicitly load glossaries-extra.

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.) Note that the glossaries package uses the tracklang package to detect the required document languages and tracklang currently can’t detect babel’s \babelprovide.

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.

Package: glossaries 2020/02/13 v4.45 (NLCT)

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

Package: glossaries-extra 2020/04/01 v1.45 (NLCT)

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.

The glossaries-extra package has an additional indexing option: a Java command-line application called bib2gls, which was written specifically for glossaries-extra. This will be covered in another article as it’s a completely different approach where the glossary information is written in bib files.

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.

For example:

\newglossaryentry{culdesac}{name=cul-de-sac,
  description={passage or 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.

When you use key=value lists, if the value contains a comma or equals sign then the value must be enclosed in braces {} otherwise it will confuse the key=value list parser. The value can’t contain a paragraph break. If you have a multi-paragraph description then you need to use

\longnewglossaryentry{label}{key=value list}{description}

The first two arguments are the same as for \newglossaryentry (except that the description key is omitted). The third argument is simply the description.

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}

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={passage or street closed at one end},plural=culs-de-sac}
\begin{document}
I used to live in a \gls{culdesac}. \Gls{culdesac} is another name
for 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
for a no-through road.
\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 “Drawbacks With Defining Entries in the Document Environment”, 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.

If you do need to enable this option and you don’t have any glossaries at the start of the document, then it’s best to use the docdef=restricted rather than docdef=true option. (Note that some commands, such as \longnewglossaryentry, are never permitted in the document environment.)

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 or LuaLaTeX.) 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={passage or 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

You can simply provide your own custom text with

\glslink{label}{text}

or

\glsdisp{label}{text}

These both have the same syntax where the first argument is the entry’s label and the second is the custom text. If your document has loaded the hyperref package then the custom text will link to the corresponding place in the glossary. For example:

The \glsdisp{cow}{kine} are \glsdisp{cow}{lowing}.

However, you may prefer to have keys analogous to the plural key.

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 (plural
  cows, 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

In a later post, 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}}

With Latin alphabets, 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}}

Note that in the above example I have used \ensuremath instead of using $ to switch in and out of math mode. This means that I don’t need to keep track of what mode I’m in when using the entry, which is convenient for the auto-generated glossary. For example:

The ratio of the circumference of a circle to its diameter is given by \gls{pi}:
\begin{equation}
\gls{pi} = \frac{C}{d}
\end{equation}

For those who prefer not to use \ensuremath, the alternative is

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

This uses the text key. The commands \gls, \Gls and \GLS are all actually using the value of the text key. The value of the name key is used in the glossary, but if the text key isn’t supplied, it’s assumed to be the same as the name, which is why I haven’t used it in any of the other examples so far.

If the name key contains commands, always supply the sort key if you want an alphabetically ordered glossary (unless you are using bib2gls, but more on that in another post).

Alternatively, you can use the glossaries-extra package with the symbols option and use \glsxtrnewsymbol (described in the next part), which sets the sort key to the label by default. For example:

\glsxtrnewsymbol[description={ratio of circumference of circle to its diameter}]{pi}{\ensuremath{\pi}}

(This will add the entry to the “symbols” glossary, rather than the default “main” glossary.)

Accents and non-Latin characters

Makeindex is hard-coded for the basic Latin set of characters (A,a–Z,z), so you will need to use the sort key if the entry’s name contains accented or non-Latin characters. For example:

\newglossaryentry{attache}{name=attach\'e,sort=attache,
  description={person with special diplomatic responsibilities}}

Xindy was designed to overcome makeindex’s inflexibility and has rules for various (but not all) languages, so if you are using xindy with the above example, you don’t need the sort key with the inputenc package (or XeLaTeX/LuaLaTeX):

\newglossaryentry{attache}{name=attaché,
  description={person with special diplomatic responsibilities}}

(Remember that the label can’t include characters outside the basic Latin set, unless you’re using XeLaTeX or LuaLaTeX.)

As mentioned earlier, care must be taken with regular (PDF)LaTeX when the first character has an accent or is a non-Latin character, regardless of whether you use makeindex or xindy. This character must be enclosed in braces if you want to use it with \Gls or \Glspl. For example

\newglossaryentry{elite}{name={\'e}lite,
  description={select group or class}}

or if you are using the inputenc package:

\newglossaryentry{elite}{name={é}lite,
  description={select group or class}}

Remember that if you are using makeindex, you also need to use the sort key:

\newglossaryentry{elite}{name={\'e}lite,
  description={select group or class},sort=elite}

or

\newglossaryentry{elite}{name={é}lite,
  description={select group or class},sort=elite}

Defining an entry with both a name and a symbol

It is also possible to define an entry that has both a name and a symbol. For example:

\newglossaryentry{ohm}{name=ohm,symbol={\ensuremath{\Omega}},
  description=unit of electrical resistance}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
  description=unit of electrical resistance}

I can reference the name as usual:

\gls{ohm}

or I can reference the symbol using:

\glssymbol{ohm}

Expansion

Be careful of fragile commands when defining new terms. For historical reasons the name, description and symbol values aren’t expanded by default but all other keys are. This means that fragile commands don’t cause a problem within these keys but they will cause an error in other keys unless they are preceded by \protect or expansion is switched off for all fields with \glsnoexpandfields (before the entries are defined). For example, \si{\ohm} works fine in the symbol key above but it will cause a problem in another key (demonstrated in an example later).

Categories

The glossaries-extra package provides an extra key called category, which isn’t available with the basic glossaries package. This is set to general by default when you use \newglossaryentry. Take care not to confuse this with the type key, which separates entries into difference glossaries (described later) or the parent key (used for hierarchical entries). Entries within the same glossary may have different categories.

The category key provides a way of making some minor adjustments to the way particular entries are displayed. This is much harder to achieve with the basic glossaries package. One of these types of adjustments is the post-link hook. This is used after all the commands like \gls and \glssymbol (outside of the hyperlink, if you’re using hyperref).

Consider first the following example:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
description=unit of electrical resistance}

\begin{document}

A \gls{resistor} is an electrical component.
The \gls{ohm} is unit of resistance.

\end{document}

This produces the text:

A resistor is an electrical component. The ohm is unit of resistance.

So far this is no different from the basic glossaries package. Neither entry has been explicitly assigned a category, so the category has been set to general. I can define \glsxtrpostlinkgeneral to automatically insert extra material after each use of commands like \gls, but only for entries with the category set to general. For example:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkgeneral}{(foo)}

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
description=unit of electrical resistance}

\begin{document}

A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

\end{document}

This now produces the text:

A resistor(foo) is an electrical component. The ohm(foo) is a unit of resistance.

This example is, of course, a little silly. It would be more practical to, say, access one of the fields. Suppose I want to insert the description instead. I can reference an entry’s description using:

\glsentrydesc{label}

For example \glsentrydesc{resistor}. The post-link hook can access the label of the last referenced entry using \glslabel. So here’s the updated example:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkgeneral}{ (\glsentrydesc{\glslabel})}

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
description=unit of electrical resistance}

\begin{document}

A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

\end{document}

This now produces the text:

A resistor (component that implements electrical resistance) is an electrical component. The ohm (unit of electrical resistance) is a unit of resistance.

Now let’s suppose I want to designate the ohm entry as a unit of measurement. I can use the category key. The value is just another form of label that you can make up, but (as with all the labelling systems) it mustn’t contain any special characters. Remember that this includes Unicode characters, unless you’re using XeLaTeX or LuaLaTeX.

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkgeneral}{ (\glsentrydesc{\glslabel})}

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
category=unit,% category label
description=unit of electrical resistance}

\begin{document}
A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

\end{document}

This produces the text:

A resistor (component that implements electrical resistance) is an electrical component. The ohm is a unit of resistance.

Only the resistor entry has the post-link text because that has the category set to general. I can change this around so that only the unit category has some post-link text, and I’m now going to use the value of the symbol field instead of the description:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkunit}{ (\glsentrysymbol{\glslabel})}% post-link for the "unit" category

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
category=unit,% category label
description=unit of electrical resistance}

\begin{document}
A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

\end{document}

Note that I’ve used \glsentrysymbol here, instead of \glssymbol. The \glsentry… commands should be used in this context to avoid triggering an infinite loop. This now produces the text:

A resistor is an electrical component. The ohm (Ω) is a unit of resistance.

A slight modification to the example document shows up some flaws:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkunit}{ (\glsentrysymbol{\glslabel})}% post-link for the "unit" category

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
category=unit,
description=unit of electrical resistance}

\begin{document}

A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

Symbol: \glssymbol{ohm} and let’s mention \gls{ohm} again.

\end{document}

This produces the text:

A resistor is an electrical component. The ohm (Ω) is a unit of resistance.
Symbol: Ω (Ω) and let’s mention ohm (Ω) again.

The \glssymbol command also uses the post-link hook, and it’s a bit repetitive to insert the symbol on every use of \gls.

The first problem can be overcome by testing \glscustomtext. If it’s empty, then \gls (or \glspl, \Gls, etc) has been used. It’s not empty if one of the other commands, such as \glssymbol, has been used. The etoolbox package provides \ifdefempty and conveniently the glossaries (and therefore glossaries-extra) package loads etoolbox.

So, to only insert the symbol after the \gls-like commands:

\newcommand*{\glsxtrpostlinkunit}{%
 \ifdefempty\glscustomtext{ (\glsentrysymbol{\glslabel})}{}}

The other problem requires testing if the entry was just used for the first time. Each entry has a “first use” flag, which is unset by \gls, \glspl, \Gls, \Glspl, \GLS, \GLSpl and \glsdisp. If this flag is false (unset), it means the entry has already been referenced using one of those commands. (The entry has been be marked as used.) If this flag is true (set), it means the entry hasn’t yet been referenced using one of those commands. (The next instance will be the first use of that entry.)

The glossaries package provides a command for testing this flag, but by the time the post-link hook occurs, the flag has already been unset. There’s another command specifically available for the post-link hook and that’s \glsxtrifwasfirstuse{true}{false}, so I could do:

\glsxtrifwasfirstuse{ (\glsentrysymbol{\glslabel})}{}

However, there’s a shortcut command that makes the code simpler:

\glsxtrpostlinkAddSymbolOnFirstUse

If the symbol key has been set, this will append a space followed by the symbol in parentheses on first use. So the modified example is now:

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries-extra}

\newcommand*{\glsxtrpostlinkunit}{%
 \ifdefempty\glscustomtext{\glsxtrpostlinkAddSymbolOnFirstUse}{}}

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
category=unit,% category label
description=unit of electrical resistance}

\begin{document}
A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

Symbol: \glssymbol{ohm} and let’s mention \gls{ohm} again.

\end{document}

This now produces the text:

A resistor is an electrical component. The ohm (Ω) is a unit of resistance.
Symbol: Ω and let’s mention ohm again.

As from glossaries-extra version 1.3, you can use

\glsdefpostlink{category}{definition}

instead of

\newcommand*{\glsxtrpostlinkcategory}{definition}

For example:

\glsdefpostlink{unit}{\ifdefempty\glscustomtext{\glsxtrpostlinkAddSymbolOnFirstUse}{}}

With just the basic glossaries package, without the category post-link hook, this example could be done using the first key, which is used by \gls on first use (and the text key is then used on subsequent use).

\documentclass{article}

\usepackage{siunitx}
\usepackage{glossaries}

\glsnoexpandfields

\newglossaryentry{resistor}{name={resistor},
 description={component that implements electrical resistance}}

\newglossaryentry{ohm}{name=ohm,symbol={\si{\ohm}},
first={ohm (\si{\ohm})},
description=unit of electrical resistance}

\begin{document}
A \gls{resistor} is an electrical component.
The \gls{ohm} is a unit of resistance.

Symbol: \glssymbol{ohm} and let’s mention \gls{ohm} again.

\end{document}

This is less flexible and, if you include the hyperref package, the entire contents of the first key will be included in the hyperlink. Whereas the glossaries-extra example will have the parenthetical material (\si{\ohm}) outside the hyperlink.

Abbreviations

The first key mentioned above can also be used for abbreviations. For example:

\newglossaryentry{led}{name=LED,description={light-emitting
diode},first={light-emitting diode (LED)}}

However, hard-coding the abbreviation style like this makes it harder to change the style. You might, for example, want to have the abbreviation first followed by the long form in parentheses. It’s a bit of a nuisance having to edit all the first fields, especially if you have a lot of entries.

The glossaries package provides an easier way of doing this with

\newacronym[options]{label}{short}{long}

This internally uses \newglossaryentry. If the optional argument is present, those options are appended to the second argument of \newglossaryentry.

Here’s an example document using the basic glossaries package:

\documentclass{article}

\usepackage{glossaries}

\setacronymstyle{long-short}

\newacronym{led}{LED}{light-emitting diode}

\begin{document}

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

\end{document}

This produces the text:

First use: light-emitting diode (LED). Next use: LED.

Now the first use format can be changed by changing the style. For example:

\setacronymstyle{short-long}

This must be set before the abbreviations are defined.

Another style is long-sc-short which uses \textsc to typeset the short form. Remember that this command uses small capitals for lowercase letters, so the short form needs to be converted to lowercase. You can either do this manually, for example

\newacronym{led}{led}{light-emitting diode}

or you can redefine \acronymfont to do the conversion. For example:

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage{glossaries}

\setacronymstyle{long-sc-short}

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

\newacronym{led}{LED}{light-emitting diode}

\begin{document}

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

\end{document}

(This redefinition must be done after the style is set.)

You can access the short and long forms using

\acrlong{label}

and

\acrshort{label}

(analogous to the \glssymbol command used earlier) or using

\glsentryshort{label}

and

\glsentrylong{label}

(analogous to the \glsentrysymbol command used earlier).

There are some drawbacks to the glossaries package’s abbreviation management. One of which is that only one style can be selected for all the defined abbreviations. So you can only have, for example, long-short or only short-long, but not a mixture of some with long-short and others with short-long.

The glossaries-extra package provides a different abbreviation management system that allows mixed styles. The abbreviations are now defined using

\newabbreviation[options]{label}{short}{long}

This sets the category to abbreviation by default. The \newacronym command provided by the base glossaries package is changed to use this new interface, but the category is set to acronym. So

\newacronym[options]{label}{short}{long}

is now the same as

\newabbreviation[category=acronym,options]{label}{short}{long}

The style is set (before the abbreviations are defined) using

\setabbreviationstyle[category]{style}

If the optional argument is omitted, abbreviation is used, so

\setabbreviationstyle{long-short}

sets the long-short style for all abbreviations with the category set to abbreviation and

\setabbreviationstyle[acronym]{short-long}

sets the short-long style for all abbreviations with the category set to acronym.

For example:

\documentclass{article}

\usepackage{glossaries-extra}

\setabbreviationstyle{long-short}
\setabbreviationstyle[acronym]{short-long}

\newabbreviation{led}{LED}{light-emitting diode}
\newacronym{laser}{laser}{light amplification by stimulated
emission of radiation}

\begin{document}

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

First use: \gls{laser}. Next use: \gls{laser}.
\end{document}

This produces the text:

First use: light-emitting diode (LED). Next use: LED.
First use: laser (light amplification by stimulated emission of radiation). Next use: laser.

The abbreviation style names provided by glossaries-extra don’t always have the same names as the closest equivalent acronym style provided by glossaries. The equivalent to the long-sc-short (glossaries) acronym style used earlier is the long-short-sc (glossaries-extra) abbreviation style, but now the font used by the short form is accessed through \glsxtrscfont not \acronymfont. As in the earlier example, this can be redefined to automatically lowercase the short version if required:

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage{glossaries-extra}

\setabbreviationstyle{long-short-sc}
\setabbreviationstyle[acronym]{short-long}

\renewcommand*{\glsxtrscfont}[1]{\textsc{\MakeLowercase{#1}}}

\newabbreviation{led}{LED}{light-emitting diode}
\newacronym{laser}{laser}{light amplification by stimulated
emission of radiation}

\begin{document}

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

First use: \gls{laser}. Next use: \gls{laser}.
\end{document}

The formatted short and long forms are now accessed using

\glsxtrshort{label}

and

\glsxtrlong{label}

(analogous to \acrshort and \acrlong). The unformatted values can also still be accessed using \glsentryshort and \glsentrylong. If you want to use the short or long form in a chapter or section title or caption, use:

\glsfmtshort{label}

and

\glsfmtlong{label}

instead. These commands aren’t available with the base glossaries package.

If you don’t want the full form on first use then you can use one of the glossaries-extra “nolong” abbreviation styles, such as short-sc-nolong. In fact, the default abbreviation style for the acronym category is short-nolong. So if you remove the second \setabbreviationstyle command from the above example, the first use of \gls{laser} will simply show the short form. If necessary, you can access the full form later in the document with

\glsxtrfull{label}

Again there is an alternative for use in headings or captions:

\glsfmtfull{label}

Don’t use any of the commands like \gls, \glsxtrshort, \glsxtrlong, \acrshort or \acrlong in chapter or section headings or captions. With glossaries-extra, use the \glsfmt... alternatives. With just the base glossaries package, use the \glsentry... alternatives.

As with \newglossaryentry, the warning about nested links still applies. Don’t use commands like \gls within the long or short form as they can cause multiple problems. For example:

\documentclass{article}

\usepackage{glossaries}

\setacronymstyle{long-short}

\newacronym{ssi}{SSI}{server-side includes}
\newacronym{html}{HTML}{hypertext markup language}
\newacronym{shtml}{SHTML}{SSI enabled HTML}

\begin{document}

First use: \gls{ssi}, \gls{html} and \gls{shtml}.

Next use: \gls{ssi}, \gls{html} and \gls{shtml}.

\end{document}

If you want the same font as the short forms (for example, you’re using the small-caps style), then you can incorporate the font changing command, for example, with just glossaries:

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage{glossaries}

\setacronymstyle{long-sc-short}

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

\newacronym{ssi}{SSI}{server-side includes}
\newacronym{html}{HTML}{hypertext markup language}
\newacronym{shtml}{SHTML}{\acronymfont{SSI} enabled \acronymfont{HTML}}

\begin{document}

First use: \gls{ssi}, \gls{html} and \gls{shtml}.

Next use: \gls{ssi}, \gls{html} and \gls{shtml}.

\end{document}

Or with glossaries-extra:

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage{glossaries-extra}

\setabbreviationstyle{long-short-sc}

\renewcommand*{\glsxtrscfont}[1]{\textsc{\MakeLowercase{#1}}}

\newabbreviation{ssi}{SSI}{server-side includes}
\newabbreviation{html}{HTML}{hypertext markup language}
\newabbreviation{shtml}{SHTML}{\glsxtrscfont{SSI} enabled \glsxtrscfont{HTML}}

\begin{document}

First use: \gls{ssi}, \gls{html} and \gls{shtml}.

Next use: \gls{ssi}, \gls{html} and \gls{shtml}.

\end{document}

The glossaries-extra package performs some patches that overcomes some, but not all, of the problems with nested entry references, so with glossaries-extra, if you really need to, you may be able to use \glsxtrshort, for example:

\newabbreviation{shtml}{SHTML}{{}\glsxtrshort{ssi} enabled \glsxtrshort{html}}

The initial empty group is protection against any use of the first letter uppercasing commands, such as \Gls. You can’t do the equivalent with just the basic glossaries package. If you have at least version 1.07 of glossaries-extra, then you can instead use:

\newabbreviation{shtml}{SHTML}{{}\glsps{ssi} enabled \glsps{html}}

which offers additional protection over simply using \glsxtrshort.

The acronym styles provided by the base glossaries package aren’t the same as the abbreviation styles provided by the glossaries-extra package so, although you can use \newacronym with glossaries-extra (as above), you can’t use \setacronymstyle, but must use \setabbreviationstyle[acronym] instead.

The available acronym styles provided by glossaries are described in Predefined Acronym Styles and the available abbreviation styles provided by the glossaries-extra package are described in Predefined Abbreviation Styles. In some cases, the styles share the same name (such as long-short), but they are implemented differently. The glossaries-extra package comes with a sample document sample-abbr-styles.pdf that demonstrates all abbreviation styles.

Both the basic glossaries package and the glossaries-extra package provide shorter synonyms for commands. In both packages they can be enabled using the shortcuts package option. For example:

\documentclass{article}

\usepackage[shortcuts]{glossaries}

\setacronymstyle{long-short}

\newacronym{led}{LED}{light-emitting diode}
\newacronym{laser}{laser}{light amplification by stimulated
emission of radiation}

\begin{document}
First use: \ac{led}. Next use: \ac{led}.

First use: \ac{laser}. Next use: \ac{laser}.

Long form: \acl{led}. Short form: \acs{led}.

\end{document}

Or

\documentclass{article}

\usepackage[shortcuts=abbr]{glossaries-extra}

\setabbreviationstyle{long-short}
\setabbreviationstyle[acronym]{short-long}

\newabbr{led}{LED}{light-emitting diode}
\newacronym{laser}{laser}{light amplification by stimulated
emission of radiation}

\begin{document}

First use: \ab{led}. Next use: \ab{led}.

First use: \ab{laser}. Next use: \ab{laser}.

Long form: \al{led}. Short form: \as{led}.
\end{document}

Other related commands are described in the glossaries manual and the glossaries-extra manual.

Next part: Multiple Glossaries