[Tex/LaTex] How to effectively use List of Symbols for a thesis

listssymbolstable of contentsthesis

I am looking at some thesis templates online, and virtually all of them have a line that says:

\chapter*{List of Symbols}

\addcontentsline{toc}{chapter}{List of Symbols}

For example:

https://groups.google.com/forum/#!topic/latexusersgroup/tfHpC9MvpsI
https://gist.github.com/FuzzyWuzzie/4678259

It creates a page like this:

But absolutely no instruction as to how to add symbols onto this list! How do I start adding symbols to this list?

One source online said the way to add new symbols to this page is to create a table under this chapter:

\chapter*{List of Symbols}
\addcontentsline{toc}{chapter}{List of Symbols}

\begin{tabular}{cp{0.6\textwidth}}
  $x$ & position \\
  $v$ & velocity \\
  $a$ & acceleration \\
  $t$ & time \\
  $F$ & force
\end{tabular}\\

But I would like to add symbols as I go so the symbols on different chapters are "hyperlinked" with the list of symbols when they are defined.

I wish to achieve this using something like \addsymbol{\beta: name of a cat}.

Is there a way to do that without creating a separate table of symbols?

Best Answer

Both the glossaries package and the glossaries-extra extension package provide the package option symbols, which creates a new list labelled symbols with the default title given by the language-sensitive \glssymbolsgroupname ("Symbols"). This list can be referenced with type=symbols. If you don't use this package option then you can use the default main glossary instead but the default title will be obtained from \glossaryname ("Glossary").

Table 1.1: Glossary Options: Pros and Cons in the glossaries manual summarises the key differences between the various options described below, and the glossaries performance page evaluates the performance (build time and sorting) of the various methods.

Method 1 (no external tools required, manual sorting)

This is the simplest method as it doesn't require any addition to the build process. Requires at least v1.08 of the glossaries-extra package.

Pros and Cons:

you need to define the entries in the required order;
there's no page list associated with each entry in the symbol list (although it's possible to add this manually);
all defined entries will be included in the list regardless of whether or not they have been used in the document;
all entries must be defined before the list is displayed;
no external tools are required.

The first three points also apply to the manual method in your question that uses the tabular environment. The fourth point is automatically ensured by glossaries-extra's default behaviour, which prohibits entries from being defined in the document environment. (If you have a lot of symbols, I recommend you put the definitions in a separate file and load it in the preamble using \input or \loadglsentries.)

Each symbol must first be defined. If the symbols package option is used, this can be done with \glsxtrnewsymbol[options]{label}{symbol}. The symbol can then be referenced in the document using \gls{label}. For example, the symbol $t$ can be defined with the label t using:

\glsxtrnewsymbol[description={time}]{t}{\ensuremath{t}}

It can then be referenced using \gls{t}. An alternative way of defining this symbol is:

\newglossaryentry{t}{name={\ensuremath{t}},sort={t},description={time}}

or (if the symbols glossary has been defined):

\newglossaryentry{t}{name={\ensuremath{t}},sort={t},description={time},type={symbols}}

The \glsxtrnewsymbol command is more compact and is more appropriate for symbols, but the symbols package option is required to provide it.

With this method, I recommend the sort=none package option, as this switches off the redundant construction of the sort key. (This option may not be available if you have an old version of glossaries.)

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,sort=none]{glossaries-extra}

\glsxtrnewsymbol[description={position}]{x}{\ensuremath{x}}
\glsxtrnewsymbol[description={velocity}]{v}{\ensuremath{v}}
\glsxtrnewsymbol[description={acceleration}]{a}{\ensuremath{a}}
\glsxtrnewsymbol[description={time}]{t}{\ensuremath{t}}
\glsxtrnewsymbol[description={force}]{F}{\ensuremath{F}}

\begin{document}
\tableofcontents
\printunsrtglossary[type=symbols,style=long]

\chapter{Sample}
Reference symbols: $\gls{x}$, $\gls{v}$, $\gls{a}$, $\gls{t}$,
$\gls{F}$.

\end{document}

If the file is called mydoc.tex, then the build process is:

pdflatex mydoc
pdflatex mydoc

(Replace pdflatex with xelatex etc as appropriate.) The second instance of pdflatex is only needed here to ensure the table of contents and the PDF bookmarks are up-to-date.

This produces the symbol list:

The list of symbols is automatically added to the table of contents:

You can change the title using the title key:

\printunsrtglossary[type=symbols,style=long,title={List of Symbols}]

I've used the long style, which is the closest match to your tabular example, but there are many predefined styles to choose from.

