\documentclass[a4paper]{ltxdoc}
\usepackage{ifthen}
\usepackage{alltt}
\usepackage[colorlinks,
            bookmarks,
            hyperindex=false,
            pdfauthor={Nicola L.C. Talbot},
            pdftitle={glossaries.sty: LaTeX2e Package to Assist Generating Glossaries},
            pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref}

 %hyperindex conflicts with doc
 %(end up with |usage|hyperpage in indexentry)
 %This unfortunately means that the changes section doesn't
 %have active links, but at least it will keep makeindex happy.

\usepackage{creatdtx}
\ifmakedtx{
\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
\renewcommand{\main}[1]{\hyperpage{#1}}
\newcommand{\see}[2]{\emph{see} #1}
\makeatletter
\def\index@prologue{\section*{Index}}
\makeatother
\RecordChanges
\PageIndex
\CheckSum{4630}
\CodelineNumbered
\newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}}
\newcommand*{\term}[1]{#1\iterm{#1}}
\newcommand*{\iterm}[1]{\index{#1|main}}
\newcommand{\dq}[1]{``#1''}
}
{
\usepackage{html}
\usepackage{makeidx}
\renewcommand{\LaTeX}{LaTeX}
\renewcommand{\LaTeXe}{LaTeX2e}
\newcommand*{\termdef}[1]{\emph{#1}\index{#1}}
\newcommand*{\term}[1]{#1\index{#1}}
\newcommand*{\iterm}[1]{\index{#1}}
\newcommand{\dq}[1]{"#1"}
}


\ifmakedtx{
\newcommand*{\istkey}[1]{\texttt{#1}\index{makeindex=\texttt{makeindex}>#1=\texttt{#1}|hyperpage}}
\newcommand*{\ics}[1]{\texttt{\char`\\#1}\SpecialMainIndex{#1}}
\newcommand*{\appname}[1]{\texttt{#1}\index{#1=\texttt{#1}|hyperpage}}
\newcommand*{\mkidxspch}{\index{makeindex=\texttt{makeindex}>special characters|hyperpage}}
\newcommand*{\igloskey}[2][newglossaryentry]{\index{#1 options=\cs{#1} options>#2=\textsf{#2}|hyperpage}}
\newcommand*{\gloskey}[2][newglossaryentry]{\textsf{#2}\igloskey[#1]{#2}}
\newcommand*{\ipkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
\index{package options>#2=\textsf{#2}|hyperpage}}{%
\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}}}
\newcommand*{\pkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
\textsf{#2}\index{package options>#2=\textsf{#2}|hyperpage}}{%
\textsf{#2=#1}\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}}}
\newcommand*{\pkgoptval}[2]{\textsf{#1}\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}}
\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles>#1|hyperpage}}
\newcommand*{\filetype}[1]{\texttt{#1}\index{file types>#1|hyperpage}}
\newcommand*{\sty}[1]{\textsf{#1}}
\newcommand*{\isty}[1]{\sty{#1}\index{#1 package=\sty{#1} package|hyperpage}}
\newcommand*{\envname}[1]{\textsf{#1}}
}
{
\newcommand{\istkey}[1]{\texttt{#1}\index{makeindex key!#1}}
\newcommand{\ics}[1]{\texttt{\char`\\#1}\index{#1@\cs{#1}}}
\html{\newcommand{\SpecialMainIndex}[1]{\index{#1@\cs{#1}}}}
\newcommand{\appname}[1]{\texttt{#1}\index{#1@\texttt{#1}}}
\newcommand*{\mkidxspch}{\index{makeindex@\texttt{makeindex}!special characters|hyperpage}}
\newcommand{\gloskey}[2][newglossaryentry]{\texttt{#2}\index{#1 keys@\cs{#1} keys!#2}}
\newcommand{\ipkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
\index{package options!#2}}{%
\index{package options!#2!#1}}}
\newcommand{\pkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
\texttt{#2}\index{package options!#2}}{%
\texttt{#2=#1}\index{package options!#2!#1}}}
\newcommand{\pkgoptval}[2]{\texttt{#1}\index{package options!#2!#1}}
\newcommand{\glostyle}[1]{\texttt{#1}\index{glossary styles!#1}}
\newcommand{\filetype}[1]{\texttt{#1}\index{file types!#1}}
\newcommand{\sty}[1]{\texttt{#1}}
\newcommand{\isty}[1]{\sty{#1}\index{#1@\sty{#1}}}
\newcommand{\envname}[1]{\texttt{#1}}
\newcommand{\toTop}{\mbox{}\par\htmlref{Top}{top}}
}

\begin{document}\ifmakedtx{}{\label{top}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}

 \title{glossaries.sty v 1.12: \LaTeXe\ Package to Assist Generating Glossaries}
 \author{Nicola L.C. Talbot\\[10pt]
School of Computing Sciences\\
University of East Anglia\\
Norwich. Norfolk\\
NR4 7TJ. United Kingdom.\\
\url{http://theoval.cmp.uea.ac.uk/~nlct/}}

 \date{8th March 2008}
 \maketitle
\tableofcontents

 \section{Introduction}

 \changes{1.0}{2007 May 16}{Initial version}
The \sty{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 \isty{glossary} package which is now
obsolete.

As from version 1.08, the \sty{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 \isty{babel} \emph{before} 
\sty{glossaries} to enable this. \ifmakedtx{(See \autoref{sec:predefinednames} for the 
predefined names used by the \sty{glossaries} package.)}{}
As from version 1.1, the \sty{glossaries} package also supports 
Till~Tantau's \isty{translator} package provided it is loaded
before the \sty{glossaries} package. This makes it easier to change
the default translations or add new dictionaries.
If you don't want to use the predefined translations, you can use the
package option \pkgopt[false]{translate} and supply your own translations.

This documentation is structured as follows: \ifmakedtx{\autoref{sec:quick}}{\htmlref{{A Quick Guide For The Impatient}}{sec:quick}} is for 
people who want a few quick pointers of how to get started,
without having to read through lengthy descriptions, 
\ifmakedtx{\autoref{sec:overview}}{\htmlref{Overview}{sec:overview}} gives an overview of available commands 
and their syntax\ifmakedtx{, \autoref{sec:mfirstuc}}{ and 
\htmlref{Mfirstuc}{sec:mfirstuc}} describes the associated
\sty{mfirstuc} 
package\ifmakedtx{, \autoref{sec:code} contains the documented 
source code for those who want to know more about how the
package works and how to do more complicated things, such as
changing the way glossary entries appear}{}.
\ifmakedtx{}{\toTop}

\subsection{Generating the associated glossary files}
\label{sec:makeglossaries}

The \sty{glossaries} package comes with the Perl script
\appname{makeglossaries} which will run \appname{makeindex} on
all the glossary files using a customized \appname{makeindex}
\filetype{.ist} style file (which is created by \ics{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 
\texttt{myfile.tex}, do:
\begin{verbatim}
latex myfile
makeglossaries myfile
latex myfile
\end{verbatim}
You may need to explicitly load \appname{makeglossaries} into
Perl:
\begin{verbatim}
perl makeglossaries myfile
\end{verbatim}
There is a batch file called \texttt{makeglossaries.bat} which
does this for Windows users.

If you don't have Perl installed, you will have to run 
\appname{makeindex} for each glossary type you have defined.
For example, if you have used the \pkgopt{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 \texttt{myfile.tex}):
\begin{verbatim}
makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo
makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acn
\end{verbatim}
This requires remembering all extensions for each of the glossaries
defined in your document, so where possible you should use
\appname{makeglossaries} instead to reduce the possibility of error.
Don't pass all the glossary files in a single call to 
\appname{makeindex} or it will merge all your glossaries into a
single glossary.

If any problems occur, remember to check the transcript files 
(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages.\ifmakedtx{}{\toTop}

\subsection{Troubleshooting}

The glossaries package comes with a minimal file called 
\texttt{minimalgls.tex} which can be used for testing. This
should be located in \texttt{texmf/doc/latex/glossaries/samples/}. Further
information on debugging \LaTeX\ code is available at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}.

There is a list of frequently asked questions for the 
\sty{glossaries} package available at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}.\ifmakedtx{}{\toTop}

\section{A Quick Guide For The Impatient}
\label{sec:quick}

This section is for people who want a few quick pointers
of how to get started, without having to read through
lengthy descriptions.

\begin{enumerate}
\item Load \sty{glossaries} \emph{after} \isty{hyperref}:
\begin{verbatim}
\usepackage{hyperref}
\usepackage{glossaries}
\end{verbatim}
Similarly for the \isty{html} package:
\begin{verbatim}
\usepackage{html}
\usepackage{glossaries}
\end{verbatim}

\item Always use \ics{makeglossaries} if you want the glossary
entries to be written to the glossary file:
\begin{verbatim}
\documentclass{article}
\usepackage{glossaries}
\makeglossaries
\end{verbatim}
If you don't use \ics{makeglossaries}, your glossaries will
not appear in the document!

\item Use \ics{printglossaries} to make your glossaries appear 
in the document at that point. For example:
\begin{verbatim}
\maketitle
\printglossaries
\section{Introduction}
\end{verbatim}
Note that only the glossary entries that have been used in the
document text will appear in the glossary.

\item When you have created your document, run \LaTeX\ on it,
then the Perl script \appname{makeglossaries}, then run \LaTeX\
on it again:
\begin{verbatim}
latex myfile
makeglossaries myfile
latex myfile
\end{verbatim}
(You may need to run \LaTeX\ again if you have used the \pkgopt{toc}
package option.)
If you use Windows, there is a batch file called 
\texttt{makeglossaries.bat} which you can use, but you will
still need Perl installed.

\item New glossaries can be defined using:\par
\ics{newglossary}\oarg{log-ext}%
\marg{label}\marg{in-ext}\marg{out-ext}%
\marg{title}\par where \meta{label} is an identifying label,
\meta{in-ext} is the extension of the file to be created
by \appname{makeindex} (called by \appname{makeglossaries}),
\meta{out-ext} is the extension of the file to be read by
\appname{makeindex} and \meta{title} is the title for this
new glossary. The first optional argument \meta{log-ext} specifies
the extension of the \appname{makeindex} transcript file. Example:
\begin{verbatim}
\newglossary[nlg]{notation}{not}{ntn}{Notation}
\end{verbatim}
This glossary's label is \texttt{notation} and its title
will be Notation. If you use \appname{makeglossaries}, the 
\appname{makeindex} transcript will be written to a file with the
extension \filetype{.nlg}. If \meta{log-ext} is omitted, the extension
\filetype{.glg} will be used.

\item Any new glossaries must be defined before 
\cs{makeglossaries}
\begin{verbatim}
\documentclass{article}
\usepackage{glossaries}
\newglossary{notation}{not}{ntn}{Notation}
\makeglossaries
\end{verbatim}

\item If you use the \pkgopt{acronym} package option, the 
\sty{glossaries} package
will automatically create a new glossary type labelled
\texttt{acronym}:
\begin{verbatim}
\usepackage[acronym]{glossaries}
\end{verbatim}

\item If your pages have a hyphen compositor (i.e.\ your page
numbers appear in the form 2-1), redefine \ics{glscompositor}
\emph{before} \ics{makeglossaries}:
\begin{verbatim}
\documentclass{article}
\usepackage{glossaries}
\renewcommand{\glscompositor}{-}
\makeglossaries
\end{verbatim}

\item To add the glossaries to the table of contents use the
\pkgopt{toc} package option:
\begin{verbatim}
\usepackage[toc]{glossaries}
\end{verbatim}

\item Define a new entry with:\par
\ics{newglossaryentry}\marg{label}\marg{key-val list}\par
The \meta{key-val list} must at least contain a \gloskey{name}
key and a \gloskey{description} key.
For example:
\begin{verbatim}
\newglossaryentry{perl}{name=Perl,
description=A scripting language}
\end{verbatim}
In this example, I have given the entry the label \texttt{perl}.
Whenever I want to use this entry, that is the label I need
to use to identify it.

\item If the entry name starts with an accented letter, you will
need to group the first letter (otherwise it will cause a
problem for \ics{Gls} and \ics{Glspl}):
\begin{verbatim}
\newglossaryentry{elite}{name={{\'e}lite},
description={select group or class}}
\end{verbatim}
Likewise with commands such as \cs{ae} and \cs{oe}:
\begin{verbatim}
\newglossaryentry{oesophagus}{%
name={{\oe}sophagus},
description={canal from mouth to stomach}}
\end{verbatim}

\item If you have multiple glossaries, use the \gloskey{type}
key to specify in which glossary the entry belongs. For example:
\begin{verbatim}
\newglossary{languages}{lan}{lng}{Index of Languages}

\makeglossaries

\newglossaryentry{perl}{name=Perl,
description=A scripting language,
type=languages}
\end{verbatim}
If \gloskey{type} is omitted, the default glossary is used.

\item Remember to group values that have a comma or equal sign.
For example:
\begin{verbatim}
\newglossaryentry{pagelist}{name=page list,
description={A list of individual pages or page ranges
(e.g.\ 1,2,4,7--9)}}
\end{verbatim}

\item Plural forms are assumed to be the singular form with an
\dq{s} appended, unless otherwise specified. To specify an
irregular plural, use the \gloskey{plural} key. For example:
\begin{verbatim}
\newglossaryentry{matrix}{name=matrix,
description=rectangular array of quantities,
plural=matrices}
\end{verbatim}

\item The way the term appears in the main text can be different
from the way the term appears in the glossary:
\begin{verbatim}
\newglossaryentry{matrix}{name=Matrix,
description=rectangular array of quantities,
text=matrix,
plural=matrices}
\end{verbatim}
In this example, the entry name appears as \dq{Matrix} in the 
glossary, and either \dq{matrix} or \dq{matrices} in the text.

\item The way the term appears on first use can be different
to the way it appears subsequently:
\begin{verbatim}
\newglossaryentry{singmtx}{name=Singular Matrix,
description=A matrix with a zero determinant,
first=singular matrix (SM),
text=SM,
firstplural=singular matrices (SMs)}
\end{verbatim}
In this example, the entry name appears as \dq{Singular Matrix} in
the glossary, and in the text it appears as \dq{singular matrix (SM)}
or \dq{singular matrices (SMs)} the first time the entry is used,
and subsequently appears as \dq{SM} or \dq{SMs}.

\item The quick and easy way to define an acronym is to use:\par
\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrev}%
\marg{long}\par
For example:
\begin{verbatim}
\newacronym{svm}{SVM}{support vector machine}
\end{verbatim}
This is equivalent to:
\begin{verbatim}
\newglossaryentry{svm}{type=\acronymtype,
name={SVM},
description={support vector machine},
text={SVM},
first={support vector machine (SVM)},
plural={SVMs},
firstplural={support vector machines (SVMs)}}
\end{verbatim}
(The value of \ics{acronymtype} varies depending on whether
the \pkgopt{acronym} package option is used or not.
The optional argument \meta{key-val list} can be used to
override any of the \ics{newglossaryentry} keys; for
example, if the acronym has an irregular plural.)

\item The font used to display the entry name in the glossary
is governed by \ics{glsnamefont}. This can be redefined
as required. For example, to make the entry names appear
in a medium sans-serif font do:
\begin{verbatim}
\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}}
\end{verbatim}
Note that the list-like glossary styles defined in the
\isty{glossary-list} package place the entry name in
the optional argument to \ics{item}, so they will
appear in bold, unless you redefine \ics{glsnamefont} to counteract the
bold font.

\item In the document use \ics{gls}\marg{label}
to use a predefined term (this will also enter the term into 
the associated glossary output file). For example:
\begin{verbatim}
A \gls{singmtx} is a matrix with a zero determinant.
\end{verbatim}

\item Other variations:
\begin{itemize}
\item \ics{Gls}\marg{label} : like \cs{gls},
but with first letter in upper case
\item \ics{GLS}\marg{label} : like \cs{gls},
but all upper case.
\item \ics{glspl}\marg{label} : use plural
\item \ics{Glspl}\marg{label} : use plural with
first letter in upper case
\item \ics{GLSpl}\marg{label} : use plural but
all upper case
\item \ics{glslink}\marg{label}\marg{link text} :
use \meta{link text} to link to the given entry in the glossary.
\end{itemize}
For example, the following will produce the plural form with
the first letter in uppercase:
\begin{verbatim}
\Glspl{singmtx} are matrices with a zero determinant.
\end{verbatim}

\item Additional text can be appended to the link using the
end optional argument. For example, to form the possessive:
\begin{verbatim}
The \gls{singmtx}['s] dimensions \ldots
\end{verbatim}

\item The format of the associated entry number can be
changed using the \gloskey[glslink]{format} key in the optional argument.
Note that the value of the \gloskey[glslink]{format} key should be the
name of a command \emph{without} the initial backslash. For
example:
\begin{verbatim}
The primary definition of \glspl[format=textbf]{singmtx}.
\end{verbatim}
In this example the relevant glossary entry will have the
page number in bold (since it uses \cs{textbf}) but
it will no longer have a hyperlink (if hyperlinks are enabled.)

\item The \sty{glossaries} package provides commands to
change the font whilst ensuring that the number remains a
hyperlink. These are of the form \cs{hyper}\meta{xx} and
are equivalent to the standard font changing commands of the
form \cs{text}\meta{xx}, as well as \ics{hyperemph}
(which uses \ics{emph}.) For example:
\begin{verbatim}
The primary definition of \glspl[format=hyperbf]{singmtx}.
\end{verbatim}

\item Don't use declarations in \gloskey[glslink]{format} as this can
cause unpredictable results, as there is no guarantee that the effect
will be localised to the required text.

\item Entries can be added to the glossary without producing
any text using \ics{glsadd}\marg{label} or
\ics{glsaddall}. These commands also taken an optional
argument where you can specify the format. For example
\begin{verbatim}
\glsadd[format=hyperbf]{singmtx}
\end{verbatim}
will add a line to the
glossary file for the specified term, but will not produce
any text where the command occurs.

\item A number range can be entered using \verb|format=(| and
\verb"format=)" to mark the beginning and ending of the
range\footnote{This is new to version 1.01}. For example:
\begin{verbatim}
 \glsadd[format=(]{singmtx}
 This is a very long section all about \glspl{singmtx}.

 % lots of text omitted

 \glsadd[format=)]{singmtx}
\end{verbatim}
This is equivalent to \appname{makeindex}'s \verb"|(" and \verb"|)" 
formats.

\item You can combine the range markers with a formatting command
(again without the preceding backslash). For example:
\begin{verbatim}
 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}.
\end{verbatim}

\item Only those terms that have actually been used in the
document will be placed in the glossary. If you have defined
a term that doesn't appear in the document, then it means
you haven't used it in the text (either via \ics{glslink}
or \ics{gls} and related commands, or via \ics{glsadd}
or \ics{glsaddall}.)

\item To change the sorting order, use the \gloskey{sort} key.
For example:
\begin{verbatim}
\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}},
description=The universal set,
sort=U}
\end{verbatim}

\item You don't need to escape \appname{makeindex}'s special characters:
\begin{verbatim}
\newglossaryentry{quote}{name={"},
description={Double quote character}}

\newglossaryentry{exclam}{name={!},
description={Exclamation mark}}

\newacronym{rna}{RNA}{ribonukleins\"aure}
\end{verbatim}

\item Associated symbols can also be specified, but whether the
symbol appears in the glossary depends on the glossary style.
For example:
\begin{verbatim}
\newglossaryentry{metre}{name={metre},
description={A metric measurement of length},
symbol={m}}
\end{verbatim}
The predefined glossary styles that display the entry symbol
are: \glostyle{long4col}, \glostyle{long4colheader},
\glostyle{long4colborder}, \glostyle{long4colheaderborder},
\glostyle{super4col}, \glostyle{super4colheader}, 
\glostyle{super4colborder} and \glostyle{super4colheaderborder}.
All the other styles supplied by this package ignore the associated 
symbol.

\item Glossary styles can be set using the \pkgopt{style} 
package option. For example:
\begin{verbatim}
\usepackage[style=long3col]{glossaries}
\end{verbatim}
or using \ics{glossarystyle}\marg{style}. For example:
\begin{verbatim}
\glossarystyle{altlist}
\end{verbatim}
The predefined glossary styles provided by the \sty{glossaries}
bundle are listed in \ifmakedtx{\autoref{sec:styles}}{\htmlref{{Glossary Styles}}{sec:styles}}.

\item The list of numbers associated with each glossary entry
can be suppressed using the package option \pkgopt{nonumberlist}:
\begin{verbatim}
\usepackage[nonumberlist]{glossaries}
\end{verbatim}

\item By default, the glossaries will appear in an unnumbered 
chapter if chapters are defined, otherwise in an unnumbered
section. This can be changed using the \pkgopt{section} package
option. For example, to make the glossaries appear in an unnumbered
section, even if chapters are defined, do:
\begin{verbatim}
\usepackage[section]{glossaries}
\end{verbatim}
Other sectional units can also be specified as 
\pkgopt{section}=\meta{value}. For example, to make the glossaries
appear in unnumbered subsections:
\begin{verbatim}
\usepackage[section=subsection]{glossaries}
\end{verbatim}

\end{enumerate}\ifmakedtx{}{\toTop}

\section{Overview}\label{sec:overview}
 \changes{1.02}{2007 May 25}{added overview section}

\subsection{Package Options}

The \sty{glossaries} package options are as follows:
\begin{description}
\item[\pkgopt{toc}] Add the glossaries to the table of contents.

\item[\pkgopt{numberline}] When used with \pkgopt{toc}, this will
add \cs{numberline}\verb|{}| in the final argument of 
\cs{addcontentsline}. This will align the table of contents entry 
with the numbered section titles. Note that this option has no
effect if the \pkgopt{toc} option is omitted. If \pkgopt{toc} is
used without \pkgopt{numberline}, the title will be aligned with
the section numbers rather than the section titles.

\item[\pkgopt{acronym}] Make a separate glossary for acronyms.

\item[\pkgopt{section}] This is a \meta{key}=\meta{value} option.  Its
value should be the name of a sectional unit (e.g.\ chapter).
This will make the glossaries appear in the named sectional unit,
otherwise each glossary will appear in a chapter, if chapters
exists, otherwise in a section. Unnumbered sectional units will be used
by default. Example:
\begin{verbatim}
\usepackage[section=subsection]{glossaries}
\end{verbatim}
You can omit the value if you want to use sections, i.e.\
\begin{verbatim}
\usepackage[section]{glossaries}
\end{verbatim}
is equivalent to
\begin{verbatim}
\usepackage[section=section]{glossaries}
\end{verbatim}
You can change this value later in the document using
\ics{setglossarysection}\marg{type}.

\item[\pkgopt{numberedsection}]
The glossaries are placed in unnumbered sectional units by default,
but this can be changed using \pkgopt{numberedsection}. This option can take
three possible values: \pkgoptval{false}{numberedsection} (no
number, i.e.\ use starred form), \pkgoptval{nolabel}{numberedsection}
(numbered, i.e.\ unstarred form, but not labelled) and
\pkgoptval{autolabel}{numberedsection} (numbered with automatic
labelling). If \pkgopt[autolabel]{numberedsection} is used, each
glossary is given a label that matches the glossary type, so the
main (default) glossary is labelled \texttt{main}, the list of
acronyms is labelled \texttt{acronym}\footnote{if the
\pkgopt{acronym} option is used, otherwise the list of
acronyms is the main glossary} and additional glossaries are labelled
using the value specified in the first mandatory argument to 
\cs{newglossary}. For example, if you load \sty{glossaries}
using:
\begin{verbatim}
\usepackage[section,numberedsection=autolabel]{glossaries}
\end{verbatim}
then each glossary will appear in a numbered section, and can
be referenced using something like:
\begin{verbatim}
The main glossary is in section~\ref{main} and the list of
acronyms is in section~\ref{acronym}.
\end{verbatim}
If you can't decide whether to have the acronyms in the main
glossary or a separate list of acronyms, you can use
\ics{acronymtype} which is set to \texttt{main} if the
\pkgopt{acronym} option is not used and is set to \texttt{acronym}
if the \pkgopt{acronym} option is used. For example:
\begin{verbatim}
The list of acronyms is in section~\ref{\acronymtype}.
\end{verbatim}

\item[\pkgopt{style}] This is a \meta{key}=\meta{value} option. Its 
value should be the name of the glossary style to use. Predefined 
glossary styles are listed \ifmakedtx{in \autoref{sec:styles}}{\htmlref{later}{sec:styles}}.

\item[\pkgopt{nonumberlist}] This option will suppress the 
associated number lists\iterm{number list} in the glossaries (see also 
\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.)

\item[\pkgopt{counter}] This is a \meta{key}=\meta{value} option. The
value should be the name of the default counter to use in the number
lists\iterm{number list}.

\ifmakedtx{\hypertarget{sanitize}{}\relax}{\label{sanitize}}
\item[\pkgopt{sanitize}] This is a \meta{key}=\meta{value} option whose
value is also a \meta{key}=\meta{value} list. By default, the
\sty{glossaries} package sanitizes the values of the
\gloskey{name}, \gloskey{description} and \gloskey{symbol} keys used
when defining a new glossary entry. This may lead to unexpected results
if you try to display these values within the document text. This
sanitization can be switched off using the \pkgopt{sanitize} package
option. \ifmakedtx{(See \autoref{sec:pkgopt} and \autoref{sec:newentry} for 
further details.)}{} For example, to switch off the sanitization for the
\gloskey{description} and \gloskey{name} keys, but not for the
\gloskey{symbol} key, do:
\begin{verbatim}
\usepackage[sanitize={name=false,description=false,%
symbol=true}]{glossaries}
\end{verbatim}

\textbf{Note}: this sanitization only applies to the \gloskey{name}, 
\gloskey{description} and \gloskey{symbol} keys. It doesn't apply
to any of the other keys (except the \gloskey{sort} key which is
always sanitized) so fragile commands contained in the value of
the other keys must always be protected using \cs{protect}.
Since the value of the \gloskey{text} key is obtained from the
\gloskey{name} key, you will still need to protect fragile commands
in the \gloskey{name} key if you don't use the \gloskey{text} key. 

\item[\pkgopt{babel}] This is a boolean key and is for use when
the \sty{glossaries} package is used in conjunction with the
\isty{babel} package. The default is \pkgopt[true]{babel}, which
adds the glossary translations to \isty{babel}'s captions. If
you don't like the translations provided by the \sty{glossaries}
package, you can set \pkgopt[false]{babel} and provide your own
translations.

\item[\pkgopt{description}] This option changes the definition of
\ics{newacronym} to allow a description. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
for further details.

\item[\pkgopt{footnote}] This option changes the definition of
\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
for further details.

\item[\pkgopt{smallcaps}] This option changes the definition of
\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
for further details.

\item[\pkgopt{dua}] This option changes the definition of
\ics{newacronym} so that acronyms are always expanded. 
See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
for further details.

\end{description}\ifmakedtx{}{\toTop}

\subsection{Defining Glossary Entries}
\label{sec:newglosentry}

All glossary entries that are used in a document must be defined in
the preamble. Only those entries that occur in the document
(using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} and 
\ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}}) will appear in the glossary. Each time an entry 
is used in this way, a line is added to an associated glossary
(\filetype{.glo}) file, which then needs to be converted into a
corresponding \filetype{.gls} file which contains the typeset glossary
which is input by \ics{printglossary} or
\ics{printglossaries}.  The Perl script \appname{makeglossaries}
can be used to call \appname{makeindex}, using a customised
\filetype{.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.

\DescribeMacro{\makeglossaries}
The command \cs{makeglossaries} must be placed in the preamble in
order to create the customised \appname{makeindex} \filetype{.ist}
style file and to ensure that glossary entries are written to the
appropriate output file. If you omit \cs{makeglossaries} none of the
glossaries will be created. Note that if your page numbers use a 
hyphen compositor, you must set this by redefining 
\DescribeMacro{\glscompositor}\cs{glscompositor} \emph{before}
using \cs{makeglossaries}:
\begin{verbatim}
\renewcommand*{\glscompositor}{-}
\end{verbatim}
(The default value of \cs{glscompositor} is a full stop.)

\DescribeMacro{\newglossaryentry}
New glossary entries are defined using the command:\\[10pt]
\cs{newglossaryentry}\marg{label}\marg{key-val list}\\[10pt] The first
argument, \meta{label}, must be a unique label with which to identify
this entry. The second argument, \meta{key-val list}, is a
\meta{key}=\meta{value} list that supplies the relevant information
about this entry. There are two required fields: \gloskey{name} and
\gloskey{description}. Available fields are listed below:

\begin{description}
\item[{\gloskey{name}}] The name of the entry (as it will appear in the
glossary).

\item[{\gloskey{description}}] A brief description of this term (to
appear in the glossary).

\item[{\gloskey{descriptionplural}}] The plural form of the 
description (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value
is set to the same as the \gloskey{description} key.

\item[{\gloskey{text}}] How this entry will appear in the document text
when using \ics{gls} (or one of its uppercase variants). If this
field is omitted, the value of the \gloskey{name} key is used.

\item[{\gloskey{first}}] How the entry will appear in the document text
the first time it is used with \ics{gls} (or one of its uppercase
variants). If this field is omitted, the value of the \gloskey{text}
key is used.

\item[{\gloskey{plural}}] How the entry will appear in the document text
when using \ics{glspl} (or one of its uppercase variants).
If this field is omitted, the value is obtained by appending an
\dq{s} to the value of the \gloskey{text} field.

\item[{\gloskey{firstplural}}] How the entry will appear in the document
text the first time it is used with \ics{glspl} (or one of
its uppercase variants). If this field is omitted, the value is
obtained by appending an \dq{s} to the value of the \gloskey{first}
field.

\item[{\gloskey{symbol}}] This field is provided to allow the user to
specify an associated symbol, but most glossary styles ignore
this value. If omitted, the value is set to \cs{relax}.

\item[{\gloskey{symbolplural}}] This is the plural form of the
symbol (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value
is set to the same as the \gloskey{symbol} key.

\item[{\gloskey{sort}}] This value indicates how \appname{makeindex}
should sort this entry. If omitted, the value is given by the
\gloskey{name} field.  This value is equivalent to
\appname{makeindex}'s \dq{actual} character (which is usually the
at-sign @ although the \sty{glossaries} package uses a different
symbol).

\item[{\gloskey{type}}] This is the glossary type to which this entry
belongs. If omitted, the default glossary is assumed
(\texttt{type=main}). The list of acronyms type is given by
\ics{acronymtype} which will either be \texttt{main} or
\texttt{acronym}, depending on whether the \pkgopt{acronym} package
option was used.
\end{description}
Note that if the key starts with an accented letter,
you must group the accented letter, otherwise it will cause a
problem for \cs{Gls} and \cs{Glspl}. For example:
\begin{verbatim}
\newglossaryentry{elite}{name={{\'e}lite},
description={select group or class}}
\end{verbatim}
Similarly, commands such as \cs{ae} and \cs{oe} should either be placed
inside a group or followed by a space. For example:
\begin{verbatim}
\newglossaryentry{oesophagus}{%
name={{\oe}sophagus},
description={canal from mouth to stomach}}
\end{verbatim}
The following is also fine:
\begin{verbatim}
\newglossaryentry{oesophagus}{%
name={\oe sophagus},
description={canal from mouth to stomach}}
\end{verbatim}
but don't do \verb|\oe{}sophagus| as it will confuse 
\ics{makefirstuc} (described 
\ifmakedtx{in \autoref{sec:mfirstuc}}{\htmlref{later}{sec:mfirstuc}}) 
and will produce \ifmakedtx{\oe{}}{oe}Sophagus instead of 
\ifmakedtx{{\OE}}{OE}sophagus. 


\DescribeMacro{\loadglsentries}
You can store all your glossary entry definitions in another
file, and use:\\[10pt]
\cs{loadglsentries}\oarg{type}\marg{filename}\\[10pt]
where \meta{filename} is the name of the file containing all the
\cs{newglossaryentry} commands. The optional argument
\meta{type} is the name of the glossary to which those entries
should belong, for those entries where the \gloskey{type} key has 
been omitted. Note that only those entries that have been used
in the text will appear in the relevant glossaries.\ifmakedtx{}{\toTop}

\subsection{Number lists}
\label{sec:numberlists}

Each entry in the glossary has an associated \termdef{number list}. 
By default,
these numbers refer to the pages on which that entry has been used
(using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} 
and \ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}}). The number list can be suppressed using 
the \pkgopt{nonumberlist} package option, or an alternative counter
can be set as the default using the \pkgopt{counter} package option.\ifmakedtx{}{\toTop}

\subsection{Links to Glossary Entries}
\label{sec:glslink}

Once you have defined a glossary entry using 
\ics{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 
\termdef{link text} (even if there are no hyperlinks).

The way the \term{link text} is displayed 
depends on \DescribeMacro{\glstextformat}\cs{glstextformat}\marg{text}.
For example, to make all \term{link text} appear in a sans-serif
font, do:
\begin{verbatim}
\renewcommand*{\glstextformat}[1]{\textsf{#1}}
\end{verbatim}

\DescribeMacro{\glslink}
The command:\\[10pt]
\cs{glslink}\oarg{options}\marg{label}\marg{text}\\[10pt]
will place \meta{text} in the document at that point and add
a line into the associated glossary file for the glossary entry
given by \meta{label}. If hyperlinks are supported, \meta{text}
will be a hyperlink to the relevant line in the glossary. The
optional argument \meta{options} must be a \meta{key}=\meta{value} 
list which can take any of the following keys:

\begin{description}
\item[{\gloskey[glslink]{format}}] This specifies how to format the
associated number for this entry in the glossary. This value is
equivalent to the \appname{makeindex} encap value, and (as with
\cs{index}) the value needs to be the name of a command \emph{without}
the initial backslash. As with \cs{index}, the characters \verb"(" and
\verb")" can also be used to specify the beginning and ending of a
number range.  Again as with \cs{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 \cs{bfseries})
instead of a text block command (such as \cs{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.\ \textbf{bold} and \emph{italic}) you will
need to create a command that applies both formats, e.g.\ 
\begin{verbatim}
\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}
\end{verbatim}
and use that command.

If you are using hyperlinks and you want to change the font of the
hyperlink, don't use \cs{hyperpage} (provided by the \isty{hyperref}
package) as the numbers may not refer to a page number.
Instead, the \sty{glossaries} package provides the following 
number formats:
\begin{center}
\ifmakedtx{\begin{tabular}{@{\sffamily}lp{0.8\linewidth}}
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
\end{tabular}}{\begin{tabular}{ll}
\texttt{hyperrm} & The number is a serif hyperlink to the relevant part of the 
document\\
\texttt{hypersf} & The number is a sans-serif hyperlink to the relevant part 
of the document\\
\texttt{hypertt} & The number is a monospaced hyperlink to the relevant part 
of the document\\
\texttt{hyperbf} & The number is a bold hyperlink to the relevant part of the 
document\\
\texttt{hypermd} & The number is a medium weight hyperlink to the relevant 
part of the document\\
\texttt{hyperit} & The number is an italic hyperlink to the relevant 
part of the document\\
\texttt{hypersl} & The number is a slanted hyperlink to the relevant 
part of the document\\
\texttt{hyperup} & The number is an upright hyperlink to the relevant 
part of the document\\
\texttt{hypersc} & The number is a small caps hyperlink to the relevant 
part of the document\\
\texttt{hyperemph} & The number is an emphasized hyperlink to the relevant 
part of the document
\end{tabular}}
\end{center}
Note that if the \cs{hyperlink} command hasn't been defined,
the \texttt{hyper}\meta{xx} formats are equivalent to the
analogous \cs{text}\meta{xx} font commands. If you want to
make a new format, you will need to define a command which takes
one argument and use that; for example, if you want the associated 
number in the glossary to be in a bold sans-serif font, you can define a
command called, say, \cs{hyperbsf}:
\begin{verbatim}
\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
\end{verbatim}
and then use \texttt{hyperbsf} as the value for the \gloskey{format}
key.\ifmakedtx{  (See also \autoref{sec:printglos}.)}{}

\item[{\gloskey[glslink]{counter}}] This specifies which counter
to use for the associated number for this glossary entry. (See also
\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.)

\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can
be used to enable/disable the hyperlink to the relevant entry
in the glossary. (Note that setting \texttt{hyper=true} will have no
effect if \cs{hyperlink} has not been defined.) The default
value is \texttt{hyper=true}.

\end{description}
\DescribeMacro{\glslink*}
There is also a starred version:\\[10pt]
\cs{glslink*}\oarg{options}\marg{label}\marg{text}\\[10pt]
which is equivalent to \cs{glslink}, except it sets
\texttt{hyper=false}.

\DescribeMacro{\gls}
The command:\\[10pt]
\cs{gls}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is the same as \cs{glslink}, except that the \term{link text}
is determined from the values of the \gloskey{text} and 
\gloskey{first} keys supplied when the entry was defined using
\ics{newglossaryentry}. There are two uppercase variants:\\[10pt]
\DescribeMacro{\Gls}
\cs{Gls}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
and\\[10pt]
\DescribeMacro{\GLS}
\cs{GLS}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
which make the first letter of the link or all the link text
uppercase, respectively.

The final optional argument \meta{insert}, allows you to insert
some additional text into the link text. By default, this will
append \meta{insert} at the end of the link text. The first optional
argument \meta{options} is the same as the optional argument to
\ics{glslink}. As with \cs{glslink}, these commands also have
a starred version that disable the hyperlink.

There are also analogous plural forms:\\[10pt]
\DescribeMacro{\glspl}
\cs{glspl}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
\DescribeMacro{\Glspl}
\cs{Glspl}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSpl}
\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
These determine the link text from the \gloskey{plural} and
\gloskey{firstplural} keys supplied when the entry was first
defined. As before, these commands also have
a starred version that disable the hyperlink.

\DescribeMacro{\glstext}The command:\\[10pt]
\cs{glstext}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{text} key and does not mark the entry as
having been used.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glstext}
\cs{Glstext}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLStext}
\cs{GLStext}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glsfirst}The command:\\[10pt]
\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{first} key and does not mark the entry as
having been used.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsfirst}
\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSfirst}
\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glsplural}The command:\\[10pt]
\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{plural} key and does not mark the entry as
having been used.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsplural}
\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSplural}
\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glsfirstplural}The command:\\[10pt]
\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{firstplural} key and does not mark the entry as
having been used.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsfirstplural}
\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSfirstplural}
\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glsname}The command:\\[10pt]
\cs{glsname}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{name} key and does not mark the entry as
having been used. Note: if you want to use this command and the
\gloskey{name} key contains commands, you will have to disable the
\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
of the \gloskey{name} key and protect fragile commands.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsname}
\cs{Glsname}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSname}
\cs{GLSname}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glssymbol}The command:\\[10pt]
\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{symbol} key and does not mark the entry as
having been used. Note: if you want to use this command and the
\gloskey{symbol} key contains commands, you will have to disable the
\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
of the \gloskey{symbol} key and protect fragile commands.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glssymbol}
\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSsymbol}
\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\DescribeMacro{\glsdesc}The command:\\[10pt]
\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
is similar to \ics{gls} except that it always uses the value
of the \gloskey{description} key and does not mark the entry as
having been used. Note: if you want to use this command and the
\gloskey{description} key contains commands, you will have to disable the
\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
of the \gloskey{description} key and protect fragile commands.

There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsdesc}
\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
\DescribeMacro{\GLSdesc}
\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert}\\[10pt]
As before, these commands also have a starred version that disable
the hyperlink.

\ifmakedtx{}{\toTop}

\subsubsection{Changing the format of the link text}
\label{sec:glsdisplay}

The format of the \term{link text} for \ics{gls}, \ics{glspl}
and their uppercase variants is governed by two commands:
\DescribeMacro{\glsdisplayfirst}\cs{glsdisplayfirst}, which is used the
first time a glossary entry is used in the text and
\DescribeMacro{\glsdisplay}\cs{glsdisplay}, which is used subsequently.
Both commands take four arguments: the first is either the singular or
plural form given by the \gloskey{text}, \gloskey{plural},
\gloskey{first} or \gloskey{firstplural} keys (used when the term was
defined) depending on context; the second argument is the term's
description (as supplied by the \gloskey{description} key); the third
argument is the symbol associated with the term (as supplied by the
\gloskey{symbol} key) and the fourth argument is the additional text
supplied in the final optional argument to \cs{gls} or
\cs{glspl} (or their uppercase variants). The default definitions
of \cs{glsdisplay} and \cs{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 \gloskey{symbol} key to store the unit:
\begin{verbatim}
\newglossaryentry{distance}{name=distance,
description={The length between two points},
symbol={km}}
\end{verbatim}
and now suppose you want \verb|\gls{distance}| to produce
\dq{distance (km)} on first use, then you can redefine
\cs{glsdisplayfirst} as follows:
\begin{verbatim}
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
\end{verbatim}
Note that the additional text is placed after \verb|#1|, so
\verb|\gls{distance}['s]| will produce \dq{distance's (km)}
rather than \dq{distance (km)'s} which looks a bit odd (even though
it may be in the context of \dq{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 \term{link text} will be formatted according
to \ics{glstextformat} (described earlier). So if you do, say:
\begin{verbatim}
\renewcommand{\glstextformat}[1]{\textbf{#1}}
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
\end{verbatim}
then \verb|\gls{distance}| will produce \dq{\textbf{distance (km)}}.

If you have multiple glossaries, changing \cs{glsdisplayfirst} and
\cs{glsdisplay} will change the way entries for all of the
glossaries appear when using commands \cs{gls}, \cs{glspl} and their
uppercase variants.  If you only
want the change to affect entries for a given glossary, then you need
to use \DescribeMacro{\defglsdisplay}\cs{defglsdisplay} and
\DescribeMacro{\defglsdisplayfirst}\cs{defglsdisplayfirst} instead
of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}.

Both \cs{defglsdisplay} and \cs{defglsdisplayfirst} take two arguments:
the first (which is optional) is the glossary name\footnote{\texttt{main} for the main
(default) glossary, \cs{acronymtype} for the list of acronyms, or the
name supplied in the first mandatory argument to \cs{newglossary} for
additional glossaries.} and the second is how the term should be
displayed when it is invoked using commands \cs{gls}, 
\cs{glspl} and their uppercase variants. This is similar to the way \cs{glsdisplayfirst} was
redefined above.

For example, suppose you have created a new glossary called
\texttt{notation} and you want to change the way the entry is
displayed on first use so that it includes the symbol, you can
do:
\begin{verbatim}
\defglsdisplayfirst[notation]{#1#4 (denoted #3)}
\end{verbatim}
Now suppose you have defined an entry as follows:
\begin{verbatim}
\newglossaryentry{set}{type=notation,
name=set,
description={A collection of objects},
symbol={$S$},
}
\end{verbatim}
The first time you reference this entry using \cs{gls} it
will be displayed as: \dq{set (denoted \ifmakedtx{$S$}{\textit{S}})} 
(similarly for \cs{glspl} and the uppercase variants).

Remember that if you use the \gloskey{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 \term{link text}, you will have to disable the
\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
of these keys and protect fragile commands.\ifmakedtx{}{\toTop}

\subsubsection{Enabling and disabling hyperlinks to glossary entries}

If you load the \isty{hyperref} or \isty{html} packages prior to
loading the \sty{glossaries} package, commands such as \ics{glslink}
and \ics{gls}, described above, will automatically have hyperlinks
to the relevant glossary entry, unless the \gloskey[glslink]{hyper}
option has been set to \texttt{false}. You can disable or enable links using:\\[10pt]
\DescribeMacro{\glsdisablehyper}\cs{glsdisablehyper}\\[10pt]
and\\[10pt]
\DescribeMacro{\glsenablehyper}\cs{glsenablehyper}\\[10pt]
respectively. The effect can be localised by placing the commands
within a group. Note that you should only use \cs{glsenablehyper}
if the commands \ics{hyperlink} and \ics{hypertarget} have been
defined (for example, by the \isty{hyperref} package).

\subsection{Adding an entry to the glossary without generating text}
\label{sec:glsadd}

\DescribeMacro{\glsadd}
It is possible to add a line in the glossary file without
generating any text at that point in the document using:\\[10pt]
\cs{glsadd}\oarg{options}\marg{label}\\[10pt]
This is similar to \ics{glslink}, only it doesn't produce
any text (so therefore, there is no \gloskey[glslink]{hyper} key
available in \meta{options} but all the other options that can
be used with \cs{glslink} can be passed to \cs{glsadd}).

\DescribeMacro{\glsaddall}
To add all entries that have been defined, use:\\[10pt]
\cs{glsaddall}\oarg{glossary list}\\[10pt]
If there are multiple glossaries, you can specify to add only
those entries which belong to the glossaries listed in
\meta{glossary list} (which must be a comma separated list of
glossary names). For example:
\begin{verbatim}
\glsaddall[notation]
\end{verbatim}
will add all the entries that have been defined for the glossary
labelled \dq{notation}.\ifmakedtx{}{\toTop}

\subsection{Displaying a glossary}

\DescribeMacro{\printglossaries}
The command \cs{printglossaries} will display all the
defined glossaries. Note that no glossaries will appear until
you have either used the Perl script \appname{makeglossaries}
or have directly used \appname{makeindex} (as described in 
\ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the Associated Glossary Files}{sec:makeglossaries}}). If the glossary still 
does not appear after you re-\LaTeX\ your document, check
the \appname{makeindex} log files to see if there is a problem.
Remember that you also need to use the command \ics{makeglossaries} in
the preamble to enable the glossaries.

\DescribeMacro{\printglossary}
An individual glossary is displayed using:\\[10pt]
\cs{printglossary}\oarg{options}\\[10pt]
where \meta{options} is a \meta{key}=\meta{value} list of options. 
The following keys are available:
\begin{description}
\item[{\gloskey[printglossary]{type}}] The value of this key
specifies which glossary to print. If omitted, the default
glossary is assumed. For example, to print the list of acronyms:
\begin{verbatim}
\printglossary[type=\acronymtype]
\end{verbatim}

\item[{\gloskey[printglossary]{title}}] This is the glossary's
title (overriding the title specified when the glossary was 
defined).

\item[{\gloskey[printglossary]{toctitle}}] This is the title
to use for the table of contents (if the \pkgopt{toc} package
option has been used). If omitted, the glossary title is used.

\item[{\gloskey[printglossary]{style}}] This specifies which
glossary style to use for this glossary, overriding the effect
of the \pkgopt{style} option or \ics{glossarystyle}.
\end{description}

\DescribeMacro{\glossarypreamble}
Information can be added to the start of the glossary by redefining
\cs{glossarypreamble}. For example:
\begin{verbatim}
\renewcommand{\glossarypreamble}{Numbers in italic indicate
primary definitions.}
\end{verbatim}
This needs to be done before the glossary is displayed using
\cs{printglossaries} or \cs{printglossary}. Note that if you
want a different preamble for each glossary, you will need to
use a separate \cs{printglossary} for each glossary and change
the definition of \cs{glossarypreamble} between each glossary.
For example:
\begin{verbatim}
\renewcommand{\glossarypreamble}{Numbers in italic indicate
primary definitions.}
\printglossary
\renewcommand{\glossarypreamble}{}
\printglossary[type=acronym]
\end{verbatim}
Alternatively, you can do something like:
\begin{verbatim}
\renewcommand{\glossarypreamble}{Numbers in italic indicate
primary definitions.\gdef\glossarypreamble{}}
\printglossaries
\end{verbatim}
which will print the preamble text for the first glossary and 
change the preamble to do nothing for subsequent glossaries.
(Note that \cs{gdef} is required as the glossary is placed within
a group.)

\DescribeMacro{\glossarypostamble}There is an analogous command
called \cs{glossarypostamble} which is placed at the end of each
glossary.\ifmakedtx{}{\toTop}

\subsubsection{Changing the way the entry name appears in the glossary}
\label{sec:glsnamefont}

\DescribeMacro{\glsnamefont}Within each glossary, each entry name is
formatted according to \cs{glsnamefont} which takes one argument: the
entry name. This command is always used regardless of the glossary
style.  By default, \cs{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 \cs{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:
\begin{verbatim}
\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
\end{verbatim}
\ifmakedtx{}{\toTop}

\subsection{Defining New Glossaries}

\DescribeMacro{\newglossary}
A new glossary can be defined using:\\[10pt]
\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\oarg{counter}\\[10pt]
where \meta{name} is label to assign to this glossary. The arguments
\meta{in-ext} and \meta{out-ext} specify the extensions to give to the
input and output files for that glossary, \meta{title} is the default
title for this new glossary and the final optional argument
\meta{counter} specifies which counter to use for the associated number
lists\iterm{number list} (see also \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) The 
first optional argument specifies the extension for the
\appname{makeindex} transcript file (this information is only used by
\appname{makeglossaries} which picks up the information from the
auxiliary file.)

Note that the main (default) glossary is automatically created as:
\begin{verbatim}
\newglossary{main}{gls}{glo}{\glossaryname}
\end{verbatim}
so it can be identified by the label \texttt{main}. Using the
\pkgopt{acronym} package option is equivalent to:
\begin{verbatim}
\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
\end{verbatim}
so it can be identified by the label \texttt{acronym}. If you are
not sure whether the \pkgopt{acronym} option has been used, you
can identify the list of acronyms by the command 
\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to
\texttt{acronym}, if the \pkgopt{acronym} option has been used,
otherwise it is set to \texttt{main}.\ifmakedtx{}{\toTop}

\subsection{Acronyms}
\label{sec:acronyms}

\DescribeMacro{\newacronym}
As you may have noticed in \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry}}, 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. The \sty{glossaries} package defines
the command:\\[10pt]
\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt]
This is equivalent to:\vskip5pt
\begin{ttfamily}\par\noindent
\cs{newglossaryentry}\textrm{\marg{label}}\{type=\cs{acronymtype},\\
name=\textrm{\marg{abbrv}},\\
description=\textrm{\marg{long}},\\
text=\textrm{\marg{abbrv}},\\
first=\{\textrm{\meta{long}} (\textrm{\meta{abbrv}})\},\\
plural=\{\textrm{\meta{abbrv}}s\},\\
firstplural=\{\textrm{\meta{long}}s (\textrm{\meta{abbrv}}s)\},\\
\textrm{\meta{key-val list}}\}\par
\end{ttfamily}
\vskip5pt
As mentioned in the previous section, the command \cs{acronymtype} is
the name of the glossary in which the acronyms should appear. If the
\pkgopt{acronym} package option has been used, this will be
\texttt{acronym}, otherwise it will be \texttt{main}. The acronyms can
then be used in exactly the same way as any other glossary entry.
For example, the following defines the acronym IDN:
\begin{verbatim}
\newacronym{idn}{IDN}{identification number}
\end{verbatim}
This is equivalent to:
\begin{verbatim}
\newglossaryentry{idn}{type=\acronymtype,
name={IDN},
description={identification number},
text={IDN},
first={identification number (IDN)},
plural={IDNs},
firstplural={identification numbers (IDNs)}}
\end{verbatim}
so \verb|\gls{idn}| will produce \dq{identification number (IDN)} on
first use and \dq{IDN} on subsequent uses.

The \sty{glossaries} package has options that change the
definition of \ics{newacronym} for common acronym formats. These
options also change the way the link text is displayed for the
acronyms.

Table~\ref{tab:acronymsettings} lists the package options and
how the keys are used to store \meta{long} (the long form) and
\meta{abbrv} (the short form). Note that the \pkgopt{smallcaps}
option redefines \ics{acronymfont} so that it sets its argument
in small captials otherwise \cs{acronymfont} simply displays its
argument in the surrounding font. Note also that if none of
the package options \pkgopt{smallcaps}, \pkgopt{description}
or \pkgopt{footnote} are used, \cs{acronymfont} is not used, so
changing the definition of \cs{acronymfont} will have no effect
under such circumstances.

\begin{table}[htbp]
\caption{Package options governing acronyms and how the information
is stored in the glossary keys}
\label{tab:acronymsettings}
\begin{center}
\begin{tabular}{lllll}
\bfseries Package Option &
\gloskey{first} &
\gloskey{text} &
\gloskey{description} &
\gloskey{symbol}\\
\pkgopt{description},\pkgopt{footnote} &
\meta{abbrv} &
\meta{abbrv} &
user supplied &
\meta{long}\\
\pkgopt{description},\pkgopt{dua} &
\meta{long} &
\meta{long} &
user supplied &
\meta{abbrv}\\
\pkgopt{description} &
\meta{long} &
\meta{abbrv} &
user supplied &
\meta{abbrv}\\
\pkgopt{footnote} &
\meta{abbrv} &
\meta{abbrv} &
\meta{long} &
 \\
\pkgopt{smallcaps} &
\meta{long} &
\meta{abbrv} &
\meta{long} &
\meta{abbrv}\\
\pkgopt{dua} &
\meta{long} &
\meta{long} &
\meta{long} &
\meta{abbrv}\\
None of the above&
\meta{long} (\meta{abbrv}) &
\meta{abbrv} &
\meta{long} &
\end{tabular}
\end{center}
\end{table}

In case you can't remember which key stores the long or short forms
(or their plurals) the \sty{glossaries} package provides the 
commands:
\begin{itemize}
\item\DescribeMacro{\glsshortkey}\cs{glsshortkey}
The key used to store the short form.
\item\DescribeMacro{\glsshortpluralkey}\cs{glsshortpluralkey}
The key used to store the plural version of the short form.
\item\DescribeMacro{\glslongkey}\cs{glslongkey}
The key used to store the long form.
\item\DescribeMacro{\glslongpluralkey}\cs{glslongpluralkey}
The key used to store the plural version of the long form.
\end{itemize}
These can be used in the optional argument of \cs{newacronym}
to override the defaults. For example:
\begin{verbatim}
\newacronym[\glslongpluralkey={diagonal matrices}]{dm}{DM}{diagonal 
matrix}
\end{verbatim}
If the first use uses the plural form, \verb|\glspl{dm}| will
display: diagonal matrices (DMs).

Each of the package options \pkgopt{smallcaps}, \pkgopt{footnote}
and \pkgopt{description} use \ics{defglsdisplay} and 
\ics{defglsdisplayfirst} (described \ifmakedtx{in 
\autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}) 
to change the way the link text is displayed.

\begin{description}
\item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} 
When these two options are used together, the first use displays
the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} 
\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
where \meta{insert} indicates the text supplied in the final
optional argument to \cs{gls}, \cs{glspl} or their uppercase 
variants.

Note also that when these two package options are used (in the
given order), the \sty{glossaries} package additionally implements the
\pkgopt{sanitize} option using 
\ipkgopt[description]{sanitize}\ipkgopt[symbol]{sanitize}\verb|sanitize={description=false,symbol=false}|, so
remember to protect fragile commands when defining acronyms.

\item[dua]\ifmakedtx{\mbox{}\par}{} 
The \pkgopt{dua} package option always displays the expanded
form and so may not be used with \pkgopt{footnote} or 
\pkgopt{smallcaps}. Both first use and subsequent use displays the
entry in the form:\\[10pt]
\meta{long}\meta{insert}\\[10pt]
If the \pkgopt{description} option is also used, the \gloskey{name}
key is set to the long form, otherwise the \gloskey{name} key is
set to the short form and the \gloskey{description} key is set to
the long form.

\item[\pkgopt{description}]\ifmakedtx{\mbox{}\par}{} 
This option displays the entry on first use as:\\[10pt]
\meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
Note also that if this package option is used, the \sty{glossaries}
package additionally implements the option 
\ipkgopt[symbol]{sanitize}\verb|sanitize={symbol=false}|, so
remember to protect fragile commands when defining acronyms.

\item[\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} 
This option displays the entry on first use as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}

Note also that if this package option is used, the \sty{glossaries}
package additionally implements the option 
\ipkgopt[description]{sanitize}\verb|sanitize={description=false}|, so
remember to protect fragile commands when defining acronyms.

\item[\pkgopt{smallcaps}]\ifmakedtx{\mbox{}\par}{} 
If neither the \pkgopt{footnote} nor \pkgopt{description} options
have been set, this option displays the entry on first use as:\\[10pt]
\meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
where \cs{acronymfont} is set to \cs{textsc}.

Note also that if this package option is used, the \sty{glossaries}
package additionally implements the option 
\ipkgopt[symbol]{sanitize}\verb|sanitize={symbol=false}|, so
remember to protect fragile commands when defining acronyms.

\item[None of the above]\ifmakedtx{\mbox{}\par}{} 
If none of the package options \pkgopt{smallcaps}, \pkgopt{footnote}
or \pkgopt{description} are used, then on first use the entry is
displayed as:\\[10pt]
\meta{long} (\meta{abbrv})\meta{insert}\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
\meta{abbrv}\meta{insert}
\end{description}

Recall from \ifmakedtx{\autoref{sec:glslink}}{\htmlref{earlier}{sec:glslink}} 
that you can access the values of individual keys using commands
like \ics{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 \sty{glossaries} package provides
commands that are set according to the package options. These are
as follows:
\vspace{10pt}\par\noindent
\DescribeMacro{\acrshort}
\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\Acrshort}
\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\ACRshort}
\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
Print the abbreviated version with a hyperlink (if necessary) to the
relevant entry in the glossary. This is usually equivalent to
\ics{glstext} (or its uppercase variants) but may additionally
put the link text within the argument to \ics{acronymfont}.
\vspace{10pt}\par\noindent
\DescribeMacro{\acrlong}
\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\Acrlong}
\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\ACRlong}
\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
Print the long version with a hyperlink (if necessary) to the
relevant entry in the glossary. This is may be equivalent to
\ics{glsdesc},  \ics{glssymbol} or \ics{glsfirst} (or their uppercase 
variants), depending on package options.
\vspace{10pt}\par\noindent
\DescribeMacro{\acrfull}
\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\Acrfull}
\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\ACRfull}
\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
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 \ics{newacronym}, you
may additionally need to change the above commands as well as
the changing way the text is displayed using \ics{defglsdisplay}
and \ics{defglsdisplayfirst}.

\ifmakedtx{}{\toTop}

\subsection{Unsetting and resetting entry flags}

When using commands such as \ics{gls} it is possible that you may want
to use the value given by the \gloskey{first} key, even though you have
already used the glossary entry. Conversely, you may want to use the
value given by the \gloskey{text} key, even though you haven't used the
glossary entry.  The former can be achieved by one of the following
commands:\\[10pt]
\DescribeMacro{\glsreset}\cs{glsreset}\marg{label}\\
\DescribeMacro{\glslocalreset}\cs{glslocalreset}\marg{label}\\[10pt]
while the latter can be achieved by one of the following commands:\\[10pt]
\DescribeMacro{\glsunset}\cs{glsunset}\marg{label}\\
\DescribeMacro{\glslocalunset}\cs{glslocalunset}\marg{label}
\\[10pt]
You can determine whether an entry has been used using:\\[10pt]
\DescribeMacro{\ifglsused}
\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}\\[10pt]
where \meta{label} is the label of the required entry. If the
entry has been used, \meta{true part} will be done, otherwise
\meta{false part} will be done.
\ifmakedtx{}{\toTop}

\subsection{Glossary Styles}
\label{sec:styles}
The \sty{glossaries} package comes with some pre-defined
glossary styles. These are as follows:
\begin{description}
\item[list] The \glostyle{list} style uses the \envname{description}
environment. The entry name is placed in the optional argument
of the \cs{item} command (so it will appear in bold by
default). The description follows, and then the associated number
list for that entry.

\item[listgroup] The \glostyle{listgroup} style is like 
\glostyle{list} but the glossary groups have headings.

\item[listhypergroup] The \glostyle{listhypergroup} style is like 
\glostyle{listgroup} but has a set of links to the glossary 
groups.

\item[altlist] The \glostyle{altlist} style is like \glostyle{list}
but the description is placed on the following line.

\item[altlistgroup] The \glostyle{altlistgroup} style is like 
\glostyle{altlist} but the glossary groups have headings.

\item[altlisthypergroup] The \glostyle{altlisthypergroup} style is like 
\glostyle{altlistgroup} but has a set of links to the glossary 
groups.

\item[listdotted] This style uses the \envname{description}
environment.  Each entry starts with \verb|\item[]|, followed by the
name followed by a dotted line, followed by the description. Note that
this style ignores both the \term{number list} and the symbol. The
length \DescribeMacro{\glslistdottedwidth}\cs{glslistdottedwidth}
governs where the description should start.\footnote{This style was
supplied by Axel~Menzel.}

\item[long] The \glostyle{long} style uses the \envname{longtable}
environment (defined by the \isty{longtable} package). It has two
columns: the first column contains the entry's name and the second
column contains the description followed by the \term{number list}.

\item[longborder] The \glostyle{longborder} style is like
\glostyle{long} but has horizontal and vertical lines around it.

\item[longheader] The \glostyle{longheader} style is like
\glostyle{long} but has a header row.

\item[longheaderborder] The \glostyle{longheaderborder} style is
like \glostyle{longheader} but has horizontal and vertical lines
around it.

\item[long3col] The \glostyle{long3col} style is like
\glostyle{long} but has three columns. The first column contains
the entry's name, the second column contains the description
and the third column contains the \term{number list}.

\item[long3colborder] The \glostyle{long3colborder} style is like
the \glostyle{long3col} style but has horizontal and vertical
lines around it.

\item[long3colheader] The \glostyle{long3colheader} style is like
\glostyle{long3col} but has a header row.

\item[long3colheaderborder] The \glostyle{long3colheaderborder} style is
like \glostyle{long3colheader} but has horizontal and vertical lines
around it.

\item[long4col] The \glostyle{long4col} style is like 
\glostyle{long3col} but has an additional column in which the
entry's associated symbol appears.

\item[long4colborder] The \glostyle{long4colborder} style is like
the \glostyle{long4col} style but has horizontal and vertical
lines around it.

\item[long4colheader] The \glostyle{long4colheader} style is like
\glostyle{long4col} but has a header row.

\item[long4colheaderborder] The \glostyle{long4colheaderborder} style is
like \glostyle{long4colheader} but has horizontal and vertical lines
around it.

\item[super] The \glostyle{super} style uses the \envname{supertabular}
environment (defined by the \isty{supertabular} package). It has two
columns: the first column contains the entry's name and the second
column contains the description followed by the \term{number list}.

\item[superborder] The \glostyle{superborder} style is like
\glostyle{super} but has horizontal and vertical lines around it.

\item[superheader] The \glostyle{superheader} style is like
\glostyle{super} but has a header row.

\item[superheaderborder] The \glostyle{superheaderborder} style is
like \glostyle{superheader} but has horizontal and vertical lines
around it.

\item[super3col] The \glostyle{super3col} style is like
\glostyle{super} but has three columns. The first column contains
the entry's name, the second column contains the description
and the third column contains the \iterm{number list}.

\item[super3colborder] The \glostyle{super3colborder} style is like
the \glostyle{super3col} style but has horizontal and vertical
lines around it.

\item[super3colheader] The \glostyle{super3colheader} style is like
\glostyle{super3col} but has a header row.

\item[super3colheaderborder] The \glostyle{super3colheaderborder} style
is like \glostyle{super3colheader} but has horizontal and vertical
lines around it.

\item[super4col] The \glostyle{super4col} style is like 
\glostyle{super3col} but has an additional column in which the
entry's associated symbol appears.

\item[super4colborder] The \glostyle{super4colborder} style is like
the \glostyle{super4col} style but has horizontal and vertical
lines around it.

\item[super4colheader] The \glostyle{super4colheader} style is like
\glostyle{super4col} but has a header row.

\item[super4colheaderborder] The \glostyle{super4colheaderborder} style
is like \glostyle{super4colheader} but has horizontal and vertical
lines around it.

\end{description}

The glossary style can be set using the \pkgopt{style} package option
or using the \gloskey[printglossary]{style} key in the optional
argument to \ics{printglossary} or using the command:\\[10pt]
\DescribeMacro{\glossarystyle}\cs{glossarystyle}\marg{style-name}\\[10pt]

 \changes{1.03}{2007 July 4}{'glspostdescription added}
All the styles except for the three- and four-column styles and the
\glostyle{listdotted} style use the command
\DescribeMacro{\glspostdescription}\cs{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 \cs{glspostdescription} before the glossary is
displayed.\ifmakedtx{}{\toTop}

\subsection{Defining your own glossary style}

If the predefined styles don't fit your requirements, you can
define your own style using\DescribeMacro{\newglossarystyle}:\\[10pt]
\cs{newglossarystyle}\marg{name}\marg{definitions}\\[10pt]
where \meta{name} is the name of the new glossary style (to be
used in \cs{glossarystyle}). The second argument \meta{definitions},
needs to redefine all of the following:

\begin{description}
\item
\DescribeEnv{theglossary}
\envname{theglossary}\par\noindent
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 \cs{glossarypreamble}) or the
glossary postamble (defined by \cs{glossarypostamble}.) For example,
the \glostyle{list} style uses the \envname{description} environment,
so the \envname{theglossary} environment is simply redefined to begin
and end the \envname{description} environment.

\item
\DescribeMacro{\glossaryheader}
\cs{glossaryheader}\par\noindent
This macro indicates what to do at the start of the main body
of the glossary. Note that this is not the same as 
\cs{glossarypreamble}, which should not be affected by changes in
the glossary style. The \glostyle{list} glossary style redefines
\cs{glossaryheader} to do nothing, whereas the \glostyle{longheader}
glossary style redefines \cs{glossaryheader} to do a header row.

\item
\DescribeMacro{\glsgroupheading}
\cs{glsgroupheading}\marg{label}\par\noindent
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 \gloskey{sort} key (or \gloskey{name} key if the \gloskey{sort}
key is omitted). The sub-divisions are in the following order: symbols,
numbers, A, \ldots, Z. Note that the argument to \cs{glsgroupheading}
is a label \emph{not} the group title. The group title can be obtained
via \cs{glsgetgrouptitle}\marg{label}, and a navigation hypertarget can
be created using \cs{glsnavhypertarget}\marg{label}. Most of the
predefined glossary styles redefine \cs{glsgroupheading} to simply
ignore its argument.  The \glostyle{listhypergroup} style redefines
\cs{glsgroupheading} as follows:
\begin{verbatim}
\renewcommand*{\glsgroupheading}[1]{%
\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]}
\end{verbatim}
See also \cs{glsgroupskip} below. (Note that command definitions within 
\cs{newglossarystyle} must use \verb|##1| etc instead of \verb|#1| etc.)

\item
\DescribeMacro{\glsgroupskip}
\cs{glsgroupskip}\par\noindent
This macro determines what to do after one logical group but before
the header for the next logical group. The \glostyle{list} glossary
style simply redefines \cs{glsgroupskip} to be \cs{indexspace}.

\item
\DescribeMacro{\glossaryentryfield}
\cs{glossaryentryfield}\marg{label}\marg{formatted
name}\marg{description}\marg{symbol}
\marg{number list}\par\noindent
This macro indicates what to do for a given glossary entry.
Note that \meta{formatted name} will always be in the form
\cs{glsnamefont}\marg{name}. This allows the user to set a given
font for the entry name, regardless of the glossary style used.
Note that \meta{label} is the label used when the glossary entry
was defined via either \cs{newglossaryentry} or \cs{newacronym}. 
Each time you use a glossary entry it creates a 
link\footnote{if the document doesn't have hyperlinks enabled
\cs{@glslink} ignores the label and simply typesets the text.} 
using \cs{@glslink}\marg{label}\marg{text} with the label 
\texttt{glo:}\meta{label}. Your
new glossary style must therefore redefine \cs{glossaryentryfield}
so that it uses \cs{@glstarget}\verb|{|\texttt{glo:}\meta{label}\verb|}|\marg{text}
to ensure the hyperlinks function correctly.\footnote{again, if the
document doesn't support hyperlinks, \cs{@glstarget} will ignore
the label, and just typeset the text.} For example, the 
\glostyle{list} style defines \cs{glossaryentryfield} as follows:
\begin{verbatim}
\renewcommand*{\glossaryentryfield}[5]{%
\item[\@glstarget{glo:##1}{##2}] ##3\glspostdescription\space ##5}
\end{verbatim}

Note also that \meta{number list} will always be of the form\\[10pt]
\cs{glossaryentrynumbers}\{\cs{relax}\\
\cs{setentrycounter}\marg{counter name}\cs{glsnumberformat}\marg{number(s)}\}\\[10pt]
where \meta{number(s)}
may contain \cs{delimN} (to delimit individual numbers) and/or
\cs{delimR} (to indicate a range of numbers). There may be 
multiple occurrences of 
\cs{setentrycounter}\marg{counter name}\cs{glsnumberformat}\marg{number(s)}, but note
that the entire number list is enclosed within the argument
to \ics{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
\cs{glossaryentrynumbers} is to provide a means of suppressing the
number list altogether. (In fact, the \pkgopt{nonumberlist} option 
redefines \cs{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 
\pkgopt{nonumberlist} package option.
\end{description}\ifmakedtx{}{\toTop}

\subsubsection{Example: creating a completely new style}

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 \texttt{.sty}
file or must be placed within \cs{makeatletter} and \cs{makeatother}.

For example, suppose you want each entry to start with a bullet point.
This means that the glossary should be placed in the \envname{itemize}
environment, so \envname{theglossary} should start and end that
environment. Let's also suppose that you don't want anything between
the glossary groups (so \cs{glsgroupheading} and \cs{glsgroupskip}
should do nothing) and suppose you don't want anything to appear
immediately after \verb|\begin{theglossary}| (so \cs{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 \term{number list} should appear within square brackets
at the end. Then you can create this new glossary style, called, say,
\texttt{mylist}, as follows:
\begin{verbatim}
 \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
 }%
 }
\end{verbatim}
\ifmakedtx{}{\toTop}

\subsubsection{Example: creating a new glossary style based on an
existing style}

\changes{1.11}{2008 March 1}{Fixed error in manual (glossary style
is set using 'glossarystyle not 'setglossarystyle)}%
If you want to define a new style that is a slightly modified
version of an existing style, you can use \cs{glossarystyle}
within the second argument of \cs{newglossarystyle} followed by
whatever alterations you require. For example, suppose you want 
a style like the \glostyle{list} style but you don't want the extra
vertical space created by \cs{indexspace} between groups, then you
can create a new glossary style called, say, \texttt{mylist} as
follows:
\begin{verbatim}
\newglossarystyle{mylist}{%
\glossarystyle{list}% base this style on the list style
\renewcommand{\glsgroupskip}{}% make nothing happen between groups
}
\end{verbatim} 
\ifmakedtx{}{\toTop}

\section{Mfirstuc Package}
\label{sec:mfirstuc}

The \sty{glossaries} package is supplied with the package 
\isty{mfirstuc} which provides the command:\\[10pt]
\DescribeMacro{\makefirstuc}
\cs{makefirstuc}\marg{stuff}\\[10pt]
which makes the first object of
\meta{stuff} uppercase unless \meta{stuff} starts with a control
sequence followed by a group, in which case the first
object in the group is converted to uppercase. Examples:
\begin{itemize}
\item \verb|\makefirstuc{abc}| produces Abc

\item \verb|\makefirstuc{\emph{abc}}| produces \emph{Abc} 
(\ics{MakeUppercase} has been applied to the letter \dq{a} rather
than \cs{emph}.)

\item \verb|\makefirstuc{{\'a}bc}| produces {\'A}bc

\item \verb|\makefirstuc{\ae bc}| produces \AE bc

\item \verb|\makefirstuc{{\ae}bc}| produces {\AE}bc
\end{itemize}

Note however that \verb|\makefirstuc{\ae{}bc}| produces \ae Bc since
the empty group following \cs{ae} is considered to be the argument
of \cs{ae} which is in fact not the case.
\ifmakedtx{}{\toTop}

 \StopEventually{\clearpage\phantomsection\addcontentsline{toc}{section}{Index}\PrintIndex}

\ifmakedtx{}{\printindex\toTop}

\end{document}