glossaries 3.0 (4apr11)

git-svn-id: svn://tug.org/texlive/trunk@21968 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 5841 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
new file mode 100644
index 00000000000..0c1a701352c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -0,0 +1,5841 @@
+\documentclass{nlctdoc}
+
+\usepackage{alltt}
+\usepackage{pifont}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\ifpdf
+\usepackage{mathpazo}
+\usepackage[scaled=.88]{helvet}
+\usepackage{courier}
+\fi
+\usepackage[colorlinks,
+            bookmarks,
+            hyperindex=false,
+            pdfauthor={Nicola L.C. Talbot},
+            pdftitle={User Manual for glossaries.sty},
+            pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref}
+\usepackage{xr-hyper}
+\usepackage[xindy,nonumberlist,seeautonumberlist,toc,style=altlist]{glossaries}
+
+\renewcommand*{\glsgroupskip}{}
+
+\renewcommand*{\glsseeformat}[3][\seename]{%
+  (\xmakefirstuc{#1} \glsseelist{#2}.)%
+}
+
+\renewcommand*{\glossarypreamble}{%
+\emph{This glossary style was setup using:}
+\begin{ttfamily}
+\begin{tabbing}
+\cs{usepackage}[\=xindy,\\
+\+\>nonumberlist,\\
+  seeautonumberlist,\\
+  toc,\\
+  style=altlist]\{glossaries\}
+\end{tabbing}
+\cs{renewcommand*}\{\ics{glsgroupskip}\}\{\}\newline
+\cs{renewcommand*}\{\ics{glsseeformat}\}[3][\ics{seename}]\{(\ics{xmakefirstuc}\{\#1\} \newline
+\ics{glsseelist}\{\#2\}.)\}
+\end{ttfamily}
+}
+
+\ifpdf
+\else
+  % Need an extra line break in the html version
+  % (Don't have time to fiddle with cfg files!)
+  \renewcommand*{\glossaryentryfield}[5]{%
+    \item[\glsentryitem{#1}\glstarget{#1}{#2}]\mbox{}\newline
+      #3\glspostdescription\space #5\newline}%
+\fi
+
+\makeglossaries
+
+\renewcommand*{\main}[1]{\hyperpage{#1}}
+\newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}}
+\newcommand*{\itermdef}[1]{\index{#1|htextbf}}
+
+\IndexPrologue{}
+
+\newglossaryentry{xindy}{
+name={\appfmt{xindy}\index{xindy|htextbf}},
+sort={xindy},
+text={\protect\app{xindy}},
+description={An flexible indexing application with multilingual
+support}
+}
+
+\newglossaryentry{makeindex}{%
+name={\appfmt{makeindex}\index{makeindex|htextbf}},%
+sort={makeindex},%
+text={\protect\app{makeindex}},%
+description={An indexing application},
+}
+
+\newglossaryentry{makeglossaries}{%
+name={\appfmt{makeglossaries}\index{makeglossaries|htextbf}},%
+sort={makeglossaries},%
+text={\protect\app{makeglossaries}},%
+description={A \sty{glossaries} custom designed Perl script interface 
+to \gls{xindy} and \gls{makeindex}}
+}
+
+\newglossaryentry{numberlist}{%
+name={Number list\itermdef{number list}},%
+sort={number list},%
+text={\protect\term{number list}},%
+description={A list of \glslink{entrylocation}{entry locations} (also 
+called a location list). The number list can be suppressed using the 
+\pkgopt{nonumberlist} package option}
+}
+
+\newglossaryentry{entrylocation}{%
+name={Entry location\itermdef{entry location}},%
+sort={entry location},%
+text={\protect\term{entry location}},%
+description={The location of the entry in the document. This
+defaults to the page number on which the entry appears. An entry may
+have multiple locations}
+}
+
+\newglossaryentry{locationlist}{%
+name={Location list},%
+sort={location list},%
+description={A list of \glslink{entrylocation}{entry locations}},%
+see={numberlist}
+}
+
+\newglossaryentry{linktext}{%
+name={Link text\itermdef{link text}},
+sort={link text},%
+text={\protect\term{link text}},
+description={The text produced by commands such as \ics{gls}. It may
+or may not be a hyperlink to the glossary}
+}
+
+\let\glsd\glsuseri
+\let\glsation\glsuserii
+
+\newglossaryentry{firstuse}{%
+name={First use\ifirstuse},
+sort={first use},%
+text={first use},%
+user1={first used},
+description={The first time a glossary entry is used (from the start of the document or after a reset) with one of the
+following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl},
+\ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}.
+\glsseeformat{firstuseflag,firstusetext}{}\nopostdesc}%
+}
+
+\newglossaryentry{firstuseflag}{%
+name={First use flag\ifirstuseflag},
+sort={first use flag},%
+text={first use flag},%
+description={A conditional that determines whether or not the entry
+has been used according to the rules of \gls{firstuse}. Commands
+to unset or reset this conditional are described in 
+\sectionref{sec:glsunset}}%
+}
+
+\newglossaryentry{firstusetext}{%
+name={First use text\ifirstusetext},
+sort={first use text},%
+text={first use text},%
+description={The text that is displayed on \gls{firstuse}, which is
+governed by the \gloskey{first} and \gloskey{firstplural} keys of
+\ics{newglossaryentry}. (May be overridden by
+\ics{glsdisp}.)\nopostdesc}%
+}
+
+\newglossaryentry{sanitize}{%
+name={Sanitize\itermdef{sanitize}},%
+sort={sanitize},
+text={\protect\term{sanitize}},%
+user1={sanitized\protect\iterm{sanitize}},%
+user2={sanitization\protect\iterm{sanitize}},
+description={Converts command names into character sequences. That is, a command called,
+say, \cs{foo}, is converted into the sequence of characters:
+\cs{}, \texttt{f}, \texttt{o}, \texttt{o}. Depending on the font,
+the backslash character may appear as a dash when used in the
+main document text, so \cs{foo} will appear as: ---foo.
+\glspar
+When \TeX\ writes information to a file, fragile
+commands must be protected. The \gloskey{name}, \gloskey{description}
+and \gloskey{symbol} keys all have their values written to a file,
+which means that care must be taken if those values contain fragile
+commands. There are two approaches: 1) the fragile commands must be
+protected using \ics{protect}; 2) the values are sanitized.
+Sanitizing the values gets rid of the inconvenience of having to
+protect fragile commands, but at the expense of no longer being able
+to use those values in the document. Sanitization is governed by the
+package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}}
+}
+
+\ifpdf
+\externaldocument{glossaries}
+\fi
+
+\doxitem{Option}{option}{package options}
+\doxitem{GlsKey}{key}{glossary keys}
+\doxitem{Style}{style}{glossary styles}
+\doxitem{Counter}{counter}{glossary counters}
+
+\setcounter{IndexColumns}{2}
+
+\newcommand*{\tick}{\ding{51}}
+
+\newcommand*{\ifirstuse}{\iterm{first use}}
+\newcommand*{\ifirstuseflag}{\iterm{first use>flag}}
+\newcommand*{\ifirstusetext}{\iterm{first use>text}}
+
+\newcommand*{\firstuse}{\gls{firstuse}}
+\newcommand*{\firstuseflag}{\gls{firstuseflag}}
+\newcommand*{\firstusetext}{\gls{firstusetext}}
+
+
+\newcommand*{\istkey}[1]{\appfmt{#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{#1}|hyperpage}}
+\newcommand*{\locfmt}[1]{\texttt{#1}\SpecialMainIndex{#1}}
+\newcommand*{\mkidxspch}{\index{makeindex=\appfmt{makeindex}>special characters|hyperpage}}
+
+\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
+\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+
+\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}}
+
+\newcommand*{\samplefile}[1]{\hyperref[ex:sample#1]{\texttt{sample#1.tex}}}
+
+\ifpdf
+  \newcommand*{\htmldoc}[2]{\qt{#1}}
+\else
+  \newcommand*{\htmldoc}[2]{\href{#2.html}{\qt{#1}}}
+\fi
+
+\begin{document}
+\MakeShortVerb{"}
+\DeleteShortVerb{\|}
+
+ \title{User Manual for glossaries.sty v3.0}
+ \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{2011-04-02}
+ \maketitle
+
+\noindent
+The \styfmt{glossaries} bundle comes with the following documentation:
+\begin{description}
+\item[\url{glossariesbegin.pdf}] 
+If you are a complete beginner, start with 
+\htmldoc{The glossaries package: a guide for
+beginners}{glossariesbegin}.
+
+\item[\url{glossary2glossaries.pdf}] 
+If you are moving over from the obsolete \sty{glossary} package,
+read \htmldoc{Upgrading from the glossary package to the
+glossaries package}{glossary2glossaries}.
+
+\item[glossaries-user.pdf]
+This document is the main user guide for the \styfmt{glossaries}
+package.
+
+\item[\url{mfirstuc-manual.pdf}]
+The commands provided by the \sty{mfirstuc} package are briefly
+described in \htmldoc{mfirstuc.sty: uppercasing first
+letter}{mfirstuc-manual}.
+
+\item[\url{glossaries.pdf}]
+Advanced users wishing to know more about the inner workings of all the
+packages provided in the \styfmt{glossaries} bundle should read
+\qt{Documented Code for glossaries v3.0}.
+This includes how to iterate over all entry labels defined in a
+given glossary or how to iterate over all glossary types, as well as
+the documented code for the \sty{mfirstuc} package.
+
+\item[INSTALL] Installation instructions.
+
+\item[CHANGES] Change log.
+
+\item[README] Package summary.
+
+\end{description}
+
+\begin{important}
+If you use \sty{hyperref} and \styfmt{glossaries}, you must load
+\sty{hyperref} \emph{first}.
+\end{important}
+
+\clearpage
+\tableofcontents
+
+\clearpage
+\printglossaries
+
+ \section{Introduction}
+
+The \styfmt{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. Only those terms used\footnote{That is, if the term has been
+referenced using any of the commands described in
+\sectionref{sec:glslink} and \sectionref{sec:glsadd} or via
+\ics{glssee} (or the \gloskey{see} key) or commands such as
+\ics{acrshort}.} in the document will be added to the glossary.
+
+\textbf{This package replaces the \sty{glossary} package which is
+now obsolete.} Please see the document \qtdocref{Upgrading from the
+glossary package to the glossaries package}{glossary2glossaries} for
+assistance in upgrading.
+
+One of the strengths of this package is its flexibility, however
+the drawback of this is the necessity of having a large manual
+that can cover all the various settings. If you are daunted by the
+size of the manual, try starting off with the much shorter
+\docref{guide for beginners}{glossariesbegin}.
+
+\begin{important}
+The \styfmt{glossaries} package comes with a
+\href{http://www.perl.org/about.html}{Perl} script called
+\gls{makeglossaries}. This provides a convenient interface to
+\gls{makeindex} or \gls{xindy}. It is strongly recommended
+that you use this script, but \emph{it is not essential}. If you are
+reluctant to install Perl, or for any other reason you don't want to
+use \gls*{makeglossaries}, you can called \gls*{makeindex} or
+\gls*{xindy} explicitly. See \sectionref{sec:makeglossaries} for
+further details.
+\end{important}
+
+The remainder of this introductory section covers the following:
+\begin{itemize}
+\item \sectionref{sec:samples} lists the sample documents provided 
+with this package.
+
+\item \sectionref{sec:languages} provides information for users who
+wish to write in a language other than English.
+
+\item \sectionref{sec:makeglossaries} describes how to use a
+post-processor to create the sorted glossaries for your document.
+
+\end{itemize}
+
+
+\subsection{Sample Documents}
+\label{sec:samples}
+
+The \styfmt{glossaries} package is provided with some sample
+documents that illustrate the various functions. These should
+be located in the \texttt{samples} subdirectory (folder) of the
+\styfmt{glossaries} documentation directory. This location varies
+according to your operating system and \TeX\ distribution. You
+can use \texttt{texdoc} to locate the main glossaries documentation.
+For example, in a terminal or command prompt, type:
+\begin{prompt}
+texdoc -l glossaries
+\end{prompt}
+This should display the full pathname of the file 
+\texttt{glossaries.pdf}. View the contents of that directory and
+see if it contains the \texttt{samples} subdirectory.
+
+If you can't find the sample files, they are available in the
+subdirectory \texttt{doc/latex/glossaries/samples/} in the
+\texttt{glossaries.tds.zip} archive which can be downloaded from
+\href{http://tug.ctan.org/tex-archive/macros/latex/contrib/glossaries/}{CTAN}.
+
+
+The sample documents are as follows:
+\begin{description}
+\item[minimalgls.tex]\label{ex:minimalgls} This document is a
+minimal working example. You can test your installation using this
+file. To create the complete document you will need to do the
+following steps:
+  \begin{enumerate}
+  \item Run \texttt{minimalgls.tex} through \LaTeX\ either by 
+  typing
+\begin{prompt}
+latex minimalgls
+\end{prompt}
+  in a terminal or by using the relevant button or menu item in
+  your text editor or front-end. This will create the required 
+  associated files but you will not see the glossary. If you use 
+  PDF\LaTeX\ you will also get warnings about non-existent 
+  references. These warnings may be ignored on the first run.
+
+  If you get a \verb"Missing \begin{document}" error, then 
+  it's most likely that your version of \sty{xkeyval} is 
+  out of date. Check the log file for a warning of that nature. 
+  If this is the case, you will need to update the \styfmt{xkeyval}
+  package.
+
+  \item Run \gls{makeglossaries} on the document. This can
+  be done on a terminal either by typing
+\begin{prompt}
+makeglossaries minimalgls
+\end{prompt}
+  or by typing
+\begin{prompt}
+perl makeglossaries minimalgls
+\end{prompt}
+  If your system doesn't recognise the command \texttt{perl} then
+  it's likely you don't have Perl installed. In which case you
+  will need to use \gls{makeindex} directly. You can do this
+  in a terminal by typing (all on one line):
+\begin{prompt}
+makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo
+\end{prompt}
+  (See \sectionref{sec:makeindexapp} for further details on using 
+   \gls*{makeindex} explicitly.)
+
+  Note that if you need to specify the full path and the path
+  contains spaces, you will need to delimit the file names with
+  the double-quote character.
+
+  \item Run \texttt{minimalgls.tex} through \LaTeX\ again (as step~1)
+  \end{enumerate}
+You should now have a complete document. The number following
+each entry in the glossary is the location number. By default, this 
+is the page number where the entry was referenced.
+
+\item[sample4col.tex]\label{ex:sample4col} This document illustrates
+a four column glossary where the entries have a symbol in addition
+to the name and description. To create the complete document, you
+need to do:
+\begin{prompt}
+latex sample4col
+makeglossaries sample4col
+latex sample4col
+\end{prompt}
+As before, if you don't have Perl installed, you will need to use
+\gls{makeindex} directly instead of using
+\gls{makeglossaries}. The vertical gap between entries is the
+gap created at the start of each group. This can be suppressed by
+redefining \ics{glsgroupskip} after the glossary style has been set:
+\begin{verbatim}
+\renewcommand*{\glsgroupskip}{}
+\end{verbatim}
+
+\item[sampleAcr.tex]\label{ex:sampleAcr} This document has some
+sample acronyms. It also adds the glossary to the table of contents,
+so an extra run through \LaTeX\ is required to ensure the document
+is up to date:
+\begin{prompt}
+latex sampleAcr
+makeglossaries sampleAcr
+latex sampleAcr
+latex sampleAcr
+\end{prompt}
+
+\item[sampleAcrDesc.tex]\label{ex:sampleAcrDesc} This is similar to
+the previous example, except that the acronyms have an associated
+description. As with the previous example, the glossary is added to
+the table of contents, so an extra run through \LaTeX\ is required:
+\begin{prompt}
+latex sampleAcrDesc
+makeglossaries sampleAcrDesc
+latex sampleAcrDesc
+latex sampleAcrDesc
+\end{prompt}
+
+\item[sampleDesc.tex]\label{ex:sampleDesc} This is similar to the
+previous example, except that it defines the acronyms using
+\ics{newglossaryentry} instead of \ics{newacronym}. As with the
+previous example, the glossary is added to the table of contents, so
+an extra run through \LaTeX\ is required:
+\begin{prompt}
+latex sampleDesc
+makeglossaries sampleDesc
+latex sampleDesc
+latex sampleDesc
+\end{prompt}
+
+\item[sample-custom-acronym.tex]\label{ex:sample-custom-acronym}
+This document illustrates how to define your own acronym style if
+the predefined styles don't suit your requirements.
+\begin{prompt}
+latex sample-custom-acronym
+makeglossaries sample-custom-acronym
+latex sample-custom-acronym
+\end{prompt}
+
+\item[sample-crossref.tex]\label{ex:sample-crossref}
+This document illustrates how to cross-reference entries in the
+glossary.
+\begin{prompt}
+latex sample-crossref
+makeglossaries sample-crossref
+latex sample-crossref
+\end{prompt}
+
+\item[sampleDB.tex]\label{ex:sampleDB} This document illustrates how
+to load external files containing the glossary definitions. It also
+illustrates how to define a new glossary type. This document has the
+\gls{numberlist} suppressed and uses \ics{glsaddall} to add all
+the entries to the glossaries without referencing each one
+explicitly. To create the document do:
+\begin{prompt}
+latex sampleDB
+makeglossaries sampleDB
+latex sampleDB
+\end{prompt}
+The glossary definitions are stored in the accompanying files
+\texttt{database1.tex} and \texttt{database2.tex}. Note that if you
+don't have Perl installed, you will need to use \gls{makeindex}
+twice instead of a single call to \gls{makeglossaries}:
+\begin{enumerate}
+\item Create the main glossary:
+\begin{prompt}
+makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo
+\end{prompt}
+\item Create the secondary glossary:
+\begin{prompt}
+makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn
+\end{prompt}
+\end{enumerate}
+
+\item[sampleEq.tex]\label{ex:sampleEq} This document illustrates how
+to change the location to something other than the page number. In
+this case, the \texttt{equation} counter is used since all glossary
+entries appear inside an \env{equation} environment. To create
+the document do:
+\begin{prompt}
+latex sampleEq
+makeglossaries sampleEq
+latex sampleEq
+\end{prompt}
+
+\item[sampleEqPg.tex]\label{ex:sampleEqPg} This is similar to the
+previous example, but the \glspl{numberlist} are a
+mixture of page numbers and equation numbers. This example adds the
+glossary to the table of contents, so an extra \LaTeX\ run is
+required:
+\begin{prompt}
+latex sampleEqPg
+makeglossaries sampleEqPg
+latex sampleEqPg
+latex sampleEqPg
+\end{prompt}
+
+\item[sampleSec.tex]\label{ex:sampleSec} This document also
+illustrates how to change the location to something other than the
+page number. In this case, the \texttt{section} counter is used.
+This example adds the glossary to the table of contents, so an extra
+\LaTeX\ run is required:
+\begin{prompt}
+latex sampleSec
+makeglossaries sampleSec
+latex sampleSec
+latex sampleSec
+\end{prompt}
+
+\item[sampleNtn.tex]\label{ex:sampleNtn} This document illustrates
+how to create an additional glossary type. This example adds the
+glossary to the table of contents, so an extra \LaTeX\ run is
+required:
+\begin{prompt}
+latex sampleNtn
+makeglossaries sampleNtn
+latex sampleNtn
+latex sampleNtn
+\end{prompt}
+Note that if you don't have Perl installed, you will need to use
+\gls{makeindex} twice instead of a single call to
+\gls{makeglossaries}:
+\begin{enumerate}
+\item Create the main glossary:
+\begin{prompt}
+makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo
+\end{prompt}
+\item Create the secondary glossary:
+\begin{prompt}
+makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn
+\end{prompt}
+\end{enumerate}
+
+\item[sample.tex]\label{ex:sample} This document illustrates some of
+the basics, including how to create child entries that use the same
+name as the parent entry. This example adds the glossary to the
+table of contents and it also uses \ics{glsrefentry}, so an extra \LaTeX\ 
+run is required:
+\begin{prompt}
+latex sample
+makeglossaries sample
+latex sample
+latex sample
+\end{prompt}
+You can see the difference between word and letter ordering if you
+substitute \pkgopt[word]{order} with \pkgopt[letter]{order}. (Note
+that this will only have an effect if you use
+\gls{makeglossaries}. If you use \gls{makeindex} explicitly,
+you will need to use the \texttt{-l} switch to indicate letter
+ordering.)
+
+\item[sampletree.tex]\label{ex:sampletree} This document illustrates
+a hierarchical glossary structure where child entries have different
+names to their corresponding parent entry. To create the document
+do:
+\begin{prompt}
+latex sampletree
+makeglossaries sampletree
+latex sampletree
+\end{prompt}
+
+\item[sample-dual.tex]\label{ex:sample-dual} This document
+illustrates how to define an entry that both appears in the list of
+acronyms and in the main glossary. To create the document do:
+\begin{prompt}
+latex sample-dual
+makeglossaries sample-dual
+latex sample-dual
+\end{prompt}
+
+\item[samplexdy.tex]\label{ex:samplexdy} This document illustrates
+how to use the \styfmt{glossaries} package with \gls{xindy} instead
+of \gls{makeindex}. The document uses UTF8 encoding (with the
+\sty{inputenc} package). The encoding is picked up by
+\gls{makeglossaries}. By default, this document will create a
+\gls{xindy} style file called \texttt{samplexdy.xdy}, but if you
+uncomment the lines
+\begin{verbatim}
+\setStyleFile{samplexdy-mc}
+\noist
+\GlsSetXdyLanguage{}
+\end{verbatim}
+it will set the style file to \texttt{samplexdy-mc.xdy} instead.
+This provides an additional letter group for entries starting with
+\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries}, you don't
+need to supply any additional information. If you don't use
+\gls*{makeglossaries}, you will need to specify the required
+information. Note that if you set the style file to
+\texttt{samplexdy-mc.xdy} you must also specify \ics{noist},
+otherwise the \styfmt{glossaries} package will overwrite
+\texttt{samplexdy-mc.xdy} and you will lose the \qt{Mc} letter
+group.
+
+To create the document do:
+\begin{prompt}
+latex samplexdy
+makeglossaries samplexdy
+latex samplexdy
+\end{prompt}
+If you don't have Perl installed, you will have to call 
+\gls{xindy} explicitly instead of using \gls{makeglossaries}.
+If you are using the default style file \texttt{samplexdy.xdy}, then
+do (no line breaks):
+\begin{prompt}
+xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo
+\end{prompt}
+otherwise, if you are using \texttt{samplexdy-mc.xdy}, then do
+(no line breaks):
+\begin{prompt}
+xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo
+\end{prompt}
+
+\item[samplexdy2.tex]\label{ex:samplexdy2} This document illustrates
+how to use the \styfmt{glossaries} package where the location
+numbers don't follow a standard format. This example will only work
+with \gls{xindy}. To create the document do:
+\begin{prompt}
+pdflatex samplexdy2
+makeglossaries samplexdy2
+pdflatex samplexdy2
+\end{prompt}
+If you can't use \gls{makeglossaries} then you need to do:
+\begin{prompt}
+xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo
+\end{prompt}
+See \sectionref{sec:xindyloc} for further details.
+
+\item[sampleutf8.tex]\label{ex:sampleutf8} This is another example
+that uses \gls{xindy}. Unlike \gls{makeindex},
+\gls{xindy} can cope with accented or non-Latin characters. This
+document uses UTF8 encoding. To create the document do:
+\begin{prompt}
+latex sampleutf8
+makeglossaries sampleutf8
+latex sampleutf8
+\end{prompt}
+If you don't have Perl installed, you will have to call
+\gls{xindy} explicitly instead of using \gls{makeglossaries}
+(no line breaks):
+\begin{prompt}
+xindy -L english -C utf8 -I xindy -M sampleutf8 -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
+\end{prompt}
+
+If you remove the \pkgopt{xindy} option from \texttt{sampleutf8.tex} 
+and do:
+\begin{prompt}
+latex sampleutf8
+makeglossaries sampleutf8
+latex sampleutf8
+\end{prompt}
+you will see that the entries that start with a non-Latin character
+now appear in the symbols group, and the word \qt{man\oe uvre} is now 
+after \qt{manor} instead of before it. If you are unable to use
+\gls{makeglossaries}, the call to \gls{makeindex} is as
+follows (no line breaks):
+\begin{prompt}
+makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
+\end{prompt}
+
+\item[sampleaccsupp.tex]\label{ex:sampleaccsupp} This document
+uses the experimental \sty{glossaries-accsupp} package. The
+symbol is set to the replacement text. Note that some PDF
+viewers don't use the accessibility support. Information 
+about the \styfmt{glossaries-accsupp} package can be found in
+\sectionref{sec:accsupp}.
+
+\end{description}
+
+
+\subsection{Multi-Lingual Support}
+\label{sec:languages}
+
+As from version 1.17, the \styfmt{glossaries} package can now be
+used with \gls{xindy} as well as \gls{makeindex}. If you
+are writing in a language that uses accented characters or
+non-Latin characters it is recommended that you use \gls*{xindy}
+as \gls*{makeindex} is hard-coded for Latin languages. This
+means that you are not restricted to the A, \ldots, Z letter groups.
+If you want to use \gls*{xindy}, remember to use the
+\pkgopt{xindy} package option. For example:
+\begin{verbatim}
+\documentclass[frenchb]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{babel}
+\usepackage[xindy]{glossaries}
+\end{verbatim}
+
+\begin{important}
+Note that although an accented character, such as é, looks like a plain
+character in your tex file, it's actually a macro and can therefore
+cause problems.
+
+\begin{enumerate}
+\item
+If you use an accented (or other expandable) character at the start of
+an entry name, you must place it in a group, or it will cause
+a problem for commands that convert the first letter to uppercase
+(e.g.\ \ics{Gls}) due to expansion issues. For example:
+\begin{verbatim}
+\newglossaryentry{elite}{name={{é}lite},
+description={select group or class}}
+\end{verbatim}
+
+\item If you use an accented (or other expandable) character in an
+entry name and you haven't switched off the \gloskey{name} key
+\glsation{sanitize}, you must use commands like
+\ics{glsentrytext} or \ics{glstext} instead of \ics{glsentryname} or
+\ics{glsname} or you will end up with strange looking characters in
+your document.
+
+\end{enumerate}
+\end{important}
+
+If you use the \sty{inputenc} package, \gls{makeglossaries}
+will pick up the encoding from the auxiliary file. If you use
+\gls{xindy} explicitly instead of via \gls*{makeglossaries},
+you may need to specify the encoding using the \texttt{-C} 
+option. Read the \gls*{xindy} manual for further details.
+
+\subsubsection{Changing the Fixed Names}
+\label{sec:fixednames}
+
+As from version 1.08, the \styfmt{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 \sty{babel} or \sty{polyglossia} \emph{before} 
+\styfmt{glossaries} to enable this. Note that if \sty{babel} is loaded 
+and the \sty{translator} package is detected on \TeX's path, then the
+\sty{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
+\sty{translator} package with the required languages. For example:
+\begin{verbatim}
+\usepackage[spanish]{babel}
+\usepackage[spanish]{translator}
+\usepackage{glossaries}
+\end{verbatim}
+Alternatively, specify the language as a class option rather
+than a package option. For example:
+\begin{verbatim}
+\documentclass[spanish]{report}
+
+\usepackage{babel}
+\usepackage{glossaries}
+\end{verbatim}
+
+If you want to use \sty{ngerman} or \sty{german} instead
+of \sty{babel}, you will need to include the \sty{translator} package 
+to provide the translations. For example:
+\begin{verbatim}
+\documentclass[ngerman]{article}
+\usepackage{ngerman}
+\usepackage{translator}
+\usepackage{glossaries}
+\end{verbatim}
+
+The languages are currently supported by the
+\styfmt{glossaries} package are listed in
+\tableref{tab:supportedlanguages}. Please note that (apart from
+spelling mistakes) I don't intend to change the default translations
+as it will cause compatibility problems.
+
+\begin{table}[htbp]
+\caption{Supported Languages}
+\label{tab:supportedlanguages}
+\begin{center}
+\begin{tabular}{lc}
+\bfseries Language & \bfseries As from version\\
+Brazilian Portuguese & 1.17\\
+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\\
+Serbian & 2.06\\
+Spanish & 1.08
+\end{tabular}
+\end{center}
+\end{table}
+
+The language dependent commands and \sty{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 Purpose\\
+\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 the glossary (for 2, 3 or 4 column glossaries 
+that support headers).\\
+\ics{descriptionname} & \texttt{Description (glossaries)} &
+Header for second column in the glossary (for 2, 3 or 4 column glossaries
+that support headers).\\
+\ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol
+column in the glossary for glossary styles that support this option.\\
+\ics{pagelistname} & \texttt{Page List (glossaries)} & 
+Header for page list column in the 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
+\sty{babel} package and do not have the \sty{translator} package
+installed, you need to be familiar with the advice given in
+\urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing
+the words babel uses}. If you have the \sty{translator} package
+installed, then you can provide your own dictionary with the
+necessary modifications (using \cs{deftranslation}) and load it
+using \cs{usedictionary}.
+
+\begin{important}
+Note that the dictionaries are loaded at the beginning of the
+document, so it won't have any effect if you put \cs{deftranslation}
+in the preamble. It should be put in your personal dictionary
+instead (as in the example below). See the \sty{translator}
+documentation for further details. (Now with \sty{beamer}
+documentation.)
+\end{important}
+
+Your custom dictionary doesn't have to be just a translation from
+English to another language. You may prefer to have a dictionary for
+a particular type of document. For example, suppose your
+institution's in-house reports have to have the glossary labelled as
+\qt{Nomenclature} and the page list should be labelled
+\qt{Location}, then you can create a file called, say,
+\begin{verbatim}
+myinstitute-glossaries-dictionary-English.dict
+\end{verbatim}
+that contains the following:
+\begin{verbatim}
+\ProvidesDictionary{myinstitute-glossaries-dictionary}{English}
+\deftranslation{Glossary}{Nomenclature}
+\deftranslation{Page List (glossaries)}{Location}
+\end{verbatim}
+You can now load it using:
+\begin{verbatim}
+\usedictionary{myinstitute-glossaries-dictionary}
+\end{verbatim}
+(Make sure that \texttt{myinstitute-glossaries-dictionary-English.dict}
+can be found by \TeX.) If you want to share your custom dictionary,
+you can upload it to \href{http://www.ctan.org/}{CTAN}.
+
+If you are using \sty{babel} and don't want to use the
+\sty{translator} interface, you can suppress it using the package
+option \pkgopt[false]{translate}, and either load
+\sty{glossaries-babel} after \styfmt{glossaries} or specify you're own
+translations. For example:
+\begin{verbatim}
+\documentclass[british]{article}
+
+\usepackage{babel}
+\usepackage[translate=false]{glossaries}
+\usepackage{glossaries-babel}
+\end{verbatim}
+or:
+\begin{verbatim}
+\documentclass[british]{article}
+
+\usepackage{babel}
+\usepackage[translate=false]{glossaries}
+
+\addto\captionsbritish{%
+    \renewcommand*{\glossaryname}{List of Terms}%
+    \renewcommand*{\acronymname}{List of Acronyms}%
+    \renewcommand*{\entryname}{Notation}%
+    \renewcommand*{\descriptionname}{Description}%
+    \renewcommand*{\symbolname}{Symbol}%
+    \renewcommand*{\pagelistname}{Page List}%
+    \renewcommand*{\glssymbolsgroupname}{Symbols}%
+    \renewcommand*{\glsnumbersgroupname}{Numbers}%
+}
+\end{verbatim}
+
+If you are using \sty{polyglossia} instead of \sty{babel}, 
+\sty{glossaries-polyglossia} will automatically be loaded unless
+you specify the package option \pkgopt[false]{translate}.
+
+Note that \gls{xindy} provides much better multi-lingual support
+than \gls{makeindex}, so it's recommended that you use \gls*{xindy}
+if you have glossary entries that contain diacritics or
+non-Roman letters. See \sectionref{sec:xindy} for further
+details.
+
+\subsection{Generating the Associated Glossary Files}
+\label{sec:makeglossaries}
+
+In order to generate a sorted glossary with compact location lists,
+it is necessary to use an external indexing application as an
+intermediate step. It is this application that creates the file
+containing the code that typesets the glossary. If this step is
+omitted, the glossaries will not appear in your document. The two
+indexing applications that are most commonly used with \LaTeX\ are
+\gls{makeindex} and \gls{xindy}. As from version 1.17, the
+\styfmt{glossaries} package can be used with either of these
+applications. Previous versions were designed to be used with
+\gls*{makeindex} only. Note that \gls*{xindy} has much better
+multi-lingual support than \gls*{makeindex}, so \gls*{xindy} is
+recommended if you're not writing in English. Commands that only
+have an effect when \gls*{xindy} is used are described in
+\sectionref{sec:xindy}.
+
+The \styfmt{glossaries} package comes with the Perl script
+\gls{makeglossaries} which will run \gls{makeindex} or \gls{xindy}
+on all the glossary files using a customized style file (which is
+created by \ics{makeglossaries}). See
+\sectionref{sec:makeglossariesapp} for further
+details. Perl is stable, cross-platform, open source software that
+is used by a number of \TeX-related applications. Further
+information is available at \url{http://www.perl.org/about.html}.
+The advantages of using \gls*{makeglossaries}:
+\begin{itemize}
+\item It automatically detects whether to use \gls*{makeindex} or
+\gls*{xindy} and sets the relevant application switches.
+
+\item One call of \gls*{makeglossaries} will run 
+\gls*{makeindex}/\gls*{xindy} for each glossary type.
+
+\item If things go wrong, \gls{makeglossaries} will scan the
+messages from \gls{makeindex} or \gls{xindy} and attempt to diagnose
+the problem in relation to the \styfmt{glossaries} package. This
+will hopefully provide more helpful messages in some cases. If it
+can't diagnose the problem, you will have to read the relevant transcript
+file and see if you can work it out from the \gls*{makeindex} or
+\gls*{xindy} messages.
+
+\end{itemize}
+
+Whilst it is strongly recommended that you use the
+\gls{makeglossaries} script, it is possible to use the
+\styfmt{glossaries} package without having Perl installed. In which
+case, if you have used the \pkgopt{xindy} package option, you will
+need to use \gls{xindy} (see \sectionref{sec:xindyapp}), otherwise
+you will need to use \gls{makeindex} (see
+\sectionref{sec:makeindexapp}). Note that some commands and package
+options have no effect if you don't use \gls*{makeglossaries}. These
+are listed in \tableref{tab:makeglossariesCmds}.
+
+Note that if any of your entries use an entry
+that is not referenced outside the glossary, you will need to
+do an additional \gls{makeglossaries}, \gls{makeindex}
+or \gls{xindy} run, as appropriate. For example,
+suppose you have defined the following entries:\footnote{Note that
+I'm assuming the \glsation{sanitize} has been switched on for the
+\gloskey{description} key, which is why I haven't used
+\cs{protect}\cs{gls} in the description.}
+\begin{verbatim}
+\newglossaryentry{citrusfruit}{name={citrus fruit},
+description={fruit of any citrus tree. (See also 
+\gls{orange})}}
+
+\newglossaryentry{orange}{name={orange},
+description={an orange coloured fruit.}}
+\end{verbatim}
+and suppose you have \verb|\gls{citrusfruit}| in your document
+but don't reference the \texttt{orange} entry, then the
+\texttt{orange} entry won't appear in your glossary until
+you first create the glossary and then do another run
+of \gls{makeglossaries}, \gls{makeindex} or \gls{xindy}.
+For example, if the document is called \texttt{myDoc.tex}, then
+you must do:
+\begin{prompt}
+latex myDoc
+makeglossaries myDoc
+latex myDoc
+makeglossaries myDoc
+latex myDoc
+\end{prompt}
+
+Likewise, an additional \gls{makeglossaries} and \LaTeX\ run
+may be required if the document pages shift with re-runs. For
+example, if the page numbering is not reset after the table of
+contents, the insertion of the table of contents on the second
+\LaTeX\ run may push glossary entries across page boundaries, which
+means that the \glspl{numberlist} in the glossary may 
+need updating.
+
+The examples in this document assume that you are accessing
+\gls{makeglossaries}, \gls{xindy} or \gls{makeindex} via a terminal.
+Windows users can use the MSDOS Prompt which is usually accessed via
+the \menu{Start}\submenu{All Programs} menu or
+\menu{Start}\submenu{All Programs}\submenu{Accessories} menu.
+
+Alternatively, your text editor may have the facility to create a
+function that will call the required application. The article
+\href{http://www.latex-community.org/index.php?option=com_content&view=article\&id=263:glossaries-nomenclature-lists-of-symbols-and-acronyms&catid=55:latex-general&Itemid=114}{\qt{Glossaries, Nomenclature, List of Symbols and
+Acronyms}}
+in the \urlfootref{http://www.latex-community.org/}{\LaTeX\
+Community's} Know How section
+describes how to do this for TeXnicCenter, and the thread
+\href{http://groups.google.com/group/comp.text.tex/browse_thread/thread/edd83831b81b0759?hl=en}{\qt{Executing Glossaries' makeindex from a WinEdt
+macro}} on the \texttt{comp.text.tex} newsgroup
+describes how to do it for WinEdt. For other editors see the editor's
+user manual for further details.
+
+If any problems occur, remember to check the transcript files 
+(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages.
+
+\begin{table}[htbp]
+\caption{Commands and package options that have no effect when
+using \texttt{xindy} or \texttt{makeindex} explicitly}
+\label{tab:makeglossariesCmds}
+\vskip\baselineskip
+\begin{tabular}{@{}lll@{}}
+\bfseries Command or Package Option & \gls{makeindex} & 
+\gls{xindy}\\
+\pkgopt[letter]{order} & use \texttt{-l} &
+ use \texttt{-M ord/letorder}\\
+\pkgopt[word]{order} & default & default\\
+\pkgopt{xindy}=\{\pkgoptfmt{language=}\meta{lang}\pkgoptfmt{,codename=}\meta{code}\} &
+N/A & use \texttt{-L} \meta{lang} \texttt{-C} \meta{code}\\
+\ics{GlsSetXdyLanguage}\marg{lang} & N/A &
+use \texttt{-L} \meta{lang}\\
+\ics{GlsSetXdyCodePage}\marg{code} & N/A &
+use \texttt{-C} \meta{code}
+\end{tabular}
+\par
+\end{table}
+
+
+\subsubsection{Using the makeglossaries Perl Script}
+\label{sec:makeglossariesapp}
+
+The \gls{makeglossaries} script picks up the relevant information
+from the auxiliary (\filetype{.aux}) file and will either call
+\gls{xindy} or \gls{makeindex}, depending on the supplied
+information. Therefore, you only need to pass the document's name
+without the extension to \gls*{makeglossaries}. For example, if your
+document is called \texttt{myDoc.tex}, type the following in your
+terminal:
+\begin{prompt}
+latex myDoc
+makeglossaries myDoc
+latex myDoc
+\end{prompt}
+You may need to explicitly load \gls{makeglossaries} into Perl:
+\begin{prompt}
+perl makeglossaries myDoc
+\end{prompt}
+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.
+
+The \gls{makeglossaries} script contains POD (Plain Old
+Documentation). If you want, you can create a man page for
+\gls*{makeglossaries} using \app{pod2man} and move the 
+resulting file onto the man path. Alternatively do
+\texttt{makeglossaries -{}-help} for a list of all options or
+\texttt{makeglossaries -{}-version} for the version number.
+
+\begin{important}
+When upgrading the \styfmt{glossaries} package, make sure you also
+upgrade your version of \gls{makeglossaries}. The current version is
+2.02.
+\end{important}
+
+\subsubsection{Using xindy explicitly}
+\label{sec:xindyapp}
+
+If you want to use \gls{xindy} to process the glossary
+files, you must make sure you have used the 
+\pkgopt{xindy} package option:
+\begin{verbatim}
+\usepackage[xindy]{glossaries}
+\end{verbatim}
+This is required regardless of whether you use \gls{xindy}
+explicitly or whether it's called implicitly via 
+\gls{makeglossaries}. This causes the glossary 
+entries to be written in raw \gls*{xindy} format, so you need to
+use \texttt{-I xindy} \emph{not} \texttt{-I tex}.
+
+To run \gls{xindy} type the following in your terminal 
+(all on one line):
+\begin{prompt}
+xindy -L \meta{language} -C \meta{encoding} -I xindy -M \meta{style} -t \meta{base}.glg -o \meta{base}.gls \meta{base}.glo
+\end{prompt}
+where \meta{language} is the required language name, \meta{encoding}
+is the encoding, \meta{base} is the name of the document without the
+\filetype{.tex} extension and \meta{style} is the name of the
+\gls{xindy} style file without the \filetype{.xdy} extension.
+The default name for this style file is \meta{base}\filetype{.xdy}
+but can be changed via \ics{setStyleFile}\marg{style}. You may need
+to specify the full path name depending on the current working
+directory. If any of the file names contain spaces, you must delimit
+them using double-quotes.
+
+For example, if your document is called \texttt{myDoc.tex} and
+you are using UTF8 encoding in English, then type the
+following in your terminal:
+\begin{prompt}
+xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo
+\end{prompt}
+
+Note that this just creates the main glossary. You need to do
+the same for each of the other glossaries (including the
+list of acronyms if you have used the \pkgopt{acronym}
+package option), substituting \filetype{.glg}, \filetype{.gls}
+and \filetype{.glo} with the relevant extensions. For example,
+if you have used the \pkgopt{acronym} package option, then 
+you would need to do:
+\begin{prompt}
+xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acn
+\end{prompt}
+For additional glossaries, the extensions are those supplied
+when you created the glossary with \ics{newglossary}.
+
+Note that if you use \gls{makeglossaries} instead, you can
+replace all those calls to \gls{xindy} with just one call
+to \gls*{makeglossaries}:
+\begin{prompt}
+makeglossaries myDoc
+\end{prompt}
+Note also that some commands and package options have no effect if 
+you use \gls{xindy} explicitly instead of using 
+\gls*{makeglossaries}. These are listed in 
+\tableref{tab:makeglossariesCmds}.
+
+
+\subsubsection{Using makeindex explicitly}
+\label{sec:makeindexapp}
+
+If you want to use \gls{makeindex} explicitly, you must
+make sure that you haven't used the \pkgopt{xindy} package
+option or the glossary entries will be written in the wrong
+format. To run \gls*{makeindex}, type the following in
+your terminal:
+\begin{prompt}
+makeindex -s \meta{style}.ist -t \meta{base}.glg -o \meta{base}.gls \meta{base}.glo
+\end{prompt}
+where \meta{base} is the name of your document without the
+\filetype{.tex} extension and \meta{style}\filetype{.ist} is the 
+name of the \gls{makeindex} style file. By default, this is
+\meta{base}\filetype{.ist}, but may be changed via
+\ics{setStyleFile}\marg{style}. Note that there are other options, 
+such as \texttt{-l} (letter ordering). See the \gls*{makeindex}
+manual for further details.
+
+For example, if your document is called \texttt{myDoc.tex}, then
+type the following at the terminal:
+\begin{prompt}
+makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
+\end{prompt}
+Note that this only creates the main glossary. If you have
+additional glossaries (for example, if you have used the
+\pkgopt{acronym} package option) then you must call 
+\gls{makeindex} for each glossary, substituting 
+\filetype{.glg}, \filetype{.gls} and \filetype{.glo} with the
+relevant extensions. For example, if you have used the
+\pkgopt{acronym} package option, then you need to type the
+following in your terminal:
+\begin{prompt}
+makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
+\end{prompt}
+For additional glossaries, the extensions are those supplied
+when you created the glossary with \ics{newglossary}.
+
+Note that if you use \gls{makeglossaries} instead, you can
+replace all those calls to \gls{makeindex} with just one call
+to \gls*{makeglossaries}:
+\begin{prompt}
+makeglossaries myDoc
+\end{prompt}
+Note also that some commands and package options have no effect if 
+you use \gls*{makeindex} explicitly instead of using 
+\gls{makeglossaries}. These are listed in 
+\tableref{tab:makeglossariesCmds}.
+
+
+\subsubsection{Note to Front-End and Script Developers}
+
+The information needed to determine whether to use \gls{xindy}
+or \gls{makeindex} and the information needed to call those
+applications is stored in the auxiliary file. This information can
+be gathered by a front-end, editor or script to make the glossaries
+where appropriate. This section describes how the information is
+stored in the auxiliary file.
+
+The file extensions used by each defined glossary are given by
+\begin{definition}[\DescribeMacro{\@newglossary}]
+\cs{@newglossary}\marg{label}\marg{log}\marg{out-ext}\marg{in-ext}
+\end{definition}
+where \meta{in-ext} is the extension of the \emph{indexing
+application's} input file (the output file from the \styfmt{glossaries}
+package's point of view), \meta{out-ext} is the extension of the
+\emph{indexing application's} output file (the input file from
+the \styfmt{glossaries} package's point of view) and \meta{log} is the
+extension of the indexing application's transcript file. The label
+for the glossary is also given for information purposes only, but
+is not required by the indexing applications. For example, the
+information for the main glossary is written as:
+\begin{verbatim}
+\@newglossary{main}{glg}{gls}{glo}
+\end{verbatim}
+
+The indexing application's style file is specified by
+\begin{definition}[\DescribeMacro{\@istfilename}]
+\cs{@istfilename}\marg{filename}
+\end{definition}
+The file extension indicates whether to use \gls{makeindex}
+(\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}). Note that
+the glossary information is formatted differently depending on
+which indexing application is supposed to be used, so it's 
+important to call the correct one.
+
+Word or letter ordering is specified by:
+\begin{definition}[\DescribeMacro{\@glsorder}]
+\cs{@glsorder}\marg{order}
+\end{definition}
+where \meta{order} can be either \texttt{word} or \texttt{letter}.
+
+If \gls{xindy} should be used, the language and code page
+for each glossary is specified by
+\begin{definition}[\DescribeMacro{\@xdylanguage}\DescribeMacro{\@gls@codepage}]
+\cs{@xdylanguage}\marg{label}\marg{language}\\
+\cs{@gls@codepage}\marg{label}\marg{code}
+\end{definition}
+where \meta{label} identifies the glossary, \meta{language} is
+the root language (e.g.\ \texttt{english}) and \meta{code}
+is the encoding (e.g.\ \texttt{utf8}). These commands are omitted
+if \gls{makeindex} should be used.
+
+
+\section{Package Options}
+\label{sec:pkgopts}
+
+This section describes the available \styfmt{glossaries} package options.
+
+\subsection{General Options}
+\label{sec:pkgopts-general}
+
+\begin{description}
+\item[\pkgopt{nowarn}] This suppresses all warnings generated by
+the \styfmt{glossaries} package.
+
+\item[\pkgopt{nomain}] This suppresses the creation of the main
+glossary. Note that if you use this option, you must create another
+glossary in which to put all your entries (either via the
+\pkgopt{acronym} package option described in
+\sectionref{sec:pkgopts-acronym} or via \ics{newglossary} described
+in \sectionref{sec:newglossary}).
+
+\item[\pkgopt{sanitize}] This is a
+\meta{key}=\meta{value} option whose value is also a
+\meta{key}=\meta{value} list. By default, the \styfmt{glossaries}
+package \glspl{sanitize} the values of the \gloskey{name},
+\gloskey{description} and \gloskey{symbol} keys used when defining a
+new glossary entry. This means that you can use fragile commands in
+those keys, but it 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. 
+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}
+You can use \pkgopt[none]{sanitize} as a shortcut for\newline
+\pkgoptfmt{sanitize=\{name=false,description=false,symbol=false\}}.
+
+\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 \glsd{sanitize} if \pkgopt[standard]{sort} is in effect) 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{savewrites}] This is a boolean option to minimises the
+number of write registers used by the \styfmt{glossaries} package.
+(Default is \pkgopt[false]{savewrites}.) There are only a limited
+number of write registers, and if you have a large number of
+glossaries or if you are using a class or other packages that
+create a lot of external files, you may exceed the maximum number
+of available registers. If \pkgopt{savewrites} is set, the glossary
+information will be stored in token registers until the end of the
+document when they will be written to the external files. If you run
+out of token registers, you can use \sty{etex}.
+
+\begin{important}
+If you want to use \TeX's \ics{write18} mechanism to call
+\gls{makeindex} or \gls{xindy} from your document and use
+\pkgopt{savewrites}, you must create the external files with 
+\cs{glswritefiles} before you call \gls*{makeindex}/\gls*{xindy}. Also set
+\cs{glswritefiles} to nothing or \cs{relax} before the end of the
+document to avoid rewriting the files. For example:
+\begin{verbatim}
+\glswritefiles
+\write18{makeindex -s \istfilename\space -t \jobname.glg
+-o \jobname.gls \jobname}
+\let\glswritefiles\relax
+\end{verbatim}
+\end{important}
+
+\item[\pkgopt{translate}] This is a boolean option. The default is
+\pkgoptval{true}{translate} if \sty{babel}, \sty{polyglossia} or 
+\sty{translator} have been loaded, otherwise the default value is
+\pkgoptval{false}{translate}.
+
+  \begin{description}
+  \item[{\pkgopt[true]{translate}}] If \sty{babel} has been loaded
+  and the \sty{translator} package is installed, \sty{translator}
+  will be loaded and the translations will be provided by the
+  \sty{translator} package interface. You can modify the 
+  translations by providing your own dictionary. If the 
+  \sty{translator} package isn't installed and \sty{babel} is
+  loaded, the \sty{glossaries-babel} package will 
+  be loaded and the translations will be provided using \styfmt{babel}'s
+  \cs{addto}\cs{caption}\meta{language} mechanism. If 
+  \sty{polyglossia} has been loaded, \sty{glossaries-polyglossia}
+  will be loaded.
+
+  \item[{\pkgopt[false]{translate}}] Don't provide translations, even
+  if \sty{babel} or \sty{polyglossia} has been loaded. You can 
+  then provide you're own translations or explicitly load 
+  \sty{glossaries-babel} or \sty{glossaries-polyglossia}.
+  \end{description}
+
+See \sectionref{sec:fixednames} for further details.
+
+\item[\pkgopt{hyperfirst}] This is a boolean option that specifies
+whether each term has a hyperlink on \firstuse. The default is 
+\pkgopt[true]{hyperfirst} (terms on \gls{firstuse} have a hyperlink, 
+unless explicitly suppressed using starred versions of commands
+such as \ics{gls*}).
+
+\end{description}
+
+\subsection{Sectioning and TOC Options}
+\label{sec:pkgopts-sec}
+
+\begin{description}
+\item[\pkgopt{toc}] Add the glossaries to the table of contents.
+Note that an extra \LaTeX\ run is required with this option.
+Alternatively, you can switch this function on and off using
+\begin{definition}[\DescribeMacro{\glstoctrue}]
+\cs{glstoctrue}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\glstocfalse}]
+\cs{glstocfalse}
+\end{definition}
+
+\item[\pkgopt{numberline}] When used with \pkgopt{toc}, this will
+add \ics{numberline}\verb|{}| in the final argument of 
+\ics{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{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
+exist, 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
+\begin{definition}[\DescribeMacro{\setglossarysection}]
+\cs{setglossarysection}\marg{name}
+\end{definition}
+where \meta{name} is the sectional unit.
+
+The start of each glossary adds information to the page header via
+\begin{definition}[\DescribeMacro{\glossarymark}]
+\cs{glossarymark}\marg{glossary title}
+\end{definition}
+This defaults to \cs{@mkboth} unless \cls{memoir} is loaded, but you may 
+need to redefine it.
+For example, to only change the right header:
+\begin{verbatim}
+\renewcommand{\glossarymark}[1]{\markright{#1}}
+\end{verbatim}
+or to prevent it from changing the headers:
+\begin{verbatim}
+\renewcommand{\glossarymark}[1]{}
+\end{verbatim}
+
+Occasionally you may find that another package defines 
+\cs{cleardoublepage} when it is not required. This may cause an 
+unwanted blank page to appear before each glossary. This can
+be fixed by redefining \ics{glsclearpage}:
+\begin{verbatim}
+\renewcommand*{\glsclearpage}{\clearpage}
+\end{verbatim}
+
+\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 \styfmt{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 
+\begin{definition}[\DescribeMacro{\glsautoprefix}]
+\cs{glsautoprefix}
+\end{definition}
+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}
+
+\end{description}
+
+\subsection{Glossary Appearance Options}
+\label{sec:pkgopts-printglos}
+
+\begin{description}
+\item[\pkgopt{entrycounter}] This is a boolean option. (Default
+is \pkgopt[false]{entrycounter}.) If set, each main (level~0)
+glossary entry will be numbered when using the standard glossary
+styles. This option creates the counter
+\DescribeCounter{glossaryentry}\ctrfmt{glossaryentry}.
+
+If you use this option, you can reference the entry number
+within the document using
+\begin{definition}[\DescribeMacro{\glsrefentry}]
+\cs{glsrefentry}\marg{label}
+\end{definition}
+where \meta{label} is the label associated with that glossary entry.
+
+\begin{important}
+If you use \cs{glsrefentry}, you must run \LaTeX\ twice after
+creating the glossary files using \gls{makeglossaries},
+\gls{makeindex} or \gls{xindy} to ensure the cross-references are
+up-to-date.
+\end{important}
+
+\item[\pkgopt{counterwithin}] This is a \meta{key}=\meta{value}
+option where \meta{value} is the name of a counter. If used, this
+option will automatically set \pkgopt[true]{entrycounter} and the
+\ctr{glossaryentry} counter will be reset every time \meta{value} is
+incremented.
+
+\begin{important}
+The \ctr{glossaryentry} counter isn't automatically reset at the
+start of each glossary, except when glossary section numbering is on
+and the counter used by \pkgopt{counterwithin} is the same as the
+counter used in the glossary's sectioning command. If you want
+the counter reset at the start of each glossary, you can redefine
+\ics{glossarypreamble} so that it sets \ctr{glossaryentry} to zero:
+\begin{verbatim}
+\renewcommand{\glossarypreamble}{%
+  \setcounter{glossaryentry}{0}%
+}
+\end{verbatim}
+\end{important}
+
+\item[\pkgopt{subentrycounter}] This is a boolean option. (Default
+is \pkgopt[false]{subentrycounter}.) If set, each level~1
+glossary entry will be numbered when using the standard glossary
+styles. This option creates the counter
+\DescribeCounter{glossarysubentry}\ctrfmt{glossarysubentry}.
+The counter is reset with each main (level~0) entry. Note that this
+package option is independent of \pkgopt{entrycounter}. You can
+reference the number within the document using
+\ics{glsrefentry}\marg{label} where \meta{label} is the label
+associated with the sub-entry. (See above.)
+
+\item[\pkgopt{style}] This is a \meta{key}=\meta{value} option.
+(Default is \pkgopt[list]{style}.) Its value should be the name of
+the glossary style to use. This key may only be used for styles
+defined in \sty{glossary-list}, \sty{glossary-long},
+\sty{glossary-super} or \sty{glossary-tree}. (See
+\sectionref{sec:styles}.)
+
+\item[\pkgopt{nolong}] This prevents the \styfmt{glossaries} package
+from automatically loading \sty{glossary-long} (which means that
+the \sty{longtable} package also won't be loaded). This reduces
+overhead by not defining unwanted styles and commands. Note that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \styfmt{glossary-long} package.
+
+\item[\pkgopt{nosuper}] This prevents the \styfmt{glossaries} package
+from automatically loading \sty{glossary-super} (which means that
+the \sty{supertabular} package also won't be loaded). This reduces
+overhead by not defining unwanted styles and commands. Note that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \styfmt{glossary-super} package.
+
+\item[\pkgopt{nolist}] This prevents the \styfmt{glossaries} package
+from automatically loading \sty{glossary-list}. This reduces
+overhead by not defining unwanted styles. Note that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \styfmt{glossary-list} package.
+Note that since the default style is \glostyle{list}, you will 
+also need to use the \pkgopt{style} option to set the style to
+something else.
+
+\item[\pkgopt{notree}] This prevents the \styfmt{glossaries} package
+from automatically loading \sty{glossary-tree}. This reduces
+overhead by not defining unwanted styles. Note that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \styfmt{glossary-tree} package.
+
+\item[\pkgopt{nostyles}] This prevents all the predefined styles
+from being loaded. This option is provided in the event that the
+user has custom styles that are not dependent on the styles
+provided by the \styfmt{glossaries} package. Note that if you use
+this option, you can't use the \pkgopt{style} package option. Instead
+you must either use \ics{glossarystyle}\marg{style} or
+the \gloskey[printglossary]{style} key in the
+optional argument to \ics{printglossary}.
+
+\item[\pkgopt{nonumberlist}] This option will suppress the 
+associated \glspl{numberlist} in the glossaries (see also 
+\sectionref{sec:numberlists}).
+
+\item[\pkgopt{seeautonumberlist}] If you suppress the
+\glspl{numberlist} with \pkgopt{nonumberlist}, described above, this
+will also suppress any cross-referencing information supplied by the
+\gloskey{see} key in \ics{newglossaryentry} or \ics{glssee}. If you
+use \pkgopt{seeautonumberlist}, the \gloskey{see} key will
+automatically implement \gloskey{nonumberlist=false} for that entry.
+(Note this doesn't affect \cs{glssee}.) For further details see
+\sectionref{sec:crossref}.
+
+\item[\pkgopt{counter}] This is a \meta{key}=\meta{value} option.
+(Default is \pkgopt[page]{counter}.) The value should be the name of
+the default counter to use in the \glspl{numberlist}
+(see \sectionref{sec:numberlists}).
+
+\end{description}
+
+\subsection{Sorting Options}
+\label{sec:pkgopts-sort}
+
+\begin{description}
+\item[\pkgopt{sort}] This is a \meta{key}=\meta{value} option where
+the option can only have one of the following values:
+
+\begin{itemize}
+\item \pkgoptval{standard}{sort} : entries are sorted according to
+the value of the \gloskey{sort} key used in \ics{newglossaryentry}
+(if present) or the \gloskey{name} key (if \gloskey{sort} key is
+missing);
+
+\item \pkgoptval{def}{sort} : entries are sorted in the order in
+which they were defined (the \gloskey{sort} key in
+\cs{newglossaryentry} is ignored);
+
+\item \pkgoptval{use}{sort} : entries are sorted according to the
+order in which they are used in the document (the \gloskey{sort} key
+in \cs{newglossaryentry} is ignored).
+\end{itemize}
+
+The default is \pkgopt[standard]{sort}.
+
+\item[\pkgopt{order}] This may take two values: 
+\pkgoptval{word}{order} or \pkgoptval{letter}{order}. The default
+is word ordering.
+
+\begin{important}
+Note that the \pkgopt{order} option has no effect if you don't use 
+\gls{makeglossaries}.
+\end{important}
+
+\item[\pkgopt{makeindex}] (Default) The glossary information and
+indexing style file will be written in \gls{makeindex} format. If
+you use \gls{makeglossaries}, it will automatically detect that it
+needs to call \gls*{makeindex}. If you don't use
+\gls*{makeglossaries}, you need to remember to use \gls*{makeindex}
+not \gls{xindy}. The indexing style file will been given a
+\filetype{.ist} extension.
+
+\item[\pkgopt{xindy}] The glossary information and indexing style
+file will be written in \gls{xindy} format. If you use
+\gls{makeglossaries}, it will automatically detect that it needs to
+call \gls*{xindy}. If you don't use \gls*{makeglossaries}, you need to
+remember to use \gls*{xindy} not \gls{makeindex}. The indexing style
+file will been given a \filetype{.xdy} extension.
+
+The \pkgopt{xindy} package option may additionally have a value that
+is a \meta{key}=\meta{value} comma-separated list to override the
+language and codepage. For example:
+\begin{verbatim}
+\usepackage[xindy={language=english,codepage=utf8}]{glossaries}
+\end{verbatim}
+You can also specify whether you want a number group in the
+glossary. This defaults to true, but can be suppressed. For example:
+\begin{verbatim}
+\usepackage[xindy={glsnumbers=false}]{glossaries}
+\end{verbatim}
+See \sectionref{sec:xindy} for further details on using \gls{xindy}
+with the \styfmt{glossaries} package.
+
+\end{description}
+
+\subsection{Acronym Options}
+\label{sec:pkgopts-acronym}
+
+\begin{description}
+\item[\pkgopt{acronym}] This creates a new glossary with the
+label \texttt{acronym}. This is equivalent to:
+\begin{verbatim}
+\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
+\end{verbatim}
+If the \pkgopt{acronym} package option is used, \ics{acronymtype}
+is set to \texttt{acronym} otherwise it is set to 
+\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to
+\ics{glsdefaulttype} if the \pkgopt{acronym} package option is
+not used, but \ics{glsdefaulttype} usually has the value
+\texttt{main}.} 
+Entries that are defined using \ics{newacronym} are placed in
+the glossary whose label is given by \ics{acronymtype}, unless
+another glossary is explicitly specified.
+
+\item[\pkgopt{acronymlists}] By default, only the \cs{acronymtype}
+glossary is considered to be a list of acronyms. If you have other
+lists of acronyms, you can specify them as a comma-separated list
+in the value of \pkgopt{acronymlists}. For example, if you use the
+\pkgopt{acronym} package option but you also want the \texttt{main} 
+glossary to also contain a list of acronyms, you can do:
+\begin{verbatim}
+\usepackage[acronym,acronymlists={main}]{glossaries}
+\end{verbatim}
+No check is performed to determine if the listed glossaries exist,
+so you can add glossaries you haven't defined yet. For example:
+\begin{verbatim}
+\usepackage[acronym,acronymlists={main,acronym2}]{glossaries}
+\newglossary[alg2]{acronym2}{acr2}{acn2}{Statistical Acronyms}
+\end{verbatim}
+
+\item[\pkgopt{description}] This option changes the definition of
+\ics{newacronym} to allow a description. This option has no effect if
+you defined your own custom acronym style. See
+\sectionref{sec:acronyms} for further details.
+
+\item[\pkgopt{footnote}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed. This
+option has no effect if you defined your own custom acronym style. See
+\sectionref{sec:acronyms} for further details.
+
+\item[\pkgopt{smallcaps}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed. This
+option may have no effect if you defined your own custom acronym
+style. See \sectionref{sec:acronyms} for further details.
+
+\item[\pkgopt{smaller}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed. If you use
+this option, you will need to include the \sty{relsize} package or
+otherwise define \ics{textsmaller} or redefine \ics{acronymfont}.
+This option may have no effect if you defined your own custom acronym
+style. See \sectionref{sec:acronyms} for further details.
+
+\item[\pkgopt{dua}] This option changes the definition of
+\ics{newacronym} so that acronyms are always expanded. This
+option has no effect if you defined your own custom acronym style. 
+See \sectionref{sec:acronyms} for further details.
+
+\item[\pkgopt{shortcuts}] This option provides shortcut commands
+for acronyms.  See \sectionref{sec:acronyms} for further details.
+
+\end{description}
+
+\section{Setting Up}
+\label{sec:setup}
+
+The command
+\begin{definition}[\DescribeMacro{\makeglossaries}]
+\cs{makeglossaries}
+\end{definition}
+must be placed in the preamble in order to create the customised
+\gls{makeindex} (\filetype{.ist}) or \gls{xindy} (\filetype{.xdy})
+style file and to ensure that glossary entries are written to the
+appropriate output files. If you omit \cs{makeglossaries} none of
+the glossaries will be created.
+
+\begin{important}
+Note that some of the commands provided by the \styfmt{glossaries}
+package must be placed before \cs{makeglossaries} as they are
+required when creating the customised style file. If you attempt
+to use those commands after \cs{makeglossaries} you will generate
+an error.
+\end{important}
+
+You can suppress the creation of the customised \gls{xindy}
+or \gls{makeindex} style file using
+\begin{definition}[\DescribeMacro{\noist}]
+\cs{noist}
+\end{definition}
+Note that this command must be used before \cs{makeglossaries}.
+\begin{important}
+Note that if you have a custom \filetype{.xdy} file created when using 
+\styfmt{glossaries} version 2.07 or below, you will need to use the
+\pkgopt{compatible-2.07} package option with it.
+\end{important}
+
+The default name for the customised style file is given by
+\ics{jobname}\filetype{.ist} (for \gls{makeindex}) or 
+\ics{jobname}\filetype{.xdy} (for \gls{xindy}). This name may be
+changed using:
+\begin{definition}[\DescribeMacro{\setStyleFile}]
+\cs{setStyleFile}\marg{name}
+\end{definition}
+where \meta{name} is the name of the style file without the 
+extension. Note that this command must be used before
+\cs{makeglossaries}.
+
+Each glossary entry is assigned a \gls{numberlist} that lists all 
+the locations in the document where that entry was used. By default,
+the location refers to the page number but this may be overridden
+using the \pkgopt{counter} package option. The default form of
+the location number assumes a full stop compositor (e.g.\ 1.2),
+but if your location numbers use a different compositor (e.g. 1-2)
+you need to set this using
+\begin{definition}[\DescribeMacro{\glsSetCompositor}]
+\cs{glsSetCompositor}\marg{symbol}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsSetCompositor{-}
+\end{verbatim}
+Note that this command must be used before \cs{makeglossaries}.
+
+If you use \gls{xindy}, you can have a different compositor for page
+numbers starting with an uppercase alphabetical character using:
+\begin{definition}[\DescribeMacro{\glsSetAlphaCompositor}]
+\cs{glsSetAlphaCompositor}\marg{symbol}
+\end{definition}
+Note that this command has no effect if you haven't used the
+\pkgopt{xindy} package option. For example, if you want 
+\glspl{numberlist} containing a mixture of A-1 and 2.3 style
+formats, then do:
+\begin{verbatim}
+\glsSetCompositor{.}\glsSetAlphaCompositor{-}
+\end{verbatim}
+See \sectionref{sec:numberlists} for further information about
+\glspl{numberlist}.
+
+\section{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 \ics{newglossaryentry} and
+\ics{newacronym} was removed in version 1.13, but the restriction
+remains for \ics{loadglsentries}.} However only those entries that
+occur in the document (using any of the commands described in
+\sectionref{sec:glslink}, \sectionref{sec:glsadd} or
+\sectionref{sec:crossref}) will appear in the glossary. Each time an
+entry is used in this way, a line is added to an associated glossary
+file (\filetype{.glo}), 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 \gls{makeglossaries} can be
+used to call \gls{makeindex} or \gls{xindy}, using a customised
+indexing style file, for each of the glossaries that are defined in
+the document. \textbf{Note that there should be no need for you to
+explicitly edit or input any of these external
+files.}\footnote{Except possibly the style file but then you'll need
+to use \ics{noist} to prevent your changes from being
+overwritten.} See
+\sectionref{sec:makeglossaries} for further details.
+
+New glossary entries are defined using the command:
+\begin{definition}[\DescribeMacro{\newglossaryentry}]
+\cs{newglossaryentry}\marg{label}\marg{key-val list}
+\end{definition}
+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{description} and either \gloskey{name} or \gloskey{parent}.
+Available fields are listed below:
+
+\begin{description}
+\item[{\gloskey{name}}] The name of the entry (as it will appear in 
+the glossary). If this key is omitted and the \gloskey{parent}
+key is supplied, this value will be the same as the parent's name.
+
+\item[{\gloskey{description}}] A brief description of this term (to
+appear in the glossary). Within this value, you can use 
+\begin{definition}[\DescribeMacro{\nopostdesc}]
+\cs{nopostdesc}
+\end{definition}
+to suppress the
+description terminator for this entry. For example, if this
+entry is a parent entry that doesn't require a description, you
+can do \verb|description={\nopostdesc}|. If you want a paragraph
+break in the description use
+\begin{definition}[\DescribeMacro{\glspar}]
+\cs{glspar}
+\end{definition}
+However, note that not all glossary styles support multi-line
+descriptions. If you are using one of the tabular-like glossary
+styles that permit multi-line descriptions, use \ics{newline}
+not \verb"\\" if you want to force a line break.
+
+\item[{\gloskey{parent}}] The label of the parent entry. Note that
+the parent entry must be defined before its sub-entries.
+See \sectionref{sec:subentries} for further details.
+
+\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. (Note that if
+you want the description to appear in the main body of the document,
+you must switch off the description \glsation{sanitize} using the
+\pkgopt{sanitize} package option described in
+\sectionref{sec:pkgopts-general}.)
+
+\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
+on \firstuse\ with \ics{gls} (or one of its uppercase
+variants). If this field is omitted, the value of the \gloskey{text}
+key is used. Note that if you use \ics{glspl}, \ics{Glspl},
+\ics{GLSpl}, \ics{glsdisp} before using \ics{gls}, the
+\gloskey{firstplural} value won't be used with \ics{gls}.
+
+\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.  The
+default value of \ics{glspluralsuffix} is the letter \qt{s}.
+
+\item[{\gloskey{firstplural}}] How the entry will appear in the
+document text on \firstuse\ 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. Note
+that if you use \ics{gls}, \ics{Gls}, \ics{GLS}, \cs{glsdisp} before
+using \ics{glspl}, the \gloskey{firstplural} value won't be used
+with \ics{glspl}.
+
+\textbf{Note:} prior to version 1.13, the default value of 
+\gloskey{firstplural} was always taken by appending \qt{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. If omitted, the value is set to
+\cs{relax}. Note that not all glossary styles display the symbol.
+(If you want the symbol to appear in the main body of the document,
+you must switch off the symbol \glsation{sanitize} using the
+\pkgopt{sanitize} package option described in
+\sectionref{sec:pkgopts-general}.)
+
+\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 \gls{makeindex} or
+\gls{xindy} should sort this entry. If omitted, the value is given
+by the \gloskey{name} field. In general, it's best to use the
+\gloskey{sort} key if the \gloskey{name} contains commands (e.g.\
+\verb|\ensuremath{\alpha}|). Note that the package options
+\pkgopt[def]{sort} and \pkgopt[use]{sort} override the
+\gloskey{sort} key in \ics{newglossaryentry} (see
+\sectionref{sec:pkgopts-sort}).
+
+\item[{\gloskey{type}}] This specifies the label of the glossary in 
+which this entry belongs. If omitted, the default glossary is 
+assumed unless \ics{newacronym} is used (see
+\sectionref{sec:acronyms}).
+
+\item[{\gloskey{user1}, \ldots, \gloskey{user6}%
+\igloskey{user2}\igloskey{user3}\igloskey{user4}\igloskey{user5}}]
+Six keys provided for any additional information the user may want
+to specify.  (For example an associated dimension or an alternative
+plural or some other grammatical construct.)
+
+\item[{\gloskey{nonumberlist}}] A boolean key. If the value is
+missing or is "true", this will suppress the \gls{numberlist} just for
+this entry. Conversely, if you have used the package option
+\pkgopt{nonumberlist}, you can activate the \gls*{numberlist} just
+for this entry with \gloskey{nonumberlist=false}.
+(See \sectionref{sec:numberlists}.)
+
+\item[{\gloskey{see}}] Cross-reference another entry. Using the
+\gloskey{see} key will automatically add this entry to the
+glossary, but will not automatically add the cross-referenced entry.
+The referenced entry should be supplied as the value to this key.
+If you want to override the \qt{see} tag, you can supply the new
+tag in square brackets before the label. For example
+\verb|see=[see also]{anotherlabel}|. Note that if you have
+suppressed the \gls{numberlist}, the cross-referencing information
+won't appear in the glossary. You can override this for individual
+glossary entries using \gloskey{nonumberlist=false} (see above).
+Alternatively, you can use the \pkgopt{seeautonumberlist} package
+option.  For further details, see \sectionref{sec:crossref}.
+
+\end{description}
+
+The following keys are reserved for \ics{newacronym} (see
+\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural},
+\gloskey{short} and \gloskey{shortplural}.
+
+Note that if the name starts with an accented letter or non-Roman
+character, you must group the character, otherwise it will 
+cause a problem for commands like \ics{Gls} and \ics{Glspl}. 
+For example:
+\begin{verbatim}
+\newglossaryentry{elite}{name={{\'e}lite},
+description={select group or class}}
+\end{verbatim}
+Note that the same applies if you are using the \sty{inputenc}
+package:
+\begin{verbatim}
+\newglossaryentry{elite}{name={{é}lite},
+description={select group or class}}
+\end{verbatim}
+Note that in both of the above examples, you will also need to
+supply the \gloskey{sort} key if you are using \gls{makeindex}
+whereas \gls{xindy} is usually able to sort accented letters
+correctly.
+
+\subsection{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 by appending 
+\begin{definition}[\DescribeMacro{\glspluralsuffix}]
+\cs{glspluralsuffix}
+\end{definition}
+to the singular form. This command defaults to the letter \qt{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 \qt{cow} and plural form
+is \qt{cows}. However, if you are writing in archaic English, you
+may want to use \qt{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 and one of the user keys to specify the
+other plural form. For example:
+\begin{verbatim}
+\newglossaryentry{cow}{name=cow,description={a fully grown
+female of any bovine animal (plural cows, archaic plural kine)},
+user1={kine}}
+\end{verbatim}
+You can then use \verb|\glspl{cow}| to produce \qt{cows} and 
+\verb|\glsuseri{cow}| to produce \qt{kine}. You can, of course,
+define an easy to remember synonym. For example:
+\begin{verbatim}
+\let\glsaltpl\glsuseri
+\end{verbatim}
+Then you don't have to remember which key you used to store the
+alternative plural.
+
+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). 
+
+\subsection{Sub-Entries}
+\label{sec:subentries}
+
+As from version 1.17, it is possible to specify sub-entries. These
+may be used to order the glossary into categories, in which case the
+sub-entry will have a different name to its parent entry, or it may
+be used to distinguish different definitions for the same word, in
+which case the sub-entries will have the same name as the parent
+entry. Note that not all glossary styles support hierarchical
+entries and may display all the entries in a flat format. Of the
+styles that support sub-entries, some display the sub-entry's name
+whilst others don't. Therefore you need to ensure that you use a
+suitable style. (See \sectionref{sec:styles} for a list of predefined
+styles.) As from version 3.0, level~1 sub-entries are automatically
+numbered in the predefined styles if you use the
+\pkgopt{subentrycounter} package option (see
+\sectionref{sec:pkgopts-printglos} for further details).
+
+Note that the parent entry will automatically be added to the
+glossary if any of its child entries are used in the document.
+If the parent entry is not referenced in the document, it will not
+have a \gls{numberlist}. Note also that \gls{makeindex} has a
+restriction on the maximum sub-entry depth.
+
+\subsubsection{Hierarchical Categories}
+
+To arrange a glossary with hierarchical categories, you need to
+first define the category and then define the sub-entries using the
+relevant category entry as the value of the \gloskey{parent} key.
+For example, suppose I want a glossary of mathematical symbols that
+are divided into Greek letters and Roman letters. Then I can define
+the categories as follows:
+\begin{verbatim}
+\newglossaryentry{greekletter}{name={Greek letters},
+description={\nopostdesc}}
+
+\newglossaryentry{romanletter}{name={Roman letters},
+description={\nopostdesc}}
+\end{verbatim}
+
+Note that in this example, the category entries don't need a
+description so I have set the descriptions to \ics{nopostdesc}.
+This gives a blank description and suppresses the
+description terminator.
+
+I can now define my sub-entries as follows:
+\begin{verbatim}
+\newglossaryentry{pi}{name={\ensuremath{\pi}},sort={pi},
+description={ratio of the circumference of a circle to the diameter},
+parent=greekletter}
+
+\newglossaryentry{C}{name={\ensuremath{C}},sort={C},
+description={Euler's constant},
+parent=romanletter}
+\end{verbatim}
+
+
+\subsubsection{Homographs}
+
+Sub-entries that have the same name as the parent entry, don't need
+to have the \gloskey{name} key. For example, the word \qt{glossary}
+can mean a list of technical words or a collection of glosses. In
+both cases the plural is \qt{glossaries}. So first define the parent
+entry:
+\begin{verbatim}
+\newglossaryentry{glossary}{name=glossary,
+description={\nopostdesc},
+plural={glossaries}}
+\end{verbatim}
+Again, the parent entry has no description, so the description
+terminator needs to be suppressed using \ics{nopostdesc}.
+
+Now define the two different meanings of the word:
+\begin{verbatim}
+\newglossaryentry{glossarylist}{
+description={list of technical words},
+sort={1},
+parent={glossary}}
+
+\newglossaryentry{glossarycol}{
+description={collection of glosses},
+sort={2},
+parent={glossary}}
+\end{verbatim}
+Note that if I reference the parent entry, the location will be
+added to the parent's \gls{numberlist}, whereas if I reference any
+of the child entries, the location will be added to the child
+entry's number list. Note also that since the sub-entries have the
+same name, the \gloskey{sort} key is required unless you are using
+the \pkgopt[use]{sort} or \pkgopt[def]{sort} package options. You
+can use the \pkgopt{subentrycounter} package option to automatically
+number the first-level child entries. See
+\sectionref{sec:pkgopts-printglos} for further details.
+
+In the above example, the plural form for both of the child entries
+is the same as the parent entry, so the \gloskey{plural} key was
+not required for the child entries. However, if the sub-entries
+have different plurals, they will need to be specified. For example:
+\begin{verbatim}
+\newglossaryentry{bravo}{name={bravo},
+description={\nopostdesc}}
+
+\newglossaryentry{bravocry}{description={cry of approval (pl.\ bravos)},
+sort={1},
+plural={bravos},
+parent=bravo}
+
+\newglossaryentry{bravoruffian}{description={hired ruffian or
+killer (pl.\ bravoes)},
+sort={2},
+plural={bravoes},
+parent=bravo}
+\end{verbatim}
+
+
+\subsection{Loading Entries From a File}
+\label{sec:loadglsentries}
+
+You can store all your glossary entry definitions in another
+file and use:
+\begin{definition}[\DescribeMacro{\loadglsentries}]
+\cs{loadglsentries}\oarg{type}\marg{filename}
+\end{definition}
+where \meta{filename} is the name of the file containing all the
+\ics{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 \ics{glsdefaulttype}, which is what
+\ics{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 \ics{newacronym} (see
+\sectionref{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.\footnote{This is
+because \ics{acronymtype} is set to \ics{glsdefaulttype} if the
+\pkgopt{acronym} package option is not used.}
+
+If you have used the \pkgopt{acronym} package option,
+there are two possible solutions to this problem:
+\begin{enumerate}
+\item Change \texttt{myacronyms.tex} so that entries are defined in
+the form:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype]{aca}{aca}{a contrived acronym}
+\end{verbatim}
+and do:
+\begin{verbatim}
+\loadglsentries[altacronym]{myacronyms}
+\end{verbatim}
+
+\item Temporarily change \cs{acronymtype} to the target glossary:
+\begin{verbatim}
+\let\orgacronymtype\acronymtype
+\def\acronymtype{altacronym}
+\loadglsentries{myacronyms}
+\let\acronymtype\orgacronymtype
+\end{verbatim}
+\end{enumerate}
+
+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.
+
+\section{Number lists}
+\label{sec:numberlists}
+
+Each entry in the glossary has an associated \gls{numberlist}.
+By default, these numbers refer to the pages on which that entry has
+been used (using any of the commands described in
+\sectionref{sec:glslink} and \sectionref{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. The number list is also
+referred to as the location list\index{location list|see{number
+list}}.
+
+Both \gls{makeindex} and \gls{xindy} concatenate a
+sequence of 3 or more consecutive pages into a range. With 
+\gls*{xindy} you can vary the minimum sequence length using
+\ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either
+an integer or the keyword \texttt{none} which indicates that there
+should be no range formation.
+
+\begin{important}
+Note that \cs{GlsSetXdyMinRangeLength} must be used before
+\ics{makeglossaries} and has no effect if \ics{noist} is used.
+\end{important}
+
+With both \gls{makeindex} and \gls{xindy}, you can replace
+the separator and the closing number in the range using:
+\begin{definition}[\DescribeMacro{\glsSetSuffixF}]
+\cs{glsSetSuffixF}\marg{suffix}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsSetSuffixFF}]
+\cs{glsSetSuffixFF}\marg{suffix}
+\end{definition}
+where the former command specifies the suffix to use for a 2 page
+list and the latter specifies the suffix to use for longer lists.
+For example:
+\begin{verbatim}
+\glsSetSuffixF{f.}
+\glsSetSuffixFF{ff.}
+\end{verbatim}
+Note that if you use \gls{xindy}, you will also need to
+set the minimum range length to 1 if you want to change these
+suffixes:
+\begin{verbatim}
+\GlsSetXdyMinRangeLength{1}
+\end{verbatim}
+Note that if you use the \sty{hyperref} package, you will need
+to use \ics{nohyperpage} in the suffix to ensure that the hyperlinks
+work correctly. For example:
+\begin{verbatim}
+\glsSetSuffixF{\nohyperpage{f.}}
+\glsSetSuffixFF{\nohyperpage{ff.}}
+\end{verbatim}
+
+\begin{important}
+Note that \cs{glsSetSuffixF} and \cs{glsSetSuffixFF} must be used 
+before \ics{makeglossaries} and have no effect if \ics{noist} is 
+used.
+\end{important}
+
+
+\section{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 \gls{linktext} (even if there are no hyperlinks). The
+commands in this section also add a line to an external file that is
+used by \gls{makeindex} or \gls{xindy} to generate the relevant
+entry in the glossary. This information includes an associated
+location that is added to the \gls{numberlist} for that entry. By
+default, the location refers to the page number. For further
+information on number lists, see \sectionref{sec:numberlists}.
+
+\begin{important}
+It is strongly recommended that you don't use the commands
+defined in this section in the arguments of sectioning or caption
+commands or any other command that has a moving argument.
+\end{important}
+
+The above warning is particularly important if you are using the
+\styfmt{glossaries} package in conjunction with the \sty{hyperref}
+package. Instead, use one of the commands listed in
+\sectionref{sec:glsnolink} (such as \ics{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 \gls{linktext} is displayed depends on 
+\begin{definition}[\DescribeMacro{\glstextformat}]
+\cs{glstextformat}\marg{text}
+\end{definition}
+For example, to make all \gls{linktext} appear in a sans-serif
+font, do:
+\begin{verbatim}
+\renewcommand*{\glstextformat}[1]{\textsf{#1}}
+\end{verbatim}
+
+Each entry has an associated conditional referred to as the
+\firstuseflag. This determines whether \ics{gls}, 
+\ics{glspl} (and their uppercase variants) should use the
+value of the \gloskey{first} or \gloskey{text} keys. Note that an 
+entry can be used without affecting the \firstuseflag\ (for example,
+when used with \cs{glslink}). See \sectionref{sec:glsunset} for 
+commands that unset or reset this conditional.
+
+The command:
+\begin{definition}[\DescribeMacro{\glslink}]
+\cs{glslink}\oarg{options}\marg{label}\marg{text}
+\end{definition}
+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. (Note that this command doesn't affect the \firstuseflag:
+use \ics{glsdisp} instead.) 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 location number for this entry in the glossary. This 
+value is equivalent to the \gls{makeindex} encap value, and (as
+with \ics{index}) the value needs to be the name of a command
+\emph{without} the initial backslash. As with \ics{index}, the
+characters \verb"(" and \verb")" can also be used to specify the
+beginning and ending of a number range.  Again as with \ics{index},
+the command should be the name of a command which takes an argument
+(which will be the associated location).  Be careful not to use a
+declaration (such as \texttt{bfseries}) instead of a text block command
+(such as \texttt{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.
+
+In this document, the standard formats refer to the standard text 
+block commands such as \ics{textbf} or \ics{emph} or any of the 
+commands listed in \tableref{tab:hyperxx}.
+
+\begin{important}
+If you use \gls{xindy} instead of \gls{makeindex}, you
+must specify any non-standard formats that you want to use
+with the \gloskey[glslink]{format} key using
+\ics{GlsAddXdyAttribute}\marg{name}. So if you use
+\gls*{xindy} with the above example, you would need to add:
+\begin{verbatim}
+\GlsAddXdyAttribute{textbfem}
+\end{verbatim}
+See \sectionref{sec:xindy} for further details.
+\end{important}
+
+Note that unlike \ics{index}, you can't have anything following the
+command name, such as an asterisk or arguments. If you want to
+cross-reference another entry, either use the \gloskey{see} key when
+you define the entry or use \ics{glssee} (described in
+\sectionref{sec:crossref}).
+
+
+If you are using hyperlinks and you want to change the font of the
+hyperlinked location, don't use \ics{hyperpage} (provided by the
+\sty{hyperref} package) as the locations may not refer to a page
+number.  Instead, the \styfmt{glossaries} package provides number
+formats listed in \tableref{tab:hyperxx}.
+
+\begin{table}[htbp]
+\caption{Predefined Hyperlinked Location Formats}
+\label{tab:hyperxx}
+\centering
+\vskip\baselineskip
+\begin{tabular}{ll}
+\locfmt{hyperrm} & serif hyperlink\\
+\locfmt{hypersf} & sans-serif hyperlink\\
+\locfmt{hypertt} & monospaced hyperlink\\
+\locfmt{hyperbf} & bold hyperlink\\
+\locfmt{hypermd} & medium weight hyperlink\\
+\locfmt{hyperit} & italic hyperlink\\
+\locfmt{hypersl} & slanted hyperlink\\
+\locfmt{hyperup} & upright hyperlink\\
+\locfmt{hypersc} & small caps hyperlink\\
+\locfmt{hyperemph} & emphasized hyperlink
+\end{tabular}
+\par
+\end{table}
+
+Note that if the \ics{hyperlink} command hasn't been defined, the
+\texttt{hyper}\meta{xx} formats are equivalent to the analogous
+\texttt{text}\meta{xx} font commands (and \texttt{hyperemph} is
+equivalent to \texttt{emph}). 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 location number to be in a bold
+sans-serif font, you can define a command called, say,
+\ics{hyperbsf}:
+\begin{verbatim}
+\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
+\end{verbatim}
+and then use \texttt{hyperbsf} as the value for the \gloskey{format}
+key. (See also \ifpdf section~\ref*{sec:code:printglos} \fi
+\qt{Displaying the glossary} in the documented code,
+\texttt{glossaries.pdf}.) Remember that if you use \gls{xindy}, you
+will need to add this to the list of location attributes:
+\begin{verbatim}
+\GlsAddXdyAttribute{hyperbsf}
+\end{verbatim}
+
+\item[{\gloskey[glslink]{counter}}] This specifies which counter
+to use for this location. This overrides the default counter
+used by this entry. (See also \sectionref{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 \ics{hyperlink} has not been defined.) The default
+value is \texttt{hyper=true}.
+
+\end{description}
+There is also a starred version:
+\begin{definition}[\DescribeMacro{\glslink*}]
+\cs{glslink*}\oarg{options}\marg{label}\marg{text}
+\end{definition}
+which is equivalent to \cs{glslink}, except it sets
+\texttt{hyper=false}. Similarly, all the following commands 
+described in this section also have a starred version that disables
+the hyperlink.
+
+\begin{important}
+Don't use commands like \cs{glslink} or \cs{gls} in the \meta{text} 
+argument of \cs{glslink}.
+\end{important}
+
+The command:
+\begin{definition}[\DescribeMacro{\gls}]
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+is the same as \cs{glslink}, except that the \gls{linktext}
+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\ifirstuseflag, 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's \gls{firstuseflag} as
+used.
+
+There are two uppercase variants:
+\begin{definition}[\DescribeMacro{\Gls}]
+\cs{Gls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\GLS}]
+\cs{GLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+which make the first letter of the link text 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 \sectionref{sec:glsdisplay}). 
+
+The first optional argument \meta{options} is the same as the optional
+argument to \ics{glslink}. As with \ics{glslink}, these commands also
+have a starred version that disable the hyperlink.
+
+\begin{important}
+Don't use commands like \cs{glslink} or \cs{gls} in the \meta{insert} 
+argument of \cs{gls} and its variants.
+\end{important}
+
+There are also analogous plural forms:
+\begin{definition}[\DescribeMacro{\glspl}]
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glspl}]
+\cs{Glspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSpl}]
+\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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.
+
+\begin{important}
+Be careful when you use glossary entries in math mode especially if you 
+are using \sty{hyperref} as it can affect the spacing of subscripts and
+superscripts. For example, suppose you have defined the following
+entry:
+\begin{verbatim}
+\newglossaryentry{Falpha}{name={F_\alpha},description=sample}
+\end{verbatim}
+and later you use it in math mode:
+\begin{verbatim}
+$\gls{Falpha}^2$
+\end{verbatim}
+This will result in $F_\alpha{}^2$ instead of $F_\alpha^2$. In this
+situation it's best to bring the superscript into the hyperlink using
+the final \meta{insert} optional argument:
+\begin{verbatim}
+$\gls{Falpha}[^2]$
+\end{verbatim}
+\end{important}
+
+Note that \ics{glslink} doesn't use or affect the \firstuseflag,
+nor does it use \ics{glsdisplay} or \ics{glsdisplayfirst} (see 
+\sectionref{sec:glsdisplay}). Instead, you can use:
+\begin{definition}[\DescribeMacro{\glsdisp}]
+\cs{glsdisp}\oarg{options}\marg{label}\marg{link text}
+\end{definition}
+This behaves in the same way as \ics{gls}, except that it uses
+\meta{link text} instead of the value of the \gloskey{first}
+or \gloskey{text} key. (Note that this command always sets
+\meta{insert} to nothing.) This command affects the \firstuseflag,
+and uses \ics{glsdisplay} or \ics{glsdisplayfirst}.
+
+The command:
+\begin{definition}[\DescribeMacro{\glstext}]
+\cs{glstext}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+is similar to \ics{gls} except that it always uses the value
+of the \gloskey{text} key and does not affect the 
+\firstuseflag. 
+Unlike \cs{gls}, the inserted text \meta{insert} 
+is always appended to the link text since \cs{glstext} doesn't
+use \ics{glsdisplay} or \ics{glsdisplayfirst}. (The same is 
+true for all the following commands described in this section.)
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glstext}]
+\cs{Glstext}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLStext}]
+\cs{GLStext}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsfirst}]
+\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+is similar to \cs{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 affect the 
+\firstuseflag.
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glsfirst}]
+\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSfirst}]
+\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsplural}]
+\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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:
+\begin{definition}[\DescribeMacro{\Glsplural}]
+\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSplural}]
+\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsfirstplural}]
+\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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:
+\begin{definition}[\DescribeMacro{\Glsfirstplural}]
+\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSfirstplural}]
+\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsname}]
+\cs{glsname}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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
+\glsation{sanitize} of the \gloskey{name} key and
+protect fragile commands.
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glsname}]
+\cs{Glsname}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSname}]
+\cs{GLSname}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glssymbol}]
+\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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
+\glsation{sanitize} of the \gloskey{symbol} key and
+protect fragile commands.
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glssymbol}]
+\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSsymbol}]
+\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsdesc}]
+\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+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 \glsation{sanitize} of the
+\gloskey{description} key and protect fragile commands.
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glsdesc}]
+\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSdesc}]
+\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink.
+
+The command:
+\begin{definition}[\DescribeMacro{\glsuseri}]
+\cs{glsuseri}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+is similar to \ics{glstext} except that it always uses the value
+of the \gloskey{user1} 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:
+\begin{definition}[\DescribeMacro{\Glsuseri}]
+\cs{Glsuseri}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseri}]
+\cs{GLSuseri}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+As before, these commands also have a starred version that disable
+the hyperlink. Similarly for the other user keys:
+\begin{definition}[\DescribeMacro{\glsuserii}]
+\cs{glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsuserii}]
+\cs{Glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuserii}]
+\cs{GLSuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsuseriii}]
+\cs{glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsuseriii}]
+\cs{Glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseriii}]
+\cs{GLSuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsuseriv}]
+\cs{glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsuseriv}]
+\cs{Glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseriv}]
+\cs{GLSuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsuserv}]
+\cs{glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsuserv}]
+\cs{Glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuserv}]
+\cs{GLSuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsuservi}]
+\cs{glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsuservi}]
+\cs{Glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuservi}]
+\cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+
+\subsection{Changing the format of the link text}
+\label{sec:glsdisplay}
+
+The format of the \gls{linktext} for \ics{gls}, \ics{glspl}
+and their uppercase variants is governed by two commands:
+\begin{definition}[\DescribeMacro{\glsdisplayfirst}]
+\cs{glsdisplayfirst}\marg{first/first plural}\marg{description}\marg{symbol}\marg{insert}
+\end{definition}
+which is used the
+\glslink{firstuse}{first time} a glossary entry is used in the text and
+\begin{definition}[\DescribeMacro{\glsdisplay}]
+\cs{glsdisplay}\marg{text/plural}\marg{description}\marg{symbol}\marg{insert}
+\end{definition}
+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 (set when the term was
+defined) depending on context; the second argument is the term's
+description (as supplied by the \gloskey{description} or
+\gloskey{descriptionplural} keys); the third
+argument is the symbol associated with the term (as supplied by the
+\gloskey{symbol} or \gloskey{symbolplural} keys) and the fourth argument is the additional text
+supplied in the final optional argument to \ics{gls} or
+\ics{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.
+
+\begin{important}
+Care needs to be taken when redefining \cs{glsdisplay} and
+\cs{glsdisplayfirst} as commands like \ics{Gls} will expand the
+displayed text before applying \ics{makefirstuc}. If you want to use
+formatting commands, it's best to define a robust version that deals
+with all the formatting. For example, suppose you want
+the text to appear in bold italic, it's best to do something like:
+\begin{verbatim}
+\DeclareRobustCommand{\textbfit}[1]{\emph{\bfseries #1}}
+\renewcommand{\glsdisplay}[4]{\textbfit{#1#4}}
+\end{verbatim}
+See the \sty{mfirstuc} documentation for further details on the
+limitations of \ics{makefirstuc}.
+\end{important}
+
+If required, you can access the label for the given entry via
+\begin{definition}[\DescribeMacro{\glslabel}]
+\cs{glslabel}
+\end{definition}
+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
+\sectionref{sec:glsnolink}, if required.
+
+Note that \cs{glsdisplay} and \cs{glsdisplayfirst} are not used
+by \ics{glslink}. If you want to supply your own link text, you
+need to use \ics{glsdisp} instead.
+
+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
+\qt{distance (km)} on \firstuse, 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 \qt{distance's (km)}
+rather than \qt{distance (km)'s} which looks a bit odd (even though
+it may be in the context of \qt{the distance (km) is measured between
+the two points} --- but in this instance it would be better not to
+use a contraction).
+
+Note also that all of the \gls{linktext} 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 \qt{\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 the commands \ics{gls}, \ics{glspl}, their
+uppercase variants and \ics{glsdisp}.  If you only
+want the change to affect entries for a given glossary, then you need
+to use
+\begin{definition}[\DescribeMacro{\defglsdisplay}]
+\cs{defglsdisplay}\oarg{type}\marg{definition}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\defglsdisplayfirst}]
+\cs{defglsdisplayfirst}\oarg{type}\marg{definition}
+\end{definition}
+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}, their uppercase variants and \cs{glsdisp}. 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 \firstuse\ 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 \glslink{firstuse}{first time} you reference this entry it will be displayed as:
+\qt{set (denoted $S$)} (assuming \ics{gls} was used).
+
+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 \gls{linktext}, you will have to disable the
+\glsation{sanitize} of these keys and protect fragile
+commands.
+
+\subsection{Enabling and disabling hyperlinks to glossary entries}
+
+If you load the \sty{hyperref} or \sty{html} packages prior to
+loading the \styfmt{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:
+\begin{definition}[\DescribeMacro{\glsdisablehyper}]
+\cs{glsdisablehyper}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\glsenablehyper}]
+\cs{glsenablehyper}
+\end{definition}
+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 \sty{hyperref} package).
+
+You can disable just the \gls{firstuse} links using the package
+option \pkgopt[false]{hyperfirst}. Note that this option only
+affects commands that recognise the \firstuseflag, for example
+\ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}.
+
+
+\section{Adding an Entry to the Glossary Without Generating Text}
+\label{sec:glsadd}
+
+It is possible to add a line in the glossary file without
+generating any text at that point in the document using:
+\begin{definition}[\DescribeMacro{\glsadd}]
+\cs{glsadd}\oarg{options}\marg{label}
+\end{definition}
+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 \ics{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}
+
+To add all entries that have been defined, use:
+\begin{definition}[\DescribeMacro{\glsaddall}]
+\cs{glsaddall}\oarg{options}
+\end{definition}
+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 \ics{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}
+
+\begin{important}
+Note that \cs{glsadd} and \cs{glsaddall} add the current location to
+the number list. In the case of \cs{glsaddall}, all entries in the
+glossary will have the same location in the number list. If you want
+to use \cs{glsaddall}, it's best to suppress the number list with
+the \pkgopt{nonumberlist} package option. (See
+sections~\ref{sec:pkgopts-printglos} and~\ref{sec:numberlists}.)
+\end{important}
+
+The sample file \samplefile{-dual} makes use of \cs{glsadd} to
+allow for an entry that should appear both in the main glossary and
+in the list of acronyms. This example sets up the list of acronyms
+using the \pkgopt{acronym} package option:
+\begin{verbatim}
+\usepackage[acronym]{glossaries}
+\end{verbatim}
+A new command is then defined to make it easier to define dual
+entries:
+\begin{verbatim}
+\newcommand*{\newdualentry}[5][]{%
+  \newglossaryentry{main-#2}{name={#4},%
+  text={#3\protect\glsadd{#2}},%
+  description={#5},%
+  #1
+  }%
+  \newacronym{#2}{#3\protect\glsadd{main-#2}}{#4}
+}
+\end{verbatim}
+This has the following syntax:
+\begin{definition}
+\ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description}
+\end{definition}
+You can then define a new dual entry:
+\begin{verbatim}
+\newdualentry{svm}% label
+  {SVM}% abbreviation
+  {support vector machine}% long form
+  {Statistical pattern recognition technique}% description
+\end{verbatim}
+Now you can reference the acronym with \verb|\gls{svm}| or you can
+reference the entry in the main glossary with \verb|\gls{main-svm}|.
+
+\section{Cross-Referencing Entries}
+\label{sec:crossref}
+
+There are several ways of cross-referencing entries in the 
+glossary: 
+
+\begin{enumerate}
+\item You can use commands such as \ics{gls} in the
+entries description. For example:
+\begin{verbatim}
+\newglossaryentry{apple}{name=apple,
+description={firm, round fruit. See also \gls{pear}}}
+\end{verbatim}
+Note that with this method, if you don't use the cross-referenced term 
+in the main part of the document, you will need two runs of
+\gls{makeglossaries}:
+\begin{verbatim}
+latex filename
+makeglossaries filename
+latex filename
+makeglossaries filename
+latex filename
+\end{verbatim}
+
+\begin{important}
+If you switch off the description
+\glsation{sanitize}, you must protect fragile
+commands like \ics{gls}:
+\begin{verbatim}
+\newglossaryentry{apple}{name=apple,
+description={firm, round fruit. See also 
+\protect\gls{pear}}}
+\end{verbatim}
+\end{important}
+
+\item As described in \sectionref{sec:newglosentry}, you can use the
+\gloskey{see} key when you define the entry. For example:
+\begin{verbatim}
+\newglossaryentry{MaclaurinSeries}{name={Maclaurin series},
+description={Series expansion},
+see={TaylorsTheorem}}
+\end{verbatim}
+Note that in this case, the entry with the \gloskey{see} key will
+automatically be added to the glossary, but the cross-referenced
+entry won't. You therefore need to ensure that you use the
+cross-referenced term with the commands described in
+\sectionref{sec:glslink} or \sectionref{sec:glsadd}.
+
+The \qt{see} tag is produce using \ics{seename}, but can be
+overridden in specific instances using square brackets
+at the start of the \gloskey{see} value. For example:
+\begin{verbatim}
+\newglossaryentry{MaclaurinSeries}{name={Maclaurin series},
+description={Series expansion},
+see=[see also]{TaylorsTheorem}}
+\end{verbatim}
+
+\item After you have defined the entry, use
+\begin{definition}[\DescribeMacro{\glssee}]
+\cs{glssee}\oarg{tag}\marg{label}\marg{xr label list}
+\end{definition}
+where \meta{xr label list} is a comma-separated list of entry 
+labels to be cross-referenced, \meta{label} is the label of the
+entry doing the cross-referencing and \meta{tag} is the \qt{see} tag.
+(The default value of \meta{tag} is \ics{seename}.)
+For example:
+\begin{verbatim}
+\glssee[see also]{series}{FourierSeries,TaylorsTheorem}
+\end{verbatim}
+Note that this automatically adds the entry given by \meta{label} to
+the glossary but doesn't add the cross-referenced entries (specified
+by \meta{xr label list}) to the glossary.
+\end{enumerate}
+
+In both cases~2 and 3 above, the cross-referenced information
+appears in the \gls{numberlist}, whereas in case~1, the
+cross-referenced information appears in the description. (See the
+\samplefile{-crossref} example file that comes with this package.)
+This means that in cases~2 and~3, the cross-referencing information
+won't appear if you have suppressed the \gls*{numberlist}. In this
+case, you will need to activate the \gls*{numberlist} for the given
+entries using \gloskey{nonumberlist=false}. Alternatively, if you
+just use the \gloskey{see} key instead of \ics{glssee}, you can
+automatically activate the \gls*{numberlist} using the
+\pkgopt{seeautonumberlist} package option.
+
+\subsection{Customising Cross-reference Text}
+
+When you use either the \gloskey{see} key or the command
+\cs{glssee}, the cross-referencing information will be typeset in the 
+glossary according to:
+\begin{definition}[\DescribeMacro{\glsseeformat}]
+\cs{glsseeformat}\oarg{tag}\marg{label-list}\marg{location}
+\end{definition}
+The default definition of \cs{glsseeformat} is:
+\begin{display}
+\cs{emph}\marg{tag} \cs{glsseelist}\marg{label-list}
+\end{display}
+Note that the location is always ignored.\footnote{\gls{makeindex}
+will always assign a location number, even if it's not needed, so it
+needs to be discarded.} For example, if you want the tag to appear
+in bold, you can do:\footnote{If you redefine \cs{glsseeformat},
+keep the default value of the optional argument as \ics{seename} as
+both \gloskey{see} and \cs{glssee} explicitly write
+\texttt[\cs{seename}\texttt] in the output file if no optional
+argument is given.}
+\begin{verbatim}
+\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} \glsseelist{#2}}
+\end{verbatim}
+
+
+The list of labels is dealt with by \cs{glsseelist}, which iterates
+through the list and typesets each entry in the label. The entries
+are separated by
+\begin{definition}[\DescribeMacro{\glsseesep}]
+\cs{glsseesep}
+\end{definition}
+or (for the last pair)
+\begin{definition}[\DescribeMacro{\glsseelastsep}]
+\cs{glsseelastsep}
+\end{definition}
+These default to ",\space" and
+\cs{space}\ics{andname}\cs{space} respectively. The list entry text
+is displayed using:
+\begin{definition}[\DescribeMacro{\glsseeitemformat}]
+\cs{glsseeitemformat}\marg{label}
+\end{definition}
+This defaults to \ics{glsentrytext}\marg{label}.\footnote{In
+versions before 3.0, \cs{glsentryname} was used, but this can cause
+problems when the \gloskey{name} key is \glsd{sanitize}.} For example, to
+make the cross-referenced list use small caps:
+\begin{verbatim}
+\renewcommand{\glsseeitemformat}[1]{\textsc{\glsentrytext{#1}}}
+\end{verbatim}
+
+\begin{important}
+You can use \ics{glsseeformat} and \ics{glsseelist} in the main body
+of the text, but they won't automatically add the cross-referenced
+entries to the glossary. If you want them added with that location,
+you can do:
+\begin{verbatim}
+Some information (see also 
+\glsseelist{FourierSeries,TaylorsTheorem}%
+\glsadd{FourierSeries}\glsadd{TaylorsTheorem}).
+\end{verbatim}
+\end{important}
+
+\section{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
+\ics{glstextformat}, they don't have any optional arguments, they
+don't affect the \firstuseflag\ and, apart from \ics{glshyperlink},
+they don't produce hyperlinks.
+\begin{definition}[\DescribeMacro{\glsentryname}]
+\cs{glsentryname}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryname}]
+\cs{Glsentryname}\marg{label}
+\end{definition}
+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.
+\begin{definition}[\DescribeMacro{\glsentrytext}]
+\cs{glsentrytext}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrytext}]
+\cs{Glsentrytext}\marg{label}
+\end{definition}
+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.
+\begin{definition}[\DescribeMacro{\glsentryplural}]
+\cs{glsentryplural}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryplural}]
+\cs{Glsentryplural}\marg{label}
+\end{definition}
+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.
+\begin{definition}[\DescribeMacro{\glsentryfirst}]
+\cs{glsentryfirst}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryfirst}]
+\cs{Glsentryfirst}\marg{label}
+\end{definition}
+These commands display the \firstusetext\ for the glossary entry
+given by \meta{label}, as specified by the \gloskey{first} key.
+\cs{Glsentryfirst} makes the first letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentryfirstplural}]
+\cs{glsentryfirstplural}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryfirstplural}]
+\cs{Glsentryfirstplural}\marg{label}
+\end{definition}
+These commands display the plural form of the \firstusetext\ for the
+glossary entry given by \meta{label}, as specified by the
+\gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first
+letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentrydesc}]
+\cs{glsentrydesc}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrydesc}]
+\cs{Glsentrydesc}\marg{label}
+\end{definition}
+These commands display the description for the glossary entry given
+by \meta{label}. \cs{Glsentrydesc} makes the first letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentrydescplural}]
+\cs{glsentrydescplural}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrydescplural}]
+\cs{Glsentrydescplural}\marg{label}
+\end{definition}
+These commands display the plural description for the glossary entry
+given by \meta{label}. \cs{Glsentrydescplural} makes the first
+letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentrysymbol}]
+\cs{glsentrysymbol}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrysymbol}]
+\cs{Glsentrysymbol}\marg{label}
+\end{definition}
+These commands display the symbol for the glossary entry given by
+\meta{label}. \cs{Glsentrysymbol} makes the first letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentrysymbolplural}]
+\cs{glsentrysymbolplural}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrysymbolplural}]
+\cs{Glsentrysymbolplural}\marg{label}
+\end{definition}
+These commands display the plural symbol for the glossary entry
+given by \meta{label}. \cs{Glsentrysymbolplural} makes the first
+letter uppercase.
+\begin{definition}[\DescribeMacro{\glsentryuseri}]
+\cs{glsentryuseri}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuseri}]
+\cs{Glsentryuseri}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryuserii}]
+\cs{glsentryuserii}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuserii}]
+\cs{Glsentryuserii}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryuseriii}]
+\cs{glsentryuseriii}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuseriii}]
+\cs{Glsentryuseriii}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryuseriv}]
+\cs{glsentryuseriv}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuseriv}]
+\cs{Glsentryuseriv}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryuserv}]
+\cs{glsentryuserv}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuserv}]
+\cs{Glsentryuserv}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryuservi}]
+\cs{glsentryuservi}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryuservi}]
+\cs{Glsentryuservi}\marg{label}
+\end{definition}
+These commands display the value of the user keys for the glossary
+entry given by \meta{label}.
+\begin{definition}[\DescribeMacro{\glshyperlink}]
+\cs{glshyperlink}\oarg{link text}\marg{label}
+\end{definition}
+This command provides a hyperlink to the glossary entry given by
+\meta{label} \textbf{but does not add any information to the
+glossary file}. The link text is given by
+\ics{glsentrytext}\marg{label} by default\footnote{versions before
+3.0 used \ics{glsentryname} as the default, but this can cause
+problems when \gloskey{name} has been \glsd{sanitize}.}, but can be
+overridden using the optional argument.
+\begin{important}
+If you use \cs{glshyperlink}, you need to ensure that the relevant
+entry has been added to the glossary using any of the commands
+described in \sectionref{sec:glslink} or \sectionref{sec:glsadd}
+otherwise you will end up with an undefined link.
+\end{important}
+
+For further information see \ifpdf section~\ref*{sec:code:glsnolink}
+\fi \qt{Displaying entry details without adding information to the
+glossary} in the documented code (\texttt{glossaries.pdf}).
+
+\section{Displaying a glossary}
+\label{sec:printglossary}
+
+The command
+\begin{definition}[\DescribeMacro{\printglossaries}]
+\cs{printglossaries}
+\end{definition}
+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 \gls{makeglossaries} or have directly used
+\gls{makeindex} or \gls{xindy} (as described in
+\sectionref{sec:makeglossaries}). If the glossary 
+still does not appear after you re-\LaTeX\ your document, check the
+\gls*{makeindex}/\gls*{xindy} 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.
+
+An individual glossary can be displayed using:
+\begin{definition}[\DescribeMacro{\printglossary}]
+\cs{printglossary}\oarg{options}
+\end{definition}
+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). It may also be used for the page header,
+depending on the page style. If omitted, the value of 
+\gloskey[printglossary]{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 in \sectionref{sec:pkgopts-sec}.
+
+\item[{\gloskey[printglossary]{nonumberlist}}] This 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}
+
+By default, the glossary is started either by \ics{chapter*} or by
+\ics{section*}, depending on whether or not \ics{chapter} is defined.
+This can be overridden by the \pkgopt{section} package option or the
+\ics{setglossarysection} command. Numbered sectional units can be
+obtained using the \pkgopt{numberedsection} package option. Each
+glossary sets the page header via the command \ics{glossarymark}. If
+this mechanism is unsuitable for your chosen class file or page
+style package, you will need to redefine \ics{glossarymark}. Further
+information about these options and commands is given in
+\sectionref{sec:pkgopts-sec}.
+
+Information can be added to the start of the glossary (after the
+title and before the main body of the glossary) by redefining
+\begin{definition}[\DescribeMacro{\glossarypreamble}]
+\cs{glossarypreamble}
+\end{definition}
+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.)
+
+There is an analogous command called
+\begin{definition}[\DescribeMacro{\glossarypostamble}]
+\cs{glossarypostamble}
+\end{definition}
+which is placed at the end of each glossary.
+
+For example: suppose you are using the \glostyle{superheaderborder}
+style\footnote{you can't use the \glostyle{longheaderborder} style
+for this example as you can't use the \env{longtable} environment in
+two column mode.}, and you want the glossary to be in two columns,
+but after the glossary you want to switch back to one column mode,
+you could do:
+\begin{verbatim}
+\renewcommand*{\glossarysection}[2][]{%
+  \twocolumn[{\section*{#2}}]%
+  \setlength\glsdescwidth{0.6\linewidth}%
+  \glossarymark{\glossarytoctitle}%
+}
+
+\renewcommand*{\glossarypostamble}{\onecolumn}
+\end{verbatim}
+
+Within each glossary, each entry name is formatted according to
+\begin{definition}[\DescribeMacro{\glsnamefont}]
+\cs{glsnamefont}\marg{name}
+\end{definition}
+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-like glossary styles
+(defined in the \sty{glossary-list} style file) the name will appear
+in bold, since the name is placed in the optional argument of
+\cs{item}, whereas in the tabular styles (defined in the
+\sty{glossary-long} and \sty{glossary-super} style files) the name
+will appear in the normal font. The hierarchical glossary styles
+(defined in the \sty{glossary-tree} style file) also set the name in
+bold.
+
+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}
+
+
+\section{Xindy}
+\label{sec:xindy}
+
+If you want to use \gls{xindy} to sort the glossary, you
+must use the package option \pkgopt{xindy}:
+\begin{verbatim}
+\usepackage[xindy]{glossaries}
+\end{verbatim}
+This ensures that the glossary information is written in 
+\gls*{xindy} syntax.
+
+\sectionref{sec:makeglossaries} covers how to use the external
+indexing application. This section covers the commands provided
+by the \styfmt{glossaries} package that allow you to adjust the
+\gls{xindy} style file (\filetype{.xdy}) and parameters.
+
+To assist writing information to the \gls{xindy} style
+file, the \styfmt{glossaries} package provides the following
+commands:
+\begin{definition}[\DescribeMacro{\glsopenbrace}]
+\cs{glsopenbrace}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsclosebrace}]
+\cs{glsclosebrace}
+\end{definition}
+which produce an open and closing brace. (This is needed because
+\verb|\{| and \verb|\}| don't expand to a simple brace character
+when written to a file.)
+
+In addition, if you are using a package that makes the double
+quote character active (e.g. \sty{ngerman}) you can use:
+\begin{definition}[\DescribeMacro{\glsquote}]
+\cs{glsquote}\marg{text}
+\end{definition}
+which will produce \verb|"|\meta{text}\verb|"|. Alternatively,
+you can use \verb|\string"| to write the double-quote character. 
+This document assumes that the double quote character has not been
+made active, so the examples just use \verb|"| for clarity.
+
+If you want greater control over the \gls{xindy} style file than is
+available through the \LaTeX\ commands provided by the
+\styfmt{glossaries} package, you will need to edit the \gls*{xindy}
+style file. In which case, you must use \ics{noist} to prevent the
+style file from being overwritten by the \styfmt{glossaries}
+package. For additional information about \gls*{xindy}, read the
+\gls*{xindy} documentation.
+
+\subsection{Language and Encodings}
+When you use \gls{xindy}, you need to specify the language
+and encoding used (unless you have written your own custom
+\gls*{xindy} style file that defines the relevant alphabet
+and sort rules). If you use \gls{makeglossaries},
+this information is obtained from the document's auxiliary 
+(\filetype{.aux}) file.  The \styfmt{glossaries} package attempts to 
+find the root language, but in the event that it gets it wrong or if 
+\gls*{xindy} doesn't support that language, then you can
+specify the language using:
+\begin{definition}[\DescribeMacro{\GlsSetXdyLanguage}]
+\cs{GlsSetXdyLanguage}\oarg{glossary type}\marg{language}
+\end{definition}
+where \meta{language} is the name of the language. The
+optional argument can be used if you have multiple glossaries
+in different languages. If \meta{glossary type} is omitted, it
+will be applied to all glossaries, otherwise the language
+setting will only be applied to the glossary given by
+\meta{glossary type}.
+
+If the \sty{inputenc} package is used, the encoding will be
+obtained from the value of \ics{inputencodingname}. 
+Alternatively, you can specify the encoding using:
+\begin{definition}[\DescribeMacro{\GlsSetXdyCodePage}]
+\cs{GlsSetXdyCodePage}\marg{code}
+\end{definition}
+where \meta{code} is the name of the encoding. For example:
+\begin{verbatim}
+\GlsSetXdyCodePage{utf8}
+\end{verbatim}
+
+Note that you can also specify the language and encoding using
+the package option 
+\verb|xindy={language=|\meta{lang}\verb|,codepage=|\meta{code}\verb|}|.
+For example:
+\begin{verbatim}
+\usepackage[xindy={language=english,codepage=utf8}]{glossaries}
+\end{verbatim}
+
+If you write your own custom \gls{xindy} style file that 
+includes the language settings, you need to set the language
+to nothing:
+\begin{verbatim}
+\GlsSetXdyLanguage{}
+\end{verbatim}
+(and remember to use \ics{noist} to prevent the style file from
+being overwritten).
+
+\begin{important}
+The commands \cs{GlsSetXdyLanguage} and \cs{GlsSetXdyCodePage}
+have no effect if you don't use \gls{makeglossaries}. If
+you call \gls{xindy} without \gls*{makeglossaries} you
+need to remember to set the language and encoding using the
+\texttt{-L} and \texttt{-C} switches.
+\end{important}
+
+
+\subsection{Locations and Number lists}
+\label{sec:xindyloc}
+
+If you use \pkgopt{xindy}, the \styfmt{glossaries} package needs to
+know which counters you will be using in the \gls{numberlist} in order to correctly format the \gls{xindy} style
+file. Counters specified using the \pkgopt{counter} package option
+or the \meta{counter} option of \ics{newglossary} are
+automatically taken care of, but if you plan to use a different
+counter in the \gloskey[glslink]{counter} key for commands like 
+\ics{glslink}, then you need to identify these counters \emph{before} 
+\ics{makeglossaries} using:
+\begin{definition}[\DescribeMacro{\GlsAddXdyCounters}]
+\cs{GlsAddXdyCounters}\marg{counter list}
+\end{definition}
+where \meta{counter list} is a comma-separated list of counter names.
+
+The most likely attributes used in the \gloskey[glslink]{format} 
+key (\locfmt{textrm}, \locfmt{hyperrm} etc) are automatically added 
+to the \gls{xindy} style file, but if you want to use another 
+attribute, you need to add it using:
+\begin{definition}[\DescribeMacro{\GlsAddXdyAttribute}]
+\cs{GlsAddXdyAttribute}\marg{name}
+\end{definition}
+where \meta{name} is the name of the attribute, as used in
+the \gloskey[glslink]{format} key. For example, suppose I want a
+bold, italic, hyperlinked location. I first need to define a
+command that will do this:
+\begin{verbatim}
+\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
+\end{verbatim}
+but with \gls{xindy}, I also need to add this as an allowed
+attribute:
+\begin{verbatim}
+\GlsAddXdyAttribute{hyperbfit}
+\end{verbatim}
+
+\begin{important}
+Note that \cs{GlsAddXdyAttribute} has no effect if \ics{noist} is
+used or if \ics{makeglossaries} is omitted.
+\cs{GlsAddXdyAttribute} must be used before \ics{makeglossaries}.
+Additionally, \cs{GlsAddXdyCounters} must come before
+\cs{GlsAddXdyAttribute}.
+\end{important}
+
+If the location numbers don't get expanded to a simple Arabic or 
+Roman number or a letter from a, \ldots, z or A, \ldots, Z, then
+you need to add a location style in the appropriate format using
+\begin{definition}[\DescribeMacro{\GlsAddXdyLocation}]
+\cs{GlsAddXdyLocation}\oarg{prefix-location}\marg{name}\marg{definition}
+\end{definition}
+where \meta{name} is the name of the format and \meta{definition} is
+the \gls{xindy} definition. The optional argument \meta{prefix-location}
+is needed if \cs{theH}\meta{counter} either isn't defined or is
+different from \cs{the}\meta{counter}.
+
+\begin{important}
+Note that \cs{GlsAddXdyLocation} has no effect if \ics{noist} is
+used or if \ics{makeglossaries} is omitted.
+\cs{GlsAddXdyLocation} must be used before \ics{makeglossaries}.
+\end{important}
+
+For example, suppose I decide to use a somewhat eccentric numbering
+system for sections that redefines \cs{thesection} as follows:
+\begin{verbatim}
+\renewcommand*{\thesection}{[\thechapter]\arabic{section}}
+\end{verbatim}
+If I haven't done "counter=section" in the package
+option, I need to specify that the counter will be used as a
+location number:
+\begin{verbatim}
+\GlsAddXdyCounters{section}
+\end{verbatim}
+Next I need to add the location style (\cs{thechapter} is assumed to
+be the standard \verb"\arabic{chapter}"):
+\begin{verbatim}
+\GlsAddXdyLocation{section}{:sep "[" "arabic-numbers" :sep "]"
+  "arabic-numbers"
+}
+\end{verbatim}
+Note that if I have further decided to use the \sty{hyperref}
+package and want to redefine \cs{theHsection} as:
+\begin{verbatim}
+\renewcommand*{\theHsection}{\thepart.\thesection}
+\renewcommand*{\thepart}{\Roman{part}}
+\end{verbatim}
+then I need to modify the \cs{GlsAddXdyLocation} code above to:
+\begin{verbatim}
+\GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "[" 
+  "arabic-numbers" :sep "]" "arabic-numbers"
+}
+\end{verbatim}
+Since \ics{Roman} will result in an empty string if the counter is
+zero, it's a good idea to add an extra location to catch this:
+\begin{verbatim}
+\GlsAddXdyLocation{zero.section}{:sep "[" 
+  "arabic-numbers" :sep "]" "arabic-numbers"
+}
+\end{verbatim}
+The above example is illustrated in the accompanying sample file
+\samplefile{xdy2}.
+
+Another example: suppose you want the page numbers written as words
+rather than digits and you use the \sty{fmtcount} package to
+do this. You can redefine \ics{thepage} as follows:
+\begin{verbatim}
+\renewcommand*{\thepage}{\Numberstring{page}}
+\end{verbatim}
+This gets expanded to \verb|\protect \Numberstringnum |\marg{n}
+where \meta{n} is the Arabic page number. This means that you need to
+define a new location that has that form:
+\begin{verbatim}
+\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
+  \string\Numberstringnum\space\glsopenbrace"
+  "arabic-numbers" :sep "\glsclosebrace"}
+\end{verbatim}
+Note that it's necessary to use \cs{space} to indicate that 
+spaces also appear in the format, since, unlike \TeX,
+\gls{xindy} doesn't ignore spaces after control sequences.
+
+\cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define commands
+\begin{definition}
+\cs{glsX}\meta{counter}"X"\meta{name}\marg{Hprefix}\marg{location}
+\end{definition}
+for each counter that has been identified either by the
+\pkgopt{counter} package option, the \meta{counter} option for
+\ics{newglossary} or in the argument of \ics{GlsAddXdyCounters}.
+
+The first argument \meta{Hprefix} is only relevant when used with
+the \sty{hyperref} package and indicates that \cs{the}\meta{Hcounter}
+is given by \cs{Hprefix}"."\cs{the}\meta{counter}. The sample
+file \samplefile{xdy}, which comes with the \styfmt{glossaries}
+package, uses the default \ctr{page} counter for locations, and it
+uses the default \ics{glsnumberformat} and a custom \cs{hyperbfit}
+format. A new \gls{xindy} location called \texttt{Numberstring}, as
+illustrated above, is defined to make the page numbers appear as
+\qt{One}, \qt{Two}, etc. In order for the location numbers to
+hyperlink to the relevant pages, I need to redefine the necessary
+\cs{glsX}\meta{counter}"X"\meta{format} commands:
+\begin{verbatim}
+\renewcommand{\glsXpageXglsnumberformat}[2]{%
+ \linkpagenumber#2%
+}
+
+\renewcommand{\glsXpageXhyperbfit}[2]{%
+ \textbf{\em\linkpagenumber#2}%
+}
+
+\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
+\end{verbatim}
+
+In the \gls{numberlist}, the locations are sorted according to
+type. The default ordering is: \texttt{roman-page-numbers} (e.g.\
+i), \texttt{arabic-page-numbers} (e.g.\ 1),
+\texttt{arabic-section-numbers} (e.g.\ 1.1 if the compositor is a
+full stop or 1-1 if the compositor is a hyphen\footnote{see
+\ics{setCompositor} described in \sectionref{sec:setup}}),
+\texttt{alpha-page-numbers} (e.g.\ a), \texttt{Roman-page-numbers}
+(e.g.\ I), \texttt{Alpha-page-numbers} (e.g.\ A),
+\texttt{Appendix-page-numbers} (e.g.\ A.1 if the Alpha compositor is
+a full stop or A-1 if the Alpha compositor is a hyphen\footnote{see
+\ics{setAlphaCompositor} described in
+\sectionref{sec:setup}}), user defined location names (as
+specified by \ics{GlsAddXdyLocation} in the order in which they were
+defined), \texttt{see} (cross-referenced entries). This ordering can
+be changed using:
+
+\DescribeMacro{\GlsSetXdyLocationClassOrder}
+\begin{definition}
+\cs{GlsSetXdyLocationClassOrder}\marg{location names}
+\end{definition}
+where each location name is delimited by double quote marks and
+separated by white space. For example:
+\begin{verbatim}
+\GlsSetXdyLocationClassOrder{
+  "arabic-page-numbers"
+  "arabic-section-numbers"
+  "roman-page-numbers"
+  "Roman-page-numbers"
+  "alpha-page-numbers"
+  "Alpha-page-numbers"
+  "Appendix-page-numbers"
+  "see"
+}
+\end{verbatim}
+
+\begin{important}\raggedright
+Note that \cs{GlsSetXdyLocationClassOrder} has no effect if 
+\ics{noist} is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyLocationClassOrder} must be used before 
+\ics{makeglossaries}.
+\end{important}
+
+If a \gls{numberlist} consists of a sequence of consecutive 
+numbers, the range will be concatenated. The 
+number of consecutive locations that causes a range formation 
+defaults to 2, but can be changed using:
+\begin{definition}[\DescribeMacro{\GlsSetXdyMinRangeLength}]
+\cs{GlsSetXdyMinRangeLength}\marg{n}
+\end{definition}
+For example:
+\begin{verbatim}
+\GlsSetXdyMinRangeLength{3}
+\end{verbatim}
+The argument may also be the keyword \texttt{none}, to indicate that
+there should be no range formations. See the \gls{xindy}
+manual for further details on range formations.
+
+\begin{important}
+Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist}
+is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyMinRangeLength} must be used before 
+\ics{makeglossaries}.
+\end{important}
+
+See \sectionref{sec:numberlists} for further details.
+
+
+\subsection{Glossary Groups}
+
+The glossary is divided into groups according to the first
+letter of the sort key. The \styfmt{glossaries} package also adds
+a number group by default, unless you suppress it in the
+\pkgopt{xindy} package option. For example:
+\begin{verbatim}
+\usepackage[xindy={glsnumbers=false}]{glossaries}
+\end{verbatim}
+Any entry that doesn't go in one of the letter groups or the
+number group is placed in the default group.
+
+If you have a number group, the default behaviour is to locate
+it before the \qt{A} letter group. If you are not using a
+Roman alphabet, you can change this using:
+
+\DescribeMacro{\GlsSetXdyFirstLetterAfterDigits}
+\begin{definition}
+\cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter}
+\end{definition}
+
+\begin{important}\raggedright
+Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if 
+\ics{noist} is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyFirstLetterAfterDigits} must be used before 
+\ics{makeglossaries}.\par
+\end{important}
+
+
+\section{Defining New Glossaries}
+\label{sec:newglossary}
+
+A new glossary can be defined using:
+\begin{definition}[\DescribeMacro{\newglossary}]
+\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\oarg{counter}
+\end{definition}
+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 \glspl{numberlist} (see also
+\sectionref{sec:numberlists}). The first optional argument specifies
+the extension for the \gls{makeindex} or \gls{xindy} transcript file
+(this information is only used by \gls{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} (unless the
+\pkgopt{nomain} package option is used). 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}. Note that if you are using
+the main glossary as your list of acronyms, you need to declare
+it as a list of acronyms using the package option 
+\pkgopt{acronymlists}.
+
+\begin{important}
+All glossaries must be defined before \ics{makeglossaries} to 
+ensure that the relevant output files are opened.
+\end{important}
+
+
+\section{Acronyms}
+\label{sec:acronyms}
+
+You may have noticed in \sectionref{sec:newglosentry} that when you
+specify a new entry, you can specify alternate text to use when the
+term is \glsd{firstuse} in the document. This provides a
+useful means to define acronyms. For convenience, the
+\styfmt{glossaries} package defines the command:
+\begin{definition}[\DescribeMacro{\newacronym}]
+\cs{newacronym}\oarg{key-val
+list}\marg{label}\marg{abbrv}\marg{long}
+\end{definition}
+
+This uses \ics{newglossaryentry} to create an entry with the given
+label in the glossary given by \ics{acronymtype}. Amongst other
+things, it sets up the \gloskey{first} and \gloskey{text} keys and,
+depending on the acronym style, may also use \ics{defdisplayfirst}
+and \ics{defdisplay} (see \sectionref{sec:glsdisplay}). 
+
+The optional argument \marg{key-val list} allows you to specify keys
+such as \gloskey{description} (when used with the
+\pkgopt{description} package option, described below) or you can
+override plural forms of \meta{abbrv} or \meta{long} using the
+\gloskey{shortplural} or \gloskey{longplural} keys.
+For example:
+\begin{verbatim}
+\newacronym[longplural={diagonal matrices}]{dm}{DM}{diagonal 
+matrix}
+\end{verbatim}
+If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will
+display: diagonal matrices (DMs).
+
+
+The following package options are available to change the acronym
+style:
+
+\begin{description}
+\item[\pkgopt{description}]
+With this package option, the \gloskey{description} key needs to be
+set in the optional argument \meta{key-val list} of \cs{newacronym}.
+(If this package option isn't used, the long form \meta{long} is put
+in the \gloskey{description} key.)
+
+\item[\pkgopt{footnote}]
+With this package option, on \gls{firstuse} the long form \meta{long} is
+placed in a footnote. By default the long form in the footnote will
+link to the relevant entry in the glossary or list of acronyms. You
+can prevent this link by doing:
+\begin{verbatim}
+\let\acrfootnote\acrnolinkfootnote
+\end{verbatim}
+
+\item[\pkgopt{smallcaps}]
+With this package option, the short form \meta{abbrv} is typeset
+using \ics{textsc}. (Recall that \cs{textsc} converts lower case
+characters into small capitals and leaves upper case characters as
+they are. Therefore, you need to have lower case characters in
+\meta{abbrv} for this option to have an effect.)
+
+\item[\pkgopt{smaller}]
+This is similar to \pkgopt{smallcaps}, except that \ics{textsmaller}
+is used instead of \ics{textsc}. Note that the \styfmt{glossaries}
+package doesn't define \ics{textsmaller} nor does it load any
+package that does so. If you use this option, you must make sure
+\ics{textsmaller} is defined (for example by loading \sty{relsize}).
+
+\item[\pkgopt{dua}]
+This option will set both the \gloskey{first} and \gloskey{text}
+keys to the long form \meta{long}.
+\end{description}
+
+If you want to define your own custom acronym style, see
+\sectionref{sec:customacronym}.
+
+\begin{important}
+If you try using \ics{newglossaryentry} for entries in a designated
+list of acronyms in combination with any of the above named package 
+options you are likely to get unexpected results such as empty
+brackets or empty footnotes.
+
+If you don't intend to use \ics{newacronym} you should skip this section]
+and not use the above package options.
+\end{important}
+
+As mentioned in \sectionref{sec:pkgopts-sec}, the command
+\ics{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. If you want more than one list of acronyms, you must
+identify the others using the package options \pkgopt{acronymlists}.
+This ensures that options such as \pkgopt{footnote} and
+\pkgopt{smallcaps} work for the additional lists of acronyms.
+
+\begin{important}\raggedright
+Since \cs{newacronym} sets \verb|type=\acronymtype|,
+if you want to load a file containing acronym definitions using
+\ics{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| in the optional argument to
+\ics{newacronym}. See \sectionref{sec:loadglsentries}.
+\end{important}
+
+Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
+commands like \ics{gls} and \ics{glsreset} as with any other
+glossary entry.
+
+For example, the following defines the acronym IDN:
+\begin{verbatim}
+\newacronym{idn}{IDN}{identification number}
+\end{verbatim}
+\verb|\gls{idn}| will produce \qt{identification number (IDN)} on
+\firstuse\ and \qt{IDN} on subsequent uses. If you want to use the
+\pkgopt{smallcaps} package option, you need to use lower case
+characters for the shortened form:
+\begin{verbatim}
+\newacronym{idn}{idn}{identification number}
+\end{verbatim}
+Now \verb|\gls{idn}| will produce \qt{identification number
+(\textsc{idn})} on \firstuse\ and \qt{\textsc{IDN}} on subsequent
+uses.
+
+If you use any of the package options \pkgopt{smallcaps},
+\pkgopt{smaller}, \pkgopt{description} or \pkgopt{footnote}, the
+short form \meta{abbrv} will be displayed in the document using:
+\begin{definition}[\DescribeMacro{\acronymfont}]
+\cs{acronymfont}\marg{text}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\firstacronymfont}]
+\cs{firstacronymfont}\marg{text}
+\end{definition}
+where \cs{firstacronymfont} is applied on \firstuse\ and
+\cs{acronymfont} is applied on subsequent use. Note that if you
+don't use any of the above package options, changing the definition
+of \cs{acronymfont} or \cs{firstacronymfont} will have no effect. In
+this case, the recommended route is to use either the
+\pkgopt{smaller} or the \pkgopt{smallcaps} package option and
+redefine \cs{acronymfont} and \cs{firstacronymfont} as required.
+(The \pkgopt{smallcaps} option sets the default plural suffix in an
+upright font to cancel the effect of \ics{textsc}, whereas
+\pkgopt{smaller} sets the suffix in the surrounding font.) For
+example, if you want acronyms in a normal font on \gls{firstuse} and
+emphasized on subsequent use, do:
+\begin{verbatim}
+\usepackage[smaller]{glossaries}
+\renewcommand*{\firstacronymfont}[1]{#1}
+\renewcommand*{\acronymfont}[1]{\emph{#1}}
+\end{verbatim}
+(Note that it is for this reason that the \sty{relsize} package is
+not automatically loaded when selecting the \pkgopt{smaller} package
+option.)
+
+There are commands analogous to \ics{glstext} (described in
+\sectionref{sec:glslink}) that allow you to access just the short
+form, just the long form or the full form, without affecting the
+\gls{firstuseflag}. (Note that the full form isn't necessarily the same
+as the text produced on \firstuse.)
+
+\begin{definition}[\DescribeMacro{\acrshort}]
+\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This displays the short form for the entry given by \meta{label}.
+The optional arguments are the same as those for \ics{glstext}.
+There is also a starred version to suppress the hyperlink. There are
+also analogous upper case variants:
+\begin{definition}[\DescribeMacro{\Acrshort}]
+\cs{Acrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRshort}]
+\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+\begin{definition}[\DescribeMacro{\acrlong}]
+\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This displays the long form for the entry given by \meta{label}.
+The optional arguments are the same as before.  There is also a starred 
+version to suppress the hyperlink. There are also analogous upper case 
+variants:
+\begin{definition}[\DescribeMacro{\Acrlong}]
+\cs{Acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRshort}]
+\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+\begin{definition}[\DescribeMacro{\acrfull}]
+\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is equivalent to: 
+\DescribeMacro{\acrfullformat}\cs{acrfullformat}"{"\ics{acrlong}"}{"\ics{acrshort}"}".
+This defaults to \meta{long} (\ics{acronymfont}\marg{short})
+regardless of the package options. There are also analogous upper
+case variants:
+\begin{definition}[\DescribeMacro{\Acrfull}]
+\cs{Acrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRfull}]
+\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+If you find the above commands too cumbersome to write, you can use
+the \pkgopt{shortcuts} package option to activate the shorter
+command names listed in \tableref{tab:shortcuts}.
+
+\begin{table}[htbp]
+\caption[Synonyms provided by the package option shortcuts]{Synonyms provided by the package option \pkgopt{shortcuts}}
+\label{tab:shortcuts}
+\vskip\baselineskip
+\centering
+\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{table}
+
+It is also possible to access the long and short forms without
+adding information to the glossary using commands analogous to
+\ics{glsentrytext} (described in \sectionref{sec:glsnolink}).
+
+The long form can be accessed using:
+\begin{definition}[\DescribeMacro{\glsentrylong}]
+\cs{glsentrylong}\marg{label}
+\end{definition}
+or, with the first letter converted to upper case:
+\begin{definition}[\DescribeMacro{\Glsentrylong}]
+\cs{Glsentrylong}\marg{label}
+\end{definition}
+Plural forms:
+\begin{definition}[\DescribeMacro{\glsentrylongpl}]
+\cs{glsentrylongpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrylongpl}]
+\cs{Glsentrylongpl}\marg{label}
+\end{definition}
+
+Similarly, to access the short form:
+\begin{definition}[\DescribeMacro{\glsentryshort}]
+\cs{glsentryshort}\marg{label}
+\end{definition}
+or, with the first letter converted to upper case:
+\begin{definition}[\DescribeMacro{\Glsentryshort}]
+\cs{Glsentryshort}\marg{label}
+\end{definition}
+Plural forms:
+\begin{definition}[\DescribeMacro{\glsentryshortpl}]
+\cs{glsentryshortpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryshortpl}]
+\cs{Glsentryshortpl}\marg{label}
+\end{definition}
+
+And the full form, \meta{long} (\meta{short}), can be obtained
+using:
+\begin{definition}[\DescribeMacro{\glsentryfull}]
+\cs{glsentryfull}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryfull}]
+\cs{Glsentryfull}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryfullpl}]
+\cs{glsentryfullpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryfullpl}]
+\cs{Glsentryfullpl}\marg{label}
+\end{definition}
+
+\subsection{Predefined Acronym Styles}
+
+Some of the acronym-related package options may be combined. Listed
+below are the effects of different combinations. If you use an
+invalid combination, you'll get an error message.
+
+\begin{description}
+\item[\pkgopt{description},\pkgopt{footnote}]\ifpdf\mbox{}\par\fi
+When these two package options are used together, the \firstuse\ displays
+the entry as:
+\begin{display}
+\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} 
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\cs{acronymfont}\marg{abbrv}\meta{insert}
+\end{display}
+where \meta{insert} indicates the text supplied in the final
+optional argument to \ics{gls}, \ics{glspl} or their uppercase 
+variants.
+
+\item[\pkgopt{dua}]\ifpdf\mbox{}\par\fi
+The \pkgopt{dua} package option always makes \ics{gls} display the 
+expanded form and so may not be used with \pkgopt{footnote}, 
+\pkgopt{smaller} or \pkgopt{smallcaps}. Both \firstuse\ and subsequent 
+use displays the entry in the form:
+\begin{display}
+\meta{long}\meta{insert}
+\end{display}
+You can, however, access the short form using \ics{acrshort} and its
+variants.
+
+\item[\pkgopt{description}]\ifpdf\mbox{}\par\fi
+This package option displays the entry on \firstuse\ as:
+\begin{display}
+\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv})
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\cs{acronymfont}\marg{abbrv}\meta{insert}
+\end{display}
+
+Note that with this option, you need to specify the description
+using the \gloskey{description} key in the optional argument
+of \ics{newacronym}.
+
+\item[\pkgopt{footnote}]\ifpdf\mbox{}\par\fi
+This package option displays the entry on \firstuse\ as:
+\begin{display}
+\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\cs{acronymfont}\marg{abbrv}\meta{insert}
+\end{display}
+Acronyms will be sorted according to the short form.
+
+Note that on \firstuse, it is the long form in the footnote that
+links to the relevant glossary entry (where hyperlinks are enabled),
+whereas on subsequent use, the acronym links to the relevant
+glossary entry. You can suppress the long form link by setting:
+\begin{verbatim}
+\let\acrfootnote\acrnolinkfootnote
+\end{verbatim}
+
+\item[\pkgopt{smallcaps}]\ifpdf\mbox{}\par\fi
+If neither the \pkgopt{footnote} nor \pkgopt{description} options
+have been set, this option displays the entry on \firstuse\ as:
+\begin{display}
+\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv})
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\cs{acronymfont}\marg{abbrv}\meta{insert}
+\end{display}
+where \ics{acronymfont} is set to \verb|\textsc{#1}|.
+
+\begin{important}
+Note that since the acronym is displayed using \ics{textsc}, 
+the short form, \meta{abbrv}, should be specified in lower case.
+\ifpdf(Recall that "\textsc{abc}" produces \textsc{abc} whereas 
+"\textsc{ABC}" produces \textsc{ABC}.)\fi
+\end{important}
+
+\item[\pkgopt{smaller}]\ifpdf\mbox{}\par\fi
+If neither the \pkgopt{footnote} nor \pkgopt{description} options
+have been set, this option displays the entry on \firstuse\ as:
+\begin{display}
+\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv})
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\ics{acronymfont}\marg{abbrv}\meta{insert}
+\end{display}
+where \ics{acronymfont} is set to 
+\verb|\textsmaller{#1}|.\footnote{not that this was change from 
+using \ics{smaller} to \ics{textsmaller} as declarations
+cause a problem for \ics{makefirstuc}.}
+The entries will be sorted according to the short form.
+
+\begin{important}
+Remember to load a package that defines \ics{textsmaller} (such as
+\sty{relsize}) if you want to use this option, unless you want
+to redefine \ics{acronymfont} to use some other formatting command.
+\end{important}
+
+\item[None of the above]\ifpdf \mbox{}\par\fi
+If none of the package options \pkgopt{smallcaps}, \pkgopt{smaller},
+\pkgopt{footnote}, \pkgopt{dua} or \pkgopt{description} are used, 
+then on \firstuse\ the entry is displayed as:
+\begin{display}
+\meta{long} (\meta{abbrv})\meta{insert}
+\end{display}
+while subsequent use displays the entry as:
+\begin{display}
+\meta{abbrv}\meta{insert}
+\end{display}
+Entries will be sorted according to the short form.
+\end{description}
+
+\subsection{Displaying the List of Acronyms}
+
+The list of acronyms is just like any other type of glossary and can
+be displayed on its own using
+\ics{printglossary}"[type=\acronymtype]" or with all the other
+glossaries using \ics{printglossaries}. However, care must be taken
+to choose a glossary style that's appropriate to your acronym style.
+The different acronym-related package options store different
+information in the \gloskey{name}, \gloskey{description} and
+\gloskey{symbol} keys.
+
+\Tableref{tab:acronymsettings} lists the package options that govern
+the acronym styles and how the information is stored in the keys
+used when displaying the glossary. Note that the \pkgopt{description} 
+package option uses the following command in the \gloskey{name}:
+\begin{definition}[\DescribeMacro{\acrnameformat}]
+\cs{acrnameformat}\marg{abbrv}\marg{long}
+\end{definition}
+This defaults to just \cs{acronymfont}\marg{abbrv}.
+
+For example, if I use the package options \pkgopt{description} and
+\pkgopt{footnote}, then the name field will contain the abbreviation
+and the symbol field will contain the long form. If I then use the 
+\glostyle{long4col} style, each entry in the list of acronyms will
+appear in the form:
+\begin{display}
+\ics{acronymfont}\marg{abbrv} \meta{description} \meta{long}
+\meta{location list}
+\end{display}
+Alternatively, you can define your own custom style (see 
+\sectionref{sec:newglossarystyle} for further details).
+
+\begin{table}[htbp]
+\caption{Package options governing \cs{newacronym} and how the 
+information is stored}
+\label{tab:acronymsettings}
+\begin{center}
+\begin{tabular}{lllll}
+\bfseries Package Option &
+\gloskey{name} &
+\gloskey{description} &
+\gloskey{symbol}\\
+\pkgopt{description},\pkgopt{footnote} &
+\ics{acronymfont}\marg{abbrv} &
+user supplied &
+\meta{long}\\
+\pkgopt{description},\pkgopt{dua} &
+\meta{long} &
+user supplied &
+\meta{abbrv}\\
+\pkgopt{description} &
+\ics{acrnameformat}\marg{abbrv}\marg{long} &
+user supplied &
+\meta{abbrv}\\
+\pkgopt{footnote} &
+\ics{acronymfont}\marg{abbrv} &
+\meta{long} &
+ \\
+\pkgopt{smallcaps} &
+\ics{acronymfont}\marg{abbrv} &
+\meta{long} &
+\meta{abbrv}\\
+\pkgopt{smaller} &
+\ics{acronymfont}\marg{abbrv} &
+\meta{long} &
+\meta{abbrv}\\
+\pkgopt{dua} &
+\meta{abbrv} &
+\meta{long} &
+\meta{abbrv}\\
+None of the above&
+\meta{abbrv} &
+\meta{long} &
+\end{tabular}
+\end{center}
+\end{table}
+
+\subsection{Defining A Custom Acronym Style}
+\label{sec:customacronym}
+
+You may find that the predefined acronyms styles that come with the
+\styfmt{glossaries} package don't suit your requirements. In this
+case you can define your own style. This is done by redefining the
+following commands:
+\begin{definition}[\DescribeMacro{\CustomAcronymFields}]
+\cs{CustomAcronymFields}
+\end{definition}
+This command sets up the keys for \ics{newglossaryentry} when
+you define an acronym using \ics{newacronym}. Within the definition
+of \cs{CustomAcronymFields}, you may use \cs{the}\ics{glslongtok} to
+access the long form, \cs{the}\ics{glsshorttok} to access the short
+form and \cs{the}\ics{glslabeltok} to access the label. This command
+is typically used to set the \gloskey{name}, \gloskey{first},
+\gloskey{firstplural}, \gloskey{text} and \gloskey{plural} keys. It
+may also be used to set the \gloskey{symbol} or
+\gloskey{description} keys depending on your requirements.
+
+\begin{definition}[\DescribeMacro{\SetCustomDisplayStyle}]
+\cs{SetCustomDisplayStyle}\marg{type}
+\end{definition}
+This is used to set up the display style for the glossary given by
+\meta{type}. This should typically just use \ics{defglsdisplayfirst}
+and \ics{defglsdisplay}.
+
+Once you have redefined \cs{CustomAcronymFields} and
+\cs{SetCustomDisplayStyle}, you must then switch to this style using
+\begin{definition}[\DescribeMacro{\SetCustomStyle}]
+\cs{SetCustomStyle}
+\end{definition}
+Note that you may still use the \pkgopt{shortcuts} package option
+with your custom style.
+
+\begin{important}
+If you omit \cs{SetCustomStyle}, or use it before you redefine
+\cs{CustomAcronymFields} and \cs{SetCustomDisplayStyle}, your new
+style won't be correctly implemented. You must set up the custom style 
+before defining new acronyms. The acronyms must be defined using
+\ics{newacronym} not \ics{newglossaryentry}.
+\end{important}
+
+As an example, suppose I want my acronym on \gls{firstuse} to have the
+short form in the text and the long form with the description in a
+footnote. Suppose also that I want the short form to be put in small
+caps in the main body of the document, but I want it in normal
+capitals in the list of acronyms. In my list of acronyms, I want the
+long form as the name with the short form in brackets followed by
+the description. That is, in the text I want \ics{gls} on \gls{firstuse}
+to display:
+\begin{display}
+\ics{textsc}\marg{abbrv}\cs{footnote}"{"\meta{long}: \meta{description}"}"
+\end{display}
+on subsequent use:
+\begin{display}
+\ics{textsc}\marg{abbrv}
+\end{display}
+and in the list of acronyms, each entry will be displayed in the
+form:
+\begin{display}
+\meta{long} (\meta{short}) \meta{description}
+\end{display}
+
+First, I need to redefine \ics{CustomAcronymFields} so that
+\ics{newacronym} will correctly set the \gloskey{name}, 
+\gloskey{text} and \gloskey{plural} keys. I want the long form to be
+stored in the \gloskey{name} and the short form to be stored in
+\gloskey{text}. In addition, I'm going to set the \gloskey{symbol}
+to the short form in upper case so that it will appear in the list
+of acronyms.
+
+\begin{verbatim}
+\renewcommand*{\CustomAcronymFields}{%
+  name={\the\glslongtok},%
+  symbol={\MakeUppercase{\the\glsshorttok}},%
+  text={\textsc{\the\glsshorttok}},%
+  plural={\textsc{\the\glsshorttok}\noexpand\acrpluralsuffix}%
+}
+\end{verbatim}
+
+When using \ics{newacronym}, the short and long forms are stored in
+the \gloskey{short} and \gloskey{long} keys, and the plural forms
+are stored in \gloskey{shortplural} and \gloskey{longplural}.
+So when I use \ics{defglsdisplayfirst}
+and \ics{defglsdisplay}, I can use \ics{glsentrylong} to access
+the long form. Recall from \sectionref{sec:glsdisplay}, that the
+optional argument to \ics{defglsdisplayfirst} and \ics{defglsdisplay}
+indicates the glossary type. This is passed to
+\ics{SetCustomDisplayStyle}. The mandatory argument sets up the
+definition of \ics{glsdisplayfirst} and \ics{glsdisplay} for the
+given glossary, where the first argument corresponds to the
+\gloskey{first}, \gloskey{firstplural}, \gloskey{text} or 
+\gloskey{plural}, as appropriate, the second argument corresponds to
+the \gloskey{description}, the third corresponds to the
+\gloskey{symbol} and the fourth argument is the inserted text.
+
+\begin{verbatim}
+\renewcommand*{\SetCustomDisplayStyle}[1]{%
+  \defglsdisplayfirst[#1]{##1##4\protect\footnote{%
+    \glsentrylong{\glslabel}: ##2%
+  }}
+  \defglsdisplay[#1]{##1##4}%
+}
+\end{verbatim}
+
+Since we have a definition inside a definition, \verb|#1| refers to
+the argument of \ics{SetCustomDisplayStyle}, and \verb|##1|, \ldots,
+\verb|##4|, refer to the arguments of \ics{glsdisplayfirst} and
+\ics{glsdisplay}.
+
+Now that I've redefined \ics{CustomAcronymFields} and
+\ics{SetCustomDisplayStyle}, I can set this style using
+\begin{verbatim}
+\SetCustomStyle
+\end{verbatim}
+and now I can define my acronyms:
+\begin{verbatim}
+\newacronym[description={set of tags for use in developing hypertext
+documents}]{html}{html}{Hyper Text Markup Language}
+
+\newacronym[description={language used to describe the layout of a
+document written in a markup language}]{css}{css}{Cascading Style
+Sheet}
+\end{verbatim}
+
+Note that since I've used the description in the main body of the
+text, I need to switch off the sanitization otherwise any commands
+within the description won't get interpreted. Also I want to use the
+\sty{hyperref} package, but this will cause a problem on \gls{firstuse}
+as I'll get nested hyperlinks, so I need to switch off the
+hyperlinks on \gls{firstuse}. In addition, I want to use a glossary style
+that displays the symbol. Therefore, in my preamble I have:
+
+\begin{verbatim}
+\usepackage[colorlinks]{hyperref}
+\usepackage[acronym,         % create list of acronyms
+            nomain,          % don't need main glossary for this example
+            style=tree,      % need a style that displays the symbol
+            hyperfirst=false,% don't hyperlink first use
+            sanitize=none    % switch off sanitization as description 
+                             % will be used in the main text
+            ]{glossaries}
+\end{verbatim}
+
+Note that I haven't used the \pkgopt{description} or
+\pkgopt{footnote} package options.
+
+\subsection{Upgrading From the glossary Package}
+\label{sec:oldacronym}
+Users of the obsolete \sty{glossary} package may recall that
+the syntax used to define new acronyms has changed with the
+replacement \styfmt{glossaries} package. In addition, the old
+\sty{glossary} package created the command 
+\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}.
+
+In order to facilitate migrating from the old package to the new
+one, the \styfmt{glossaries} package\footnote{as from version 1.18} 
+provides the command:
+\begin{definition}[\DescribeMacro{\oldacronym}]
+\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}
+\end{definition}
+This uses the same syntax as the \sty{glossary} package's
+method of defining acronyms. It is equivalent to:\\[10pt]
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt]
+In addition, \ics{oldacronym} also defines the commands
+\cs{}\meta{label}, which is equivalent to \ics{gls}\marg{label},
+and \cs{}\meta{label}\texttt{*}, which is equivalent to
+\ics{Gls}\marg{label}. If \meta{label} is omitted, \meta{abbrv}
+is used. Since commands names must consist only of alphabetical
+characters, \meta{label} must also only consist of alphabetical
+characters. Note that \cs{}\meta{label} doesn't allow you to use
+the first optional argument of \ics{gls} or \ics{Gls} --- you will
+need to explicitly use \ics{gls} or \ics{Gls} to change the
+settings.
+
+\begin{important}
+Recall that, in general, \LaTeX\ ignores spaces following command 
+names consisting of alphabetical characters. This is also true for 
+\cs{}\meta{label} unless you additionally load the
+\sty{xspace} package.
+\end{important}
+
+The \styfmt{glossaries} package doesn't load the \sty{xspace} package
+since there are both advantages and disadvantages to using
+\ics{xspace} in \cs{}\meta{label}. If you don't use the 
+\sty{xspace} package you need to explicitly force a space using
+\verb*|\ | (backslash space) however you can follow \cs{}\meta{label}
+with additional text in square brackets (the final optional
+argument to \ics{gls}). If you use the \sty{xspace} package
+you don't need to escape the spaces but you can't use
+the optional argument to insert text (you will have to explicitly
+use \ics{gls}).
+
+To illustrate this, suppose I define the acronym \qt{abc} as
+follows:
+\begin{verbatim}
+\oldacronym{abc}{example acronym}{}
+\end{verbatim}
+This will create the command \cs{abc} and its starred version
+\cs{abc*}. \Tableref{tab:xspace} illustrates the effect of
+\cs{abc} (on subsequent use) according to whether or not the
+\sty{xspace} package has been loaded. As can be seen from the
+final row in the table, the \sty{xspace} package prevents the
+optional argument from being recognised.
+
+\begin{table}[htbp]
+\caption[The effect of using xspace]{The effect of using 
+\styfmt{xspace} with \cs{oldacronym}}
+\label{tab:xspace}
+\vskip\baselineskip
+\centering
+\begin{tabular}{lll}
+\bfseries Code & \bfseries With \styfmt{xspace} &
+\bfseries Without \styfmt{xspace}\\
+\verb|\abc.| & abc. & abc.\\
+\verb|\abc xyz| & abc xyz & abcxyz\\
+\verb|\abc\ xyz| & abc xyz & abc xyz\\
+\verb|\abc* xyz| & Abc xyz & Abc xyz\\
+\verb|\abc['s] xyz| & abc ['s] xyz & abc's xyz
+\end{tabular}
+\par
+\end{table}
+
+
+
+\section{Unsetting and Resetting Entry Flags}
+\label{sec:glsunset}
+
+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 \glslink{firstuse}{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:
+\begin{definition}[\DescribeMacro{\glsreset}]
+\cs{glsreset}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalreset}]
+\cs{glslocalreset}\marg{label}
+\end{definition}
+while the latter can be achieved by one of the following commands:
+\begin{definition}[\DescribeMacro{\glsunset}]
+\cs{glsunset}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalunset}]
+\cs{glslocalunset}\marg{label}
+\end{definition}
+You can also reset or unset all entries for a given glossary or list of
+glossaries using:
+\begin{definition}[\DescribeMacro{\glsresetall}]
+\cs{glsresetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalresetall}]
+\cs{glslocalresetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsunsetall}]
+\cs{glsunsetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalunsetall}]
+\cs{glslocalunsetall}\oarg{glossary list}
+\end{definition}
+where \meta{glossary list} is a comma-separated list of 
+glossary labels. If omitted, all defined glossaries are assumed.
+For example, to reset all entries in the main glossary and the
+list of acronyms:
+\begin{verbatim}
+\glsresetall[main,acronym]
+\end{verbatim}
+
+You can determine whether an entry's \gls{firstuseflag} is set using:
+\begin{definition}[\DescribeMacro{\ifglsused}]
+\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+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.
+
+
+\section{Glossary Styles}
+\label{sec:styles}
+The \styfmt{glossaries} package comes with some pre-defined
+glossary styles. Note that the styles are suited to different
+types of glossaries: some styles ignore the associated
+symbol; some styles are not designed for hierarchical entries,
+so they display sub-entries in the same way as they display top
+level entries; some styles are designed for homographs, so they 
+ignore the name for sub-entries. You should therefore pick a style 
+that suits your type of glossary. See \tableref{tab:styles} for
+a summary of the available styles. The predefined styles can
+accommodate numbered level~0 (main) and level~1 entries. See the
+package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and
+\pkgopt{subentrycounter} described in
+\sectionref{sec:pkgopts-printglos}.
+
+\begin{table}[htbp]
+\caption[Glossary Styles]{Glossary Styles. An asterisk in the style 
+name indicates anything that matches that doesn't match any
+previously listed style (e.g.\ \texttt{long3col*}
+matches \glostyle{long3col}, \glostyle{long3colheader}, 
+\glostyle{long3colborder} and \glostyle{long3colheaderborder}).
+A maximum level of 0 indicates a flat glossary (sub-entries
+are displayed in the same way as main entries). Where the maximum
+level is given as --- there is no limit, but note that 
+\gls{makeindex} imposes a limit of 2 sub-levels. If the
+homograph column is checked, then the name is not displayed for
+sub-entries. If the symbol column is checked, then the symbol will
+be displayed.}
+\label{tab:styles}
+\vskip\baselineskip
+\centering
+\begin{tabular}{lccc}
+\bfseries Style & \bfseries Maximum Level &
+\bfseries Homograph & \bfseries Symbol\\
+\ttfamily listdotted & 0 & & \\
+\ttfamily sublistdotted & 1 & & \\
+\ttfamily list* & 1 & \tick & \\
+\ttfamily altlist* & 1 & \tick & \\
+\ttfamily long*3col* & 1 & \tick & \\
+\ttfamily long4col* & 1 & \tick & \tick \\
+\ttfamily altlong*4col* & 1 & \tick & \tick \\
+\ttfamily long* & 1 & \tick & \\
+\ttfamily super*3col* & 1 & \tick & \\
+\ttfamily super4col* & 1 & \tick & \tick \\
+\ttfamily altsuper*4col* & 1 & \tick & \tick \\
+\ttfamily super* & 1 & \tick & \\
+\ttfamily index* & 2 & & \tick\\
+\ttfamily treenoname* & --- & \tick & \tick\\
+\ttfamily tree* & --- & & \tick\\
+\ttfamily alttree* & --- & & \tick
+\end{tabular}
+\par
+\end{table}
+
+The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
+argument to \ics{printglossary} or using the command:
+\begin{definition}[\DescribeMacro{\glossarystyle}]
+\cs{glossarystyle}\marg{style-name}
+\end{definition}
+Some of the glossary styles may also be set using the \pkgopt{style} 
+package option, it depends if the package in which they are defined
+is automatically loaded by the \styfmt{glossaries} package.
+
+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.\footnote{these lengths will not be
+available if you use both the \pkgopt{nolong} and \pkgopt{nosuper}
+package options or if you use the \pkgopt{nostyles} package option
+unless you explicitly load the relevant package.}
+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.  If you want to
+explicitly create a line-break within a multi-line description in
+a tabular-like style you should use \ics{newline} instead of
+\verb|\\|.
+
+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}
+then 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}, e.g.:
+\begin{verbatim}
+\glossarystyle{long}
+\renewcommand*{\glsgroupskip}{}
+\end{verbatim}
+
+All the styles except for the three- and four-column styles and the
+\glostyle{listdotted} style use the command
+\begin{definition}[\DescribeMacro{\glspostdescription}]
+\cs{glspostdescription}
+\end{definition}
+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. Alternatively, you can suppress it for a
+given entry by placing \ics{nopostdesc} in the entry's description.
+
+\subsection{List Styles}
+\label{sec:liststyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-list}. Since they all use the \env{description}
+environment, they are governed by the same parameters as that
+environment. These styles all ignore the entry's symbol.  Note that
+these styles will automatically be available unless you use the
+\pkgopt{nolist} or \pkgopt{nostyles} package options.
+
+\begin{description}
+\item[list] The \glostyle{list} style uses the \env{description}
+environment. The entry name is placed in the optional argument of
+the \ics{item} command (so it will appear in bold by default). The
+description follows, and then the associated \gls{numberlist} for 
+that entry. The symbol is ignored.  If the entry has child entries,
+the description and number list follows (but not the name) for each
+child entry.  Groups are separated using \ics{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 navigation line at the start of the
+glossary with links 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 line, each group is
+separated by
+\begin{definition}[\DescribeMacro{\glshypernavsep}]
+\cs{glshypernavsep}
+\end{definition}
+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 line is now (as from version 1.14) 
+set inside the optional argument to \ics{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 starts on the line following the name. (As
+with the \glostyle{list} style, the symbol is ignored.) Each child
+entry starts a new line, but as with the \glostyle{list} style,
+the name associated with each child entry is ignored.
+
+\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 line is the same as that for 
+\glostyle{listhypergroup}, described above.
+
+\item[listdotted] This style uses the \env{description}
+environment.\footnote{This style was supplied by Axel~Menzel.} 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 \gls{numberlist} and the symbol. The length
+\begin{definition}[\DescribeMacro{\glslistdottedwidth}]
+\cs{glslistdottedwidth}
+\end{definition}
+governs where the description should start. This is a flat style, so
+child entries are formatted in the same way as the parent entries.
+
+\item[sublistdotted] This is a variation on the \glostyle{listdotted}
+style designed for hierarchical glossaries. The main entries
+have just the name displayed. The sub entries are displayed in
+the same manner as \glostyle{listdotted}.
+\end{description}
+
+
+\subsection{Longtable Styles}
+\label{sec:longstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-long}. Since they all use the \env{longtable}
+environment, they are governed by the same parameters as that
+environment.  Note that these styles will automatically be available
+unless you use the \pkgopt{nolong} or \pkgopt{nostyles} package
+options.  These styles fully justify the description and page list
+columns.  If you want ragged right formatting instead, use the
+analogous styles described in \sectionref{sec:longraggedstyles}.
+
+
+\begin{description}
+\item[long] The \glostyle{long} style uses the \env{longtable}
+environment (defined by the \sty{longtable} package). It has two
+columns: the first column contains the entry's name and the second
+column contains the description followed by the \gls{numberlist}.
+The entry's symbol is ignored.
+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}. Child entries have a similar format to the
+parent entries except that their name is suppressed.
+
+\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 \gls{numberlist}.
+The entry's symbol is ignored. 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}, and 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 
+multi-line 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 widths of the
+name and symbol columns are 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.
+\end{description}
+
+
+\subsection{Longtable Styles (Ragged Right)}
+\label{sec:longraggedstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-longragged}. These styles are analogous to those
+defined in \sty{glossary-long} but the multiline columns are left
+justified instead of fully justified. Since these styles all use the
+\env{longtable} environment, they are governed by the same
+parameters as that environment. The \sty{glossary-longragged}
+package additionally requires the \sty{array} package.  Note that
+these styles will only be available if you explicitly load
+\sty{glossary-longragged}:
+\begin{verbatim}
+\usepackage{glossaries}
+\usepackage{glossary-longragged}
+\end{verbatim}
+Note that you can't set these styles using the \pkgopt{style}
+package option since the styles aren't defined until after
+the \styfmt{glossaries} package has been loaded.
+
+\begin{description}
+\item[longragged] The \glostyle{longragged} style has two
+columns: the first column contains the entry's name and the second
+column contains the (left-justified) description followed by the 
+\gls{numberlist}.  The entry's symbol is ignored.
+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}. Child entries have a similar format to the
+parent entries except that their name is suppressed.
+
+\item[longraggedborder] The \glostyle{longraggedborder} style is like
+\glostyle{longragged} but has horizontal and vertical lines around it.
+
+\item[longraggedheader] The \glostyle{longraggedheader} style is like
+\glostyle{longragged} but has a header row.
+
+\item[longraggedheaderborder] The \glostyle{longraggedheaderborder} 
+style is like \glostyle{longraggedheader} but has horizontal and 
+vertical lines around it.
+
+\item[longragged3col] The \glostyle{longragged3col} style is like
+\glostyle{longragged} but has three columns. The first column
+contains the entry's name, the second column contains the (left
+justified) description and the third column contains the (left
+justified) \gls{numberlist}.  The entry's symbol is ignored. 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}, and the width of the third column is governed by
+the length \ics{glspagelistwidth}.
+
+\item[longragged3colborder] The \glostyle{longragged3colborder}
+style is like the \glostyle{longragged3col} style but has horizontal
+and vertical lines around it.
+
+\item[longragged3colheader] The \glostyle{longragged3colheader} style is like
+\glostyle{longragged3col} but has a header row.
+
+\item[longragged3colheaderborder] The \glostyle{longragged3colheaderborder} style is
+like \glostyle{longragged3colheader} but has horizontal and vertical lines
+around it.
+
+\item[altlongragged4col] The \glostyle{altlongragged4col} style is
+like \glostyle{longragged3col} but has an additional column in which
+the entry's associated symbol appears. 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 widths of the name and symbol columns
+are governed by the widest entry in the given column.
+
+\item[altlongragged4colborder] The
+\glostyle{altlongragged4colborder} style is like the
+\glostyle{altlongragged4col} but has horizontal and vertical lines
+around it.
+
+\item[altlongragged4colheader] The
+\glostyle{altlongragged4colheader} style is like
+\glostyle{altlongragged4col} but has a header row.
+
+\item[altlongragged4colheaderborder] The
+\glostyle{altlongragged4colheaderborder} style is like
+\glostyle{altlongragged4colheader} but has horizontal and vertical
+lines around it.
+
+\end{description}
+
+
+\subsection{Supertabular Styles}
+\label{sec:superstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-super}. Since they all use the \env{supertabular}
+environment, they are governed by the same parameters as that
+environment.  Note that these styles will automatically be available
+unless you use the \pkgopt{nosuper} or \pkgopt{nostyles} package
+options.  In general, the \env{longtable} environment is better,
+but there are some circumstances where it is better to use
+\env{supertabular}.\footnote{e.g.\ with the \sty{flowfram}
+package.} These styles fully justify the description and page list
+columns.  If you want ragged right formatting instead, use the
+analogous styles described in \sectionref{sec:superraggedstyles}.
+
+\begin{description}
+\item[super] The \glostyle{super} style uses the \env{supertabular}
+environment (defined by the \sty{supertabular} package). It has two
+columns: the first column contains the entry's name and the second
+column contains the description followed by the \gls{numberlist}.
+The entry's symbol is ignored.
+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}. Child entries have a similar format to the
+parent entries except that their name is suppressed.
+
+\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 \gls{numberlist}. The
+entry's symbol is ignored. 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 multi-line 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}
+
+
+\subsection{Supertabular Styles (Ragged Right)}
+\label{sec:superraggedstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-superragged}. These styles are analogous to those
+defined in \sty{glossary-super} but the multiline columns are left
+justified instead of fully justified. Since these styles all use the
+\env{supertabular} environment, they are governed by the same
+parameters as that environment. The \sty{glossary-superragged}
+package additionally requires the \sty{array} package.  Note that
+these styles will only be available if you explicitly load
+\sty{glossary-superragged}:
+\begin{verbatim}
+\usepackage{glossaries}
+\usepackage{glossary-superragged}
+\end{verbatim}
+Note that you can't set these styles using the \pkgopt{style}
+package option since the styles aren't defined until after
+the \styfmt{glossaries} package has been loaded.
+
+\begin{description}
+\item[superragged] The \glostyle{superragged} style uses the
+\env{supertabular} environment (defined by the
+\sty{supertabular} package). It has two columns: the first column
+contains the entry's name and the second column contains the (left
+justified) description followed by the \gls{numberlist}.  The
+entry's symbol is ignored.  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}. Child entries have a similar format to
+the parent entries except that their name is suppressed.
+
+\item[superraggedborder] The \glostyle{superraggedborder} style is
+like \glostyle{superragged} but has horizontal and vertical lines
+around it.
+
+\item[superraggedheader] The \glostyle{superraggedheader} style is
+like \glostyle{superragged} but has a header row.
+
+\item[superraggedheaderborder] The
+\glostyle{superraggedheaderborder} style is like
+\glostyle{superraggedheader} but has horizontal and vertical lines
+around it.
+
+\item[superragged3col] The \glostyle{superragged3col} style is like
+\glostyle{superragged} but has three columns. The first column
+contains the entry's name, the second column contains the (left
+justified) description and the third column contains the (left
+justified) \gls{numberlist}. The entry's symbol is ignored. 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[superragged3colborder] The \glostyle{superragged3colborder}
+style is like the \glostyle{superragged3col} style but has
+horizontal and vertical lines around it.
+
+\item[superragged3colheader] The \glostyle{superragged3colheader}
+style is like \glostyle{superragged3col} but has a header row.
+
+\item[superragged3colheaderborder] The
+\glostyle{superragged3colheaderborder} style is like
+\glostyle{superragged3colheader} but has horizontal and vertical
+lines around it.
+
+\item[altsuperragged4col] The \glostyle{altsuperragged4col} style is
+like \glostyle{superragged3col} but has an additional column in
+which the entry's associated symbol appears. The column widths for
+the name and symbol column are governed by the widest entry in the
+given column.
+
+\item[altsuperragged4colborder] The
+\glostyle{altsuperragged4colborder} style is like the
+\glostyle{altsuperragged4col} style but has horizontal and vertical
+lines around it.
+
+\item[altsuperragged4colheader] The
+\glostyle{altsuperragged4colheader} style is like
+\glostyle{altsuperragged4col} but has a header row.
+
+\item[altsuperragged4colheaderborder] The
+\glostyle{altsuperragged4colheaderborder} style is like
+\glostyle{altsuperragged4colheader} but has horizontal and vertical
+lines around it.
+
+\end{description}
+
+\subsection{Tree-Like Styles}
+\label{sec:treestyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-tree}. These styles are designed for hierarchical
+glossaries but can also be used with glossaries that don't have
+sub-entries. These styles will display the entry's symbol if it
+exists. Note that these styles will automatically be available
+unless you use the \pkgopt{notree} or \pkgopt{nostyles} package
+options.
+
+\begin{description}
+\item[index] The \glostyle{index} style is similar to the way
+indices are usually formatted in that it has a hierarchical
+structure up to three levels (the main level plus two sub-levels).
+The name is typeset in bold, and if the symbol is present it is set
+in parentheses after the name and before the description.
+Sub-entries are indented and also include the name, the symbol
+in brackets (if present) and the description.  Groups are separated
+using \ics{indexspace}.
+
+\item[indexgroup] The \glostyle{indexgroup} style is similar to
+the \glostyle{index} style except that each group has a heading.
+
+\item[indexhypergroup] The \glostyle{indexhypergroup} style is like 
+\glostyle{indexgroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above.
+
+\item[tree] The \glostyle{tree} style is similar to the
+\glostyle{index} style except that it can have arbitrary levels.
+(Note that \gls{makeindex} is limited to three levels, so
+you will need to use \gls{xindy} if you want more than 
+three levels.) Each sub-level is indented by 
+\DescribeMacro{\glstreeindent}\cs{glstreeindent}. Note that the
+name, symbol (if present) and description are placed in the
+same paragraph block. If you want the name to be apart from the
+description, use the \glostyle{alttree} style instead. (See below.)
+
+\item[treegroup] The \glostyle{treegroup} style is similar to
+the \glostyle{tree} style except that each group has a heading.
+
+\item[treehypergroup] The \glostyle{treehypergroup} style is like 
+\glostyle{treegroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above.
+
+\item[treenoname] The \glostyle{treenoname} style is like
+the \glostyle{tree} style except that the name for each sub-entry
+is ignored.
+
+\item[treenonamegroup] The \glostyle{treenonamegroup} style is 
+similar to the \glostyle{treenoname} style except that each group 
+has a heading.
+
+\item[treenonamehypergroup] The \glostyle{treenonamehypergroup} 
+style is like \glostyle{treenonamegroup} but has a set of links to 
+the glossary groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above.
+
+\item[alttree] The \glostyle{alttree} style is similar to the
+\glostyle{tree} style except that the indentation for each level
+is determined by the width of the text specified by
+\begin{definition}[\DescribeMacro{\glssetwidest}]
+\cs{glssetwidest}\oarg{level}\marg{text}
+\end{definition}
+The optional argument \meta{level} indicates the level, where
+0 indicates the top-most level, 1 indicates the first level 
+sub-entries, etc. If \cs{glssetwidest} hasn't been used for a 
+given sub-level, the level~0 widest text is used instead. If
+\meta{level} is omitted, 0 is assumed.
+
+For each level, the name is placed to the left of the paragraph
+block containing the symbol (optional) and the description. If the
+symbol is present, it is placed in parentheses before the
+description.
+
+\item[alttreegroup] The \glostyle{alttreegroup} is like the
+\glostyle{alttree} style except that each group has a heading.
+
+\item[alttreehypergroup] The \glostyle{alttreehypergroup} style is 
+like \glostyle{alttreegroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above.
+
+\end{description}
+
+\section{Defining your own glossary style}
+\label{sec:newglossarystyle}
+
+If the predefined styles don't fit your requirements, you can
+define your own style using:
+\begin{definition}[\DescribeMacro{\newglossarystyle}]
+\cs{newglossarystyle}\marg{name}\marg{definitions}
+\end{definition}
+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{definition}[\DescribeEnv{theglossary}]
+\env{theglossary}
+\end{definition}
+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 \ics{glossarypreamble}) or the
+glossary postamble (defined by \ics{glossarypostamble}). For example,
+the \glostyle{list} style uses the \env{description} environment,
+so the \env{theglossary} environment is simply redefined to begin
+and end the \env{description} environment.
+
+\begin{definition}[\DescribeMacro{\glossaryheader}]
+\cs{glossaryheader}
+\end{definition}
+This macro indicates what to do at the start of the main body
+of the glossary. Note that this is not the same as 
+\ics{glossarypreamble}, which should not be affected by changes in
+the glossary style. The \glostyle{list} glossary style redefines
+\ics{glossaryheader} to do nothing, whereas the \glostyle{longheader}
+glossary style redefines \cs{glossaryheader} to do a header row.
+
+\begin{definition}[\DescribeMacro{\glsgroupheading}]
+\cs{glsgroupheading}\marg{label}
+\end{definition}
+This macro indicates
+what to do at the start of each logical block within the main body
+of the glossary. If you use \gls{makeindex} the glossary is
+sub-divided into a maximum of 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\@. If you use \gls{xindy}, the sub-divisions depend on
+the language settings.
+
+Note that the argument to \cs{glsgroupheading}
+is a label \emph{not} the group title. The group title can be obtained
+via
+\begin{definition}[\DescribeMacro{\glsgetgrouptitle}]
+\cs{glsgetgrouptitle}\marg{label}
+\end{definition}
+This obtains the title as follows: if 
+\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the 
+title, otherwise the title is just \meta{label}.
+
+A navigation hypertarget can be created using
+\begin{definition}[\DescribeMacro{\glsnavhypertarget}]
+\cs{glsnavhypertarget}\marg{label}\marg{text}
+\end{definition}
+For further details about \cs{glsnavhypertarget}, see
+\ifpdf section~\ref*{sec:code:hypernav} in \fi the documented code 
+(\texttt{glossaries.pdf}).
+
+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 
+\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc.)
+
+\begin{definition}[\DescribeMacro{\glsgroupskip}]
+\cs{glsgroupskip}
+\end{definition}
+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 \ics{indexspace},
+whereas the tabular-like styles redefine \cs{glsgroupskip} to
+produce a blank row.
+
+\begin{definition}[\DescribeMacro{\glossaryentryfield}]
+\cs{glossaryentryfield}\marg{label}\marg{formatted name}\marg{description}
+\marg{symbol}\marg{number list}
+\end{definition}
+This macro indicates what to do for a given glossary entry.
+Note that \meta{formatted name} will always be in the form
+\ics{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 \ics{newglossaryentry} or \ics{newacronym}. 
+
+\begin{definition}[\DescribeMacro{\glsentryitem}]
+\cs{glsentryitem}\marg{label}
+\end{definition}
+This macro will increment and display the associated counter for the
+main (level~0) entries if the \pkgopt{entrycounter} or
+\pkgopt{counterwithin} package options have been used. This macro
+is typically called by \cs{glossaryentryfield} before \cs{glstarget}. 
+The format of the counter is controlled by the macro
+\begin{definition}[\DescribeMacro{\glsentrycounterlabel}]
+\cs{glsentrycounterlabel}
+\end{definition}
+
+Each time you use a glossary entry it creates a hyperlink (if
+hyperlinks are enabled) to the relevant line in the glossary.
+Your new glossary style must therefore redefine
+\cs{glossaryentryfield} to set the appropriate target. This
+is done using
+\begin{definition}[\DescribeMacro{\glstarget}]
+\cs{glstarget}\marg{label}\marg{text}
+\end{definition}
+where \meta{label} is the entry's label. Note that you
+don't need to worry about whether the \sty{hyperref} package has
+been loaded, as \cs{glstarget} won't create a target if
+\cs{hypertarget} hasn't been defined.
+
+For example, the 
+\glostyle{list} style defines \cs{glossaryentryfield} as follows:
+\begin{verbatim}
+\renewcommand*{\glossaryentryfield}[5]{%
+\item[\glsentryitem{##1}\glstarget{##1}{##2}] 
+  ##3\glspostdescription \space ##5}
+\end{verbatim}
+
+Note also that \meta{number list} will always be of the form\\
+\begin{definition}
+\ics{glossaryentrynumbers}\{\cs{relax}\\
+\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}\}
+\end{definition}
+where \meta{number(s)}
+may contain \ics{delimN} (to delimit individual numbers) and/or
+\ics{delimR} (to indicate a range of numbers). There may be 
+multiple occurrences of 
+\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}, but note
+that the entire number list is enclosed within the argument
+of \linebreak\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
+\ics{glossaryentrynumbers} is to provide a means of suppressing the
+number list altogether. (In fact, the \pkgopt{nonumberlist} option 
+redefines \ics{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.
+
+\begin{definition}[\DescribeMacro{\glossarysubentryfield}]
+\cs{glossarysubentryfield}\marg{level}\marg{label}\marg{formatted name}
+\marg{description}\marg{symbol}\marg{number list}
+\end{definition}
+This is new to version 1.17, and is used to display sub-entries.
+The first argument, \meta{level}, indicates the sub-entry level.
+This must be an integer from 1 (first sub-level) onwards. The
+remaining arguments are analogous to those for
+\ics{glossaryentryfield} described above.
+
+\begin{definition}[\DescribeMacro{\glssubentryitem}]
+\cs{glssubentryitem}\marg{label}
+\end{definition}
+This macro will increment and display the associated counter for the
+level~1 entries if the \pkgopt{subentrycounter} package options have
+been used. This macro is typically called by \cs{glossarysubentryfield}
+before \ics{glstarget}. The format of the counter is controlled by
+the macro
+\begin{definition}[\DescribeMacro{\glssubentrycounterlabel}]
+\cs{glssubentrycounterlabel}
+\end{definition}
+
+Note that \ics{printglossary} (which \ics{printglossaries} calls)
+sets
+\begin{definition}[\DescribeMacro{\currentglossary}]
+\cs{currentglossary}
+\end{definition}
+to the current glossary label, so it's possible to create a glossary
+style that varies according to the glossary type.
+
+For further details of these commands, see \ifpdf
+section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary}
+in the documented code (\texttt{glossaries.pdf}).
+
+\subsection{Example: creating a completely new style}
+
+If you want a completely new style, you will need to redefine all
+of the commands and the environment listed above. 
+
+For example, suppose you want each entry to start with a bullet point.
+This means that the glossary should be placed in the \env{itemize}
+environment, so \env{theglossary} should start and end that
+environment. Let's also suppose that you don't want anything between
+the glossary groups (so \ics{glsgroupheading} and \ics{glsgroupskip}
+should do nothing) and suppose you don't want anything to appear
+immediately after \verb|\begin{theglossary}| (so \ics{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 \gls{numberlist} 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{##1}{##2}% the entry name
+ \space (##4)% the symbol in brackets
+ \space ##3% the description
+ \space [##5]% the number list in square brackets
+ }%
+ % set how sub-entries appear:
+ \renewcommand*{\glossarysubentryfield}[6]{%
+   \glossaryentryfield{##2}{##3}{##4}{##5}{##6}}%
+ }
+\end{verbatim}
+Note that this style creates a flat glossary, where sub-entries
+are displayed in exactly the same way as the top level entries.
+It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so
+it won't be affected by the \pkgopt{entrycounter},
+\pkgopt{counterwithin} or \pkgopt{subentrycounter} package options.
+
+\subsection{Example: creating a new glossary style based on an
+existing style}
+
+If you want to define a new style that is a slightly modified
+version of an existing style, you can use \ics{glossarystyle}
+within the second argument of \ics{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 \ics{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} 
+
+\subsection{Example: creating a glossary style that uses the
+\texorpdfstring{\gloskey{user1}}{user1}, \ldots, 
+\texorpdfstring{\gloskey{user6}}{user6} keys}
+
+Since \ics{glossaryentryfield} and \ics{glossarysubentryfield}
+provide the label for the entry, it's also possible to access
+the values of the generic user keys, such as \gloskey{user1}. For
+example, suppose each entry not only has an associated symbol,
+but also units (stored in \gloskey{user1}) and dimension
+(stored in \gloskey{user2}). Then you can define a glossary style
+that displays each entry in a \env{longtable} as follows:
+\begin{verbatim}
+\newglossarystyle{long6col}{%
+ % put the glossary in a longtable environment:
+ \renewenvironment{theglossary}%
+  {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}%
+  {\end{longtable}}%
+ % Set the table's header:
+ \renewcommand*{\glossaryheader}{%
+  \bfseries Term & \bfseries Description & \bfseries Symbol &
+  \bfseries Units & \bfseries Dimensions & \bfseries Page List
+  \\\endhead}%
+ % No heading between groups:
+  \renewcommand*{\glsgroupheading}[1]{}%
+ % Main (level 0) entries displayed in a row optionally numbered:
+  \renewcommand*{\glossaryentryfield}[5]{%
+    \glsentryitem{##1}% Entry number if required
+    \glstarget{##1}{##2}% Name
+    & ##3% Description
+    & ##4% Symbol
+    & \glsentryuseri{##1}% Units
+    & \glsentryuserii{##1}% Dimensions
+    & ##5% Page list
+    \\% end of row
+  }%
+ % Similarly for sub-entries (no sub-entry numbers):
+ \renewcommand*{\glossarysubentryfield}[6]{%
+    % ignoring first argument (sub-level)
+    \glstarget{##2}{##3}% Name
+    & ##4% Description
+    & ##5% Symbol
+    & \glsentryuseri{##2}% Units
+    & \glsentryuserii{##2}% Dimensions
+    & ##6% Page list
+    \\% end of row
+  }%
+ % Nothing between groups:
+ \renewcommand*{\glsgroupskip}{}%
+}
+\end{verbatim}
+
+
+\section{Accessibility Support}\label{sec:accsupp}
+Limited accessibility support is provided by the accompanying
+\sty{glossaries-accsupp} package, but note that this package is
+experimental and it requires the \sty{accsupp} package 
+which is also listed as experimental. This package defines
+additional keys that may be used when defining glossary entries.
+The keys are as follows:
+\begin{description}
+\item[{\gloskey{access}}] The replacement text corresponding to
+the \gloskey{name} key.
+
+\item[{\gloskey{textaccess}}] The replacement text corresponding
+to the \gloskey{text} key.
+
+\item[{\gloskey{firstaccess}}] The replacement text corresponding
+to the \gloskey{first} key.
+
+\item[{\gloskey{pluralaccess}}] The replacement text corresponding
+to the \gloskey{plural} key.
+
+\item[{\gloskey{firstpluralaccess}}] The replacement text corresponding
+to the \gloskey{firstplural} key.
+
+\item[{\gloskey{symbolaccess}}] The replacement text corresponding
+to the \gloskey{symbol} key.
+
+\item[{\gloskey{symbolpluralaccess}}] The replacement text corresponding
+to the \gloskey{symbolplural} key.
+
+\item[{\gloskey{descriptionaccess}}] The replacement text corresponding
+to the \gloskey{description} key.
+
+\item[{\gloskey{descriptionpluralaccess}}] The replacement text corresponding
+to the \gloskey{descriptionplural} key.
+
+\item[{\gloskey{longaccess}}] The replacement text corresponding to
+the \gloskey{long} key (used by \ics{newacronym}).
+
+\item[{\gloskey{shortaccess}}] The replacement text corresponding to
+the \gloskey{short} key (used by \ics{newacronym}).
+
+\item[{\gloskey{longpluralaccess}}] The replacement text corresponding to
+the \gloskey{longplural} key (used by \ics{newacronym}).
+
+\item[{\gloskey{shortpluralaccess}}] The replacement text corresponding to
+the \gloskey{shortplural} key (used by \ics{newacronym}).
+
+\end{description}
+For example:
+\begin{verbatim}
+\newglossaryentry{tex}{name={\TeX},description={Document preparation
+language},access={TeX}}
+\end{verbatim}
+Now \verb|\gls{tex}| will be equivalent to
+\begin{verbatim}
+\BeginAccSupp{ActualText=TeX}\TeX\EndAccSupp{}
+\end{verbatim}
+The sample file \samplefile{accsupp} illustrates the
+\sty{glossaries-accsupp} package.
+
+See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code
+(\texttt{glossaries.pdf}) for further details. It is recommended
+that you also read the \sty{accsupp} documentation. 
+
+\section{Troubleshooting}
+\label{sec:trouble}
+
+The \styfmt{glossaries} package comes with a minimal file called 
+\texttt{minimalgls.tex} which can be used for testing. This
+should be located in the \texttt{samples} subdirectory (folder)
+of the \styfmt{glossaries} documentation directory. The location
+varies according to your operating system and \TeX\ installation.
+For example, on my Linux partition it can be found in
+\texttt{/usr/local/texlive/2008/texmf-dist/doc/latex/glossaries/}. 
+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 \styfmt{glossaries} FAQ at
+\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}. 
+
+\begin{enumerate}
+\item \textbf{Q.} I get the error message:
+\begin{verbatim}
+Missing \begin{document}
+\end{verbatim}
+
+\textbf{A.} Check you are using an up to date version of the \sty{xkeyval}
+package.
+
+\item \textbf{Q.} When I use \gls{xindy}, I get the following error
+message:
+\begin{verbatim}
+ERROR: CHAR: index 0 should be less than the length of the string
+\end{verbatim}
+
+\textbf{A.} \gls{xindy} discards all commands and braces from the
+sort string. If your sort string (either specified by the \gloskey{sort}
+key or the \gloskey{name} key) only consists of commands, this will
+be treated by \gls*{xindy} as an empty sort string, which produces an
+error message in newer versions of \gls*{xindy}. For example, the
+following will cause a problem:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
+  description=alpha}
+\end{verbatim}
+Either use a different sort key for the entry, for example:
+\begin{verbatim}
+\newglossaryentry{alpha}{sort=alpha,
+  name={\ensuremath{\alpha}},
+  description=alpha}
+\end{verbatim}
+or, if all entries are like this, you may prefer to use the
+\pkgopt[use]{sort} or \pkgopt[def]{sort} package options. See
+\sectionref{sec:pkgopts-sort} for further details of the \pkgopt{sort}
+option.
+
+\item \textbf{Q.} I've used the \pkgopt{smallcaps} option, but the acronyms
+are displayed in normal sized upper case letters.
+
+\textbf{A.} The \pkgopt{smallcaps} package option uses \ics{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 \textbf{Q.} My acronyms won't break across a line when they're
+expanded.
+
+\textbf{A.} PDF\LaTeX\ can break hyperlinks across a line, but
+\LaTeX\ can't. If you can't use PDF\LaTeX\ then disable the \gls{firstuse}
+links using the package option \pkgopt[false]{hyperfirst}.
+
+\item \textbf{Q.} How do I change the font that the acronyms are displayed in?
+
+\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package
+option and redefine \ics{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 \textbf{Q.} How do I change the font that the acronyms are displayed in
+on \firstuse?
+
+\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package
+option and redefine \ics{firstacronymfont} to use the required 
+command. Note that if you don't want the acronym on subsequent use
+to use \ics{textsmaller}, you will also need to redefine \ics{acronymfont},
+as above. For example to make the acronym emphasized on 
+\firstuse, 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 \textbf{Q.} I don't have Perl installed, do I have to use 
+\gls{makeglossaries}?
+
+\textbf{A.} Although it is strongly recommended that you use
+\gls{makeglossaries}, you don't have to use it. For further details,
+read \sectionref{sec:xindyapp} or \sectionref{sec:makeindexapp},
+depending on whether you want to use \gls{xindy} or \gls{makeindex}.
+
+\item \textbf{Q.} I'm used to using the \styfmt{glossary} package: are there any
+instructions on migrating from the \sty{glossary} package to the
+\styfmt{glossaries} package?
+
+\textbf{A.} Read \qtdocref{Upgrading from the glossary package to
+the glossaries package}{glossary2glossaries} which should be
+available from the same location as this document.
+
+\item \textbf{Q.} I'm using \sty{babel} but the fixed names haven't
+been translated.
+
+\textbf{A.} The \styfmt{glossaries} package currently only supports
+the following languages: Brazilian Portuguese, Danish, Dutch,
+English, French, German, Irish, Italian, Hungarian, Polish, Serbian 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 \sty{translator} package with the
+required languages explicitly (before you load the \styfmt{glossaries}
+package). For example:
+\begin{verbatim}
+\usepackage[ngerman]{babel}
+\usepackage[ngerman]{translator}
+\usepackage{glossaries}
+\end{verbatim}
+Alternatively, you can add the language as a global option
+to the class file. Check the \styfmt{translator} package documentation 
+for further details.
+
+\item \textbf{Q.} My acronyms contain strange characters when I use commands
+like \ics{acrlong}.
+
+\textbf{A.} Switch off the sanitization:
+\begin{verbatim}
+\usepackage[sanitize=none]{glossaries}
+\end{verbatim}
+and protect fragile commands.
+
+\item \textbf{Q.} Weird characters appear when I use
+\ics{glsentryname} or \ics{glsname}.
+
+\textbf{A.} Either use \ics{glsentrytext} or \ics{glstext},
+respectively, or switch off the sanitization for the \gloskey{name}
+key:
+\begin{verbatim}
+\usepackage[sanitize={name=false}]{glossaries}
+\end{verbatim}
+and protect fragile commands.
+
+\item \textbf{Q.} Weird characters appear when I try to display an
+entry's description.
+
+\textbf{A.} Switch off the sanitization for the \gloskey{description}
+key:
+\begin{verbatim}
+\usepackage[sanitize={description=false}]{glossaries}
+\end{verbatim}
+and protect fragile commands.
+
+\item \textbf{Q.} My glossaries haven't appeared.
+
+\textbf{A.} 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 the commands listed in \sectionref{sec:glslink},
+\sectionref{sec:glsadd} or \sectionref{sec:crossref} for each entry
+that you want to appear in the glossary.
+
+\item Run \LaTeX\ on your document, then run \gls{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. If any of your entries cross-reference an entry that's not
+referenced in the main body of the document, you will need to run
+\gls*{makeglossaries} (see \sectionref{sec:makeglossaries}) after the
+second \LaTeX\ run, followed by another \LaTeX\ run.
+\end{itemize}
+
+Check the log files (\filetype{.log}, \filetype{.glg} etc) for any 
+warnings.
+
+\item \textbf{Q.} It is possible to change the rules used to sort
+the glossary entries?
+
+\textbf{A.} If it's for an individual entry, then you can use the
+entry's \gloskey{sort} key to sort it according to a different term.
+If it's for the entire alphabet, then you will need to use
+\gls{xindy} (instead of \gls{makeindex}) and use an appropriate
+\gls*{xindy} language module. Writing \gls*{xindy} modules or styles
+is beyond the scope of this manual. Further information about
+\gls*{xindy} can be found at the
+\urlfootref{http://xindy.sourceforge.net/}{Xindy Web Site}. There is
+also a link to the \gls*{xindy} mailing list from that site.
+
+If you want to sort according to order of definition or order of
+use, use the \pkgopt{sort} package option described in 
+\sectionref{sec:pkgopts-sort}.
+
+\end{enumerate}
+
+
+\clearpage\phantomsection
+\addcontentsline{toc}{section}{Index}\PrintIndex
+
+\end{document}