Make sure hyperref is loaded before glossaries-extra. (This is contrary to the general rule that hyperref should be loaded last.) This will allow commands like \gls to link to the relevant entry in the list of symbols.

It is possible to include a location, but as with all manual methods, this can be tiresome an error-prone. The following example only includes a location for the first symbol:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,record]{glossaries-extra}

\glsxtrnewsymbol[
 description={position},
 location={(see chapter~\ref{ch:sample}).}
]{x}{\ensuremath{x}}
\glsxtrnewsymbol[description={velocity}]{v}{\ensuremath{v}}
\glsxtrnewsymbol[description={acceleration}]{a}{\ensuremath{a}}
\glsxtrnewsymbol[description={time}]{t}{\ensuremath{t}}
\glsxtrnewsymbol[description={force}]{F}{\ensuremath{F}}

\begin{document}
\tableofcontents
\printunsrtglossary[type=symbols,style=long]

\chapter{Sample}\label{ch:sample}
Reference symbols: $\gls{x}$, $\gls{v}$, $\gls{a}$, $\gls{t}$,
$\gls{F}$.

\end{document}

The record option (amongst other things), creates a field called location which \printunsrtglossary checks for. The list of symbols now looks like:

Method 2 (using an external tool to sort)

This method is more complicated as it requires an extra step in the build process. It's much like the previous example, but there are a few modifications:

The nonumberlist option is added to suppress the location list that would automatically appear after each entry in the symbol list. (Remove this option if you actually want the locations.)
The command \makeglossaries must be added to the preamble (before the symbols are defined).
The command \printunsrtglossary must be replaced with \printglossary.

Pros and Cons:

the entries are listed alphabetically (according to their sort value);
each entry in the list can have a list of locations where that symbol has been used (with \gls) in the document;
only those entries used (with \gls) in the document are included in the list;
entries may be defined in the document (but this must be enabled with the docdef=restricted or docdef=true package option, which has some potentially problematic issues);
an external tool is required in the build process.

Modified example:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,nonumberlist]{glossaries-extra}

\makeglossaries

\glsxtrnewsymbol[description={position}]{x}{\ensuremath{x}}
\glsxtrnewsymbol[description={velocity}]{v}{\ensuremath{v}}
\glsxtrnewsymbol[description={acceleration}]{a}{\ensuremath{a}}
\glsxtrnewsymbol[description={time}]{t}{\ensuremath{t}}
\glsxtrnewsymbol[description={force}]{F}{\ensuremath{F}}

\begin{document}
\tableofcontents
\printglossary[type=symbols,style=long,title={List of Symbols}]

\chapter{Sample}
Reference symbols: $\gls{x}$, $\gls{v}$, $\gls{a}$, $\gls{t}$,
$\gls{F}$.

\end{document}

Assuming the file is called mydoc.tex, the build process is:

pdflatex mydoc
makeglossaries mydoc
pdflatex mydoc

makeglossaries is a Perl script, so you need Perl installed to use it. If you don't have Perl, there's a light-weight Lua alternative called makeglossaries-lite which you can use instead. (Since modern TeX distributions come with LuaTeX, you should have a Lua interpreter already available.) The build process in this case is:

pdflatex mydoc
makeglossaries-lite mydoc
pdflatex mydoc

(makeglossaries-lite is actually distributed as makeglossaries-lite.lua, but TeX Live on Unix-like systems strip the .lua extension. I don't use Windows, but I think the extension can be omitted there as I believe the Windows distributions convert the Lua script to an executable makeglossaries-lite.exe.)

This produces an ordered list of symbols where the sort order is obtained from the first required argument of \glsxtrnewsymbol, which is also the label used to identify the term. If \newglossaryentry is used instead, the sort defaults to the name field, which causes problems for symbols that are defined in terms of LaTeX commands, such as \alpha or \sum. (This is why \glsxtrnewsymbol uses the label instead.)

Without the nonumberlist option the list includes a location list:

In this case, each location list consists of the number 3, which is the page on which all instances of \gls occur. You can switch to another counter if you prefer (for example, using the counter package option). The postpunc option allows a way of automatically inserting a punctuation character after the description but it's best used with the stylemods option. For example:

\usepackage[symbols,nogroupskip,stylemods,postpunc=dot]{glossaries-extra}

You can change the sort value using the sort key in the optional argument of \glsxtrnewsymbol. For example:

\glsxtrnewsymbol[description={time},sort={time}]{t}{\ensuremath{t}}

How you actually run makeglossaries/makeglossaries-lite depends on your setup. See, for example:

If you're really stuck you can use the automake package option:

\usepackage[symbols,nogroupskip,nonumberlist,automake]{glossaries-extra}

This doesn't have the diagnostic tools provided by makeglossaries and requires the shell escape.

Both makeglossaries and makeglossaries-lite call an indexing application. You can call it directly, but you need to know all the necessary switches and file extensions. (The Perl and Lua scripts provided with the glossaries package find the necessary information in the .aux file.) The default behaviour is to use makeindex. You can switch to xindy by adding xindy to the list of package options:

\usepackage[symbols,nogroupskip,nonumberlist,xindy]{glossaries-extra}

(Note that xindy is a Perl script, so you need Perl installed to use it.) In the above example, there's no difference since \glsxtrnewsymbol sets the sort field to the label, which only contains ASCII characters.

Things become much more complicated if you directly use \newglossaryentry and the name field contains commands. For example:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,nonumberlist]{glossaries-extra}

