[Tex/LaTex] Best solution for acronyms, abbreviations, glossary and index

Question

I am writing a scientific text/book which will contain acronyms, which should have a glossary and should also have an index. The question is: which LaTeX setup is best for this? Which are the best packages, etc.

Obviously some of the problems are overlapping.

• I want to have a glossary where I explain some terms or where I give a one sentence explanation and refer to the section where the term is discussed in detail.
• For some of these terms it might be common to use the acronym/abbreviation. Examples are HTTP, TCP or Dow Jones.
• Other terms are usually written out, but I might want to use an abbreviation (in some sections) because they appear often or because they are so lengthy. (Examples: Distributed Event-Based System: DEBS or Peer-to-Peer: P2P)
• I want to have a List of Abbreviations and Acronyms.
• I also want to have a Glossary where some of the acronyms/abbreviations appear, but not all.
• I also want to have an index that links to the relevant pages where some of the index terms appear. It should also be possible for the index to contain terms that do not appear in the glossary or acronym list.

Searching for possibilities to achieve this I found several partial solutions, but I am not sure how they will work together, especially since some seem to overlap.

• acronym package
  • seems to be quite common and powerful when it comes to acronyms – maybe ever a little overkill.
  • unclear how to make use of it for index/glossary purposes
• glossaries package
  • supports glossaries nicely
  • also supports acronyms. But how can I define acronyms that should not appear in the glossary, but some should appear in the glossary
  • seems to work well with hyperref
  • uses makeindex
• index with makeindex, \index{..} and \printindex
  • is build-in in LaTeX
  • can I combine it with the glossaries package?
• other glossary packages like makeglos, gloss, glossary, glosstex
• other acronym packages like nomencl
• other index packages like makeidx

So there are many solutions, but which is the best?

Answer 1

• I want to have a glossary where I explain some terms or where I give a one sentence explanation and refer to the section where the term is discussed in detail.

With the glossaries package, each term is first defined (in the preamble if you don't want nasty surprises that can occur in certain circumstances) using \newglossaryentry. For example:

\newglossaryentry{duck}{name=duck,
  description={a waterbird with webbed feet}}

\newglossaryentry{parrot}{name=parrot,
  description={mainly tropical bird with bright plumage}}

(Make sure you use braces { } around the values if they contain a comma , or equal sign =.)

The first argument is a label (avoid special characters) so that you can reference the term in the document text. For example:

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

Use \printglossaries where you want all the glossaries, lists of abbreviations etc to occur. These are displayed in order that each type of glossary was defined (the default main is usually first), but if you want to change the ordering or have some in the front matter and some in the back matter you'll need to use \printglossary and specify the type in the optional argument.

Complete minimal example:

% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
\documentclass{article}

\usepackage{glossaries}

\makeglossaries

\newglossaryentry{duck}{name=duck,%
  description={a waterbird with webbed feet}}

\newglossaryentry{parrot}{name=parrot,%
  description={mainly tropical bird with bright plumage}}


\begin{document}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

\printglossaries

\end{document}

The comments at the start are arara directives. If you don't use arara, you can remove those lines. If you do use arara, then you can build the complete document using arara myDoc where the document is in the file myDoc.tex. If you're not using arara, you can build the document using

pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc

The makeglossaries application is actually a Perl script, so you'll need Perl installed if you want to use it. If you don't have Perl installed, you can use a Lua alternative instead:

makeglossaries-lite myDoc

(The advantage of makeglossaries is that it has some diagnostic tools to check for common problems.) This Lua script is actually distributed with the filename makeglossaries-lite.lua but the TeX distributions usually arrange it so that you don't use the .lua extension.

For help integrating makeglossaries or makeglossaries-lite into your document build process, see Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.

If you're still stuck, another possibility is to use the automake package option:

\usepackage[automake]{glossaries}

This just requires two LaTeX calls for the above example. Note that you can't use this if the shell escape has been disabled. (For a large document, it's more efficient to just call makeglossaries or makeglossaries-lite when the glossaries need updating rather than use automake which tries to rebuild them on every LaTeX run.)

The above example produces:

The number 1 that appears after the description is the page number where the term was referenced. You can change the counter used with the counter package option. For example, to switch to the section counter:

