path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex

\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{5329}
\CodelineNumbered
\newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}}
\newcommand*{\term}[1]{#1\iterm{#1}}
\newcommand*{\iterm}[1]{\index{#1|main}}
\newcommand{\dq}[1]{``#1''}
\newcommand*{\tableref}[1]{\hyperref[#1]{table~\ref*{#1}}}
\newcommand*{\Tableref}[1]{\hyperref[#1]{Table~\ref*{#1}}}
\newlength\boxlength
\newsavebox\importantbox
\newenvironment{important}{%
\setlength{\fboxrule}{4pt}%
\setlength\boxlength{\linewidth}%
\addtolength\boxlength{-2\fboxsep}%
\addtolength\boxlength{-2\fboxrule}%
\begin{lrbox}{\importantbox}%
\begin{minipage}{\boxlength}%
}{\end{minipage}\end{lrbox}%
\par\vskip10pt\noindent
\fcolorbox{red}{white}{\usebox{\importantbox}}\par\vskip10pt}
}
{
\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"}
\newcommand*{\tableref}[1]{\htmlref{table~}{#1}\ref{#1}}
\newcommand*{\Tableref}[1]{\htmlref{Table~}{#1}\ref{#1}}
\newenvironment{important}{}{}
}


\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.16: \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{27th August 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.

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 \autoref{sec:code:mfirstuc} contains the documented
code for the \sty{mfirstuc} package}{}.
\ifmakedtx{}{\toTop}

\subsection{Multi-Lingual Support}
\label{sec:languages}

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 
\texttt{comp.text.tex}.
However you must load \isty{babel} \emph{before} 
\sty{glossaries} to enable this. Note that if \isty{babel} is loaded 
and the \isty{translator} package is detected on \TeX's path, then the
\isty{translator} package will be loaded automatically, however,
it may not pick up on the required languages, so if the predefined
text is not translated, you may need to explicitly load the
\isty{translator} package with the required languages. For example:
\begin{verbatim}
\usepackage[spanish]{babel}
\usepackage[spanish]{translator}
\usepackage{glossaries}
\end{verbatim}

If you want to use \isty{ngerman} or \isty{german} instead
of \isty{babel}, you will need to include the \isty{translator} package 
to provide the translations. For example:
\begin{verbatim}
\documentclass[ngerman]{article}
\usepackage{ngerman}
\usepackage{translator}
\usepackage{glossaries}
\end{verbatim}

The following languages are currently supported:
\begin{center}
\begin{tabular}{lc}
\bfseries Language & \bfseries 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
\end{tabular}
\end{center}
The language dependent commands and \isty{translator} keys used by the 
glossaries package are listed in \tableref{tab:predefinednames}.

\begin{table}[htbp]
\caption{Customised Text}
\label{tab:predefinednames}
\begin{center}
\begin{tabular}{@{}llp{0.4\linewidth}@{}}
\bfseries Command Name & \bfseries Translator key word &
\bfseries What it's for\\
\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\\
\ics{acronymname} & \texttt{Acronyms} & Title of the list of acronyms
(when used with package option \pkgopt{acronym}).\\
\ics{entryname} & \texttt{Notation (glossaries)} & 
Header for first column in glossary (for 2, 3 or 4 column glossaries 
that support headers).\\
\ics{descriptionname} & \texttt{Description (glossaries)} &
Header for second column in glossary (for 2, 3 or 4 column glossaries
that support headers).\\
\ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol
column in glossary for glossary styles that support this option.\\
\ics{pagelistname} & \texttt{Page List (glossaries)} & 
Header for page list column in glossary for glossaries that support 
this option.\\
\ics{glssymbolsgroupname} & \texttt{Symbols (glossaries)} & 
Header for symbols section of the glossary for glossary styles that 
support this option.\\
\ics{glsnumbersgroupname} & \texttt{Numbers (glossaries)} & Header for
numbers section of the glossary for glossary styles that support
this option.
\end{tabular}
\end{center}
\end{table}

Due to the varied nature of glossaries, it's likely that the
predefined translations may not be appropriate. If you are using
the \isty{babel} package and do not have the \isty{translator} package
installed, you need to be familiar with the 
\ifmakedtx{ advice given in 
\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}{advice on \htmladdnormallink{changing the words babel uses}{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}. 

If you have the \isty{translator} package installed, then it becomes
much easier to change the default translations. For example, if you
are writing in Irish and you want \cs{symbolname} to produce
\dq{Siombail} instead of \dq{Comhartha}, then you can put the following
in your document preamble:
\begin{verbatim}
\deftranslation[to=Irish]{Symbol (glossaries)}{Siombail}
\end{verbatim}

\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, but you must have Perl installed to
be able to use it.

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 \sty{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/}.

Below is a list of the most frequently asked questions. For
other queries, consult the \sty{glossaries} FAQ at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}. 

\begin{enumerate}
\item I've used the \pkgopt{smallcaps} option, but the acronyms
are displayed in normal sized upper case letters.

The \pkgopt{smallcaps} package option uses \cs{textsc} to typeset
the acronyms. This command converts lower case letters to small 
capitals, while upper case letters remain their usual size. Therefore
you need to specify the acronym in lower case letters.

\item How do I change the font that the acronyms are displayed in?

The easiest way to do this is to specify the \pkgopt{smaller} package
option and redefine \cs{acronymfont} to use the required typesetting
command.  For example, suppose you would like the acronyms displayed in 
a sans-serif font, then you can do:
\begin{verbatim}
\usepackage[smaller]{glossaries}
\renewcommand*{\acronymfont}[1]{\textsf{#1}}
\end{verbatim}

\item How do I change the font that the acronyms are displayed in
on first use?

The easiest way to do this is to specify the \pkgopt{smaller} package
option and redefine \cs{firstacronymfont} to use the required 
command. Note that if you don't want the acronym on subsequent use
to use \cs{smaller}, you will also need to redefine \cs{acronymfont},
as above. For example to make the acronym emphasized on first use,
but use the surrounding font for subsequent use, you can do:
\begin{verbatim}
\usepackage[smaller]{glossaries}
\renewcommand*{\firstacronymfont}[1]{\emph{#1}}
\renewcommand*{\acronymfont}[1]{#1}
\end{verbatim}

\item I don't have Perl installed, do I have to use 
\appname{makeglossaries}?

Read \ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{the previous
section}{sec:makeglossaries}}.


\item I'm used to using the \sty{glossary} package: are there any
instructions on migrating from the \isty{glossary} package to the
\sty{glossaries} package?

Read \ifmakedtx{the file \texttt{glossary2glossaries.pdf}}{\htmladdnormallink{Upgrading 
from the glossary package to the glossaries 
package}{glossary2glossaries.html}} which should be available from the 
same location as this document.

\item I'm using \isty{babel} but the fixed names haven't been 
translated.

The \sty{glossaries} package currently only supports the following
languages: Danish, Dutch, English, French, German, Irish, Italian,
Hungarian, Polish and Spanish. If you want to add another language,
send me the translations, and I'll add them to the next version.

If you are using one of the above languages, but the text hasn't been
translated, try adding the \isty{translator} package with the
required languages explicitly (before you load the \sty{glossaries}
package). For example:
\begin{verbatim}
\usepackage[ngerman]{babel}
\usepackage[ngerman]{translator}
\usepackage{glossaries}
\end{verbatim}
Alternatively, you may be able to add the language as a global option
to the class file. Check the \sty{translator} package documentation for
further details.

\item My glossaries haven't appeared.

Remember to do the following:
\begin{itemize}
\item Add \ics{makeglossaries} to the document preamble.

\item Use either \ics{printglossary} for each glossary that has
been defined or \ics{printglossaries}.

\item Use \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl}, \ics{Glspl},
\ics{GLSpl}, \ics{glslink}, \ics{glsadd} or \ics{glsaddall} in the
document.

\item Run \LaTeX\ on your document, then run \appname{makeglossaries},
then run \LaTeX\ on your document again. If you want the glossaries
to appear in the table of contents, you will need an extra \LaTeX\
run.
\end{itemize}
\end{enumerate}
\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. However it is recommended that you read 
\ifmakedtx{\autoref{sec:overview}}{\htmlref{the overview section}{sec:overview}} 
for additional commands and advice not listed here.

\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 take 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{tex}{name={\TeX},
description={A typesetting language},
sort=tex}
\end{verbatim}
This will put the entry in the \dq{T} group (entries starting with
the letter \dq{t} or \dq{T}) rather than the
\dq{symbols} group (entries starting with a symbol).
Similarly, the following example puts the entry in the \dq{U}
group instead of the \dq{symbol} group.
\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{altlong4col}, \glostyle{altlong4colheader},
\glostyle{altlong4colborder}, \glostyle{altlong4colheaderborder},
\glostyle{super4col}, \glostyle{super4colheader}, 
\glostyle{super4colborder}, \glostyle{super4colheaderborder}.
\glostyle{altsuper4col}, \glostyle{altsuper4colheader}, 
\glostyle{altsuper4colborder} and \glostyle{altsuper4colheaderborder}.
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}
\label{sec:pkgopts}

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}

As from version 1.14, you can add a prefix to the label by
redefining \DescribeMacro{\glsautoprefix}\cs{glsautoprefix}.
For example:
\begin{verbatim}
\renewcommand*{\glsautoprefix}{glo:}
\end{verbatim}
will add \texttt{glo:} to the automatically generated label, so
you can then, for example, refer to the list of acronyms as follows:
\begin{verbatim}
The list of acronyms is in section~\ref{glo:\acronymtype}.
\end{verbatim}
Or, if you are undecided on a prefix:
\begin{verbatim}
The list of acronyms is in section~\ref{\glsautoprefix\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}

\begin{important}%
\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. 
\end{important}

\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{smaller}] 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.

\item[\pkgopt{shortcuts}] This option provides shortcut commands
for acronyms.
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 must be defined before they are used, so it
is better to define them in the preamble to ensure this.\footnote{The
only preamble restriction on \cs{newglossaryentry} and \cs{newacronym}
was removed in version 1.13, but the restriction remains for
\cs{loadglsentries}.} However
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 
\ics{glspluralsuffix} 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
from the \gloskey{plural} key, if the \gloskey{first} key is omitted,
or by appending \ics{glspluralsuffix} to the value of the
\gloskey{first} field, if the \gloskey{first} field is present.

\textbf{Note:} prior to version 1.13, the default value of 
\gloskey{firstplural} was always taken by appending \dq{s} to the
\gloskey{first} key, which meant that you had to specify both
\gloskey{plural} and \gloskey{firstplural}, even if you hadn't
used the \gloskey{first} key.

\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.
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 commands like \cs{Gls} and \cs{Glspl}. For example:
\begin{verbatim}
\newglossaryentry{elite}{name={{\'e}lite},
description={select group or class}}
\end{verbatim}
\ifmakedtx{}{\toTop}


\subsubsection{Plurals}
You may have noticed from above that you can specify the plural form
when you define a term. If you omit this, the plural will be obtained 
\DescribeMacro{\glspluralsuffix}by appending \cs{glspluralsuffix} to 
the singular form. This command defaults to \texttt{s}. For example:
\begin{verbatim}
\newglossaryentry{cow}{name=cow,description={a fully grown
female of any bovine animal}}
\end{verbatim}
defines a new entry whose singular form is \dq{cow} and plural form 
is \dq{cows}. However, if you are writing in archaic English, you 
may want to use \dq{kine} as the plural form, in which case you would 
have to do:
\begin{verbatim}
\newglossaryentry{cow}{name=cow,plural=kine,
description={a fully grown female of any bovine animal}}
\end{verbatim}

If you are writing in a language that supports
multiple plurals (for a given term) then use the \gloskey{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
\cs{glslink} rather than using \cs{glspl}. Returning to the cow 
example above, suppose you will mostly be using \dq{cows} as the
plural, but occasionally you want to use \dq{kine} as the plural,
then define the term as
\begin{verbatim}
\newglossaryentry{cow}{name=cow,description={a fully grown
female of any bovine animal (plural cows, archaic plural kine)}}
\end{verbatim}
and use \verb|\glspl{cow}| to produce \dq{cows} and use
\verb|\glslink{cow}{kine}| to produce \dq{kine}.

If you are using a language that usually forms plurals
by appending a different letter, or sequence of letters, you can
redefine \cs{glspluralsuffix} as required. However, this must be
done \emph{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 \gloskey{plural} key (and the \gloskey{firstplural}
key where necessary). 

\ifmakedtx{}{\toTop}

\subsubsection{Loading Entries From a File}
\label{sec:loadglsentries}

\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 (or, more specifically, for those entries whose
type has been specified by \cs{glsdefaulttype}, which is what
\cs{newglossaryentry} uses by default). For example, suppose I have
a file called \texttt{myentries.tex} which contains:
\begin{verbatim}
\newglossaryentry{perl}{type=main,
name={Perl},
description={A scripting language}}

\newglossaryentry{tex}{name={\TeX},
description={A typesetting language},sort={TeX}}

\newglossaryentry{html}{type=\glsdefaulttype,
name={html},
description={A mark up language}}
\end{verbatim}
and suppose in my document preamble I use the command:
\begin{verbatim}
\loadglsentries[languages]{myentries}
\end{verbatim}
then this will add the entries \texttt{tex} and \texttt{html}
to the glossary whose type is given by \texttt{languages}, but
the entry \texttt{perl} will be added to the main glossary, since
it explicitly sets the type to \texttt{main}.

\textbf{Note:} if you
use \cs{newacronym} (see \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}}) 
the type is set as \verb|type=\acronymtype| 
unless you explicitly override it. For example, if my file
\texttt{myacronyms.tex} contains:
\begin{verbatim}
\newacronym{aca}{aca}{a contrived acronym}
\end{verbatim}
then (supposing I have defined a new glossary type called
\texttt{altacronym})
\begin{verbatim}
\loadglsentries[altacronym]{myacronyms}
\end{verbatim}
will add \texttt{aca} to the glossary type \texttt{acronym}, if the
package option \pkgopt{acronym} has been specified, or will add
\texttt{aca} to the glossary type \texttt{altacronym}, if the
package option \pkgopt{acronym} is not specified. In this instance,
it is better to change \texttt{myacronyms.tex} to:
\begin{verbatim}
\newacronym[type=\glsdefaulttype]{aca}{aca}{a contrived acronym}
\end{verbatim}
and now
\begin{verbatim}
\loadglsentries[altacronym]{myacronyms}
\end{verbatim}
will add \texttt{aca} to the glossary type \texttt{altacronym},
regardless of whether or not the package option \pkgopt{acronym} is
used.

Note that only those entries that have been used
in the text will appear in the relevant glossaries.
Note also that \cs{loadglsentries} may only be used in the 
preamble.\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 commands
in this section also add a line to an external file that is used
by \appname{makeindex} to generate the relevant entry in the
glossary. It is strongly recommended that you don't use the commands
defined in this section in the arguments of sectioning or caption
commands. This is particularly important if you are using the
\sty{glossaries} package in conjunction with the \isty{hyperref} package.
Instead, use one of the commands listed in 
\ifmakedtx{\autoref{sec:glsnolink}}{\htmlref{Using Glossary Terms
Without Links}{sec:glsnolink}} (such as \cs{glsentrytext}) or provide an alternative via
the optional argument to the sectioning/caption command.
Examples:
\begin{verbatim}
\section{An overview of \glsentrytext{perl}}
\section[An overview of Perl]{An overview of \gls{perl}}
\end{verbatim}

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 \cs{glstextformat}\marg{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}. If the entry has been marked as having
been used, the value of the \gloskey{text} key will be used, otherwise
the value of the \gloskey{first} key will be used. 
On completion, \cs{gls} will mark the entry given by \meta{label} as
used.

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, but this
can be changed (see 
\ifmakedtx{\autoref{sec:glsdisplay}}{\htmlref{later}{sec:glsdisplay}}). 


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. Unlike \cs{gls}, the inserted text \meta{insert} 
is always appended to the link text.

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{glstext} except that it always uses the value
of the \gloskey{first} key. Again, \meta{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:\\[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{glstext} except that it always uses the value
of the \gloskey{plural} key. Again, \meta{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:\\[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{glstext} except that it always uses the value
of the \gloskey{firstplural} key. Again, \meta{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:\\[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{glstext} except that it always uses the value of the
\gloskey{name} key. Again, \meta{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
\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{glstext} except that it always uses the value of the
\gloskey{symbol} key. Again, \meta{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
\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{glstext} except that it always uses the value
of the \gloskey{description} key. Again, \meta{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 \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. Note that \ics{glslink} (which
is used by commands like \cs{gls} and \cs{glspl}) sets 
\DescribeMacro{\glslabel}\ics{glslabel} to the label for the given
entry (i.e.\ the label supplied to the mandatory argument to
\cs{gls}), so it is possible to use this label in the definition of
\cs{glsdisplay} or \cs{glsdisplayfirst} to supply additional
information using any of the commands described in 
\ifmakedtx{\autoref{sec:glsnolink}}{\htmlref{Using Glossary Terms
Without Links}{sec:glsnolink}}, if required. 

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's label\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).\ifmakedtx{}{\toTop}

\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}).
For example, to add a page range to the glossary number list for the
entry whose label is given by \texttt{set}:
\begin{verbatim}
\glsadd[format=(]{set}
Lots of text about sets spanning many pages.
\glsadd[format=)]{set}
\end{verbatim}

\DescribeMacro{\glsaddall}
To add all entries that have been defined, use:\\[10pt]
\cs{glsaddall}\oarg{options}\\[10pt]
The optional argument is the same as for \cs{glsadd}, except
there is also a key \gloskey[glsaddall]{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 \cs{acronymtype}) and a list of
notation (specified by the glossary type \texttt{notation}) then you can
do:
\begin{verbatim}
\glsaddall[types={\acronymtype,notation}]
\end{verbatim}
\ifmakedtx{}{\toTop}

\subsection{Using Glossary Terms Without Links}
\label{sec:glsnolink}

The commands described in this section display entry details without
adding any information to the glossary. They don't use 
\cs{glstextformat}, they don't have any optional arguments,
they don't affect the flag that determines if the term has been
used and they don't produce hyperlinks.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryname}\cs{glsentryname}\marg{label}\\
\DescribeMacro{\Glsentryname}\cs{Glsentryname}\marg{label}\par\vskip10pt\noindent
These commands display the name of the glossary entry given by
\meta{label}, as specified by the \gloskey{name} key. 
\cs{Glsentryname} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentrytext}\cs{glsentrytext}\marg{label}\\
\DescribeMacro{\Glsentrytext}\cs{Glsentrytext}\marg{label}\par\vskip10pt\noindent
These commands display the subsequent use text for the glossary entry 
given by \meta{label}, as specified by the \gloskey{text} key. 
\cs{Glsentrytext} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryplural}\cs{glsentryplural}\marg{label}\\
\DescribeMacro{\Glsentryplural}\cs{Glsentryplural}\marg{label}\par\vskip10pt\noindent
These commands display the subsequent use plural text for the glossary 
entry given by \meta{label}, as specified by the \gloskey{plural} key. 
\cs{Glsentryplural} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryfirst}\cs{glsentryfirst}\marg{label}\\
\DescribeMacro{\Glsentryfirst}\cs{Glsentryfirst}\marg{label}\par\vskip10pt\noindent
These commands display the first use text for the glossary entry 
given by \meta{label}, as specified by the \gloskey{first} key. 
\cs{Glsentryfirst} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryfirstplural}\cs{glsentryfirstplural}\marg{label}\\
\DescribeMacro{\Glsentryfirstplural}\cs{Glsentryfirstplural}\marg{label}\par\vskip10pt\noindent
These commands display the plural form of the first use text for the 
glossary entry given by \meta{label}, as specified by the 
\gloskey{firstplural} key.  \cs{Glsentryfirstplural} makes the first 
letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentrydesc}\cs{glsentrydesc}\marg{label}\\
\DescribeMacro{\Glsentrydesc}\cs{Glsentrydesc}\marg{label}\par\vskip10pt\noindent
These commands display the description for the glossary entry given by
\meta{label}. \cs{Glsentrydesc} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentrydescplural}\cs{glsentrydescplural}\marg{label}\\
\DescribeMacro{\Glsentrydescplural}\cs{Glsentrydescplural}\marg{label}\par\vskip10pt\noindent
These commands display the plural description for the glossary entry 
given by \meta{label}. \cs{Glsentrydescplural} makes the first letter 
uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentrysymbol}\cs{glsentrysymbol}\marg{label}\\
\DescribeMacro{\Glsentrysymbol}\cs{Glsentrysymbol}\marg{label}\par\vskip10pt\noindent
These commands display the symbol for the glossary entry given by
\meta{label}. \cs{Glsentrysymbol} makes the first letter uppercase.
\par\vskip10pt\noindent
\DescribeMacro{\glsentrysymbolplural}\cs{glsentrysymbolplural}\marg{label}\\
\DescribeMacro{\Glsentrysymbolplural}\cs{Glsentrysymbolplural}\marg{label}\par\vskip10pt\noindent
These commands display the plural symbol for the glossary entry given by
\meta{label}. \cs{Glsentrysymbolplural} makes the first letter uppercase.

For further information see \ifmakedtx{\autoref{sec:code:glsnolink}}{the
section \dq{Displaying entry details without adding information to
the glossary} in the document \texttt{glossaries.pdf}}.
\ifmakedtx{}{\toTop}

\subsection{Displaying a glossary}

\DescribeMacro{\printglossaries}
The command \cs{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 \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 can be 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} package option or \ics{glossarystyle}.

\item[{\gloskey[printglossary]{numberedsection}}] This specifies
whether to use a numbered section for this glossary, overriding
the effect of the \pkgopt{numberedsection} package option. This
key has the same syntax as the \pkgopt{numberedsection} package
option, described \ifmakedtx{in \autoref{sec:pkgopts}}{\htmlref{earlier}{sec:pkgopts}}.

\item[{\gloskey[printglossary]{nonumberlist}}] Unlike the package option
of the same name, this key is a boolean key. If true (\verb|nonumberlist=true|) the numberlist
is suppressed for this glossary. If false (\verb|nonumberlist=false|) the numberlist is
displayed for this glossary. If no value is supplied, true is 
assumed.

\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 the 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. For convenience, the \sty{glossaries} package
defines the command:\\[10pt]
\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt]
By default, 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}}\cs{glspluralsuffix}\},\\
firstplural=\{\textrm{\meta{long}}\cs{glspluralsuffix}\cs{space}
(\textrm{\meta{abbrv}}\cs{glspluralsuffix})\},\\
\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.

\begin{important}%
\textbf{Note:} since \cs{newacronym} sets \verb|type=\acronymtype|,
if you want to load a file containing acronym definitions using
\cs{loadglsentries}\oarg{type}\marg{filename}, the optional argument 
\meta{type} will not have an effect unless you explicitly set the
type as \verb|type=\glsdefaulttype|. See \ifmakedtx{\autoref{sec:loadglsentries}}{\htmlref{earlier}{sec:loadglsentries} for details}.
\end{important}

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.

This section describes acronyms that have been defined using
\cs{newacronym}. If you prefer to define all your acronyms using
\cs{newglossaryentry} explicitly, then you should skip this section
and ignore the package options: \pkgopt{smallcaps}, \pkgopt{smaller},
\pkgopt{description}, \pkgopt{dua}, \pkgopt{footnote} and
\pkgopt{shortcuts}, as these options change the
definition of \ics{newacronym} for common acronym formats
as well as the way that the link text is displayed (see
\ifmakedtx{\autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}). 
Likewise you should ignore the new commands described in this section,
such as \cs{acrshort}, as they vary according to the definition of
\cs{newacronym}.


\Tableref{tab:acronymsettings} lists the package options and how the
\ics{newglossaryentry} keys are used to store \meta{long} (the long
form) and \meta{abbrv} (the short form). Note that the
\pkgopt{smallcaps} option redefines
\DescribeMacro{\acronymfont}\cs{acronymfont} so that it sets its
argument using \cs{textsc} (so you should use lower case characters in
\meta{abbrv}) and the \pkgopt{smaller} option redefines
\cs{acronymfont} to use \cs{smaller},\footnote{you will need to load a
package, such as \sty{relsize}, that defines \cs{smaller} if you use
this option.} otherwise \cs{acronymfont} simply displays its argument
in the surrounding font. Note also that if none of the package options
\pkgopt{smallcaps}, \pkgopt{smaller}, \pkgopt{dua},
\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.

If you want to display the acronym in another font, for example,
emphasized, then use the \pkgopt{smaller} package option and
redefine \ics{acronymfont} to use the required font. For example:
\begin{verbatim}
\usepackage[smaller]{glossaries}
\renewcommand*{\acronymfont}[1]{\emph{#1}}
\end{verbatim}
Where \cs{acronymfont} is available, 
\DescribeMacro{\firstacronymfont}\cs{firstacronymfont} is also
available. By default, this simply uses \cs{acronymfont}, but it
can be redefined to change the way the acronym is displayed on
first use.

\begin{table}[htbp]
\caption{Package options governing \cs{newacronym} and how the 
information is stored in the keys for \cs{newglossaryentry}}
\label{tab:acronymsettings}
\begin{center}
\begin{tabular}{lllll}
\bfseries Package Option &
\gloskey{first} key &
\gloskey{text} key &
\gloskey{description} key &
\gloskey{symbol} key\\
\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{smaller} &
\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{smaller}, 
\pkgopt{footnote}, \pkgopt{dua}
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. This means that these
package options only work for the glossary type given by
\cs{acronymtype}. If you have multiple lists of acronyms, you
will need to make the appropriate changes for each additional
glossary type.

\begin{description}
\item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} 
When these two package options are used together, the first use displays
the entry as:\\[10pt]
\cs{firstacronymfont}\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[\pkgopt{dua}]\ifmakedtx{\mbox{}\par}{} 
The \pkgopt{dua} package option always displays the expanded
form and so may not be used with \pkgopt{footnote}, \pkgopt{smaller} 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} package 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 package option displays the entry on first use as:\\[10pt]
\meta{long}\meta{insert} (\cs{firstacronymfont}\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 package option displays the entry on first use as:\\[10pt]
\cs{firstacronymfont}\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{firstacronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
where \cs{acronymfont} is set to \verb|\textsc{#1}|, so \meta{abbrv}
should be specified in lower case.

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{smaller}]\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{firstacronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
where \cs{acronymfont} is set to \verb|{\smaller #1}|.

Remember to load a package that defines \ics{smaller} (such as
\isty{relsize}) if you want to use this option.

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{smaller},
\pkgopt{footnote}, \pkgopt{dua} 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]
\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}.

The package option \pkgopt{shortcuts} provides the synonyms listed
in \tableref{tab:shortcuts}. If any of those commands generate
an \dq{undefined control sequence} error message, check that you
have enabled the shortcuts using the \pkgopt{shortcuts} package 
option. Note that there are no shortcuts for the commands that
produce all upper case text.

\begin{table}[htbp]
\caption{Synonyms provided by the package option \pkgopt{shortcuts}}
\label{tab:shortcuts}
\begin{center}
\begin{tabular}{ll}
\bfseries Shortcut Command & \bfseries Equivalent Command\\
\ics{acs} & \ics{acrshort}\\
\ics{Acs} & \ics{Acrshort}\\
\ics{acsp} & \ics{acrshortpl}\\
\ics{Acsp} & \ics{Acrshortpl}\\
\ics{acl} & \ics{acrlong}\\
\ics{Acl} & \ics{Acrlong}\\
\ics{aclp} & \ics{acrlongpl}\\
\ics{Aclp} & \ics{Acrlongpl}\\
\ics{acf} & \ics{acrfull}\\
\ics{Acf} & \ics{Acrfull}\\
\ics{acfp} & \ics{acrfullpl}\\
\ics{Acfp} & \ics{Acrfullpl}\\
\ics{ac} & \ics{gls}\\
\ics{Ac} & \ics{Gls}\\
\ics{acp} & \ics{glspl}\\
\ics{Acp} & \ics{Glspl}
\end{tabular}
\end{center}
\end{table}

\ifmakedtx{}{\toTop}

\subsection{Unsetting and Resetting Entry Flags}

When using \ics{gls}, \ics{glspl} and their uppercase variants 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. Sub groups are separated using \cs{indexspace}.

\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. The start of the glossary has a navigation panel to
each group that is present in the glossary. This requires an
additional run through \LaTeX\ to ensure the group information
is up-to-date.  In the navigation panel, each group is separated
by \DescribeMacro{\glshypernavsep}\cs{glshypernavsep} which 
defaults to a vertical bar with a space on either side. For example,
to simply have a space separating each group, do:
\begin{verbatim}
\renewcommand*{\glshypernavsep}{\space}
\end{verbatim}

Note that the hyper-navigation panel is now (as from version 1.14) 
set inside the optional argument to \cs{item} instead of after it
to prevent a spurious space at the start. This can be changed
by redefining \ics{glossaryheader}, but note that this needs to
be done \emph{after} the glossary style has been set.

\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. The navigation panel is the same as that for 
\glostyle{listhypergroup}, described above.

\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}.
Sub groups are separated with a blank row. The width of the
first column is governed by the widest entry in that column. The
width of the second column is governed by the length
\ics{glsdescwidth}.

\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}. The width of the
first column is governed by the widest entry in that column. The
width of the second column is governed by the length
\ics{glsdescwidth}. The width of the third column is governed by the
length \ics{glspagelistwidth}.

\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. This style is used for brief
single line descriptions. The column widths are governed by the
widest entry in the given column. Use \glostyle{altlong4col} for long
descriptions.

\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[altlong4col] The \glostyle{altlong4col} style is like 
\glostyle{long4col} but allows multi-line descriptions and page lists.
The width of the description column is governed by the length
\ics{glsdescwidth} and the width of the page list column is
governed by the length \ics{glspagelistwidth}. The width of the name 
and symbol columns is governed by the widest entry in the 
given column.

\item[altlong4colborder] The \glostyle{altlong4colborder} style is like
the \glostyle{long4colborder} but allows multi-line descriptions and
page lists.

\item[altlong4colheader] The \glostyle{altlong4colheader} style is like
\glostyle{long4colheader} but allows multi-line descriptions and
page lists.

\item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder} 
style is like \glostyle{long4colheaderborder} but allows multi-line
descriptions and page lists.

\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}.
Sub groups are separated with a blank row. The width of the
first column is governed by the widest entry in that column. The
width of the second column is governed by the length
\ics{glsdescwidth}.

\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}. The width of the
first column is governed by the widest entry in that column. The
width of the second column is governed by the length
\ics{glsdescwidth}. The width of the third column is governed by the
length \ics{glspagelistwidth}.

\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. This style is designed for
entries with brief single line descriptions. The column widths are governed by the
widest entry in the given column. Use \glostyle{altsuper4col}
for longer descriptions.

\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.

\item[altsuper4col] The \glostyle{altsuper4col} style is like 
\glostyle{super4col} but allows multi-line descriptions and page
lists.
The width of the description column is governed by the length
\ics{glsdescwidth} and the width of the page list column is
governed by the length \ics{glspagelistwidth}. The width of the name 
and symbol columns is governed by the widest entry in the 
given column.

\item[altsuper4colborder] The \glostyle{altsuper4colborder} style is like
the \glostyle{super4colborder} style but allows multi-line descriptions
and page lists.

\item[altsuper4colheader] The \glostyle{altsuper4colheader} style is like
\glostyle{super4colheader} but allows multi-line descriptions and
page lists.

\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder}
style is like \glostyle{super4colheaderborder} but allows multi-line
descriptions and page lists.

\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]
The tabular-like styles that allow multi-line descriptions and page
lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} to
set the width of the description column and the length 
\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the
width of the page list column. These will need to be changed using
\cs{setlength} if the glossary is too wide. Note that the 
\glostyle{long4col} and \glostyle{super4col} styles (and their header and border
variations) don't use these lengths as they are designed for single
line entries. Instead you should use the analogous 
\glostyle{altlong4col} and \glostyle{altsuper4col} styles.

Note that if you use the \gloskey[printglossary]{style} key in the
optional argument to \ics{printglossary}, it will override any 
previous style settings for the given glossary, so if, for example,
you do:
\begin{verbatim}
\renewcommand*{\glsgroupskip}{}
\printglossary[style=long]
\end{verbatim}
The new definition of \ics{glsgroupskip} will not have an affect
for this glossary, as \cs{glsgroupskip} is redefined by 
\verb|style=long|. Likewise, \ics{glossarystyle} will also
override any previous style definitions, so, again:
\begin{verbatim}
\renewcommand*{\glsgroupskip}{}
\glossarystyle{long}
\end{verbatim}
will reset \cs{glsgroupskip} back to its default definition for the
named glossary style (\glostyle{long} in this case). If you want to 
modify the styles, either use \ics{newglossarystyle} (described
in the next section) or make the modifications after 
\ics{glossarystyle}.

 \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 non-empty 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}

\begin{important}
In version 1.02 of \sty{mfirstuc}, a bug fix resulted in a change
in output if the first object is a control sequence followed by
an empty group. Prior to version 1.02, \verb|\makefirstuc{\ae{}bc}|
produced \ae Bc. However as from version 1.02, it now produces
\AE bc.
\end{important}

Note also that
\begin{verbatim}
\newcommand{\abc}{abc}
\makefirstuc{\abc}
\end{verbatim}
produces: ABC. This is because the first object in the argument of
\cs{makefirstuc} is \cs{abc}, so it does \verb|\MakeUppercase{\abc}|.
Whereas:
\begin{verbatim}
\newcommand{\abc}{abc}
\expandafter\makefirstuc\expandafter{\abc}
\end{verbatim}
produces: Abc. There is a short cut command which will do this:\\[10pt]
\DescribeMacro{\xmakefirstuc}
\cs{xmakefirstuc}\marg{stuff}\\[10pt]
This is equivalent to \cs{expandafter}\cs{makefirstuc}\cs{expandafter}\marg{stuff}. So
\begin{verbatim}
\newcommand{\abc}{abc}
\xmakefirstuc{\abc}
\end{verbatim}
produces: Abc.

If you want to use an alternative command to convert to uppercase,
for example \cs{MakeTextUppercase}\footnote{defined in the 
\sty{textcase} package}, you can redefine the internal
command \cs{@gls@makefirstuc}. For example:
\begin{verbatim}
\renewcommand{\@gls@makefirstuc}[1]{\MakeTextUppercase #1}
\end{verbatim}
(Remember that command names that contain the @ character must
either be placed in packages or be placed between \cs{makeatletter} 
\cs{makeatother}.)

\ifmakedtx{}{\toTop}

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

\ifmakedtx{}{\printindex\toTop}

\end{document}