\makeglossaries

\newglossaryentry{alpha}{
 name=\ensuremath{\alpha},
 description={angular acceleration},
 type=symbols
}
\newglossaryentry{delta}{
 name=\ensuremath{\delta},
 description={Kronecker delta},
 type=symbols
}
\newglossaryentry{lambda}{
 name=\ensuremath{\lambda},
 description={Lagrange multiplier},
 type=symbols
}
\newglossaryentry{chi}{
 name=\ensuremath{\chi},
 description={chromatic number},
 type=symbols
}
\newglossaryentry{zeta}{
 name=\ensuremath{\zeta},
 description={Riemann zeta function},
 type=symbols
}

\begin{document}
\tableofcontents
\printglossary[type=symbols,style=long,title={List of Symbols}]

\chapter{Sample}
Reference symbols: $\gls{delta}$, $\gls{chi}$, $\gls{alpha}$,
$\gls{zeta}$, $\gls{lambda}$.

\end{document}

In this case, the sort field is obtained from the name field, but neither makeindex nor xindy understand LaTeX commands. In the case of makeindex, it treats \ensuremath{\alpha} as a string containing 19 characters, starting with \ so the result is:

This doesn't follow the natural ordering of Greek letters (which should be α δ ζ λ χ) and will position the Greek symbols before Latin symbols (since \ is ordered before a by makeindex).

This example fails completely with xindy. If you use the makeglossaries-lite script, it fails with a cryptic message. If I just modify the document so that it includes the xindy package option:

\usepackage[symbols,nogroupskip,nonumberlist,xindy]{glossaries-extra}

then makeglossaries-lite reports:

Cannot locate xindy module for language english in codepage nil.
Cannot locate xindy module for language nil in codepage nil.

This is because the document doesn't have the codepage set. This needs to be added:

\usepackage[symbols,nogroupskip,nonumberlist,
 xindy={codepage=utf8,language=english}]{glossaries-extra}

(This isn't necessary with makeglossaries which falls back on -L english -C utf8 if this information is omitted.) However, even with this information, makeglossaries-lite fails with xindy's rather cryptic message:

ERROR: CHAR: index 0 should be less than the length of the string

Switching to makeglossaries provides a more intelligible explanation:

Sort key required for entries only containing command names.
Attempting to determine which entries have problem sort keys.
Parsing 'mydoc.slo'
5 problematic entries found:

Label: 'chi'. Sort value : '\\ensuremath {\\chi }'
(Try adding sort={chi} to the definition.)
Label: 'delta'. Sort value : '\\ensuremath {\\delta }'
(Try adding sort={delta} to the definition.)
Label: 'zeta'. Sort value : '\\ensuremath {\\zeta }'
(Try adding sort={zeta} to the definition.)
Label: 'alpha'. Sort value : '\\ensuremath {\\alpha }'
(Try adding sort={alpha} to the definition.)
Label: 'lambda'. Sort value : '\\ensuremath {\\lambda }'
(Try adding sort={lambda} to the definition.)

So with xindy you must supply a sensible sort value (or use \glsxtrnewsymbol to default to the label) for entries that only contain commands in the name field.

Method 3 (no external tools required, order by use in the document)

To order the symbol list according to the first time the symbol is used in the document, you need to make the following changes:

Add sort=use
Replace \makeglossaries with \makenoidxglossaries
Replace \printglossary with \printnoidxglossary

Pros and Cons:

entries may be listed in alphabetical order (not recommended with this method) or by order of use (sort=use, as in this example) or by order of definition (sort=def);
each entry in the list can have a list of locations where that symbol has been used (with \gls) in the document;
only those entries used (with \gls) in the document are included in the list;
all entries must be defined in the preamble;
no external tools are required.

As you might be able to gather from the first point, you can also use this method as a substitute for the other two methods. However, when sorting alphabetically, Method 2 is far more efficient and can support various locales (when used with the xindy option), although this may not be applicable for symbols (especially when they just contain ASCII characters). For a large list, this method can take a long time when sorting alphabetically. When sorting by definition (sort=def), this method differs from Method 1 as it only includes those entries that have been used in the document (whereas Method 1 lists all defined entries).

Adjusted example (third page modified to show effect):

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,nonumberlist,sort=use]{glossaries-extra}

