Nicola L.C. Talbot
School of Computing Sciences
University of East Anglia
Norwich. Norfolk
NR4 7TJ. United Kingdom.
http://theoval.cmp.uea.ac.uk/~nlct/
12th May 2008
The glossaries package is provided to assist generating glossaries. It has a certain amount of flexibility, allowing the user to customize the format of the glossary and define multiple glossaries. It also supports acronyms and glossary styles that include symbols (in addition to a name and description) for glossary entries. There is provision for loading a database of glossary terms where only those terms used in the text are added to the glossary. This package replaces the glossary package which is now obsolete.
This documentation is structured as follows: A Quick Guide For The Impatient is for people who want a few quick pointers of how to get started, without having to read through lengthy descriptions, Overview gives an overview of available commands and their syntax and Mfirstuc describes the associated mfirstuc package.
As from version 1.08, the glossaries package now has limited multi-lingual support, thanks to all the people who have sent me the relevant translations either via email or via comp.text.tex. However you must load babel before glossaries to enable this. Note that if babel is loaded and the translator package is detected on TEX's path, then the translator package will be loaded automatically.
If you want to use ngerman or german instead of babel, you will need to include the translator package to provide the translations. For example:
\documentclass[ngerman]{article} \usepackage{ngerman} \usepackage{translator} \usepackage{glossaries}
The following languages are currently supported:
Language | As from version |
---|---|
Danish | 1.08 |
Dutch | 1.08 |
English | 1.08 |
French | 1.08 |
German | 1.08 |
Irish | 1.08 |
Italian | 1.08 |
Hungarian | 1.08 |
Polish | 1.13 |
Spanish | 1.08 |
Due to the varied nature of glossaries, it's likely that the predefined translations may not be appropriate. If you are using the babel package and do not have the translator package installed, you need to be familiar with the advice on changing the words babel uses.
If you have the translator package installed, then it becomes much easier to change the default translations. For example, if you are writing in Irish and you want \symbolname to produce "Siombail" instead of "Comhartha", then you can put the following in your document preamble:
\deftranslation[to=Irish]{Symbol (glossaries)}{Siombail}
The glossaries package comes with the Perl script makeglossaries which will run makeindex on all the glossary files using a customized makeindex .ist style file (which is created by \makeglossaries). The relevant extensions are obtained from the auxiliary file, so you should only pass the basename as the argument. For example, if your document is called myfile.tex, do:
latex myfile makeglossaries myfile latex myfileYou may need to explicitly load makeglossaries into Perl:
perl makeglossaries myfileThere is a batch file called makeglossaries.bat which does this for Windows users, but you must have Perl installed to be able to use it.
If you don't have Perl installed, you will have to run makeindex for each glossary type you have defined. For example, if you have used the acronym package option then you will have both a main glossary as well as a list of acronyms, so you will need to do (assuming your document is called myfile.tex):
makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acnThis requires remembering all extensions for each of the glossaries defined in your document, so where possible you should use makeglossaries instead to reduce the possibility of error. Don't pass all the glossary files in a single call to makeindex or it will merge all your glossaries into a single glossary.
If any problems occur, remember to check the transcript files (e.g. .glg or .alg) for messages.
The glossaries package comes with a minimal file called minimalgls.tex which can be used for testing. This should be located in texmf/doc/latex/glossaries/samples/. Further information on debugging LaTeX code is available at http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/.
There is a list of frequently asked questions for the glossaries package available at http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html.
This section is for people who want a few quick pointers of how to get started. However it is recommended that you read the overview section for additional commands and advice not listed here.
\usepackage{hyperref} \usepackage{glossaries}Similarly for the html package:
\usepackage{html} \usepackage{glossaries}
\documentclass{article} \usepackage{glossaries} \makeglossariesIf you don't use \makeglossaries, your glossaries will not appear in the document!
\maketitle \printglossaries \section{Introduction}Note that only the glossary entries that have been used in the document text will appear in the glossary.
latex myfile makeglossaries myfile latex myfile(You may need to run LaTeX again if you have used the toc package option.) If you use Windows, there is a batch file called makeglossaries.bat which you can use, but you will still need Perl installed.
\newglossary[log-ext]{label}{in-ext}{out-ext}{title}
where label is an identifying label, in-ext is the extension of the file to be created by makeindex (called by makeglossaries), out-ext is the extension of the file to be read by makeindex and title is the title for this new glossary. The first optional argument log-ext specifies the extension of the makeindex transcript file. Example:
\newglossary[nlg]{notation}{not}{ntn}{Notation}This glossary's label is notation and its title will be Notation. If you use makeglossaries, the makeindex transcript will be written to a file with the extension .nlg. If log-ext is omitted, the extension .glg will be used.
\documentclass{article} \usepackage{glossaries} \newglossary{notation}{not}{ntn}{Notation} \makeglossaries
\usepackage[acronym]{glossaries}
\documentclass{article} \usepackage{glossaries} \renewcommand{\glscompositor}{-} \makeglossaries
\usepackage[toc]{glossaries}
\newglossaryentry{label}{key-val list}
The key-val list must at least contain a name key and a description key. For example:
\newglossaryentry{perl}{name=Perl, description=A scripting language}In this example, I have given the entry the label perl. Whenever I want to use this entry, that is the label I need to use to identify it.
\newglossaryentry{elite}{name={{\'e}lite}, description={select group or class}}Likewise with commands such as \ae and \oe:
\newglossaryentry{oesophagus}{% name={{\oe}sophagus}, description={canal from mouth to stomach}}
\newglossary{languages}{lan}{lng}{Index of Languages} \makeglossaries \newglossaryentry{perl}{name=Perl, description=A scripting language, type=languages}If type is omitted, the default glossary is used.
\newglossaryentry{pagelist}{name=page list, description={A list of individual pages or page ranges (e.g.\ 1,2,4,7--9)}}
\newglossaryentry{matrix}{name=matrix, description=rectangular array of quantities, plural=matrices}
\newglossaryentry{matrix}{name=Matrix, description=rectangular array of quantities, text=matrix, plural=matrices}In this example, the entry name appears as "Matrix" in the glossary, and either "matrix" or "matrices" in the text.
\newglossaryentry{singmtx}{name=Singular Matrix, description=A matrix with a zero determinant, first=singular matrix (SM), text=SM, firstplural=singular matrices (SMs)}In this example, the entry name appears as "Singular Matrix" in the glossary, and in the text it appears as "singular matrix (SM)" or "singular matrices (SMs)" the first time the entry is used, and subsequently appears as "SM" or "SMs".
\newacronym[key-val list]{label}{abbrev}{long}
For example:
\newacronym{svm}{SVM}{support vector machine}This is equivalent to:
\newglossaryentry{svm}{type=\acronymtype, name={SVM}, description={support vector machine}, text={SVM}, first={support vector machine (SVM)}, plural={SVMs}, firstplural={support vector machines (SVMs)}}(The value of \acronymtype varies depending on whether the acronym package option is used or not. The optional argument key-val list can be used to override any of the \newglossaryentry keys; for example, if the acronym has an irregular plural.)
\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}}Note that the list-like glossary styles defined in the glossary-list package place the entry name in the optional argument to \item, so they will appear in bold, unless you redefine \glsnamefont to counteract the bold font.
A \gls{singmtx} is a matrix with a zero determinant.
\Glspl{singmtx} are matrices with a zero determinant.
The \gls{singmtx}['s] dimensions \ldots
The primary definition of \glspl[format=textbf]{singmtx}.In this example the relevant glossary entry will have the page number in bold (since it uses \textbf) but it will no longer have a hyperlink (if hyperlinks are enabled.)
The primary definition of \glspl[format=hyperbf]{singmtx}.
\glsadd[format=hyperbf]{singmtx}will add a line to the glossary file for the specified term, but will not produce any text where the command occurs.
format=(
and
format=)
to mark the beginning and ending of the
range1. For example:
\glsadd[format=(]{singmtx} This is a very long section all about \glspl{singmtx}. % lots of text omitted \glsadd[format=)]{singmtx}This is equivalent to makeindex's
|(
and |)
formats.
This is the start of a very long section all about \glspl[format=(hyperbf]{singmtx}. % lots of text omitted This is the end a very long section all about \glspl[format=)hyperbf]{singmtx}.
\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}}, description=The universal set, sort=U}
\newglossaryentry{quote}{name={"}, description={Double quote character}} \newglossaryentry{exclam}{name={!}, description={Exclamation mark}} \newacronym{rna}{RNA}{ribonukleins\"aure}
\newglossaryentry{metre}{name={metre}, description={A metric measurement of length}, symbol={m}}The predefined glossary styles that display the entry symbol are: long4col, long4colheader, long4colborder, long4colheaderborder, super4col, super4colheader, super4colborder and super4colheaderborder. All the other styles supplied by this package ignore the associated symbol.
\usepackage[style=long3col]{glossaries}or using \glossarystyle{style}. For example:
\glossarystyle{altlist}The predefined glossary styles provided by the glossaries bundle are listed in Glossary Styles.
\usepackage[nonumberlist]{glossaries}
\usepackage[section]{glossaries}Other sectional units can also be specified as section=value. For example, to make the glossaries appear in unnumbered subsections:
\usepackage[section=subsection]{glossaries}
The glossaries package options are as follows:
{}
in the final argument of
\addcontentsline. This will align the table of contents entry
with the numbered section titles. Note that this option has no
effect if the toc option is omitted. If toc is
used without numberline, the title will be aligned with
the section numbers rather than the section titles.
\usepackage[section=subsection]{glossaries}You can omit the value if you want to use sections, i.e.
\usepackage[section]{glossaries}is equivalent to
\usepackage[section=section]{glossaries}You can change this value later in the document using \setglossarysection{type}.
\usepackage[section,numberedsection=autolabel]{glossaries}then each glossary will appear in a numbered section, and can be referenced using something like:
The main glossary is in section~\ref{main} and the list of acronyms is in section~\ref{acronym}.If you can't decide whether to have the acronyms in the main glossary or a separate list of acronyms, you can use \acronymtype which is set to main if the acronym option is not used and is set to acronym if the acronym option is used. For example:
The list of acronyms is in section~\ref{\acronymtype}.
\usepackage[sanitize={name=false,description=false,% symbol=true}]{glossaries}
Note: this sanitization only applies to the name, description and symbol keys. It doesn't apply to any of the other keys (except the sort key which is always sanitized) so fragile commands contained in the value of the other keys must always be protected using \protect. Since the value of the text key is obtained from the name key, you will still need to protect fragile commands in the name key if you don't use the text key.
All glossary entries must be defined before they are used, so it is better to define them in the preamble to ensure this.3 However only those entries that occur in the document (using any of the commands described in Links to Glossary Entries and Adding an entry to the glossary without generating text) will appear in the glossary. Each time an entry is used in this way, a line is added to an associated glossary (.glo) file, which then needs to be converted into a corresponding .gls file which contains the typeset glossary which is input by \printglossary or \printglossaries. The Perl script makeglossaries can be used to call makeindex, using a customised .ist style file, for each of the glossaries that are defined in the document. Note that there should be no need for you to explicitly edit or input any of these external files.
The command \makeglossaries must be placed in the preamble in order to create the customised makeindex .ist style file and to ensure that glossary entries are written to the appropriate output file. If you omit \makeglossaries none of the glossaries will be created. Note that if your page numbers use a hyphen compositor, you must set this by redefining \glscompositor before using \makeglossaries:
\renewcommand*{\glscompositor}{-}(The default value of \glscompositor is a full stop.)
New glossary entries are defined using the command:
\newglossaryentry{label}{key-val list}
The first
argument, label, must be a unique label with which to identify
this entry. The second argument, key-val list, is a
key=value list that supplies the relevant information
about this entry. There are two required fields: name and
description. Available fields are listed below:
\newglossaryentry{elite}{name={{\'e}lite}, description={select group or class}}Similarly, commands such as \ae and \oe should either be placed inside a group or followed by a space. For example:
\newglossaryentry{oesophagus}{% name={{\oe}sophagus}, description={canal from mouth to stomach}}The following is also fine:
\newglossaryentry{oesophagus}{% name={\oe sophagus}, description={canal from mouth to stomach}}but don't do
\oe{}sophagus
as it will confuse
\makefirstuc (described
later)
and will produce oeSophagus instead of
OEsophagus.
\newglossaryentry{cow}{name=cow,description={a fully grown female of any bovine animal}}defines a new entry whose singular form is "cow" and plural form is "cows". However, if you are writing in archaic English, you may want to use "kine" as the plural form, in which case you would have to do:
\newglossaryentry{cow}{name=cow,plural=kine, description={a fully grown female of any bovine animal}}
If you are writing in a language that supports multiple plurals (for a given term) then use the plural key for one of them (typically the one you are most likely to use) and for the others you will need to explicitly write the plural form using \glslink rather than using \glspl. Returning to the cow example above, suppose you will mostly be using "cows" as the plural, but occasionally you want to use "kine" as the plural, then define the term as
\newglossaryentry{cow}{name=cow,description={a fully grown female of any bovine animal (plural cows, archaic plural kine)}}and use
\glspl{cow}
to produce "cows" and use
\glslink{cow}{kine}
to produce "kine".
If you are using a language that usually forms plurals by appending a different letter, or sequence of letters, you can redefine \glspluralsuffix as required. However, this must be done before the entries are defined. For languages that don't form plurals by simply appending a suffix, all the plural forms must be specified using the plural key (and the firstplural key where necessary).
You can store all your glossary entry definitions in another
file, and use:
\loadglsentries[type]{filename}
where filename is the name of the file containing all the
\newglossaryentry commands. The optional argument
type is the name of the glossary to which those entries
should belong, for those entries where the type key has
been omitted (or, more specifically, for those entries whose
type has been specified by \glsdefaulttype, which is what
\newglossaryentry uses by default). For example, suppose I have
a file called myentries.tex which contains:
\newglossaryentry{perl}{type=main, name={Perl}, description={A scripting language}} \newglossaryentry{tex}{name={\TeX}, description={A typesetting language}} \newglossaryentry{html}{type=\glsdefaulttype, name={html}, description={A mark up language}}and suppose in my document preamble I use the command:
\loadglsentries[languages]{myentries}then this will add the entries tex and html to the glossary whose type is given by languages, but the entry perl will be added to the main glossary, since it explicitly sets the type to main.
Note: if you
use \newacronym (see later)
the type is set as type=\acronymtype
unless you explicitly override it. For example, if my file
myacronyms.tex contains:
\newacronym{aca}{aca}{a contrived acronym}then (supposing I have defined a new glossary type called altacronym)
\loadglsentries[altacronym]{myacronyms}will add aca to the glossary type acronym, if the package option acronym has been specified, or will add aca to the glossary type altacronym, if the package option acronym is not specified. In this instance, it is better to change myacronyms.tex to:
\newacronym[type=\glsdefaulttype]{aca}{aca}{a contrived acronym}and now
\loadglsentries[altacronym]{myacronyms}will add aca to the glossary type altacronym, regardless of whether or not the package option acronym is used.
Note that only those entries that have been used in the text will appear in the relevant glossaries. Note also that \loadglsentries may only be used in the preamble.
Each entry in the glossary has an associated number list. By default, these numbers refer to the pages on which that entry has been used (using any of the commands described in Links to Glossary Entries and Adding an entry to the glossary without generating text). The number list can be suppressed using the nonumberlist package option, or an alternative counter can be set as the default using the counter package option.
Once you have defined a glossary entry using \newglossaryentry, you can refer to that entry in the document using one of the commands listed in this section. The text which appears at that point in the document when using one of these commands is referred to as the link text (even if there are no hyperlinks).
The way the link text is displayed depends on \glstextformat{text}. For example, to make all link text appear in a sans-serif font, do:
\renewcommand*{\glstextformat}[1]{\textsf{#1}}
The command:
\glslink[options]{label}{text}
will place \glstextformat{text} in the document at that point
and add a line into the associated glossary file for the glossary entry
given by label. If hyperlinks are supported, text will be
a hyperlink to the relevant line in the glossary. The optional argument
options must be a key=value list which can take
any of the following keys:
(
and
)
can also be used to specify the beginning and ending of a
number range. Again as with \index, the command should be the name
of a command which takes an argument (which will be the associated
number). Be careful not to use a declaration (such as \bfseries)
instead of a text block command (such as \textbf) as the effect is
not guaranteed to be localised. If you want to apply more than one
style to a given entry (e.g. bold and italic) you will
need to create a command that applies both formats, e.g.
\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}and use that command.
If you are using hyperlinks and you want to change the font of the hyperlink, don't use \hyperpage (provided by the hyperref package) as the numbers may not refer to a page number. Instead, the glossaries package provides the following number formats:
hyperrm | The number is a serif hyperlink to the relevant part of the document |
hypersf | The number is a sans-serif hyperlink to the relevant part of the document |
hypertt | The number is a monospaced hyperlink to the relevant part of the document |
hyperbf | The number is a bold hyperlink to the relevant part of the document |
hypermd | The number is a medium weight hyperlink to the relevant part of the document |
hyperit | The number is an italic hyperlink to the relevant part of the document |
hypersl | The number is a slanted hyperlink to the relevant part of the document |
hyperup | The number is an upright hyperlink to the relevant part of the document |
hypersc | The number is a small caps hyperlink to the relevant part of the document |
hyperemph | The number is an emphasized hyperlink to the relevant part of the document |
\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}and then use hyperbsf as the value for the format key.
The command:
\gls[options]{label}[insert]
is the same as \glslink, except that the link text
is determined from the values of the text and
first keys supplied when the entry was defined using
\newglossaryentry. If the entry has been marked as having
been used, the value of the text key will be used, otherwise
the value of the first key will be used.
On completion, \gls will mark the entry given by label as
used.
There are two uppercase variants:
\Gls[options]{label}[insert]
and
\GLS[options]{label}[insert]
which make the first letter of the link or all the link text
uppercase, respectively.
The final optional argument insert, allows you to insert some additional text into the link text. By default, this will append insert at the end of the link text, but this can be changed (see later).
The first optional argument options is the same as the optional argument to \glslink. As with \glslink, these commands also have a starred version that disable the hyperlink.
There are also analogous plural forms:
\glspl[options]{label}[insert]
\Glspl[options]{label}[insert]
\GLSpl[options]{label}[insert]
These determine the link text from the plural and
firstplural keys supplied when the entry was first
defined. As before, these commands also have
a starred version that disable the hyperlink.
The command:
\glstext[options]{label}[insert]
is similar to \gls except that it always uses the value
of the text key and does not mark the entry as
having been used. Unlike \gls, the inserted text insert
is always appended to the link text.
There are also analogous commands:
\Glstext[options]{text}[insert]
\GLStext[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glsfirst[options]{label}[insert]
is similar to \glstext except that it always uses the value
of the first key. Again, insert is always appended
to the end of the link text and does not mark the entry as having
been used.
There are also analogous commands:
\Glsfirst[options]{text}[insert]
\GLSfirst[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glsplural[options]{label}[insert]
is similar to \glstext except that it always uses the value
of the plural key. Again, insert is always appended
to the end of the link text and does not mark the entry as having
been used.
There are also analogous commands:
\Glsplural[options]{text}[insert]
\GLSplural[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glsfirstplural[options]{label}[insert]
is similar to \glstext except that it always uses the value
of the firstplural key. Again, insert is always
appended to the end of the link text and does not mark the entry as
having been used.
There are also analogous commands:
\Glsfirstplural[options]{text}[insert]
\GLSfirstplural[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glsname[options]{label}[insert]
is similar to \glstext except that it always uses the value of the
name key. Again, insert is always appended to the end
of the link text and does not mark the entry as having
been used. Note: if you want to use this command and the
name key contains commands, you will have to disable the
sanitization
of the name key and protect fragile commands.
There are also analogous commands:
\Glsname[options]{text}[insert]
\GLSname[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glssymbol[options]{label}[insert]
is similar to \glstext except that it always uses the value of the
symbol key. Again, insert is always appended to the
end of the link text and does not mark the entry as having
been used. Note: if you want to use this command and the
symbol key contains commands, you will have to disable the
sanitization
of the symbol key and protect fragile commands.
There are also analogous commands:
\Glssymbol[options]{text}[insert]
\GLSsymbol[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The command:
\glsdesc[options]{label}[insert]
is similar to \glstext except that it always uses the value
of the description key. Again, insert is always
appended to the end of the link text and does not mark the entry as
having been used. Note: if you want to use this
command and the description key contains commands, you will
have to disable the
sanitization
of the description key and protect fragile commands.
There are also analogous commands:
\Glsdesc[options]{text}[insert]
\GLSdesc[options]{text}[insert]
As before, these commands also have a starred version that disable
the hyperlink.
The format of the link text for \gls, \glspl and their uppercase variants is governed by two commands: \glsdisplayfirst, which is used the first time a glossary entry is used in the text and \glsdisplay, which is used subsequently. Both commands take four arguments: the first is either the singular or plural form given by the text, plural, first or firstplural keys (used when the term was defined) depending on context; the second argument is the term's description (as supplied by the description key); the third argument is the symbol associated with the term (as supplied by the symbol key) and the fourth argument is the additional text supplied in the final optional argument to \gls or \glspl (or their uppercase variants). The default definitions of \glsdisplay and \glsdisplayfirst simply print the first argument immediately followed by the fourth argument. The remaining arguments are ignored.
For example, suppose you want a glossary of measurements and units, you can use the symbol key to store the unit:
\newglossaryentry{distance}{name=distance, description={The length between two points}, symbol={km}}and now suppose you want
\gls{distance}
to produce
"distance (km)" on first use, then you can redefine
\glsdisplayfirst as follows:
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}Note that the additional text is placed after
#1
, so
\gls{distance}['s]
will produce "distance's (km)"
rather than "distance (km)'s" which looks a bit odd (even though
it may be in the context of "the distance (km) is measured between
the two points" -- but in this instance it may be better not to
use a contraction).
Note also that all of the link text will be formatted according to \glstextformat (described earlier). So if you do, say:
\renewcommand{\glstextformat}[1]{\textbf{#1}} \renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}then
\gls{distance}
will produce "distance (km)".
If you have multiple glossaries, changing \glsdisplayfirst and \glsdisplay will change the way entries for all of the glossaries appear when using commands \gls, \glspl and their uppercase variants. If you only want the change to affect entries for a given glossary, then you need to use \defglsdisplay and \defglsdisplayfirst instead of redefining \glsdisplay and \glsdisplayfirst.
Both \defglsdisplay and \defglsdisplayfirst take two arguments: the first (which is optional) is the glossary's label4 and the second is how the term should be displayed when it is invoked using commands \gls, \glspl and their uppercase variants. This is similar to the way \glsdisplayfirst was redefined above.
For example, suppose you have created a new glossary called notation and you want to change the way the entry is displayed on first use so that it includes the symbol, you can do:
\defglsdisplayfirst[notation]{#1#4 (denoted #3)}Now suppose you have defined an entry as follows:
\newglossaryentry{set}{type=notation, name=set, description={A collection of objects}, symbol={$S$} }The first time you reference this entry using \gls it will be displayed as: "set (denoted S)" (similarly for \glspl and the uppercase variants).
Remember that if you use the symbol key, you need to use a glossary style that displays the symbol, as many of the styles ignore it. In addition, if you want either the description or symbol to appear in the link text, you will have to disable the sanitization of these keys and protect fragile commands.
If you load the hyperref or html packages prior to
loading the glossaries package, commands such as \glslink
and \gls, described above, will automatically have hyperlinks
to the relevant glossary entry, unless the hyper
option has been set to false. You can disable or enable links using:
\glsdisablehyper
and
\glsenablehyper
respectively. The effect can be localised by placing the commands
within a group. Note that you should only use \glsenablehyper
if the commands \hyperlink and \hypertarget have been
defined (for example, by the hyperref package).
It is possible to add a line in the glossary file without
generating any text at that point in the document using:
\glsadd[options]{label}
This is similar to \glslink, only it doesn't produce
any text (so therefore, there is no hyper key
available in options but all the other options that can
be used with \glslink can be passed to \glsadd).
For example, to add a page range to the glossary number list for the
entry whose label is given by set:
\glsadd[format=(]{set} Lots of text about sets spanning many pages. \glsadd[format=)]{set}
To add all entries that have been defined, use:
\glsaddall[options]
The optional argument is the same as for \glsadd, except
there is also a key types which can be
used to specify which glossaries to use. This should be a
comma separated list. For example, if you only want to add
all the entries belonging to the list of acronyms (specified by
the glossary type \acronymtype) and a list of
notation (specified by the glossary type notation) then you can
do:
\glsaddall[types={\acronymtype,notation}]
The command \printglossaries will display all the glossaries in the order in which they were defined. Note that no glossaries will appear until you have either used the Perl script makeglossaries or have directly used makeindex (as described in Generating the Associated Glossary Files). If the glossary still does not appear after you re-LaTeX your document, check the makeindex log files to see if there is a problem. Remember that you also need to use the command \makeglossaries in the preamble to enable the glossaries.
An individual glossary can be displayed using:
\printglossary[options]
where options is a key=value list of options.
The following keys are available:
\printglossary[type=\acronymtype]
Information can be added to the start of the glossary by redefining \glossarypreamble. For example:
\renewcommand{\glossarypreamble}{Numbers in italic indicate primary definitions.}This needs to be done before the glossary is displayed using \printglossaries or \printglossary. Note that if you want a different preamble for each glossary, you will need to use a separate \printglossary for each glossary and change the definition of \glossarypreamble between each glossary. For example:
\renewcommand{\glossarypreamble}{Numbers in italic indicate primary definitions.} \printglossary \renewcommand{\glossarypreamble}{} \printglossary[type=acronym]Alternatively, you can do something like:
\renewcommand{\glossarypreamble}{Numbers in italic indicate primary definitions.\gdef\glossarypreamble{}} \printglossarieswhich will print the preamble text for the first glossary and change the preamble to do nothing for subsequent glossaries. (Note that \gdef is required as the glossary is placed within a group.)
There is an analogous command called \glossarypostamble which is placed at the end of each glossary.
Within each glossary, each entry name is formatted according to \glsnamefont which takes one argument: the entry name. This command is always used regardless of the glossary style. By default, \glsnamefont simply displays its argument in whatever the surrounding font happens to be. This means that in the list styles the name will appear in bold, since the name is placed in the optional argument of \item, whereas in the tabular styles the name will appear in the normal font.
For example, suppose you want all the entry names to appear in medium weight small caps, then you can do:
\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
A new glossary can be defined using:
\newglossary[log-ext]{name}{in-ext}{out-ext}{title}[counter]
where name is the label to assign to this glossary. The arguments
in-ext and out-ext specify the extensions to give to the
input and output files for that glossary, title is the default
title for this new glossary and the final optional argument
counter specifies which counter to use for the associated number
lists (see also Number Lists). The
first optional argument specifies the extension for the
makeindex transcript file (this information is only used by
makeglossaries which picks up the information from the
auxiliary file).
Note that the main (default) glossary is automatically created as:
\newglossary{main}{gls}{glo}{\glossaryname}so it can be identified by the label main. Using the acronym package option is equivalent to:
\newglossary[alg]{acronym}{acr}{acn}{\acronymname}so it can be identified by the label acronym. If you are not sure whether the acronym option has been used, you can identify the list of acronyms by the command \acronymtype which is set to acronym, if the acronym option has been used, otherwise it is set to main.
As you may have noticed in Defining Glossary Entries, when you
specify a new entry, you can specify alternate text to use when
the term is first used in the document. This provides a useful
means to define acronyms. For convenience, the glossaries package
defines the command:
\newacronym[key-val list]{label}{abbrv}{long}
By default, this is equivalent to:
\newglossaryentry {label}{type=\acronymtype,
name= {abbrv},
description= {long},
text= {abbrv},
first={ long ( abbrv)},
plural={ abbrv\glspluralsuffix},
firstplural={ long\glspluralsuffix\space
( abbrv\glspluralsuffix)},
key-val list}
As mentioned in the previous section, the command \acronymtype is the name of the glossary in which the acronyms should appear. If the acronym package option has been used, this will be acronym, otherwise it will be main. The acronyms can then be used in exactly the same way as any other glossary entry.
(Note: since \newacronym sets type=\acronymtype
,
if you want to load a file containing acronym definitions using
\loadglsentries[type]{filename}, the optional argument
type will not have an effect unless you explicitly set the
type as type=\glsdefaulttype
. See earlier for details.)
For example, the following defines the acronym IDN:
\newacronym{idn}{IDN}{identification number}This is equivalent to:
\newglossaryentry{idn}{type=\acronymtype, name={IDN}, description={identification number}, text={IDN}, first={identification number (IDN)}, plural={IDNs}, firstplural={identification numbers (IDNs)}}so
\gls{idn}
will produce "identification number (IDN)" on
first use and "IDN" on subsequent uses.
This section describes acronyms that have been defined using \newacronym. If you prefer to define all your acronyms using \newglossaryentry explicitly, then you should skip this section and ignore the package options: smallcaps, smaller, description, dua, footnote and shortcuts, as these options change the definition of \newacronym for common acronym formats as well as the way that the link text is displayed (see earlier). Likewise you should ignore the new commands described in this section, such as \acrshort, as they vary according to the definition of \newacronym.
Table 2 lists the package options and how the \newglossaryentry keys are used to store long (the long form) and abbrv (the short form). Note that the smallcaps option redefines \acronymfont so that it sets its argument using \textsc (so you should use lower case characters in abbrv) and the smaller option redefines \acronymfont to use \smaller5, otherwise \acronymfont simply displays its argument in the surrounding font. Note also that if none of the package options smallcaps, smaller, dua, description or footnote are used, \acronymfont is not used, so changing the definition of \acronymfont will have no effect under such circumstances.
In case you can't remember which key stores the long or short forms (or their plurals) the glossaries package provides the commands:
\newacronym[\glslongpluralkey={diagonal matrices}]{dm}{DM}{diagonal matrix}If the first use uses the plural form,
\glspl{dm}
will
display: diagonal matrices (DMs).
Each of the package options smallcaps, smaller, footnote, dua and description use \defglsdisplay and \defglsdisplayfirst (described earlier) to change the way the link text is displayed.
Note also that when these two package options are used (in the
given order), the glossaries package additionally implements the
sanitize option using
sanitize={description=false,symbol=false}
, so
remember to protect fragile commands when defining acronyms.
sanitize={symbol=false}
, so
remember to protect fragile commands when defining acronyms.
Note also that if this package option is used, the glossaries
package additionally implements the option
sanitize={description=false}
, so
remember to protect fragile commands when defining acronyms.
\textsc{#1}
, so abbrv
should be specified in lower case.
Note also that if this package option is used, the glossaries
package additionally implements the option
sanitize={symbol=false}
, so
remember to protect fragile commands when defining acronyms.
{\smaller #1}
.
Note also that if this package option is used, the glossaries
package additionally implements the option
sanitize={symbol=false}
, so
remember to protect fragile commands when defining acronyms.
Recall from earlier
that you can access the values of individual keys using commands
like \glstext, so it is possible to use these commands to
print just the long form or just the abbreviation without affecting
the flag that determines whether the entry has been used. However
the keys that store the long and short form vary depending on
the acronym style, so the glossaries package provides
commands that are set according to the package options. These are
as follows:
\acrshort[options]{label}[insert]
\ACRshort[options]{label}[insert]
\ACRshort[options]{label}[insert]
Print the abbreviated version with a hyperlink (if necessary) to the
relevant entry in the glossary. This is usually equivalent to
\glstext (or its uppercase variants) but may additionally
put the link text within the argument to \acronymfont.
\acrlong[options]{label}[insert]
\ACRlong[options]{label}[insert]
\ACRlong[options]{label}[insert]
Print the long version with a hyperlink (if necessary) to the
relevant entry in the glossary. This is may be equivalent to
\glsdesc, \glssymbol or \glsfirst (or their uppercase
variants), depending on package options.
\acrfull[options]{label}[insert]
\ACRfull[options]{label}[insert]
\ACRfull[options]{label}[insert]
Print the long version followed by the abbreviation in brackets
with a hyperlink (if necessary) to the
relevant entry in the glossary.
Note that if you change the definition of \newacronym, you may additionally need to change the above commands as well as the changing way the text is displayed using \defglsdisplay and \defglsdisplayfirst.
The package option shortcuts provides the synonyms listed in table 3. If any of those commands generate an "undefined control sequence" error message, check that you have enabled the shortcuts using the shortcuts package option. Note that there are no shortcuts for the commands that produce all upper case text.
When using \gls, \glspl and their uppercase variants it is
possible that you may want to use the value given by the
first key, even though you have already used the glossary
entry. Conversely, you may want to use the value given by the
text key, even though you haven't used the glossary entry.
The former can be achieved by one of the following commands:
\glsreset{label}
\glslocalreset{label}
while the latter can be achieved by one of the following commands:
\glsunset{label}
\glslocalunset{label}
You can determine whether an entry has been used using:
\ifglsused{label}{true part}{false part}
where label is the label of the required entry. If the
entry has been used, true part will be done, otherwise
false part will be done.
\item[]
, followed by the
name followed by a dotted line, followed by the description. Note that
this style ignores both the number list and the symbol. The
length \glslistdottedwidth
governs where the description should start.6
The glossary style can be set using the style package option
or using the style key in the optional
argument to \printglossary or using the command:
\glossarystyle{style-name}
All the styles except for the three- and four-column styles and the listdotted style use the command \glspostdescription after the description. This simply displays a full stop by default. To eliminate this full stop (or replace it with something else, say a comma) you will need to redefine \glspostdescription before the glossary is displayed.
If the predefined styles don't fit your requirements, you can
define your own style using:
\newglossarystyle{name}{definitions}
where name is the name of the new glossary style (to be
used in \glossarystyle). The second argument definitions,
needs to redefine all of the following:
This environment defines how the main body of the glossary should be typeset. Note that this does not include the section heading, the glossary preamble (defined by \glossarypreamble) or the glossary postamble (defined by \glossarypostamble.) For example, the list style uses the description environment, so the theglossary environment is simply redefined to begin and end the description environment.
This macro indicates what to do at the start of the main body of the glossary. Note that this is not the same as \glossarypreamble, which should not be affected by changes in the glossary style. The list glossary style redefines \glossaryheader to do nothing, whereas the longheader glossary style redefines \glossaryheader to do a header row.
This macro indicates what to do at the start of each logical block within the main body of the glossary. The glossary is sub-divided into twenty-eight logical blocks that are determined by the first character of the sort key (or name key if the sort key is omitted). The sub-divisions are in the following order: symbols, numbers, A, ..., Z. Note that the argument to \glsgroupheading is a label not the group title. The group title can be obtained via \glsgetgrouptitle{label}, and a navigation hypertarget can be created using \glsnavhypertarget{label}. Most of the predefined glossary styles redefine \glsgroupheading to simply ignore its argument. The listhypergroup style redefines \glsgroupheading as follows:
\renewcommand*{\glsgroupheading}[1]{% \item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]}See also \glsgroupskip below. (Note that command definitions within \newglossarystyle must use
##1
etc instead of #1
etc.)
This macro determines what to do after one logical group but before the header for the next logical group. The list glossary style simply redefines \glsgroupskip to be \indexspace.
This macro indicates what to do for a given glossary entry.
Note that formatted name will always be in the form
\glsnamefont{name}. This allows the user to set a given
font for the entry name, regardless of the glossary style used.
Note that label is the label used when the glossary entry
was defined via either \newglossaryentry or \newacronym.
Each time you use a glossary entry it creates a
link7
using \@glslink{label}{text} with the label
glo:label. Your
new glossary style must therefore redefine \glossaryentryfield
so that it uses \@glstarget{
glo:label}
{text}
to ensure the hyperlinks function correctly.8 For example, the
list style defines \glossaryentryfield as follows:
\renewcommand*{\glossaryentryfield}[5]{% \item[\@glstarget{glo:##1}{##2}] ##3\glspostdescription\space ##5}
Note also that number list will always be of the form
\glossaryentrynumbers{\relax
\setentrycounter{counter name}\glsnumberformat{number(s)}}
where number(s)
may contain \delimN (to delimit individual numbers) and/or
\delimR (to indicate a range of numbers). There may be
multiple occurrences of
\setentrycounter{counter name}\glsnumberformat{number(s)}, but note
that the entire number list is enclosed within the argument
to \glossaryentrynumbers. The user can redefine this to change
the way the entire number list is formatted, regardless of
the glossary style. However the most common use of
\glossaryentrynumbers is to provide a means of suppressing the
number list altogether. (In fact, the nonumberlist option
redefines \glossaryentrynumbers to ignore its argument.)
Therefore, when you define a new glossary style, you don't need
to worry about whether the user has specified the
nonumberlist package option.
If you want a completely new style, you will need to redefine all of the commands and environment listed above. You also need to take care when using internal commands (commands whose name contain the @ symbol). These should either be used in a .sty file or must be placed within \makeatletter and \makeatother.
For example, suppose you want each entry to start with a bullet point.
This means that the glossary should be placed in the itemize
environment, so theglossary should start and end that
environment. Let's also suppose that you don't want anything between
the glossary groups (so \glsgroupheading and \glsgroupskip
should do nothing) and suppose you don't want anything to appear
immediately after \begin{theglossary}
(so \glossaryheader
should do nothing). In addition, let's suppose the symbol should
appear in brackets after the name, followed by the description and
last of all the number list should appear within square brackets
at the end. Then you can create this new glossary style, called, say,
mylist, as follows:
\newglossarystyle{mylist}{% % put the glossary in the itemize environment: \renewenvironment{theglossary}{\begin{itemize}}{\end{itemize}}% % have nothing after \begin{theglossary}: \renewcommand*{\glossaryheader}{}% % have nothing between glossary groups: \renewcommand*{\glsgroupheading}[1]{}% \renewcommand*{\glsgroupskip}{}% % set how each entry should appear: \renewcommand*{\glossaryentryfield}[5]{% \item % bullet point \@glstarget{glo:##1}{##2}% the entry name \space (##4)% the symbol in brackets \space ##3% the description \space [##5]% the number list in square brackets }% }
If you want to define a new style that is a slightly modified version of an existing style, you can use \glossarystyle within the second argument of \newglossarystyle followed by whatever alterations you require. For example, suppose you want a style like the list style but you don't want the extra vertical space created by \indexspace between groups, then you can create a new glossary style called, say, mylist as follows:
\newglossarystyle{mylist}{% \glossarystyle{list}% base this style on the list style \renewcommand{\glsgroupskip}{}% make nothing happen between groups }
The glossaries package is supplied with the package
mfirstuc which provides the command:
\makefirstuc{stuff}
which makes the first object of
stuff uppercase unless stuff starts with a control
sequence followed by a group, in which case the first
object in the group is converted to uppercase. Examples:
\makefirstuc{abc}
produces Abc
\makefirstuc{\emph{abc}}
produces Abc
(\MakeUppercase has been applied to the letter "a" rather
than \emph.)
\makefirstuc{{\'a}bc}
produces Ábc
\makefirstuc{\ae bc}
produces Æbc
\makefirstuc{{\ae}bc}
produces Æbc
Note however that \makefirstuc{\ae{}bc}
produces æBc since
the empty group following \ae is considered to be the argument
of \ae which is in fact not the case.
Note also that
\newcommand{\abc}{abc} \makefirstuc{\abc}produces: ABC. This is because the first object in the argument of \makefirstuc is \abc, so it does
\MakeUppercase{\abc}
.
Whereas:
\newcommand{\abc}{abc} \expandafter\makefirstuc\expandafter{\abc}produces: Abc. There is a short cut command which will do this:
\newcommand{\abc}{abc} \xmakefirstuc{\abc}produces: Abc.