Gallery: Brief Descriptions

image of glossary with one or two word descriptions

This example has brief descriptions, which look best with a compact glossary style, so the mcolindex style is used. This isn’t available by default, so you need to remember to load the glossaries-mcol package.

The first four comment lines below are arara directives. You can remove them if you don’t use arara.

% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
% arara: pdflatex
\documentclass[oneside]{book}

\usepackage[colorlinks]{hyperref}
\usepackage[nopostdot,toc]{glossaries}
\usepackage{glossary-mcols}

\makeglossaries

\loadglsentries{example-glossaries-brief}

\title{Sample Document}
\author{Nicola Talbot}

\begin{document}

\pagenumbering{alph}
\maketitle

\frontmatter
\tableofcontents

\mainmatter

\chapter{Sample Entries}

\forglsentries{\thislabel}{\gls{\thislabel}. }

\printglossary[style=mcolindex]

\end{document}

This document loads the hyperref package, which creates hyperlinks from the entries in the document (referenced using commands like \gls) to their definition in the glossary. These hyperlinks are displayed in red text by default (with the colorlinks option). I’ve used \forglsentries for this example to iterate over all the defined entries. In practice, you would typically just use commands like \gls{label} in the text. For example:

Here is a reference to the term \gls{lorem}.

The entries have all been defined in the file example-glossaries-brief.tex, which you should find installed in the same location as the glossaries package (or in a sub-directory called test-entries). The file can be input using either \loadglsentries or \input (but not \include). The entry definitions look like this:

\newglossaryentry{lorem}{name={lorem},description={ipsum}}

\newglossaryentry{dolor}{name={dolor},description={sit}}

\newglossaryentry{amet}{name={amet},description={consectetuer}}

If you don’t use arara, you need to run the following commands:

pdflatex brief-descriptions
makeglossaries brief-descriptions
pdflatex brief-descriptions
pdflatex brief-descriptions

(See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.)

I’ve used the toc option to add the glossary to the table of contents (which is automatically generated with \tableofcontents). I’ve also used the nopostdot option to remove the terminating full stop (period) that is placed by default after the descriptions (since they don’t form complete sentences). The entries all have a “1” after the description. This is the page number on which the entry was referenced. In this sample document all the entries were referenced on page 1. If you don’t want these numbers to appear, use the nonumberlist option.

Care needs to be taken with a hyperlinked book-style document like this one where there are duplicate page numbers. The title page (generated by \maketitle) is on page one, but so is the first page of the table of contents (the numbering has been reset by \frontmatter) and the first page of the first chapter (the numbering has been reset by \mainmatter). The hyperref option plainpages=false (the default) forms the anchor at the start of each page from the formatted value of the page number. This means that the first page of the front matter has the anchor page.i. This ensures uniqueness since there’s no other page “i”.

Since \mainmatter switches the numbering to use \arabic, the first page of the main matter is “1” and the anchor page.1 is formed from that. However, users often forget that the title page also defaults to page “1”. The page number isn’t visible, but it’s still assigned and hyperref still creates an anchor for it. This causes a problem as this would cause the creation of two page.1 anchors, which leads to a warning that looks like:

pdfTeX warning (ext4): destination with the same identifier (name{page.1}) 
has been already used, duplicate ignored

This means that the back-references in the glossary location lists will hyperlink to the title page instead of the first page of the main matter. A simple solution is to just switch to a different numbering scheme for the title page. I’ve done this using:

\pagenumbering{alph}

Since the title page number isn’t displayed in the document, this doesn’t change the PDF but the page hyperlinks are now unique and the back-references take you to the correct page.

Download: PDF (64.25K), source code (536B), sample glossary definitions (3.33K).