\makenoidxglossaries

\glsxtrnewsymbol[description={position}]{x}{\ensuremath{x}}
\glsxtrnewsymbol[description={velocity}]{v}{\ensuremath{v}}
\glsxtrnewsymbol[description={acceleration}]{a}{\ensuremath{a}}
\glsxtrnewsymbol[description={time}]{t}{\ensuremath{t}}
\glsxtrnewsymbol[description={force}]{F}{\ensuremath{F}}

\begin{document}
\tableofcontents
\printnoidxglossary[type=symbols,style=long,title={List of Symbols}]

\chapter{Sample}
Reference symbols: $\gls{F}$, $\gls{t}$, $\gls{x}$, $\gls{v}$, $\gls{a}$.

\end{document}

The build process is back to:

pdflatex mydoc
pdflatex mydoc

The list of symbols now looks like:

Again, removing the nonumberlist option makes the location list appear:

Things go badly wrong if you use this method with the default alphabetical sorting when the sort value contains commands. Adjusting the earlier example with Greek symbols:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,nonumberlist]{glossaries-extra}

\makenoidxglossaries

\newglossaryentry{alpha}{
 name=\ensuremath{\alpha},
 description={angular acceleration},
 type=symbols
}
\newglossaryentry{delta}{
 name=\ensuremath{\delta},
 description={Kronecker delta},
 type=symbols
}
\newglossaryentry{lambda}{
 name=\ensuremath{\lambda},
 description={Lagrange multiplier},
 type=symbols
}
\newglossaryentry{chi}{
 name=\ensuremath{\chi},
 description={chromatic number},
 type=symbols
}
\newglossaryentry{zeta}{
 name=\ensuremath{\zeta},
 description={Riemann zeta function},
 type=symbols
}

\begin{document}
\tableofcontents
\printnoidxglossary[type=symbols,style=long,title={List of Symbols}]

\chapter{Sample}
Reference symbols: $\gls{delta}$, $\gls{chi}$, $\gls{alpha}$,
$\gls{zeta}$, $\gls{lambda}$.

\end{document}

During sorting, the following error occurs:

! Improper alphabetic constant.
<to be read again> 
                   \protect 
l.36 ...ymbols,style=long,title={List of Symbols}]

This method is only designed for ASCII sorting. With this method, you must ensure that the sort value doesn't contain any commands (for example, use \glsxtrnewsymbol which obtains the sort value from the label) or use sort=def or sort=use.

Method 4 (external tool and `.bib` file(s) required)

This is a fairly new method. Instead of using makeindex or xindy (via makeglossaries or makeglossaries-lite), it requires bib2gls, which performs two functions:

selects entries according to records found in the .aux file (similar to bibtex);
hierarchically sorts entries and collates location lists (similar to makeindex or xindy).

Pros and Cons:

you need to define the entries in a .bib file (not in the document);
bib2gls allows any location format or you may instruct it to omit the location list;
you can instruct bib2gls to select all defined entries or only recorded entries (and optionally their dependencies);
can interpret common symbol commands;
can sort according to locale, character code, letter-number mix, numeric, date, time, order of definition, order of use, or can shuffle or omit the sorting;
requires at least Java 7.

The symbols are now defined in a .bib file. For example, instead of:

\glsxtrnewsymbol[description={angular acceleration}]{alpha}{\ensuremath{\alpha}}

the symbol is defined as:

@symbol{alpha,
 name={\ensuremath{\alpha}},
 description={angular acceleration}
}

Alternatively, instead of

\newglossaryentry{alpha}{
 name=\ensuremath{\alpha},
 description={angular acceleration},
 type=symbols
}

use

@entry{alpha,
 name={\ensuremath{\alpha}},
 description={angular acceleration}
}