\usepackage[counter=section]{glossaries}

or you can completely omit the number lists using the nonumberlist package option.

If you're really stuck and you're happy to omit the location numbers and do the sorting manually, then you can use \printunsrtglossary (or \printunsrtglossaries) provided by glossaries-extra:

\documentclass{article}

\usepackage[sort=none]{glossaries-extra}

\newglossaryentry{duck}{name=duck,%
  description={a waterbird with webbed feet}}

\newglossaryentry{parrot}{name=parrot,%
  description={mainly tropical bird with bright plumage}}

\begin{document}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

\printunsrtglossaries

\end{document}

In this case the entries must be defined in the preamble (or using the package option docdefs=restricted they can be defined in the document anywhere before they are referenced and before the glossary). This method doesn't perform any indexing and simply iterates over all defined entries (so they must be defined first) in the order in which they were defined. There's no check to determine if the entries have actually been used in the document.

Note that the sentence terminating dot hasn't been automatically inserted after the description in this case. With glossaries-extra you need to use the package option postdot or nopostdot=false to add it.

The sort=none option may be omitted (\printunsrtglossary is always according to definition) but this option prevents the automated assignment of the sort field, which isn't required in this case. (It's not significant for such a small example.)

An alternative approach is to use glossaries-extra with bib2gls. This requires entries to be defined in .bib files, which means that if you have a large set of terms that you commonly use in your documents then you can use a .bib management system like JabRef to organise your definitions. (Both bib2gls and JabRef require Java.)

For example, the file entries.bib might contain:

% Encoding: UTF-8
@entry{duck,
  name = {duck},
  description = {a waterbird with webbed feet}
}

@entry{parrot,
  name = {parrot},
  description = {mainly tropical bird with bright plumage}
}

(I can create this entries.bib file from my earlier myDoc.tex file using convertgls2bib myDoc.tex entries.bib which searches for commands like \newglossaryentry and converts them to the require .bib format.)

I now need to edit myDoc.tex to become:

\documentclass{article}

\usepackage[record]{glossaries-extra}

\GlsXtrLoadResources[src={entries}]

\begin{document}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

\printunsrtglossaries

\end{document}

The build process is now:

pdflatex myDoc
bib2gls myDoc
pdflatex myDoc

If letter groups are required then you need --group (or -g):

bib2gls --group myDoc

and a glossary style that supports groups. For example:

\documentclass{article}

\usepackage[record,style=indexgroup]{glossaries-extra}

\GlsXtrLoadResources[src={entries}]

\begin{document}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

\printunsrtglossaries

\end{document}

• For some of these terms it might be common to use the acronym/abbreviation. Examples are HTTP, TCP or Dow Jones.
• Other terms are usually written out, but I might want to use an abbreviation (in some sections) because they appear often or because they are so lengthy. (Examples: Distributed Event-Based System: DEBS or Peer-to-Peer: P2P)
• I want to have a List of Abbreviations and Acronyms.

Abbreviations and acronyms can be defined with \newacronym. This internally uses \newglossaryentry and assigns a long and short form. The first argument is optional and can be used to provide additional fields for the second argument of \newglossaryentry. With just the base glossaries package, you can set the style using \setacronymstyle but this needs to be done before you define the terms. If you want a separate list of acronyms/abbreviations you can use the acronym package option. For example:

\documentclass{article}

\usepackage[acronym]{glossaries}

\makeglossaries

\newglossaryentry{duck}{name=duck,
  description={a waterbird with webbed feet}}

\newglossaryentry{parrot}{name=parrot,
  description={mainly tropical bird with bright plumage}}

\setacronymstyle{long-short}

\newacronym{debs}{DEBS}{Distributed Event-Based System}
\newacronym{p2p}{P2P}{Peer-to-Peer}

\begin{document}
\section{Sample}

First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
\gls{p2p}.

\section{Another Sample}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

\printglossaries

\end{document}

This produces:

Note that this expands on first use and uses the abbreviated form on subsequent use. (You can reset this if required.)

For abbreviations that shouldn't be expanded, there are three approaches:

1. Define them with \newacronym and then unset them (which pretends they have already been used):

   \documentclass{article}
   
   \usepackage[acronym]{glossaries}
   
   \makeglossaries
   
   \newglossaryentry{duck}{name=duck,
     description={a waterbird with webbed feet}}
   
   \newglossaryentry{parrot}{name=parrot,
     description={mainly tropical bird with bright plumage}}
   
   \setacronymstyle{long-short}
   
   \newacronym{debs}{DEBS}{Distributed Event-Based System}
   \newacronym{p2p}{P2P}{Peer-to-Peer}
   
   \newacronym{http}{HTTP}{Hypertext Transfer Protocol}
   \glsunset{http}
   
   \begin{document}
   \section{Sample}
   
   First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
   \gls{p2p}.
   
   No expansion: \gls{http}.
   
   \section{Another Sample}
   
   A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.
   
   \printglossaries
   
   \end{document}
   

2. Define them as a regular term but use the type key to put them in the list of abbreviations/acronyms:

   \documentclass{article}
   
   \usepackage[acronym]{glossaries}
   
   \makeglossaries
   
   \newglossaryentry{duck}{name=duck,
     description={a waterbird with webbed feet}}
   
   \newglossaryentry{parrot}{name=parrot,
     description={mainly tropical bird with bright plumage}}
   
   \setacronymstyle{long-short}
   
   \newacronym{debs}{DEBS}{Distributed Event-Based System}
   \newacronym{p2p}{P2P}{Peer-to-Peer}
   
   \newglossaryentry{http}{name=HTTP,
    type=\acronymtype,
    description={Hypertext Transfer Protocol}}
   
   \begin{document}
   \section{Sample}
   
   First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
   \gls{p2p}.
   
   No expansion: \gls{http}.
   
   \section{Another Sample}
   
   A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.
   
   \printglossaries
   
   \end{document}
   

3. Use the extension package glossaries-extra, which allows different abbreviation styles. This package provides \newabbreviation to define an abbreviation with the entry's category (a new key provided by glossaries-extra) set to abbreviation and redefines glossaries's \newacronym to use \newabbreviation with the category set to acronym (and the type set to \acronymtype). The abbreviation style is set using \setabbreviationstyle[category]{style} (not \setacronymstyle). The default style for the abbreviation category is long-short and the default style for the acronym category is short, so we can just use \newabbreviation for the abbreviations that need expansion on first use and \newacronym for abbreviations that don't need expansion on first use.

   \documentclass{article}
   
   \usepackage[abbreviations]{glossaries-extra}
   
   \makeglossaries
   
   \newglossaryentry{duck}{name=duck,
     description={a waterbird with webbed feet}}
   
   \newglossaryentry{parrot}{name=parrot,
     description={mainly tropical bird with bright plumage}}
   
   \newabbreviation{debs}{DEBS}{Distributed Event-Based System}
   \newabbreviation{p2p}{P2P}{Peer-to-Peer}
   
   \newacronym{http}{HTTP}{Hypertext Transfer Protocol}
   
   \begin{document}
   \section{Sample}
   
   First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
   \gls{p2p}.
   
   No expansion: \gls{http}.
   
   \section{Another Sample}
   
   A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.
   
   \printglossaries
   
   \end{document}
   

4. With bib2gls, the earlier entries.bib supplies the terms (duck and parrot) and the abbreviations can be stored in another .bib file called, say, abbrvs.bib:

   % Encoding: UTF-8
   @abbreviation{debs,
     short = {DEBS},
     long = {Distributed Event-Based System}
   }
   
   @abbreviation{p2p,
     short = {P2P},
     long = {Peer-to-Peer}
   }
   

   and the common abbreviation in common.bib:

   % Encoding: UTF-8 
   @acronym{http,
     short = {HTTP},
     long = {Hypertext Transfer Protocol}
   }
   

   (or they can be combined in the same file). The document is now:

   \documentclass{article}
   
   \usepackage[record,abbreviations]{glossaries-extra}
   
   \GlsXtrLoadResources[src={entries}]
   
   \GlsXtrLoadResources[src={abbrvs,common}]
   
   \begin{document}
   \section{Sample}
   
   First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
   \gls{p2p}.
   
   No expansion: \gls{http}.
   
   \section{Another Sample}
   
   A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.
   
   \printunsrtglossaries
   
   \end{document}
   

The first two examples both produce:

The third and fourth examples produce:

The only differences here are the missing post-description dot (which can be added with postdot) and the title of the list of abbreviations. This is because I used the abbreviations package option. If I'd used acronym (or acronyms) instead, I would have to add the line

\renewcommand{\glsxtrabbrvtype}{\acronymtype}

to ensure the abbreviations defined using \newabbreviation are placed in the acronym glossary (otherwise they'd end up in the main glossary).

Alternatively, (with glossaries-extra) instead of using \newacronym, you can provide your own category and use \newabbreviation, which ensures it's placed in the same glossary list as the other abbreviations. For example:

\setabbreviationstyle[common]{short}

to set the abbreviation style for the common category and

\newabbreviation[category=common]{http}{HTTP}{Hypertext Transfer Protocol}

or

@abbreviation{http,
  short = {HTTP},
  long = {Hypertext Transfer Protocol},
  category={common}
}

to define the abbreviation. Alternatively, you can instruct bib2gls to set the category field to the base name of the corresponding .bib file. For example, if the general abbreviations are now in abbreviation.bib and the common abbreviations are in common.bib then you can use:

    \GlsXtrLoadResources[src={abbreviation,common},
     category={same as base}]

• I also want to have a Glossary where some of the acronyms/abbreviations appear, but not all.

You can use the type key to put terms into a specific glossary. You can also create an "ignored" glossary, in which you can put any entries you want to reference but don't want listed. For example, to create an ignored glossary labelled "ignored":

\newignoredglossary{ignored}

Now you can define terms to go in it. For example:

\newacronym[type=ignored]{p2p}{P2P}{Peer-to-Peer}

Or with glossaries-extra:

\newabbreviation[type=ignored]{p2p}{P2P}{Peer-to-Peer}

Or with bib2gls, the easiest way is to move the ignored abbreviations to another file, say, ignored.bib and use:

\GlsXtrLoadResources[src={entries}]% main terms
\GlsXtrLoadResources[src={abbrvs,common}]% abbrvs.bib and common.bib
\GlsXtrLoadResources[src={ignored},% ignored.bib
   type={ignored},% put them in the `ignored` glossary
   sort={none},% don't bother sorting
   save-locations=false% don't bother saving the locations
]

(If you want to keep them in the same abbrvs.bib file you can apply pattern matching in the selection, but that's more complicated.)

• I also want to have an index that links to the relevant pages where some of the index terms appear. It should also be possible for the index to contain terms that do not appear in the glossary or acronym list.

You can use the index package option

\usepackage[index]{glossaries}

which will create a new glossary labelled index and will also define the command \newterm, which is a shortcut for \newglossaryentry that defines a term without a description and uses type=index to add it to the index glossary. For example:

\newterm{hippo}
\newterm[plural=geese]{goose}

If the term contains any special characters, you'll need to use the name key in the optional argument and strip the special characters from the mandatory argument. For example:

\newterm[name={ch\^ateau},plural={ch\^ateaux}]{chateau}

With bib2gls you can use:

@index{hippo}
@index{goose,plural={geese}}
@index{chateau,name={ch\^ateau},plural={ch\^ateaux}}

(With XeLaTeX or LuaLaTeX you can use UTF-8 characters in the label but with inputenc you can't.)

The best style for displaying an index is bookindex, which is provided by the glossary-bookindex.sty distributed with glossaries-extra. This doesn't show the description, so even with the earlier @entry examples, it will still only show the name and location list.

bib2gls has special dual entries that essentially define two linked entries. If one is referenced in the text then the other is automatically selected. Suppose I have a file called terms.bib that contains:

@index{hippo}
@index{goose,plural={geese}}
@index{chateau,name={ch\^ateau},plural={ch\^ateaux}}
@dualindexentry{duck,
 name = {duck},
 description = {a waterbird with webbed feet}
}
@dualindexentry{parrot,
 name = {parrot},
 description = {mainly tropical bird with bright plumage}
}
@dualindexabbreviation{debs,
  short = {DEBS},
  long = {Distributed Event-Based System}
}
@dualindexabbreviation{p2p,
 short = {P2P},
 long = {Peer-to-Peer}
}
@dualindexabbreviation{http,
 short = {HTTP},
 long = {Hypertext Transfer Protocol},
 category={common}
}

Then the document can be changed to:

\documentclass{article}

\usepackage[colorlinks]{hyperref}
\usepackage[record,% using bib2gls
 index,% create 'index' glossary
 abbreviations,% create 'abbreviations' glossary
 postdot,% insert dot after descriptions
 nostyles,%don't load predefined styles
 stylemods={tree,bookindex},% load the 'tree' and 'bookindex' style packages
 style={tree}% set the default style to 'tree'
]{glossaries-extra}

\setabbreviationstyle[common]{short} % set abbreviation style before \GlsXtrLoadResources

\GlsXtrLoadResources[
 src={terms},% data in terms.bib
 label-prefix={idx.},% prefix for primary entry labels
 dual-prefix={},% prefix for dual entry labels
 type=index,% put primary entries in 'index' glossary
 combine-dual-locations={primary}% merge locations and assign to primary list
]

% provide commands that work like \gls etc for the @index entries
% (that don't have a dual counterpart)
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}

\begin{document}
\section{Sample}

First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
\gls{p2p}.

No expansion: \gls{http}.

\section{Another Sample}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.
\Idx{hippo}, \idxpl{goose} and a \idx{chateau}.

\printunsrtglossary % main glossary
\printunsrtglossary[type=abbreviations]% list of abbreviations
\printunsrtglossary[type=index,style=bookindex] % index

\end{document}

This produces:

It's not particularly convenient to have to edit the .bib files to substitute @entry with @dualindexentry and @abbreviation with @dualindexabbreviation, so bib2gls allows aliasing with the entry-type-aliases, which makes bib2gls treat the given entry types as though they were actually defined with the aliased type:

\GlsXtrLoadResources[
 src={entries,abbrvs,generalterms},% data in entries.bib, abbrvs.bib and generalterms.bib
 label-prefix={idx.},% prefix for primary entry labels
 dual-prefix={},% prefix for dual entry labels
 type=index,% put primary entries in 'index' glossary
 combine-dual-locations={primary},% merge locations and assign to primary list
 entry-type-aliases={
   entry=dualindexentry, % make @entry behave like @dualindexentry
   abbreviation=dualindexabbreviation % make @abbreviation behave like @dualindexabbreviation
 }
]

Alternatively, just use one of the indexing packages, such as makeidx or imakeidx. With makeidx you'll need an extra step in the build process that runs the makeindex application. This can be done after makeglossaries (and should be done after rather than before makeglossaries if \index occurs any of the glossary lists). The imakeidx package runs makeindex through the shell escape.

For example:

\documentclass{report}

\usepackage{imakeidx}
\usepackage[abbreviations]{glossaries-extra}

\makeglossaries
\makeindex

\newglossaryentry{duck}{name=duck,
  description={a waterbird with webbed feet}}

\newglossaryentry{parrot}{name=parrot,
  description={mainly tropical bird with bright plumage}}

\newabbreviation{debs}{DEBS}{Distributed Event-Based System}
\newabbreviation{p2p}{P2P}{Peer-to-Peer}

\setabbreviationstyle[common]{short}
\newabbreviation[category=common]{http}{HTTP}{Hypertext Transfer Protocol}

\begin{document}
\chapter{Sample}

First use \gls{debs} and \gls{p2p}. Next use: \gls{debs} and
\gls{p2p}.

No expansion: \gls{http}.

\chapter{Another Sample}

A \gls{duck} and a \gls{parrot}. Lots of \glspl{duck}.

Index aardvark\index{aardvark}.

\printglossaries
\printindex

\end{document}

The glossaries-extra package provides a way of automatically indexing entries so they appear both in the glossary list and the index. For example, if I add

\glssetcategoryattribute{common}{dualindex}{true}

to the preamble, then the HTTP entry (that has the category set to common) referenced on page 1 will also appear in the index. Alternatively, I can use:

\glssetcategoryattribute{common}{indexname}{true}

which will instead index the page where HTTP occurs in the list of abbreviations. If I want to change the encap (how the page number is formatted in the index), then I can replace true with the encap value. For example:

\glssetcategoryattribute{common}{indexname}{textbf}

There are various different glossary styles see, for example, the glossaries gallery.