(The type field has been omitted, as it's more flexible to assign it in the document.) As with \glsxtrnewsymbol, the @symbol definition uses the label as the fall back for the sort field, whereas the @entry definition uses the name as the fall back.

For example, the file greek-symbols.bib may contain:

% Encoding: UTF-8

@entry{alpha,
 name={\ensuremath{\alpha}},
 description={angular acceleration}
}
@entry{delta,
 name={\ensuremath{\delta}},
 description={Kronecker delta}
}
@entry{lambda,
 name={\ensuremath{\lambda}},
 description={Lagrange multiplier}
}
@entry{chi,
 name={\ensuremath{\chi}},
 description={chromatic number}
}
@entry{zeta,
 name={\ensuremath{\zeta}},
 description={Riemann zeta function}
}

The document needs the record package option. Instead of nonumberlist I can instruct bib2gls to not save the location list (which is more efficient). Instead of \makeglossaries/\makenoidxglossaries you need to use \GlsXtrLoadResources:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,nogroupskip,
   record % using 'bib2gls'
]{glossaries-extra}

\GlsXtrLoadResources[
 src={greek-symbols},% entries in 'greek-symbols.bib'
 type=symbols,% put these entries in the 'symbols' glossary
 save-locations=false% don't save locations
]

\begin{document}
\tableofcontents
\printunsrtglossary[type=symbols,style=long,title={List of Symbols}]

\chapter{Sample}
Reference symbols: $\gls{delta}$, $\gls{chi}$, $\gls{alpha}$,
$\gls{zeta}$, $\gls{lambda}$.

\end{document}

This uses \printunsrtglossary from the earlier Method 1. Unlike the other methods, bib2gls works by selecting only those entries that are required and then writes the definition (\newglossaryentry) to the file input by \GlsXtrLoadResources in the appropriate order. This means that \printunsrtglossary automatically lists the entries in the requested order (since that's the order of definition from glossaries-extra's point of view).

The build process is now

pdflatex mydoc
bib2gls mydoc
pdflatex mydoc

This produces:

(Remove save-locations=false if you want the location list.)

Since bib2gls recognises commands like \ensuremath{\alpha}, it's used the correct Greek order. Alternatively you can instruct bib2gls to sort by the description instead:

\GlsXtrLoadResources[
 src={greek-symbols},
 type=symbols,
 sort-field=description,
 save-locations=false
]

If the file latin-symbols.bib similarly contains the Latin symbols:

% Encoding: UTF-8

@entry{x,
 name={\ensuremath{x}},
 description={position}
}
@entry{v,
 name={\ensuremath{v}},
 description={velocity}
}
@entry{a,
 name={\ensuremath{a}},
 description={acceleration}
}
@entry{t,
 name={\ensuremath{t}},
 description={time}
}
@entry{F,
 name={\ensuremath{F}},
 description={force}
}

Then they can be combined:

\GlsXtrLoadResources[
 src={greek-symbols,latin-symbols},% entries in 'greek-symbols.bib' and 'latin-symbols.bib'
 type=symbols,
 save-locations=false
]

or separated into two distinct groups within the same glossary:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[symbols,
  stylemods={tree},% loads glossaries-extra-stylemods to patch styles
  record % using 'bib2gls'
]{glossaries-extra}

% assign titles to group labels:
\glsxtrsetgrouptitle{latin}{Latin}
\glsxtrsetgrouptitle{greek}{Greek}

\GlsXtrLoadResources[
 src={latin-symbols},
 type=symbols,
 group={latin},% assign group label
 set-widest,% needed for 'alttree' styles
 save-locations=false
]

\GlsXtrLoadResources[
 src={greek-symbols},
 type=symbols,
 group={greek},% assign group label
 set-widest,% needed for 'alttree' styles
 save-locations=false
]

\begin{document}
\tableofcontents
\printunsrtglossary[type=symbols,style=alttreegroup,title={List of Symbols}]

\chapter{Sample}
Reference Greek symbols: $\gls{delta}$, $\gls{chi}$, $\gls{alpha}$,
$\gls{zeta}$, $\gls{lambda}$.

Reference Latin symbols: $\gls{x}$, $\gls{v}$, $\gls{a}$, $\gls{t}$,
$\gls{F}$.

\end{document}

The group setting requires the --group (or -g) switch when calling bib2gls:

pdflatex mydoc
bib2gls --group mydoc
pdflatex mydoc

This setting also requires a style that supports group headings, which is why I changed to the style to altlistgroup.

Best Answer

Method 1 (no external tools required, manual sorting)

Method 2 (using an external tool to sort)

Method 3 (no external tools required, order by use in the document)

Method 4 (external tool and .bib file(s) required)

Related Solutions

[Tex/LaTex] Problems with \addtocontent and \addcontentsline

[Tex/LaTex] Roman page numbers before table of contents which also appear in it

Related Question

Method 4 (external tool and `.bib` file(s) required)