summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/glossaries/glossaries-user.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')
-rw-r--r--macros/latex/contrib/glossaries/glossaries-user.tex13059
1 files changed, 13059 insertions, 0 deletions
diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex
new file mode 100644
index 0000000000..698933ac27
--- /dev/null
+++ b/macros/latex/contrib/glossaries/glossaries-user.tex
@@ -0,0 +1,13059 @@
+\documentclass[report,inlinetitle,widecs]{nlctdoc}
+
+\usepackage[inner=0.5in,includemp]{geometry}
+
+\usepackage{array}
+\usepackage{alltt}
+\usepackage{pifont}
+\usepackage{textcomp}
+\usepackage{amssymb}
+\ifpdf
+ \usepackage{lmodern}
+ \usepackage{mathpazo}
+ \usepackage[scaled=.88]{helvet}
+ \usepackage{courier}
+ \usepackage{metalogo}
+\else
+ \newcommand{\grimace}{{\fontencoding {U}\fontfamily{futs}\selectfont \char77}}
+ \providecommand{\XeLaTeX}{XeLaTeX}
+ \providecommand{\XeTeX}{XeTeX}
+\fi
+\usepackage[colorlinks,
+ bookmarks,
+ linkcolor=blue,
+ 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,
+ toc,
+ nopostdot,
+ nogroupskip,
+ style=altlist
+]{glossaries}
+\usepackage{glossary-inline}
+
+\pagestyle{headings}
+
+\glsnoexpandfields
+
+\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,\\
+ toc,\\
+ nopostdot,\\
+ style=altlist,\\
+ nogroupskip]\{glossaries\}
+\end{tabbing}
+\end{ttfamily}
+}
+
+\ifpdf
+\else
+ % Need an extra line break in the html version
+ % (Don't have time to fiddle with cfg files!)
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{#1}\glstarget{#1}{\glossentryname{#1}}]\mbox{}\newline
+ \glossentrydesc{#1}\glspostdescription\space #2\newline}%
+\fi
+
+\makeglossaries
+
+\renewcommand*{\main}[1]{\hyperpage{#1}}
+\newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}}
+\newcommand*{\itermdef}[1]{\index{#1|htextbf}}
+
+\newcommand{\itempar}[1]{\item[{#1}]\mbox{}\par}
+
+\newcommand{\pkgoptdef}[1]{\hypertarget{pkgopt:#1}{\pkgopt{#1}}}
+
+\newcommand{\glslike}{\hyperref[sec:gls-like]{\cs{gls}-like}}
+\newcommand{\glstextlike}{\hyperref[sec:glstext-like]{\cs{glstext}-like}}
+
+\IndexPrologue{\chapter*{\indexname}
+ \addcontentsline{toc}{chapter}{\indexname}%
+ \markboth{\indexname}{\indexname}}
+
+\longnewglossaryentry{indexingapp}%
+{
+ name={Indexing application},
+ text={indexing application}
+}%
+{%
+ An application (piece of software) separate from
+ \TeX/\LaTeX\ that collates and sorts information that has an
+ associated page reference. Generally the information is an index
+ entry but in this case the information is a glossary entry.
+ There are two main indexing applications that are used with \TeX:
+ \gls{makeindex} and \gls{xindy}. These are both
+ \gls{cli} applications.
+}
+
+\longnewglossaryentry{cli}
+{
+ name={Command Line Interface (CLI)},
+ first={command line interface (CLI)},
+ text={CLI}
+}
+{%
+ An application that doesn't have a graphical user
+ interface. That is, an application that doesn't have any windows,
+ buttons or menus and can be run in
+ \href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{a command
+ prompt or terminal}.
+}
+
+\longnewglossaryentry{xindy}{%
+ name={\appfmt{xindy}\index{xindy=\appfmt{xindy}|htextbf}},
+ sort={xindy},
+ text={\appfmt{xindy}\iapp{xindy}}
+}%
+{%
+ A flexible \gls{indexingapp} with multilingual
+ support written in Perl.
+}
+
+\newglossaryentry{makeindex}{%
+name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},%
+sort={makeindex},%
+text={\appfmt{makeindex}\iapp{makeindex}},%
+description={An \gls{indexingapp}.}
+}
+
+\newglossaryentry{bib2gls}{%
+name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},%
+sort={bib2gls},%
+text={\appfmt{bib2gls}\iapp{bib2gls}},%
+description={An \gls{indexingapp} that combines two functions in
+one: (1) fetches entry definition from a \texttt{.bib} file
+based on information provided in the \texttt{.aux} file (similar
+to \appfmt{bibtex}); (2) hierarchically sorts and collates location
+lists (similar to \appfmt{makeindex} and \appfmt{xindy}).
+This application is designed for use with \styfmt{glossaries-extra}
+and can't be used with just the base \styfmt{glossaries} package.}
+}
+
+\newglossaryentry{makeglossaries}{%
+name={\appfmt{makeglossaries}\index{makeglossaries=\appfmt{makeglossaries}|htextbf}},%
+sort={makeglossaries},%
+text={\appfmt{makeglossaries}\iapp{makeglossaries}},%
+description={A custom designed Perl script interface
+to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
+package. \TeX\ distributions on Windows convert the original
+\texttt{makeglossaries} script into an executable
+\texttt{makeglossaries.exe} for convenience (but Perl is still
+required).}
+}
+
+\newglossaryentry{makeglossaries-lite.lua}{%
+name={\appfmt{makeglossaries-lite}\index{makeglossaries-lite=\appfmt{makeglossaries-lite}|htextbf}},%
+sort={makeglossaries-lite},%
+text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},%
+description={A custom designed Lua script interface
+to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
+package. This is a cut-down alternative to the Perl
+\appfmt{makeglossaries} script. If you have Perl installed, use the
+Perl script instead. This script is actually distributed with the
+file name \texttt{makeglossaries-lite.lua}, but \TeX~Live
+(on Unix-like systems) creates a symbolic link
+called \texttt{makeglossaries-lite} (without the \texttt{.lua}
+extension) to the actual \texttt{makeglossaries-lite.lua} script.}
+}
+
+\longnewglossaryentry{makeglossariesgui}{%
+name={\appfmt{makeglossariesgui}\index{makeglossariesgui=\appfmt{makeglossariesgui}|htextbf}},%
+sort={makeglossariesgui},%
+text={\appfmt{makeglossariesgui}\iapp{makeglossariesgui}}%
+}%
+{%
+ A Java GUI alternative to \gls{makeglossaries} that
+ also provides diagnostic tools. Available separately on
+ \href{http://ctan.org/pkg/makeglossariesgui}{CTAN}.
+}
+
+\newglossaryentry{numberlist}{%
+name={Number list\itermdef{number list}},%
+sort={number list},%
+text={number list\iterm{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={entry location\iterm{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},%
+text={location list},
+sort={location list},%
+description={A list of \glslink{entrylocation}{entry locations}.
+See \gls{numberlist}.}%
+}
+
+\newglossaryentry{linktext}{%
+name={Link text\itermdef{link text}},
+sort={link text},%
+text={link text\iterm{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
+
+\longnewglossaryentry{firstuse}{%
+name={First use\ifirstuse},
+sort={first use},%
+text={first use},%
+user1={first used}}
+{%
+ 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}{}
+}
+
+\longnewglossaryentry{firstuseflag}{%
+name={First use flag\ifirstuseflag},
+sort={first use flag},%
+text={first use flag}%
+}
+{%
+ 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} or by \ics{defglsentry}.)}%
+}
+
+\longnewglossaryentry{sanitize}{%
+name={Sanitize\itermdef{sanitize}},%
+sort={sanitize},
+text={sanitize\iterm{sanitize}},%
+user1={sanitized\protect\iterm{sanitize}},%
+user2={sanitization\protect\iterm{sanitize}}%
+}%
+{%
+ 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.
+
+ Earlier versions of \styfmt{glossaries} used this technique to write
+ information to the files used by the indexing applications to
+ prevent problems caused by fragile commands. Now, this is only used
+ for the \gloskey{sort} key.
+}
+
+\newglossaryentry{latinchar}{%
+ name={Latin Character\itermdef{Latin character}},
+ text={Latin character\iterm{Latin character}},
+ sort={Latin character},
+ description={One of the letters \texttt{a}, \ldots, \texttt{z},
+ \texttt{A}, \ldots, \texttt{Z}\@.
+ See also \gls{exlatinchar}.}
+}
+
+\newglossaryentry{exlatinchar}{%
+ name={Extended Latin Character\itermdef{extended Latin character}},
+ text={extended Latin character\iterm{extended Latin character}},
+ sort={extended Latin character},
+ description={A character that's created by combining \glspl{latinchar}
+ to form ligatures (e.g.\ \ae) or by applying diacritical marks
+ to a~\gls*{latinchar} or characters (e.g.\ \'a or \o).
+ See also \gls{nonlatinchar}.}
+}
+
+\newglossaryentry{latexexlatinchar}{%
+ name={Standard \LaTeX\ Extended Latin Character\itermdef{standard
+\LaTeX\ extended Latin character}},
+ text={standard \LaTeX\ extended Latin character\iterm{standard
+\LaTeX\ extended Latin character}},
+ sort={standard LaTeX extended Latin character},
+ description={An \gls{exlatinchar} that can be created by a~core
+\LaTeX\ command, such as \cs{o} (\o) or \cs{'}\texttt{e} (\'e).
+ That is, the character can be produced without the need to load
+ a~particular package.}
+}
+
+\newglossaryentry{nonlatinchar}{%
+ name={Non-Latin Character\itermdef{non-Latin character}},
+ text={non-Latin character\iterm{non-Latin character}},
+ sort={non-Latin character},
+ description={An \gls{exlatinchar} or a~character that isn't
+ a~\gls{latinchar}.}
+}
+
+\newglossaryentry{latinalph}{%
+ name={Latin Alphabet\itermdef{Latin alphabet}},
+ text={Latin alphabet\iterm{Latin alphabet}},
+ sort={Latin alphabet},
+ description={The alphabet consisting of \glspl{latinchar}.
+ See also \gls{exlatinalph}.}
+}
+
+\newglossaryentry{exlatinalph}{%
+ name={Extended Latin Alphabet\itermdef{Extended Latin Alphabet}},
+ text={extended Latin alphabet},
+ sort={extended Latin alphabet},
+ description={An alphabet consisting of \glspl{latinchar}
+ and \glspl{exlatinchar}.}
+}
+
+\newglossaryentry{nonlatinalph}{%
+ name={Non-Latin Alphabet\itermdef{Non-Latin Alphabet}},
+ text={non-Latin alphabet},
+ sort={non-Latin alphabet},
+ description={An alphabet consisting of \glspl{nonlatinchar}.}
+}
+
+\newglossaryentry{glossaries-extra}{%
+ name={\styfmt{glossaries-extra}},
+ sort={glossaries-extra},
+ description={A separate package that extends the
+ \styfmt{glossaries} package, providing new features or improving
+ existing features. If you want to use \styfmt{glossaries-extra},
+ you must have both the \styfmt{glossaries} package and the
+ \styfmt{glossaries-extra} package installed.}
+}
+
+\ifpdf
+\externaldocument{glossaries-code}
+\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*{\yes}{\ding{52}}
+\newcommand*{\no}{\ding{56}}
+
+\newcommand*{\proyes}{\textcolor{green}{\yes}}
+\newcommand*{\prono}{\textcolor{red}{\no}}
+
+\newcommand*{\conyes}{\textcolor{red}{\yes}}
+\newcommand*{\conno}{\textcolor{green}{\no}}
+
+\makeatletter
+\newcommand{\fnsymmark}[1]{#1}
+\newcommand*{\fnsym}[1]{\textsuperscript{\fnsymmark{%
+ \ifcase#1\or \textasteriskcentered \or \textdagger
+ \or \textdaggerdbl \or \textsection
+ \or $\lozenge$ \or \textparagraph
+ \or \#\or {\fontfamily{cmr}\selectfont\textreferencemark}%
+ \or \@nlctdoc@if@usingtexht{\HCode{&\#x2051;}}{\shortstack{*\\[-1.5ex]*}}%
+ \or $\star$
+ \or \ding{94}%
+ \else
+ \number#1
+ \fi
+}}}%
+\newcommand*{\optionlabel}[1]{%
+ \@glstarget{option#1}{Option~#1}}
+\makeatother
+
+\newcounter{option}
+\newcommand{\optionsec}[2][\opttitle]{%
+ \def\opttitle{\appfmt{#2}}%
+ \refstepcounter{option}%
+ \pdfbookmark[2]{Option~\theoption\space (#2)}{option\theoption}%
+ \subsection*{\protect\optionlabel{\theoption} (#1)}%
+}
+
+\newcommand*{\opt}[1]{\hyperlink{option#1}{Option~#1}}
+\newcommand*{\optsor}[2]{Options~\hyperlink{option#1}{#1}
+or~\hyperlink{option#2}{#2}}
+\newcommand*{\optsand}[2]{Options~\hyperlink{option#1}{#1}
+and~\hyperlink{option#2}{#2}}
+
+
+\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*{\mkidxopt}[1]{\texttt{-#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{-#1}|hyperpage}}
+
+\newcommand*{\xdyopt}[1]{\texttt{-#1}\index{xindy=\appfmt{xindy}>#1=\texttt{-#1}|hyperpage}}
+
+\newcommand*{\mkglsopt}[1]{\texttt{-#1}\index{makeglossaries=\appfmt{makeglossaries}>#1=\texttt{-#1}|hyperpage}}
+
+\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
+\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+\newcommand*{\optfmt}[1]{\textsf{#1}}
+\newcommand*{\field}[1]{\optfmt{#1}\index{internal fields:>#1=\protect\optfmt{#1}|main}}
+
+\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}}
+
+\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym styles:>#1={\protect\ttfamily#1}|main}}
+
+\newcounter{sample}
+\newcommand{\exitem}[2][sample]{%
+ \item[\texttt{#1#2.tex}]%
+ \refstepcounter{sample}\label{ex:#1#2}}
+
+\newenvironment{samplelist}%
+{\begin{description}}%
+{\end{description}}
+
+\newcommand*{\samplefile}[2][sample]{%
+ \hyperref[ex:#1#2]{\texttt{#1#2.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 v4.42}
+ \author{Nicola L.C. Talbot\\%
+ \url{http://www.dickimaw-books.com/}}
+
+ \date{2019-01-06}
+ \maketitle
+
+\begin{abstract}
+The \styfmt{glossaries} package provides a means to define terms or
+abbreviations or symbols that can be referenced within your document.
+Sorted lists with collated \glslink{entrylocation}{locations} can be
+generated either using \TeX\ or using a supplementary \gls{indexingapp}.
+
+Additional features not provided here may be available through
+the extension package \gls{glossaries-extra} which, if required,
+needs to be installed separately. New features will be added to
+\gls*{glossaries-extra}. Versions of the \styfmt{glossaries}
+package after v4.21 will mostly be just bug fixes. Note that
+\gls{glossaries-extra} provides an extra indexing option
+(\gls{bib2gls}) which isn't available with just the base
+\sty{glossaries} package.
+\end{abstract}
+
+If you require multilingual support you must also separately install
+the relevant language module. Each language module is distributed
+under the name \texttt{glossaries-}\meta{language}, where \meta{language} is the
+root language name. For example, \texttt{glossaries-french}
+or \texttt{glossaries-german}. If a language module is required,
+the \styfmt{glossaries} package will automatically try to load it and
+will give a warning if the module isn't found. See
+\sectionref{sec:languages} for further details.
+If there isn't any support available for your language, use
+the \pkgopt{nolangwarn} package option to suppress the warning
+and provide your own translations. (For example, use
+the \gloskey[printglossary]{title} key in \cs{printglossary}.)
+
+The \styfmt{glossaries} package requires a number of other packages
+including, but not limited to, \sty{tracklang}, \sty{mfirstuc},
+\sty{etoolbox},
+\sty{xkeyval} (at least version dated 2006/11/18), \sty{textcase},
+\sty{xfor}, \sty{datatool-base} (part of the \sty{datatool} bundle) and \sty{amsgen}. These
+packages are all available in the latest \TeX~Live and Mik\TeX\
+distributions. If any of them are missing, please update your
+\TeX\ distribution using your update manager.
+For help on this see, for example,
+\href{http://tex.stackexchange.com/questions/55437/how-do-i-update-my-tex-distribution}{How
+do I update my \TeX\ distribution?}
+or (for Linux users)
+\href{http://tex.stackexchange.com/questions/14925/updating-tex-on-linux}{Updating
+\TeX\ on Linux}.
+
+Note that occasionally you may find that certain packages need to be
+loaded \emph{after} packages that are required by \styfmt{glossaries}. For
+example, a package \meta{X} might need to be loaded after \sty{amsgen}. In
+which case, load the required package first (for example,
+\sty{amsgen}), then \meta{X}, and finally load \styfmt{glossaries}.
+
+\begin{important}
+Documents have wide-ranging styles when it comes to presenting glossaries
+or lists of terms or notation. People have their own preferences and
+to a large extent this is determined by the kind of information that
+needs to go in the glossary. They may just have symbols with
+terse descriptions or they may have long technical words with
+complicated descriptions. The \styfmt{glossaries} package is
+flexible enough to accommodate such varied requirements, but this
+flexibility comes at a price: a~big manual.
+
+\aargh\ If you're freaking out at the size of this manual, start with
+\texttt{glossariesbegin.pdf} (\qt{The glossaries package: a guide
+for beginnners}). You should find it in the same directory as this
+document or try \texttt{texdoc glossariesbegin.pdf}. Once you've got
+to grips with the basics, then come back to this manual to find out
+how to adjust the settings.
+\end{important}
+
+\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{glossaries-code.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 v4.42}.
+
+\item[INSTALL] Installation instructions.
+
+\item[CHANGES] Change log.
+
+\item[README] Package summary.
+
+\end{description}
+Related resources:
+\begin{itemize}
+\item \styfmt{glossaries-extra} and \gls{bib2gls}: An Introductory
+Guide. (\href{http://mirrors.ctan.org/support/bib2gls/bib2gls-begin.pdf}{\texttt{bib2gls-begin.pdf}}).
+
+
+\item \href{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries}
+FAQ}
+
+\item \href{http://www.dickimaw-books.com/gallery/#glossaries}{\styfmt{glossaries}
+gallery}
+
+\item
+\href{http://www.dickimaw-books.com/gallery/glossaries-styles/}{a
+summary of all glossary styles provided by \styfmt{glossaries}}
+
+\item
+\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries}
+performance} (comparing document build times for the different
+options provided by \styfmt{glossaries} and \styfmt{glossaries-extra}).
+
+\item \href{http://www.dickimaw-books.com/latex/thesis/}{Using LaTeX to Write a PhD Thesis}
+(chapter 6).
+
+\item
+\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build}
+
+\item The
+\href{http://ctan.org/pkg/glossaries-extra}{\styfmt{glossaries-extra} package}
+
+\item \href{http://ctan.org/pkg/bib2gls}{\appfmt{bib2gls}}
+\end{itemize}
+
+\begin{important}
+If you use \sty{hyperref} and \styfmt{glossaries}, you must load
+\sty{hyperref} \emph{first}. Similarly the \sty{doc} package must
+also be loaded before \styfmt{glossaries}. (If \sty{doc} is loaded,
+the file extensions for the default main glossary are changed to
+\filetype{gls2}, \filetype{glo2} and \filetype{.glg2} to avoid
+conflict with \sty{doc}'s changes
+glossary.)\hypertarget{pdflatexnote}{}%
+
+If you are using \sty{hyperref}, it's best to use \app{pdflatex}
+rather than \app{latex} (DVI format) as \appfmt{pdflatex} deals with
+hyperlinks much better. If you use the DVI format, you will
+encounter problems where you have long hyperlinks or hyperlinks in
+subscripts or superscripts. This is an issue with the DVI format not
+with \styfmt{glossaries}. If you really need to use the DVI format
+and have a problem with hyperlinks in maths mode, I recommend you use
+\gls{glossaries-extra} with the \texttt{hyperoutside} and
+\texttt{textformat} attributes set to appropriate values
+for problematic entries.
+\end{important}
+
+\clearpage
+\pdfbookmark[0]{Contents}{contents}
+\tableofcontents
+\clearpage
+\pdfbookmark[0]{List of Examples}{examples}
+\listofexamples
+\clearpage
+\pdfbookmark[0]{List of Tables}{tables}
+\listoftables
+
+\clearpage
+\printglossaries
+
+\glsresetall
+
+ \chapter{Introduction}
+\label{sec:intro}
+
+The \styfmt{glossaries} package is provided to assist generating
+lists of terms, symbols or abbreviations. (For convenience, these
+lists are all referred to as glossaries in this manual.)
+The package has a certain amount of flexibility, allowing the
+user to customize the format of the glossary and define multiple
+glossaries. It also supports 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 indexed\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.
+
+The \styfmt{glossaries-extra} package, which is distributed as a
+separated bundle, extends the capabilities of
+the \styfmt{glossaries} package. The simplest document can be
+created with \styfmt{glossaries-extra} (which internally loads the
+\styfmt{glossaries} package):
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[
+ sort=none,% no sorting or indexing required
+ abbreviations,% create list of abbreviations
+ symbols,% create list of symbols
+ postdot % append a full stop after the descriptions
+]{glossaries-extra}
+
+\newglossaryentry % provided by glossaries.sty
+ {cafe}% label
+ {% definition:
+ name={caf\'e},
+ description={small restaurant selling refreshments}
+ }
+
+\newabbreviation % provided by glossaries-extra.sty
+ {html}% label
+ {HTML}% short form
+ {hypertext markup language}% long form
+
+\glsxtrnewsymbol % provided by glossaries-extra.sty 'symbols' option
+ [description={Archimedes' constant}]% options
+ {pi}% label
+ {\ensuremath{\pi}}% symbol
+
+\begin{document}
+First use: \gls{cafe}, \gls{html}, \gls{pi}.
+Next use: \gls{cafe}, \gls{html}, \gls{pi}.
+
+\printunsrtglossaries % list all defined entries
+\end{document}
+\end{verbatim}
+
+\textbf{The \styfmt{glossaries} 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 covers 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}
+There's a~common misconception that you have to have Perl installed
+in order to use the \styfmt{glossaries} package. Perl is \emph{not}
+a~requirement but it does increase the available options,
+particularly if you use an \gls{exlatinalph} or a~\gls{nonlatinalph}.
+\end{important}
+
+This document uses the \styfmt{glossaries} package. For example,
+when viewing the PDF version of this document in a
+hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
+you click on the word \qt{\gls{xindy}} you'll be taken to the entry
+in the glossary where there's a brief description of
+the term \qt{\gls*{xindy}}. This is the way the \styfmt{glossaries}
+mechanism works. An \gls{indexingapp} is used to generated the
+sorted list of terms. The \glspl{indexingapp} are \gls{cli} tools,
+which means they can be run directly from a command prompt or terminal, or can
+be integrated into some text editors, or you can use a build tool
+such as \app{arara} to run them.
+
+The remainder of this introductory section covers the following:
+\begin{itemize}
+\item \sectionref{sec:indexingoptions} lists the available indexing
+options.
+
+\item \sectionref{sec:samples} lists the sample documents provided
+with this package.
+
+\item \sectionref{sec:lipsum} lists the dummy glossary files that
+may be used for testing.
+
+\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 an
+\gls{indexingapp} to create the sorted glossaries for your document
+(\optsor23).
+
+\end{itemize}
+
+\section{Indexing Options}
+\label{sec:indexingoptions}
+
+The basic idea behind the \styfmt{glossaries} package is that you
+first define your entries (terms, symbols or abbreviations). Then
+you can reference these within your document (like \cs{cite} or
+\cs{ref}). You can also, optionally, display a~list of the entries
+you have referenced in your document (the glossary). This last part,
+displaying the glossary, is the part that most new users find
+difficult. There are three options available with the base
+\styfmt{glossaries} package and two further options with the
+extension package \gls{glossaries-extra}.
+An overview of these options is given in
+\tableref{tab:options}.
+
+If you are developing a class or package that loads
+\styfmt{glossaries}, I recommend that you don't force the user into
+a particular indexing method by adding an unconditional \cs{makeglossaries}
+into your class or package code. Aside from forcing the user into a
+particular indexing method, it means that they're unable to use any
+commands that must come before \cs{makeglossaries} (such as
+\cs{newglossary}) and they can't switch off the indexing whilst
+working on a draft document.
+
+For a comparison of the various methods when used with large entry
+sets or when used with symbols such as \cs{alpha}, see the
+\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} performance page}.
+
+\begin{table}[htbp]
+ \caption{Glossary Options: Pros and Cons}
+ \label{tab:options}
+ {%
+ \renewcommand{\fnsymmark}[1]{\rlap{#1}}%
+ \setlength{\tabcolsep}{3pt}%
+ \centering
+ \begin{tabular}{@{}>{\raggedright\small}p{0.35\textwidth}ccccc@{}}
+ & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3
+ & \bfseries \opt4 & \bfseries \opt5\\
+ Requires \gls{glossaries-extra}? &
+ \conno & \conno & \conno & \conyes & \conyes\\
+ Requires an external application? &
+ \conno & \conyes & \conyes & \conyes & \conno\\
+ Requires Perl? &
+ \conno & \conno & \conyes & \conno & \conno\\
+ Requires Java? &
+ \conno & \conno & \conno & \conyes & \conno\\
+ Can sort \glspl{exlatinalph}
+ or \glspl{nonlatinalph}? &
+ \prono\fnsym{1} & \prono & \proyes & \proyes & N/A\\
+ Efficient sort algorithm? &
+ \prono & \proyes & \proyes & \proyes & N/A\\
+ Can use a different sort method for each glossary? &
+ \proyes
+ & \prono\fnsym{2}
+ & \prono\fnsym{2} & \proyes & N/A\\
+ Any problematic sort values? &
+ \conyes & \conyes & \conyes & \conno & \conno\fnsym{3}\\
+ Are entries with identical sort values treated as separate unique
+ entries? &
+ \proyes & \proyes & \prono\fnsym{4} & \proyes & \proyes\\
+ Can automatically form ranges in the location lists? &
+ \prono & \proyes & \proyes & \proyes & \prono\\
+ Can have non-standard locations in the location lists? &
+ \proyes & \prono
+ & \proyes\fnsym{5}
+ & \proyes
+ & \proyes\fnsym{6}\\
+ Maximum hierarchical depth (style-dependent) &
+ $\infty$\fnsym{7} & 3 & $\infty$ & $\infty$ & $\infty$\\
+ \ics{glsdisplaynumberlist} reliable? &
+ \proyes & \prono & \prono & \proyes & \prono\\
+ \ics{newglossaryentry} allowed in \env{document} environment?
+ (Not recommended.) &
+ \no & \yes & \yes & \no\fnsym{8} & \yes\fnsym{9}\\
+ Requires additional write registers? &
+ \conno & \conyes & \conyes & \conno & \conno\fnsym{10}\\
+ Default value of \pkgopt{sanitizesort} package option &
+ \texttt{false} & \texttt{true} & \texttt{true}
+ & \texttt{true}\fnsym{11}
+ & \texttt{true}\fnsym{11}
+ \end{tabular}
+ \par
+ }\par
+ \smallskip
+ \hrulefill\par
+ \smallskip\footnotesize
+ \fnsym{1} Strips standard \LaTeX\ accents
+(that is, accents generated by core \LaTeX\ commands) so,
+for example, \ics{AA} is treated the same as A.\par
+ \fnsym{2} Only with the hybrid method provided with \sty{glossaries-extra}.\par
+ \fnsym{3} Provided \pkgopt[none]{sort} is used.\par
+ \fnsym{4} Entries with the same sort value are merged.\par
+ \fnsym{5} Requires some setting up.\par
+ \fnsym{6} The locations must be set explicitly
+through the custom \field{location} field provided by
+\styfmt{glossaries-extra}.\par
+ \fnsym{7} Unlimited but unreliable.\par
+ \fnsym{8} Entries are defined in \texttt{.bib}
+format. \cs{newglossaryentry} should not be used explicitly.\par
+ \fnsym{9} Provided \pkgoptfmt{docdefs=true} or
+\pkgoptfmt{docdefs=restricted} but not recommended.\par
+ \fnsym{10} Provided \pkgoptfmt{docdefs=false} or
+\pkgoptfmt{docdefs=restricted}.\par
+ \fnsym{11} Irrelevant with \pkgopt[none]{sort}. (The \optfmt{record=only}
+ option automatically switches this on.)
+\par
+\end{table}
+
+\optionsec[\TeX]{TeX}
+
+This option doesn't require an external \gls{indexingapp} but, with
+the default alphabetic sorting, it's very slow with severe limitations.
+If you want a sorted list, it doesn't work well for
+\glspl{exlatinalph} or \glspl{nonlatinalph}. However, if you use
+the \pkgopt[false]{sanitizesort} package option (the default for
+Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\
+accent commands} will be ignored, so if an entry's name is set to
+\verb|{\'e}lite| then the sort value will default to \texttt{elite} if
+\pkgopt[false]{sanitizesort} is used and will default to
+\verb|\'elite| if \pkgopt[true]{sanitizesort} is used. If you have
+any other kinds of commands that don't expand to ASCII characters,
+such as \cs{alpha} or \cs{si}, then you must use
+\pkgopt[true]{sanitizesort} or change the sort method
+(\pkgopt[use]{sort} or \pkgopt[def]{sort}) in the package options
+or explicitly set the \gloskey{sort} key when you define the
+relevant entries. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
+ sort={alpha},description={...}}
+\end{verbatim}
+
+This option works best with the \pkgopt[def]{sort} or
+\pkgopt[use]{sort} setting. For any
+other setting, be prepared for a long document build time,
+especially if you have a lot of entries defined. \textbf{This
+option is intended as a last resort for alphabetical sorting.}
+This option allows a mixture of sort methods. (For example,
+sorting by word order for one glossary and order of use for another.)
+This option is not suitable for hierarchical glossaries and does
+not form ranges in the \glspl{numberlist}. If you really can't use an
+\gls{indexingapp} consider using \opt{5} instead.
+
+ \begin{enumerate}
+ \item Add
+\begin{verbatim}
+\makenoidxglossaries
+\end{verbatim}
+ to your preamble (before you start defining your entries, as described in
+ \sectionref{sec:newglosentry}).
+
+ \item Put
+\begin{verbatim}
+\printnoidxglossary
+\end{verbatim}
+ where you want your list of entries to appear (described in
+ \sectionref{sec:printglossary}). Alternatively, to display all
+ glossaries use the iterative command:
+\begin{verbatim}
+\printnoidxglossaries
+\end{verbatim}
+
+ \item Run \LaTeX\ twice on your document. (As you would do to
+ make a~table of contents appear.) For example, click twice on
+ the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor.
+ \end{enumerate}
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makenoidxglossaries % use TeX to sort
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printnoidxglossary
+\end{document}
+\end{verbatim}
+
+\optionsec{makeindex}
+
+This option uses a~\gls{cli} application called \gls{makeindex} to sort
+the entries. This application comes with all modern \TeX\ distributions,
+but it's hard-coded for the non-extended \gls{latinalph}. It can't
+correctly sort accent commands (such as \cs{'} or \cs{c}) and fails
+with UTF-8 characters, especially for any sort values that start
+with a UTF-8 character (as it separates the octets resulting in an
+invalid file encoding). This process involves making \LaTeX\ write
+the glossary information to a temporary file which \gls{makeindex}
+reads. Then \gls{makeindex} writes a~new file containing the code
+to typeset the glossary. Then \cs{printglossary} reads this file in
+on the next run.
+
+This option works best if you want to sort entries according to the
+English alphabet and you don't want to install Perl (or Java or
+you don't want to use \gls{glossaries-extra}). This method can
+also work with the restricted shell escape since \gls{makeindex}
+is considered a trusted application. (So you should be able to
+use the \pkgopt{automake} package option provided the shell
+escape hasn't been completely disabled.)
+
+This method can form ranges in the \gls{numberlist} but only
+accepts limited number formats: \cs{arabic}, \cs{roman},
+\cs{Roman}, \cs{alph} and \cs{Alph}.
+
+This option does not allow a mixture of sort methods.
+All glossaries must be sorted according to the same method:
+word\slash letter ordering or order of use or order of definition.
+If you need word ordering for one glossary and letter ordering
+for another you'll have to explicitly call \gls{makeindex} for
+each glossary type.
+(The \sty{glossaries-extra} package allows a hybrid mix of
+\optsand12 to provide word\slash letter ordering with \opt2 and order
+of use\slash definition with \opt1. See the \sty{glossaries-extra}
+documentation for further details.)
+
+ \begin{enumerate}
+ \item If you want to use \gls{makeindex}['s] \mkidxopt{g} option
+ you must change the quote character using \ics{GlsSetQuote}. For example:
+\begin{verbatim}
+\GlsSetQuote{+}
+\end{verbatim}
+ This must be used before \cs{makeglossaries}.
+ Note that if you are using \sty{babel}, the shorthands aren't
+ enabled until the start of the document, so you won't be able to use
+ the shorthands in definitions made in the preamble.
+
+ \item Add
+\begin{verbatim}
+\makeglossaries
+\end{verbatim}
+to your preamble (before you start
+ defining your entries, as described in
+ \sectionref{sec:newglosentry}).
+
+ \item Put
+\begin{verbatim}
+\printglossary
+\end{verbatim}
+ where you want your list of entries to appear (described in
+ \sectionref{sec:printglossary}). Alternatively, to display all
+ glossaries use the iterative command:
+\begin{verbatim}
+\printglossaries
+\end{verbatim}
+
+ \item Run \LaTeX\ on your document. This creates files with the
+ extensions \texttt{.glo} and \texttt{.ist} (for example, if your
+ \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
+ two extra files called \texttt{myDoc.glo} and \texttt{myDoc.ist}).
+ If you look at your document at this point, you won't see the
+ glossary as it hasn't been created yet. (If you use
+ \sty{glossaries-extra} you'll see the section heading and some
+ boilerplate text.)
+
+ \item Run \gls{makeindex} with the \texttt{.glo} file as the
+ input file and the \texttt{.ist} file as the style so that
+ it creates an output file with the extension \texttt{.gls}. If
+ you have access to a terminal or a command prompt (for example, the
+ MSDOS command prompt for Windows users or the bash console for
+ Unix-like users) then you need to run the command:
+\begin{verbatim}
+makeindex -s myDoc.ist -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (Replace \texttt{myDoc} with the base name of your \LaTeX\
+ document file. Avoid spaces in the file name if possible.) If you don't know
+ how to use the command prompt, then you can probably access
+ \gls{makeindex} via your text editor, but each editor has a
+ different method of doing this, so I~can't give a~general
+ description. You will have to check your editor's manual. The
+ simplest approach is to use \app{arara} and add the following
+ comment lines to the start of your document:
+\begin{alltt}
+\% arara:\ pdflatex
+\% arara:\ makeglossaries
+\% arara:\ pdflatex
+\end{alltt}
+ (Replace \texttt{makeglossaries} with
+ \texttt{makeglossaries-lite} if you don't have Perl installed.)
+
+ The default sort is word order (\qt{sea lion} comes before \qt{seal}).
+ If you want letter ordering you need to add the \mkidxopt{l}
+ switch:
+\begin{verbatim}
+makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (See \sectionref{sec:makeindexapp} for further details on using
+ \gls*{makeindex} explicitly.) If you use \gls{makeglossaries}
+ or \gls{makeglossaries-lite.lua} then use the \pkgopt[letter]{order}
+ package option and the \mkidxopt{l} option will be added
+ automatically.
+
+ \item Once you have successfully completed the previous step,
+ you can now run \LaTeX\ on your document again. You'll need to
+ repeat the process if you have used the \pkgopt{toc} option
+ (unless you're using \sty{glossaries-extra}) to ensure the
+ section heading is added to the table of contents. You'll also
+ need to repeat the process if you have any cross-references
+ which can't be indexed until the glossary file has been created.
+ \end{enumerate}
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries % open glossary files
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printglossary
+\end{document}
+\end{verbatim}
+
+\optionsec{xindy}
+
+This option uses a~\gls{cli} application called
+\gls{xindy} to sort the entries. This application is more flexible than
+\texttt{makeindex} and is able to sort \glspl{exlatinalph} or
+\glspl{nonlatinalph}, however it does still have some limitations.
+
+The \gls{xindy} application comes with both \TeX~Live and
+MiK\TeX, but since \gls{xindy} is a Perl script, you will also need
+to install Perl, if you don't already have it. In a~similar way to
+\opt2, this option involves making \LaTeX\ write the glossary
+information to a~temporary file which \gls{xindy} reads. Then
+\gls{xindy} writes a~new file containing the code to typeset the
+glossary. Then \cs{printglossary} reads this file in on the next run.
+
+This is the best option with just the base \styfmt{glossaries}
+package if you want to sort according to a~language other than
+English or if you want non-standard location lists, but it can
+require some setting up (see \sectionref{sec:xindy}). There are
+some problems with certain sort values:
+\begin{itemize}
+ \item entries with the same sort value are merged by \gls*{xindy}
+ into a single glossary line so you must make sure that each entry
+ has a unique sort value;
+ \item \gls*{xindy} forbids empty sort values;
+ \item \gls*{xindy} automatically strips control sequences, the math-shift
+ character \verb|$| and braces \verb|{}| from the sort value,
+ which is usually desired but this can cause the sort value to
+ collapse to an empty string which \gls*{xindy} forbids.
+\end{itemize}
+In these problematic cases, you must set the \gloskey{sort} field
+explicitly. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
+ sort={alpha},description={...}}
+\end{verbatim}
+
+All glossaries must be sorted according to the same method
+(word/letter ordering, order of use, or order of definition).
+(The \sty{glossaries-extra} package allows a hybrid mix of
+\optsand13 to provide word\slash letter ordering with \opt3 and order
+of use\slash definition with \opt1. See the \sty{glossaries-extra}
+documentation for further details.)
+
+\begin{enumerate}
+ \item Add the \pkgopt{xindy} option to the \styfmt{glossaries}
+package option list:
+\begin{verbatim}
+\usepackage[xindy]{glossaries}
+\end{verbatim}
+ If you are using a non-Latin script you'll also need to either
+ switch off the creation of the number group:
+\begin{verbatim}
+\usepackage[xindy={glsnumbers=false}]{glossaries}
+\end{verbatim}
+ or use either \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} or
+ \cs{GlsSetXdyNumberGroupOrder}\marg{spec} to indicate where the number
+ group should be placed (see \sectionref{sec:xindy}).
+
+ \item Add \cs{makeglossaries} to your preamble (before you start
+ defining your entries, as described in \sectionref{sec:newglosentry}).
+
+ \item Run \LaTeX\ on your document. This creates files with the
+ extensions \texttt{.glo} and \texttt{.xdy} (for example, if your
+ \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
+ two extra files called \texttt{myDoc.glo} and \texttt{myDoc.xdy}).
+ If you look at your document at this point, you won't see the
+ glossary as it hasn't been created yet. (If you're using the
+ extension package \sty{glossaries-extra}, you'll see the section
+ header and some boilerplate text.)
+
+ \item Run \gls{xindy} with the \texttt{.glo} file as the
+ input file and the \texttt{.xdy} file as a~module so that
+ it creates an output file with the extension \texttt{.gls}. You
+ also need to set the language name and input encoding. If
+ you have access to a terminal or a command prompt (for example, the
+ MSDOS command prompt for Windows users or the bash console for
+ Unix-like users) then you need to run the command (all on one
+ line):
+\begin{verbatim}
+xindy -L english -C utf8 -I xindy -M myDoc
+-t myDoc.glg -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (Replace \texttt{myDoc} with the base name of your \LaTeX\
+ document file. Avoid spaces in the file name. If necessary, also replace
+ \texttt{english} with the name of your language and \texttt{utf8}
+ with your input encoding, for example,
+ \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.)
+ Note that it's much simpler to use \gls{makeglossaries} instead:
+\begin{verbatim}
+makeglossaries myDoc
+\end{verbatim}
+ (Remember that \gls{xindy} is a Perl script so if you can use
+ \gls{xindy} then you can also use \gls{makeglossaries}, and if
+ you don't want to use \gls{makeglossaries} because you don't
+ want to install Perl, then you can't use \gls{xindy} either.)
+
+ If you don't know how to use the command prompt, then you can
+ probably access \gls{xindy} or \gls{makeglossaries} via your text editor,
+ but each editor has a different method of doing this, so I~can't give
+ a~general description. You will have to check your editor's manual. Again,
+ a convenient method is to use \appfmt{arara} and add the follow comment
+ lines to the start of your document:
+\begin{alltt}
+\% arara:\ pdflatex
+\% arara:\ makeglossaries
+\% arara:\ pdflatex
+\end{alltt}
+
+ The default sort is word order (\qt{sea lion} comes before \qt{seal}).
+ If you want letter ordering you need to add the
+ \pkgopt[letter]{order} package option:
+\begin{verbatim}
+\usepackage[xindy,order=letter]{glossaries}
+\end{verbatim}
+ (and return to the previous step). This option is picked up
+ by \gls{makeglossaries}. If you are explicitly using \gls{xindy}
+ then you'll need to add \texttt{-M ord/letorder} to the options list.
+ See \sectionref{sec:xindyapp} for further details on using
+ \gls*{xindy} explicitly.
+
+ \item Once you have successfully completed the previous step,
+ you can now run \LaTeX\ on your document again. As with the
+ previous option, you may need to repeat the process to ensure
+ the table of contents and cross-references are resolved.
+
+\end{enumerate}
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[xindy]{glossaries}
+\makeglossaries % open glossary files
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printglossary
+\end{document}
+\end{verbatim}
+
+\optionsec{bib2gls}
+
+This option is only available with the extension package
+\gls{glossaries-extra}. This method uses \gls{bib2gls} to both
+fetch entry definitions from \texttt{.bib} files and to
+hierarchically sort and collate.
+
+All entries must be provided in one or more \texttt{.bib} files.
+(See the \gls{bib2gls} user manual for the required format.) The
+\sty{glossaries-extra} package needs to be loaded with the
+\pkgoptfmt{record} package option
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+or (equivalently)
+\begin{verbatim}
+\usepackage[record=only]{glossaries-extra}
+\end{verbatim}
+(It's possible to use a hybrid of this method and \optsor23 with
+\pkgoptfmt{record=alsoindex} but in general there is little need
+for this and it complicates the build process.)
+
+Each resource set is loaded with \cs{GlsXtrLoadResources}\oarg{options}.
+For example:
+\begin{verbatim}
+\GlsXtrLoadResources
+[% definitions in entries1.bib and entries2.bib:
+ src={entries1,entries2},
+ sort={de-CH-1996}% sort according to this locale
+]
+\end{verbatim}
+You can have multiple resource commands.
+
+The glossary is displayed using
+\begin{verbatim}
+\printunsrtglossary
+\end{verbatim}
+Alternatively all glossaries can be displayed using the iterative
+command:
+\begin{verbatim}
+\printunsrtglossaries
+\end{verbatim}
+The document is build using:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{verbatim}
+If letter groups are required, you need the \verb|--group| switch:
+\begin{verbatim}
+bib2gls --group myDoc
+\end{verbatim}
+Unlike \optsand23, this method doesn't create a file containing
+the typeset glossary but simply determines which entries are
+needed for the document, their associated locations and (if
+required) their associated letter group. This option allows
+a mixture of sort methods. (For example, sorting by word order
+for one glossary and order of use for another or even sorting
+one block of the glossary differently to another block in the
+same glossary.)
+
+This method supports Unicode and (with at least Java~8) uses
+the Common Locale Data Repository, which provides more extensive
+language support than \gls{xindy}.\footnote{Except for Klingon,
+which is supported by \gls{xindy}, but not by the
+CLDR.}\ The locations in the
+\gls{numberlist} may be in any format. If \gls{bib2gls} can
+deduce a numerical value it will attempt to form ranges otherwise
+it will simply list the locations.
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[record]{glossaries-extra}
+\GlsXtrLoadResources[src={entries}]
+\begin{document}
+\gls{sample}.
+\printunsrtglossary
+\end{document}
+\end{verbatim}
+where \texttt{entries.bib} contains
+\begin{verbatim}
+@entry{sample,
+ name={sample},
+ description={an example}
+}
+\end{verbatim}
+See the \gls{bib2gls} user manual for further details.
+
+\optionsec[no sorting]{no sorting}
+
+This option is only available with the extension package
+\gls{glossaries-extra}. No \gls{indexingapp} is required. This
+method is best used with the package option \pkgopt[none]{sort}.
+\begin{verbatim}
+\usepackage[sort=none]{glossaries-extra}
+\end{verbatim}
+There's no \qt{activation} command (such as \cs{makeglossaries}
+for \optsand23).
+
+All entries must be defined before the glossary is displayed
+(preferably in the preamble) in the required order, and child
+entries must be defined immediately after their parent entry
+if they must be kept together in the glossary
+
+The glossary is displayed using
+\begin{verbatim}
+\printunsrtglossary
+\end{verbatim}
+Alternatively all glossaries can be displayed using the iterative
+command:
+\begin{verbatim}
+\printunsrtglossaries
+\end{verbatim}
+This will display \emph{all} defined entries, regardless of
+whether or not they have been used in the document. The
+\glspl{numberlist} have to be set explicitly otherwise they won't
+appear. Note that this uses the same command for displaying the
+glossary as \opt4. This is because \gls{bib2gls} takes advantage
+of this method by defining the wanted entries in the required order and
+setting the locations (and letter group information, if required).
+
+This just requires a single \LaTeX\ call
+\begin{verbatim}
+pdflatex myDoc
+\end{verbatim}
+unless the glossary needs to appear in the table of contents, in which case
+a second run is required.
+\begin{verbatim}
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+(Naturally if the document also contains citations, and so on,
+then additional steps are required. Similarly for all the other
+options above.)
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[sort=none]{glossaries-extra}
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printunsrtglossary
+\end{document}
+\end{verbatim}
+See the \sty{glossaries-extra} documentation for
+further details.
+
+\section{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
+\href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{terminal or command prompt}, type:
+\begin{prompt}
+texdoc -l glossaries
+\end{prompt}
+This should display a list of all the files in the glossaries
+documentation directory with their full pathnames. (The GUI version
+of \texttt{texdoc} may also provide you with the information.)
+
+If you can't find the sample files on your computer, they are also available
+from your nearest CTAN mirror at
+\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}.
+
+The sample documents are listed below\footnote{Note that although I've written
+\texttt{latex} in this section, it's better to use \texttt{pdflatex}, where
+possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.}
+If you prefer to use UTF-8 aware engines (\texttt{xelatex} or
+\texttt{lualatex}) remember that you'll need to switch from
+\styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where
+appropriate. The \gls{glossaries-extra} package provides some
+additional sample files.
+
+\begin{samplelist}
+\exitem[minimal]{gls} 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 that look something like:
+\begin{verbatim}
+pdfTeX warning (dest): name{glo:aca} has been
+referenced but does not exist,
+replaced by a fixed one
+\end{verbatim}
+ 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 If you have Perl installed, run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can
+ be done on a terminal by typing
+\begin{prompt}
+makeglossaries minimalgls
+\end{prompt}
+ otherwise do
+\begin{prompt}
+makeglossaries-lite minimalgls
+\end{prompt}
+ If for some reason you want to call \gls{makeindex} explicitly, 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 the file name contains spaces, you will need to use
+ the double-quote character to delimit the name.
+
+ \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.
+
+There are three other files that can be used as a
+\href{http://www.dickimaw-books.com/latex/minexample/}{minimal working
+example}: \texttt{mwe-gls.tex}, \texttt{mwe-acr.tex} and
+\texttt{mwe-acr-desc.tex}.
+
+\exitem{-noidxapp} This document illustrates how to use the
+\styfmt{glossaries} package without an external \gls{indexingapp} (\opt1).
+To create the complete document, you need to do:
+\begin{prompt}
+latex sample-noidxapp
+latex sample-noidxapp
+\end{prompt}
+
+\exitem{-noidxapp-utf8} As the previous example, except that it uses
+the \sty{inputenc} package.
+To create the complete document, you need to do:
+\begin{prompt}
+latex sample-noidxapp-utf8
+latex sample-noidxapp-utf8
+\end{prompt}
+
+\exitem{4col} 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}
+or
+\begin{prompt}
+latex sample4col
+makeglossaries-lite sample4col
+latex sample4col
+\end{prompt}
+The vertical gap between entries is the
+gap created at the start of each group. This can be suppressed
+using the \pkgopt{nogroupskip} package option.
+
+\exitem{Acr} This document has some
+sample abbreviations. 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}
+(or use \gls{makeglossaries-lite.lua}).
+
+\exitem{AcrDesc} This is similar to
+the previous example, except that the abbreviations 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}
+
+\exitem{Desc} This is similar to the
+previous example, except that it defines the abbreviations 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}
+
+\exitem{CustomAcr} This document has some sample abbreviations with a
+custom acronym style. It also adds the glossary to the table of
+contents, so an extra run through \LaTeX\ is required:
+\begin{prompt}
+latex sampleCustomAcr
+makeglossaries sampleCustomAcr
+latex sampleCustomAcr
+latex sampleCustomAcr
+\end{prompt}
+
+\exitem{FnAcrDesc} This is similar to \samplefile{AcrDesc}, except that it
+uses the \acrstyle{footnote-sc-desc} style. 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 sampleFnAcrDesc
+makeglossaries sampleFnAcrDesc
+latex sampleFnAcrDesc
+latex sampleFnAcrDesc
+\end{prompt}
+
+\exitem{-FnDesc} This example
+defines a custom display format that puts the description in a
+footnote on first use.
+\begin{prompt}
+latex sample-FnDesc
+makeglossaries sample-FnDesc
+latex sample-FnDesc
+\end{prompt}
+
+\exitem{-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}
+
+\exitem{-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}
+
+\exitem{-dot-abbr} This document illustrates how to use the
+post link hook to adjust the space factor after abbreviations.
+\begin{prompt}
+latex sample-dot-abbr
+makeglossaries sampledot-abbrf
+latex sample-dot-abbr
+\end{prompt}
+
+\exitem{DB} 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}
+or
+\begin{prompt}
+latex sampleDB
+makeglossaries-lite sampleDB
+latex sampleDB
+\end{prompt}
+The glossary definitions are stored in the accompanying files
+\texttt{database1.tex} and \texttt{database2.tex}. If for some
+reason you want to call \gls{makeindex} explicitly you must
+have a separate call for each glossary:
+\begin{enumerate}
+\item Create the main glossary (all on one line):
+\begin{prompt}\raggedright
+makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo
+\end{prompt}
+\item Create the secondary glossary (all on one line):
+\begin{prompt}\raggedright
+makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn
+\end{prompt}
+Note that both \gls{makeglossaries} and \gls{makeglossaries-lite.lua} do
+this all in one call, so they not only make it easier because you
+don't need to supply all the switches and remember all the
+extensions but they also call \gls{makeindex} the appropriate number of times.
+\end{enumerate}
+
+\exitem{Eq} 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}
+
+\exitem{EqPg} 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}
+
+\exitem{Sec} 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}
+
+\exitem{Ntn} 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 want to call \gls{makeindex} explicitly instead of
+using \gls{makeglossaries} or \gls{makeglossaries-lite.lua} then you
+need to call \gls{makeindex} twice:
+\begin{enumerate}
+\item Create the main glossary (all on one line):
+\begin{prompt}\raggedright
+makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo
+\end{prompt}
+\item Create the secondary glossary (all on one line):
+\begin{prompt}\raggedright
+makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn
+\end{prompt}
+\end{enumerate}
+
+\exitem{} 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} or \gls{makeglossaries-lite.lua}.
+If you use \gls{makeindex} explicitly, you will need to use the
+\mkidxopt{l} switch to indicate letter ordering.)
+
+\exitem{-inline} This document is
+like \texttt{sample.tex}, above, but uses the \glostyle{inline}
+glossary style to put the glossary in a footnote.
+
+\exitem{tree} 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}
+
+\exitem{-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}
+
+\exitem{-langdict} This document
+illustrates how to use the glossaries package to create English
+to French and French to English dictionaries. To create the document
+do:
+\begin{prompt}
+latex sample-langdict
+makeglossaries sample-langdict
+latex sample-langdict
+\end{prompt}
+
+\exitem{xdy} 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} or
+\gls{makeglossaries-lite.lua}, 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 then you can't use
+\gls{makeglossaries}, but you also can't use \gls{xindy}!
+However, if for some reason you want to call
+\gls{xindy} explicitly instead of using \gls{makeglossaries} (or
+\gls{makeglossaries-lite.lua}):
+\begin{itemize}
+\item if you are using the default style file \texttt{samplexdy.xdy}, then
+do (no line breaks):
+\begin{prompt}\raggedright
+xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo
+\end{prompt}
+\item if you are using \texttt{samplexdy-mc.xdy}, then do
+(no line breaks):
+\begin{prompt}\raggedright
+xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo
+\end{prompt}
+\end{itemize}
+
+\exitem{xdy2} 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}
+The explicit \gls{xindy} call is:
+\begin{prompt}\raggedright
+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.
+
+\exitem{xdy3} This document is like \samplefile{xdy} but uses the
+command \cs{Numberstring} from the \sty{fmtcount} package to
+format the page numbers.
+
+\exitem{utf8} This is another example
+that uses \gls{xindy}. Unlike \gls{makeindex},
+\gls{xindy} can cope with \glspl{nonlatinchar}. This
+document uses UTF8 encoding. To create the document do:
+\begin{prompt}
+latex sampleutf8
+makeglossaries sampleutf8
+latex sampleutf8
+\end{prompt}
+The explicit \gls{xindy} call is
+(no line breaks):
+\begin{prompt}\raggedright
+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}
+or
+\begin{prompt}
+latex sampleutf8
+makeglossaries-lite sampleutf8
+latex sampleutf8
+\end{prompt}
+you will see that the entries that start with an \gls{exlatinchar}
+now appear in the symbols group, and the word \qt{man\oe uvre} is now
+after \qt{manor} instead of before it. If you want to explicitly
+call \gls{makeindex} (no line breaks):
+\begin{prompt}\raggedright
+makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
+\end{prompt}
+
+\exitem{-index} This document uses
+the \styfmt{glossaries} package to create both a glossary and an
+index. This requires two \gls{makeglossaries} (or
+\gls{makeglossaries-lite.lua}) calls to ensure the
+document is up to date:
+\begin{prompt}
+latex sample-index
+makeglossaries sample-index
+latex sample-index
+makeglossaries sample-index
+latex sample-index
+\end{prompt}
+
+\exitem{-newkeys} This document illustrates how add custom keys
+(using \cs{glsaddkey}).
+
+\exitem{-storage-abbr} This document illustrates how add custom
+storage keys (using \cs{glsaddstoragekey}).
+
+\exitem{-storage-abbr-desc} An extension of the previous example
+where the user needs to provide a~description.
+
+\exitem{-chap-hyperfirst} This document illustrates how to add
+a~custom key using \cs{glsaddstoragekey} and hook into the \glslike\
+and \glstextlike\ mechanism used to determine whether or not to
+hyperlink an entry.
+
+\exitem{-font-abbr} This document illustrates how to different fonts
+for abbreviations within the style.
+
+\exitem{-numberlist} This document illustrates how to reference the
+\gls{numberlist} in the document text. This requires an additional
+\LaTeX\ run:
+\begin{prompt}
+latex sample-numberlist
+makeglossaries sample-numberlist
+latex sample-numberlist
+latex sample-numberlist
+\end{prompt}
+
+\exitem{People} This document illustrates how you can hook into the
+standard sort mechanism to adjust the way the sort key is set. This
+requires an additional run to ensure the table of contents is
+up-to-date:
+\begin{prompt}
+latex samplePeople
+makeglossaries samplePeople
+latex samplePeople
+latex samplePeople
+\end{prompt}
+
+\exitem{Sort} This is another document that illustrates how to hook
+into the standard sort mechanism. An additional run is required to
+ensure the table of contents is up-to-date:
+\begin{prompt}
+latex sampleSort
+makeglossaries sampleSort
+latex sampleSort
+latex sampleSort
+\end{prompt}
+
+\exitem{-nomathhyper} This document illustrates how to selectively
+enable and disable entry hyperlinks in \ics{glsentryfmt}.
+
+\exitem{-entryfmt} This document illustrates how to change the
+way an entry is displayed in the text.
+
+\exitem{-prefix} This document illustrates the use of the
+\sty{glossaries-prefix} package. An additional run is required to
+ensure the table of contents is up-to-date:
+\begin{prompt}
+latex sample-prefix
+makeglossaries sample-prefix
+latex sample-prefix
+latex sample-prefix
+\end{prompt}
+
+\exitem{accsupp} 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}.
+
+\exitem{-ignored} This document defines an ignored glossary for
+common terms that don't need a definition.
+
+\exitem{-entrycount} This document uses \ics{glsenableentrycount}
+and \ics{cgls} (described in \sectionref{sec:enableentrycount})
+so that acronyms only used once don't appear in the list of
+acronyms.
+\end{samplelist}
+
+\section{Dummy Entries for Testing}
+\label{sec:lipsum}
+
+In addition to the sample files described above, \sty{glossaries} also provides
+some files containing lorum ipsum dummy entries. These are provided
+for testing purposes and are on \TeX's path (in
+\texttt{tex\slash latex\slash glossaries\slash test-entries}) so they can be included
+via \ics{input} or \ics{loadglsentries}. The files are as follows:
+\begin{description}
+\item[example-glossaries-brief.tex] These entries all have brief
+descriptions. For example:
+\begin{verbatim}
+\newglossaryentry{lorem}{name={lorem},description={ipsum}}
+\end{verbatim}
+
+\item[example-glossaries-long.tex] These entries all have long
+descriptions. For example:
+\begin{verbatim}
+\newglossaryentry{loremipsum}{name={lorem ipsum},
+description={dolor sit amet, consectetuer adipiscing
+elit. Ut purus elit, vestibulum ut, placerat ac,
+adipiscing vitae, felis. Curabitur dictum gravida
+mauris.}}
+\end{verbatim}
+
+\item[example-glossaries-multipar.tex] These entries all have
+multi-paragraph descriptions.
+
+\item[example-glossaries-symbols.tex] These entries all use the
+\gloskey{symbol} key. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={alpha},
+symbol={\ensuremath{\alpha}},
+description={Quisque ullamcorper placerat ipsum.}}
+\end{verbatim}
+
+\item[example-glossaries-symbolnames.tex] Similar to the previous
+file but the \gloskey{symbol} key isn't used. Instead the symbol
+is stored in the \gloskey{name} key. For example:
+\begin{verbatim}
+\newglossaryentry{sym.alpha}{sort={alpha},
+name={\ensuremath{\alpha}},
+description={Quisque ullamcorper placerat ipsum.}}
+\end{verbatim}
+
+\item[example-glossaries-images.tex] These entries use the
+\gloskey{user1} key to store the name of an image file. (The images
+are provided by the \sty{mwe} package and should be on \TeX's path.)
+One entry doesn't have an associated image to help test for a~missing key.
+
+\item[example-glossaries-acronym.tex] These entries are all
+abbreviations. For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum
+dolor}
+\end{verbatim}
+
+\item[example-glossaries-acronym-desc.tex] These entries are all
+abbreviations that use the \gloskey{description} key.
+For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype,
+ description={fringilla a, euismod sodales,
+ sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula}
+\end{verbatim}
+
+\item[example-glossaries-acronyms-lang.tex] These entries are all
+abbreviations, where some of them have a~translation supplied in the
+\gloskey{user1} key.
+For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype,user1={love itself}]
+ {li}{LI}{lorem ipsum}
+\end{verbatim}
+
+\item[example-glossaries-parent.tex] These are hierarchical entries
+where the child entries use the \gloskey{name} key.
+For example:
+\begin{verbatim}
+\newglossaryentry{sedmattis}{name={sed mattis},
+description={erat sit amet}
+
+\newglossaryentry{gravida}{parent={sedmattis},
+ name={gravida},description={malesuada}}
+\end{verbatim}
+
+\item[example-glossaries-childnoname.tex] These are hierarchical entries
+where the child entries don't use the \gloskey{name} key.
+For example:
+\begin{verbatim}
+\newglossaryentry{scelerisque}{name={scelerisque},
+ description={at}}
+\end{verbatim}
+
+\item[example-glossaries-cite.tex] These entries use the
+\gloskey{user1} key to store a citation key (or comma-separated list
+of citation keys). The citations are defined in \texttt{xampl.bib},
+which should be available on all modern \TeX\ distributions.
+One entry doesn't have an associated citation to help test for a~missing
+key.
+For example:
+\begin{verbatim}
+\newglossaryentry{fusce}{name={fusce},
+description={suscipit cursus sem},user1={article-minimal}}
+\end{verbatim}
+
+\item[example-glossaries-url.tex] These entries use the
+\gloskey{user1} key to store an URL associated with the entry.
+For example:
+\begin{verbatim}
+\newglossaryentry{aenean-url}{name={aenean},
+ description={adipiscing auctor est},
+ user1={http://uk.tug.org/}}
+\end{verbatim}
+\end{description}
+
+The sample file \texttt{glossary-lipsum-examples.tex} in the
+\texttt{doc\slash latex\slash glossaries\slash samples} directory
+uses all these files. See also
+\url{http://www.dickimaw-books.com/gallery/#glossaries}.
+The \sty{glossaries-extra} package provides additional test files.
+
+\section{Multi-Lingual Support}
+\label{sec:languages}
+
+As from version 1.17, the \styfmt{glossaries} package can be
+used with \gls{xindy} as well as \gls{makeindex}. If you
+are writing in a language that uses an \gls{exlatinalph} or
+\gls{nonlatinalph} it's best to use \opt3 (\gls*{xindy})
+or \opt4 (\gls{bib2gls})
+as \gls*{makeindex} (\opt2) is hard-coded for the non-extended
+\gls{latinalph} and \opt1 can performed limited ASCII comparisons.
+
+This means that with \optsor34 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}
+If you want to use \gls*{bib2gls}, you need to use the
+\pkgopt{record} option with \sty{glossaries-extra} and supply the
+definitions in \texttt{.bib} files. (See the \gls{bib2gls} user
+manual for further details.)
+
+\begin{important}
+Note that although a~\gls{nonlatinchar}, such as \'e, looks like a plain
+character in your \filetype{.tex} file, with standard \LaTeX\ it's actually a~macro and can therefore
+cause expansion problems. You may need to switch off the field
+expansions with \cs{glsnoexpandfields}. This issue doesn't occur
+with \XeLaTeX\ or Lua\LaTeX.
+\end{important}
+
+With \sty{inputenc}, if you use a~\gls{nonlatinchar} (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 upper case (e.g.\ \ics{Gls}). For example:
+\begin{alltt}
+\verb|\newglossaryentry}{elite}{name={{|\'e\verb|}lite},|
+description=\verb|{select group or class}}|
+\end{alltt}
+(With newer versions of \sty{mfirstuc} and \sty{datatool-base} you
+may be able to omit this grouping.)
+For further details, see the \qt{UTF-8} section in the
+\sty{mfirstuc} user manual.
+
+If you are using \gls{xindy} or \gls{bib2gls}, the application needs
+to know the encoding of the \filetype{.tex} file. This information
+is added to the \filetype{.aux} file and can be picked up by
+\gls{makeglossaries} and \gls{bib2gls}. If you use
+\gls{xindy} explicitly instead of via \gls*{makeglossaries},
+you may need to specify the encoding using the \xdyopt{C}
+option. Read the \gls*{xindy} manual for further details of this
+option.
+
+As from v4.24, if you are writing in German (for example, using the \sty{ngerman}
+package\footnote{deprecated, use \styfmt{babel} instead} or \sty{babel} with the \pkgopt{ngerman} package option),
+and you want to use \gls{makeindex}['s] \mkidxopt{g} option, you'll
+need to change \gls{makeindex}['s] quote character using:
+\begin{definition}[\DescribeMacro\GlsSetQuote]
+\cs{GlsSetQuote}\marg{character}
+\end{definition}
+Note that \meta{character} may not be one of \verb"?" (question
+mark), \verb"|" (pipe) or \verb"!" (exclamation mark).
+For example:
+\begin{verbatim}
+\GlsSetQuote{+}
+\end{verbatim}
+This must be done before \ics{makeglossaries} and any entry
+definitions. It's only applicable for \app{makeindex}. This option
+in conjunction with \sty{ngerman} will also cause
+\app{makeglossaries} to use the \mkidxopt{g} switch when invoking
+\app{makeindex}.
+
+\begin{important}
+Be careful of \sty{babel}'s shorthands. These aren't switched
+on until the start of the document, so any entries defined
+in the preamble won't be able to use those shorthands.
+However, if you define the entries in the document and any
+of those shorthands happen to be special characters for
+\gls{makeindex} or \gls{xindy} (such as the double-quote)
+then this will interfere with code that tries to escape
+any of those characters that occur in the \gloskey{sort} key.
+\end{important}
+
+In general, it's best not to use \sty{babel}'s shorthands
+in entry definitions. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[ngerman]{babel}
+\usepackage{glossaries}
+
+\GlsSetQuote{+}
+
+\makeglossaries
+
+\newglossaryentry{rna}{name={ribonukleins\"aure},
+ sort={ribonukleins"aure},
+ description={eine Nukleins\"aure}}
+
+\begin{document}
+\gls{rna}
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
+The \sty{ngerman} package has the shorthands on in the preamble, so
+they can be used if \cs{GlsSetQuote} has changed the \gls{makeindex}
+quote character. Example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[ngerman]{babel}
+\usepackage{glossaries}
+
+\GlsSetQuote{+}
+
+\makeglossaries
+
+\newglossaryentry{rna}{name={ribonukleins"aure},
+ description={eine Nukleins"aure}}
+
+\begin{document}
+\gls{rna}
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
+\subsection{Changing the Fixed Names}
+\label{sec:fixednames}
+
+The fixed names are produced using the commands listed in
+\tableref{tab:predefinednames}. If you aren't using a language
+package such as \sty{babel} or \sty{polyglossia} that uses caption
+hooks, you can just redefine these commands as appropriate. If you
+are using \sty{babel} or \sty{polyglossia}, you need to use their
+caption hooks to change the defaults. See \urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing
+the words babel uses} or read the \sty{babel} or \sty{polyglossia}
+documentation. If you have loaded \sty{babel}, then \sty{glossaries}
+will attempt to load \sty{translator}, unless you have used the
+\pkgopt{notranslate}, \pkgopt[false]{translate} or \pkgopt[babel]{translate}
+package options. If the \sty{translator} package is loaded, the
+translations are provided by dictionary files (for example,
+\texttt{glossaries-dictionary-English.dict}). See the
+\sty{translator} package for advice on changing translations provided by
+\sty{translator} dictionaries. If you can't work out how to modify
+these dictionary definitions, try switching to \sty{babel}'s
+interface using \pkgopt[babel]{translate}:
+\begin{verbatim}
+\documentclass[english,french]{article}
+\usepackage{babel}
+\usepackage[translate=babel]{glossaries}
+\end{verbatim}
+and then use \sty{babel}'s caption hook mechanism. Note that if you
+pass the language options directly to \sty{babel} rather that using
+the document class options or otherwise passing the same options to
+\sty{translator}, then \sty{translator} won't pick up the
+language and no dictionaries will be loaded and \sty{babel}'s
+caption hooks will be used instead.
+
+\begin{table}[htbp]
+\caption{Customised Text}
+\label{tab:predefinednames}
+\centering
+\setlength{\tabcolsep}{3pt}
+\begin{tabular}{@{}l>{\raggedright}p{0.3\linewidth}>{\raggedright}p{0.4\linewidth}@{}}
+\bfseries Command Name & \bfseries Translator Key Word &
+\bfseries Purpose\cr
+\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\cr
+\ics{acronymname} & \texttt{Acronyms} & Title of the list of acronyms
+(when used with package option \pkgopt{acronym}).\cr
+\ics{entryname} & \texttt{Notation (glossaries)} &
+Header for first column in the glossary (for 2, 3 or 4 column glossaries
+that support headers).\cr
+\ics{descriptionname} & \texttt{Description (glossaries)} &
+Header for second column in the glossary (for 2, 3 or 4 column glossaries
+that support headers).\cr
+\ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol
+column in the glossary for glossary styles that support this option.\cr
+\ics{pagelistname} & \texttt{Page List (glossaries)} &
+Header for page list column in the glossary for glossaries that support
+this option.\cr
+\ics{glssymbolsgroupname} & \texttt{Symbols (glossaries)} &
+Header for symbols section of the glossary for glossary styles that
+support this option.\cr
+\ics{glsnumbersgroupname} & \texttt{Numbers (glossaries)} & Header for
+numbers section of the glossary for glossary styles that support
+this option.
+\end{tabular}
+\end{table}
+
+As from version 4.12, multilingual support is provided by separate
+language modules that need to be installed in addition to installing
+the \styfmt{glossaries} package. You only need to install the
+modules for the languages that you require. If the language module
+has an unmaintained status, you can volunteer to take over the
+maintenance by contacting me at
+\url{http://www.dickimaw-books.com/contact.html}. The
+\sty{translator} dictionary files for \styfmt{glossaries} are now
+provided by the appropriate language module. For further details
+about information specific to a given language, please see the
+documentation for that language module.
+
+Examples of use:
+\begin{itemize}
+\item Using \sty{babel} and \sty{translator}:
+\begin{verbatim}
+\documentclass[english,french]{article}
+\usepackage{babel}
+\usepackage{glossaries}
+\end{verbatim}
+(\sty{translator} is automatically loaded).
+
+\item Using \sty{babel}:
+\begin{verbatim}
+\documentclass[english,french]{article}
+\usepackage{babel}
+\usepackage[translate=babel]{glossaries}
+\end{verbatim}
+(\sty{translator} isn't loaded).
+
+\item Using \sty{polyglossia}:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{polyglossia}
+\setmainlanguage{english}
+\usepackage{glossaries}
+\end{verbatim}
+
+\end{itemize}
+
+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 the \styfmt{glossaries} package option \pkgopt[babel]{translate}, 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 are using the \sty{translator}
+package, then you can provide your own dictionary with the necessary
+modifications (using \cs{deftranslation}) and load it using
+\cs{usedictionary}. If you simply want to change the title of a
+glossary, you can use the \gloskey[printglossary]{title} key in
+commands like \cs{printglossary} (but not the iterative commands
+like \cs{printglossaries}).
+
+\begin{important}
+Note that the \sty{translator} 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 use the package
+option \pkgopt[babel]{translate}. For example:
+\begin{verbatim}
+\documentclass[british]{article}
+
+\usepackage{babel}
+\usepackage[translate=babel]{glossaries}
+
+\addto\captionsbritish{%
+ \renewcommand*{\glossaryname}{List of Terms}%
+ \renewcommand*{\acronymname}{List of Acronyms}%
+}
+\end{verbatim}
+
+Note that \gls{xindy} and \gls{bib2gls} provide much better multi-lingual support
+than \gls{makeindex}, so I~recommend that you use \optsor34
+if you have glossary entries that contain
+\glspl{nonlatinchar}. See \sectionref{sec:xindy} for further
+details on \gls{xindy}, and see the \gls{bib2gls} user manual for
+further details of that application.
+
+\subsubsection{Creating a New Language Module}
+\label{sec:newlang}
+
+The \styfmt{glossaries} package now uses the \sty{tracklang} package
+to determine which language modules need to be loaded. If you want
+to create a new language module, you should first read the
+\sty{tracklang} documentation.
+
+To create a new language module, you need to at least create two
+files: \texttt{glossaries-}\meta{lang}\texttt{.ldf} and
+\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict} where
+\meta{lang} is the root language name (for example,
+\texttt{english}) and \meta{Lang} is the language name used by
+\sty{translator} (for example, \texttt{English}).
+
+Here's an example of \texttt{glossaries-dictionary-English.dict}:
+\begin{verbatim}
+\ProvidesDictionary{glossaries-dictionary}{English}
+
+\providetranslation{Glossary}{Glossary}
+\providetranslation{Acronyms}{Acronyms}
+\providetranslation{Notation (glossaries)}{Notation}
+\providetranslation{Description (glossaries)}{Description}
+\providetranslation{Symbol (glossaries)}{Symbol}
+\providetranslation{Page List (glossaries)}{Page List}
+\providetranslation{Symbols (glossaries)}{Symbols}
+\providetranslation{Numbers (glossaries)}{Numbers}
+\end{verbatim}
+You can use this as a template for your dictionary file. Change
+\texttt{English} to the \sty{translator} name for your language
+(so that it matches the file name
+\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict})
+and, for each \cs{providetranslation}, change the second argument to
+the appropriate translation.
+
+Here's an example of \texttt{glossaries-english.ldf}:
+\begin{verbatim}
+\ProvidesGlossariesLang{english}
+
+\glsifusedtranslatordict{English}
+{%
+ \addglossarytocaptions{\CurrentTrackedLanguage}%
+ \addglossarytocaptions{\CurrentTrackedDialect}%
+}
+{%
+ \@ifpackageloaded{polyglossia}%
+ {%
+ \newcommand*{\glossariescaptionsenglish}{%
+ \renewcommand*{\glossaryname}{\textenglish{Glossary}}%
+ \renewcommand*{\acronymname}{\textenglish{Acronyms}}%
+ \renewcommand*{\entryname}{\textenglish{Notation}}%
+ \renewcommand*{\descriptionname}{\textenglish{Description}}%
+ \renewcommand*{\symbolname}{\textenglish{Symbol}}%
+ \renewcommand*{\pagelistname}{\textenglish{Page List}}%
+ \renewcommand*{\glssymbolsgroupname}{\textenglish{Symbols}}%
+ \renewcommand*{\glsnumbersgroupname}{\textenglish{Numbers}}%
+ }%
+ }%
+ {%
+ \newcommand*{\glossariescaptionsenglish}{%
+ \renewcommand*{\glossaryname}{Glossary}%
+ \renewcommand*{\acronymname}{Acronyms}%
+ \renewcommand*{\entryname}{Notation}%
+ \renewcommand*{\descriptionname}{Description}%
+ \renewcommand*{\symbolname}{Symbol}%
+ \renewcommand*{\pagelistname}{Page List}%
+ \renewcommand*{\glssymbolsgroupname}{Symbols}%
+ \renewcommand*{\glsnumbersgroupname}{Numbers}%
+ }%
+ }%
+ \ifcsdef{captions\CurrentTrackedDialect}
+ {%
+ \csappto{captions\CurrentTrackedDialect}%
+ {%
+ \glossariescaptionsenglish
+ }%
+ }%
+ {%
+ \ifcsdef{captions\CurrentTrackedLanguage}
+ {
+ \csappto{captions\CurrentTrackedLanguage}%
+ {%
+ \glossariescaptionsenglish
+ }%
+ }%
+ {%
+ }%
+ }%
+ \glossariescaptionsenglish
+}
+\renewcommand*{\glspluralsuffix}{s}
+\renewcommand*{\glsacrpluralsuffix}{\glspluralsuffix}
+\renewcommand*{\glsupacrpluralsuffix}{\glstextup{\glspluralsuffix}}
+\end{verbatim}
+This is a somewhat longer file, but again you can use it as a
+template. Replace \texttt{English} with the \sty{translator}
+language label \meta{Lang} used for the dictionary file and
+replace \texttt{english} with the root language name \meta{lang}. Within the
+definition of \cs{glossariescaptions}\meta{lang}, replace the
+English text (such as \qt{Glossaries}) with the appropriate
+translation.
+
+\label{pluralsuffix}%
+\textbf{Note:} the suffixes used to generate the plural forms when
+the plural hasn't been specified are given by
+\cs{glspluralsuffix} (for general entries) and
+\cs{glsupacrpluralsuffix} for acronyms where the suffix needs to be
+set using \cs{glstextup} to counteract the effects of \cs{textsc}
+and \cs{glsacrpluralsuffix} for other acronym styles. There's no
+guarantee when these commands will be expanded. They may be expanded
+on definition or they may be expanded on use, depending on the
+\styfmt{glossaries} configuration.
+
+\begin{important}
+Therefore these plural suffix command definitions
+aren't included in the caption mechanism as that's typically not switched on
+until the start of the document. \textbf{This means that the suffix in
+effect will be for the last loaded language that redefined these
+commands.} It's best to initialise these commands to the most common
+suffix required in your document and use the \gloskey{plural},
+\gloskey{longplural}, \gloskey{shortplural} etc keys to override
+exceptions.
+\end{important}
+
+If you want to add a regional variation, create a file called
+\texttt{glossaries-}\meta{iso lang}\texttt{-}\meta{iso
+country}\texttt{.ldf}, where \meta{iso lang} is the ISO language
+code and \meta{iso country} is the ISO country code. For example,
+\texttt{glossaries-en-GB.ldf}. This file can load the root
+language file and make the appropriate changes, for example:
+\begin{verbatim}
+ \ProvidesGlossariesLang{en-GB}
+ \RequireGlossariesLang{english}
+ \glsifusedtranslatordict{British}
+ {%
+ \addglossarytocaptions{\CurrentTrackedLanguage}%
+ \addglossarytocaptions{\CurrentTrackedDialect}%
+ }
+ {%
+ \@ifpackageloaded{polyglossia}%
+ {%
+ % Modify \glossariescaptionsenglish as appropriate for
+ % polyglossia
+ }%
+ {%
+ % Modify \glossariescaptionsenglish as appropriate for
+ % non-polyglossia
+ }%
+ }
+\end{verbatim}
+
+If the translations includes \glspl{nonlatinchar}, it's necessary to
+provide code that's independent of the input encoding. Remember that
+while some users may use UTF-8, others may use Latin-1 or any other
+supported encoding, but while users won't appreciate you enforcing
+your preference on them, it's useful to provide a UTF-8 version for
+\XeLaTeX\ users.
+
+The \texttt{glossaries-irish.ldf} file provides this as follows:
+\begin{verbatim}
+\ProvidesGlossariesLang{irish}
+
+\glsifusedtranslatordict{Irish}
+{%
+ \addglossarytocaptions{\CurrentTrackedLanguage}%
+ \addglossarytocaptions{\CurrentTrackedDialect}%
+}
+{%
+ \ifdefstring{\inputencodingname}{utf8}
+ {\input{glossaries-irish-utf8.ldf}}%
+ {%
+ \ifdef{\XeTeXinputencoding}% XeTeX defaults to UTF-8
+ {\input{glossaries-irish-utf8.ldf}}%
+ {\input{glossaries-irish-noenc.ldf}}
+ }
+ \ifcsdef{captions\CurrentTrackedDialect}
+ {%
+ \csappto{captions\CurrentTrackedDialect}%
+ {%
+ \glossariescaptionsirish
+ }%
+ }%
+ {%
+ \ifcsdef{captions\CurrentTrackedLanguage}
+ {
+ \csappto{captions\CurrentTrackedLanguage}%
+ {%
+ \glossariescaptionsirish
+ }%
+ }%
+ {%
+ }%
+ }%
+ \glossariescaptionsirish
+}
+\end{verbatim}
+(Again you can use this as a template. Replace \texttt{irish} with
+your root language label and \texttt{Irish} with the
+\sty{translator} dictionary label.)
+
+There are now two extra files: \texttt{glossaries-irish-noenc.ldf}
+and \texttt{glossaries-irish-utf8.ldf}.
+
+These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses
+\LaTeX\ accent commands:
+\begin{verbatim}
+\@ifpackageloaded{polyglossia}%
+{%
+ \newcommand*{\glossariescaptionsirish}{%
+ \renewcommand*{\glossaryname}{\textirish{Gluais}}%
+ \renewcommand*{\acronymname}{\textirish{Acrainmneacha}}%
+ \renewcommand*{\entryname}{\textirish{Ciall}}%
+ \renewcommand*{\descriptionname}{\textirish{Tuairisc}}%
+ \renewcommand*{\symbolname}{\textirish{Comhartha}}%
+ \renewcommand*{\glssymbolsgroupname}{\textirish{Comhartha\'{\i}}}%
+ \renewcommand*{\pagelistname}{\textirish{Leathanaigh}}%
+ \renewcommand*{\glsnumbersgroupname}{\textirish{Uimhreacha}}%
+ }%
+}%
+{%
+ \newcommand*{\glossariescaptionsirish}{%
+ \renewcommand*{\glossaryname}{Gluais}%
+ \renewcommand*{\acronymname}{Acrainmneacha}%
+ \renewcommand*{\entryname}{Ciall}%
+ \renewcommand*{\descriptionname}{Tuairisc}%
+ \renewcommand*{\symbolname}{Comhartha}%
+ \renewcommand*{\glssymbolsgroupname}{Comhartha\'{\i}}%
+ \renewcommand*{\pagelistname}{Leathanaigh}%
+ \renewcommand*{\glsnumbersgroupname}{Uimhreacha}%
+ }%
+}
+\end{verbatim}
+whereas the \texttt{*-utf8.ldf} replaces the accent commands with
+the appropriate UTF-8 characters.
+
+
+\section{Generating the Associated Glossary Files}
+\label{sec:makeglossaries}
+
+\begin{important}
+This section is only applicable if you have chosen \optsor23. You can
+ignore this section if you have chosen any of the other options. If you want to
+alphabetically sort your entries always remember to use the
+\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ commands.
+\end{important}
+
+If this section seriously confuses you, and you can't work out how
+to run external tools like \gls{makeglossaries} or \gls{makeindex}, you can try using
+the \pkgopt{automake} package option, described in
+\sectionref{sec:pkgopts-sort}, but you will need \TeX's shell escape
+enabled.
+
+In order to generate a sorted glossary with compact
+\glspl{numberlist}, it is necessary to use an external
+\gls{indexingapp} as an intermediate step (unless you have chosen
+\opt1, which uses \TeX\ to do the sorting or \opt5, which doesn't
+perform any sorting). It is this application
+that creates the file containing the code required to typeset the
+glossary. \textbf{If this step is omitted, the glossaries will not
+appear in your document.} The two \glspl*{indexingapp} 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. With the \sty{glossaries-extra} package, you
+can also use \gls{bib2gls} as the indexing application. (See
+the \sty{glossaries-extra} and \gls{bib2gls} user manuals for
+further details.) Note that \gls*{xindy} and \gls*{bib2gls} have much
+better multi-lingual support than \gls*{makeindex}, so \gls*{xindy}
+or \gls*{bib2gls} are 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}.
+
+\begin{important}
+This is a multi-stage process, but there are methods of automating
+document compilation using applications such as \app{latexmk} and
+\app{arara}. With \app{arara} you can just add special comments to
+your document source:
+\begin{alltt}
+\% arara: pdflatex
+\% arara: makeglossaries
+\% arara: pdflatex
+\end{alltt}
+With \app{latexmk} you need to set up the required dependencies.
+\end{important}
+
+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 (including
+\gls*{xindy} and \app{latexmk}). Most Unix-like
+operating systems come with a~Perl interpreter. \TeX~Live also comes
+with a~Perl interpreter. MiK\TeX\ doesn't come with a~Perl
+interpreter so if you are a~Windows MiK\TeX\ user you will need to
+install Perl if you want to use \gls{makeglossaries} or \gls{xindy}.
+Further information is available at \url{http://www.perl.org/about.html}
+and
+\href{http://tex.stackexchange.com/questions/158796/miktex-and-perl-scripts-and-one-python-script}{MiKTeX and Perl scripts (and one Python script)}.
+
+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}\slash\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.
+
+\item If \gls{makeindex} warns about multiple encap values,
+\gls{makeglossaries} will detect this and attempt to correct the
+problem.\footnote{Added to version \gls{makeglossaries} 2.18.} This
+correction is only provided by \gls{makeglossaries} when
+\gls{makeindex} is used since \gls{xindy} uses the order of the
+attributes list to determine which format should take precedence.
+(See \cs{GlsAddXdyAttribute} in \sectionref{sec:xindyloc}.)
+
+\end{itemize}
+
+As from version 4.16, the \styfmt{glossaries} package also comes
+with a~Lua script called \gls{makeglossaries-lite.lua}. This is a
+\emph{trimmed-down} alternative to the \gls{makeglossaries} Perl
+script. It doesn't have some of the options that the Perl version
+has and it doesn't attempt to diagnose any problems, but since
+modern \TeX\ distributions come with Lua\TeX\ (and therefore have
+a~Lua interpreter) you don't need to install anything else in order
+to use \gls{makeglossaries-lite.lua} so it's an alternative to
+\gls{makeglossaries} if you want to use \opt2 (\gls{makeindex}).
+
+If things go wrong and you can't work out why your glossaries
+aren't being generated correctly, you can use
+\gls{makeglossariesgui} as a diagnostic tool. Once you've
+fixed the problem, you can then go back to using
+\gls{makeglossaries} or \gls{makeglossaries-lite.lua}.
+
+Whilst I strongly recommended that you use the \gls{makeglossaries}
+Perl script or the \gls{makeglossaries-lite.lua} Lua script, it is
+possible to use the \styfmt{glossaries} package without using those
+applications. However, note that some commands and package options
+have no effect if you explicitly run \gls{makeindex}\slash\gls{xindy}.
+These are listed in \tableref{tab:makeglossariesCmds}.
+
+\begin{important}
+If you are choosing not to use \gls*{makeglossaries} because you
+don't want to install Perl, you will only be able to use
+\gls*{makeindex} as \gls*{xindy} also requires Perl. (Other useful
+Perl scripts include \appfmt{epstopdf} and \appfmt{latexmk}, so it's
+well-worth the effort to install Perl.)
+\end{important}
+
+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{As from
+v3.01 \ics{gls} is no longer fragile and doesn't need protecting.}
+\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}
+(Note that if you use \gls{glossaries-extra}, this will be done
+automatically for you if the \pkgoptfmt{indexcrossrefs} feature is
+enabled. See the \gls*{glossaries-extra} user guide for further
+details.)
+
+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. See
+\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating
+makeglossaries or makeglossaries-lite or bib2gls into the document
+build}.
+
+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 xindy or makeindex explicitly]{Commands and package options that have no effect when
+using \gls{xindy} or \gls{makeindex} explicitly}
+\label{tab:makeglossariesCmds}
+\vskip\baselineskip
+\begin{tabular}{@{}lll@{}}
+\bfseries Command or Package Option & \gls{makeindex} &
+\gls{xindy}\\
+\pkgopt[letter]{order} & use \mkidxopt{l} &
+ use \xdyopt{M}\texttt{ ord/letorder}\\
+\pkgopt[word]{order} & default & default\\
+\pkgopt{xindy}=\{\pkgoptfmt{language=}\meta{lang}\pkgoptfmt{,codename=}\meta{code}\} &
+N/A & use \xdyopt{L} \meta{lang} \xdyopt{C} \meta{code}\\
+\ics{GlsSetXdyLanguage}\marg{lang} & N/A &
+use \xdyopt{L} \meta{lang}\\
+\ics{GlsSetXdyCodePage}\marg{code} & N/A &
+use \xdyopt{C} \meta{code}
+\end{tabular}
+\par
+\end{table}
+
+
+\subsection{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}
+
+Windows users: \TeX~Live on Windows has its own internal Perl
+interpreter and provides \texttt{makeglossaries.exe} as a~convenient
+wrapper for the \gls{makeglossaries} Perl script. MiKTeX also
+provides a~wrapper \texttt{makeglossaries.exe} but doesn't provide
+a~Perl interpreter, which is still required even if you run MiKTeX's
+\texttt{makeglossaries.exe}, so with MiKTeX you'll need to install
+Perl.\footnote{The batch file \texttt{makeglossaries.bat} has been
+removed since the \TeX\ distributions for Windows provide
+\texttt{makeglossaries.exe}.} There's more information about this at
+\url{http://tex.stackexchange.com/q/158796/19862} on the TeX.SX
+site.
+
+The \gls{makeglossaries} script attempts to fork the
+\gls{makeindex}\slash\gls{xindy} process using \texttt{open()} on the
+piped redirection \verb"2>&1 |" and parses the processor output to
+help diagnose problems. If this method fails \gls{makeglossaries}
+will print an \qt{Unable to fork} warning and will retry without
+redirection. If you run \gls{makeglossaries} on an operating system
+that doesn't support this form of redirection, then you can use the
+\mkglsopt{Q} switch to suppress this warning or you can use the
+\mkglsopt{k} switch to make \gls{makeglossaries} automatically use
+the fallback method without attempting the redirection. Without this
+redirection, the \mkglsopt{q} (quiet) switch doesn't work as well.
+
+You can specify in which directory the \filetype{.aux},
+\filetype{.glo} etc files are located using the \texttt{-d} switch.
+For example:
+\begin{prompt}
+pdflatex -output-directory myTmpDir myDoc
+makeglossaries -d myTmpDir myDoc
+\end{prompt}
+Note that \gls*{makeglossaries} assumes by default that
+\gls*{makeindex}\slash\gls*{xindy} is on your operating system's
+path. If this isn't the case, you can specify the full pathname
+using \mkglsopt{m} \meta{path/to/makeindex} for \gls*{makeindex}
+or \mkglsopt{x} \meta{path/to/xindy} for \gls*{xindy}.
+
+As from \gls{makeglossaries} v2.18, if you are using
+\gls{makeindex}, there's a check for \gls*{makeindex}['s] multiple
+encap warning. This is where different encap values (location formats) are
+used on the same location for the same entry. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+\makeglossaries
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\begin{document}
+\gls{sample}, \gls[format=textbf]{sample}.
+\printglossaries
+\end{document}
+\end{verbatim}
+If you explicitly use \gls{makeindex}, this will cause a warning and
+the location list will be \qt{1, \textbf{1}}. That is, the page
+number will be repeated with each format. As from v2.18,
+\gls{makeglossaries} will check for this warning and, if found, will
+attempt to correct the problem by removing duplicate locations and
+retrying. There's no similar check for \gls{xindy} as \gls*{xindy}
+won't produce any warning and will simply discard duplicates.
+
+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
+4.41.
+\end{important}
+
+\subsection{Using the makeglossaries-lite Lua Script}
+\label{sec:makeglossarieslua}
+
+The Lua alternative to the \gls{makeglossaries} Perl script requires
+a~Lua interpreter, which should already be available if you have
+a~modern \TeX\ distribution that includes Lua\TeX. Lua is
+a~light-weight, cross-platform scripting language, but because it's
+light-weight it doesn't have the full-functionality of heavy-weight
+scripting languages, such as Perl. The \gls{makeglossaries-lite.lua}
+script is therefore limited by this and some of the options
+available to the \gls{makeglossaries} Perl script aren't available
+here. (In particular the \mkglsopt{d} option.)
+
+\begin{important}
+Note that \TeX~Live on Unix-like systems creates a
+symbolic link called \texttt{makeglossaries-lite} (without the
+\texttt{.lua} extension) to the actual
+\texttt{makeglossaries-lite.lua} script, so you may not need to
+supply the extension.
+\end{important}
+
+The \gls{makeglossaries-lite.lua} script can be invoked in the same way
+as \gls{makeglossaries}. For example, if your document is called
+\texttt{myDoc.tex}, then do
+\begin{prompt}
+makeglossaries-lite.lua myDoc
+\end{prompt}
+or
+\begin{prompt}
+makeglossaries-lite myDoc
+\end{prompt}
+
+\emph{Some} of the options available with \gls{makeglossaries} are
+also available with \gls{makeglossaries-lite.lua}. For a complete list of
+available options, do
+\begin{prompt}
+makeglossaries-lite.lua -{}-help
+\end{prompt}
+
+
+\subsection[Using xindy explicitly (Option~3)]{Using
+\gls{xindy} explicitly (\ifpdf \opt3\else Option 3\fi)}
+\label{sec:xindyapp}
+
+\Gls{xindy} comes with \TeX~Live. It has also been added
+to Mik\TeX, but if you don't have it installed, see
+\href{http://tex.stackexchange.com/questions/71167/how-to-use-xindy-with-miktex}{How
+to use Xindy with MikTeX} on
+\urlfootref{http://www.stackexchange.com/}{\TeX\ on StackExchange}.
+
+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 applications such
+as \gls{makeglossaries}. This causes the glossary
+entries to be written in raw \gls*{xindy} format, so you need to
+use \xdyopt{I}\texttt{ xindy} \emph{not} \xdyopt{I}\texttt{ 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}.
+
+
+\subsection[Using makeindex explicitly (Option~2)]{Using
+\gls{makeindex} explicitly (\ifpdf \opt2\else Option 2\fi)}
+\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 \mkidxopt{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}.
+
+
+\subsection{Note to Front-End and Script Developers}
+\label{sec:notedev}
+
+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{\gls{indexingapp}['s]} input file (the output file from the
+\styfmt{glossaries} package's point of view), \meta{out-ext} is the
+extension of the \emph{\gls*{indexingapp}['s]} output file (the
+input file from the \styfmt{glossaries} package's point of view) and
+\meta{log} is the extension of the \gls*{indexingapp}['s] transcript
+file. The label for the glossary is also given for information
+purposes only, but is not required by the \glspl*{indexingapp}. For
+example, the information for the default main glossary is written
+as:
+\begin{verbatim}
+\@newglossary{main}{glg}{gls}{glo}
+\end{verbatim}
+
+The \gls{indexingapp}['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 \gls*{indexingapp} 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.
+
+If \opt1 has been used, the \texttt{.aux} file will contain
+\begin{definition}
+\cs{@gls@reference}\marg{type}\marg{label}\marg{location}
+\end{definition}
+for every time an entry has been referenced. If \opt4 has been
+used, the \texttt{.aux} file will contain one or more instances of
+\begin{definition}
+\cs{glsxtr@resource}\marg{options}\marg{basename}
+\end{definition}
+
+\chapter{Package Options}
+\label{sec:pkgopts}
+
+This section describes the available \styfmt{glossaries} package
+options. You may omit the \texttt{=true} for boolean options. (For
+example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}).
+The \gls{glossaries-extra} package has additional options described
+in the \gls*{glossaries-extra} manual.
+
+\begin{important}
+Note that \meta{key}=\meta{value} package options can't be passed via the
+document class options. (This includes options where the
+\meta{value} part may be omitted, such as \pkgopt{acronym}.) This is
+a general limitation not restricted to the \styfmt{glossaries}
+package. Options that aren't \meta{key}=\meta{value} (such as
+\pkgopt{makeindex}) may be passed via the document class options.
+\end{important}
+
+\section{General Options}
+\label{sec:pkgopts-general}
+
+\begin{description}
+\item[\pkgoptdef{nowarn}] This suppresses all warnings generated by
+the \styfmt{glossaries} package. Don't use this option if you're new to using
+\styfmt{glossaries} as the warnings are designed to help detect
+common mistakes (such as forgetting to use \ics{makeglossaries}).
+Note that the \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} will override this option.
+
+\item[\pkgoptdef{nolangwarn}] This suppresses the warning generated by
+a missing language module.
+
+\item[\pkgoptdef{noredefwarn}] If you load \styfmt{glossaries} with
+a~class or another package that already defines glossary related
+commands, by default \styfmt{glossaries} will warn you that it's
+redefining those commands. If you are aware of the consequences of
+using \styfmt{glossaries} with that class or package and you don't
+want to be warned about it, use this option to suppress those
+warnings. Other warnings will still be issued unless you use the
+\pkgopt{nowarn} option described above.
+
+\item[\pkgoptdef{debug}] Introduced in version 4.24.
+The default setting is \pkgopt[false]{debug}.
+This was a boolean option but as from v4.32 it now accepts the
+values: \pkgoptfmt{false}, \pkgoptfmt{true} and
+\pkgoptfmt{showtargets}. If no value is given, \pkgopt[true]{debug} is assumed.
+Both \pkgopt[true]{debug} and \pkgopt[showtargets]{debug}
+switch on the debug mode (and will automatically
+cancel the \pkgopt{nowarn} option). The \pkgopt[showtargets]{debug}
+option will additionally use
+\begin{definition}[\DescribeMacro\glsshowtarget]
+\cs{glsshowtarget}\marg{target name}
+\end{definition}
+to show the hypertarget or hyperlink name in the margin when
+\cs{glsdohypertarget} is used by commands like \cs{glstarget}
+and when \cs{glsdohyperlink} is used by commands like \cs{gls}.
+This puts the information in the margin using \ics{marginpar} unless
+math mode or inner mode are detected, in which case it puts the
+information in line enclosed by square brackets. The
+\gls{glossaries-extra} package provides an additional setting that
+may be used to show where the indexing is occurring. See the
+\gls{glossaries-extra} manual for further details.
+
+The purpose of the debug mode can be demonstrated with
+the following example document:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\newglossaryentry{sample1}{name={sample1},
+ description={example}}
+\newglossaryentry{sample2}{name={sample2},
+ description={example}}
+\glsadd{sample2}
+\makeglossaries
+\begin{document}
+\gls{sample1}.
+\printglossaries
+\end{document}
+\end{verbatim}
+In this case, only the \texttt{sample1} entry has been indexed, even
+though \verb|\glsadd{sample2}| appears in the source code.
+This is because \verb|\glsadd{sample2}| has been used before the
+associated file is opened by \ics{makeglossaries}. Since the file
+isn't open yet, the information can't be written to it, which is why
+the \texttt{sample2} entry doesn't appear in the glossary.
+
+This situation doesn't cause any errors or warnings as it's
+perfectly legitimate for a user to want to use \styfmt{glossaries}
+to format the entries (e.g.\ abbreviation expansion) but not display
+any lists of terms, abbreviations, symbols etc.
+Without \cs{makeglossaries} the indexing is suppressed but, other
+than that, commands like \cs{gls} behave as usual. It's also
+possible that the user may want to temporarily comment out
+\cs{makeglossaries} in order to suppress the indexing while working
+on a draft version to speed compilation. Therefore
+\cs{makeglossaries} can't be used to enable \cs{newglossaryentry}
+and \cs{glsadd}. They must be enabled by default. (It does, however,
+enable the \gloskey{see} key as that's a more common problem. See
+below.)
+
+The debug mode, enabled with the \pkgopt{debug} option,
+\begin{verbatim}
+\usepackage[debug]{glossaries}
+\end{verbatim}
+will write information to the log file when the indexing
+can't occur because the associated file isn't open.
+The message is written in the form
+\begin{quote}
+Package glossaries Info: wrglossary(\meta{type})(\meta{text}) on
+input line \meta{line number}.
+\end{quote}
+where \meta{type} is the glossary label and \meta{text} is the line
+of text that would've been written to the associated file if
+it had been open. So if any entries haven't appeared in the
+glossary but you're sure you used commands like \cs{glsadd}
+or \cs{glsaddall}, try switching on the \pkgopt{debug} option
+and see if any information has been written to the log file.
+
+\item[\pkgoptdef{seenoindex}] Introduced in version 4.24, this option
+may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or
+\pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the
+cross-referenced entry using \cs{glsadd}. This means that it suffers
+from the same problem as the above. If used before the relevant
+glossary file has been opened, the indexing can't be performed.
+Since this is easy to miss, the \styfmt{glossaries} package by
+default issues an error message if the \gloskey{see} key is used
+before \cs{makeglossaries}. This option allows you to change the
+error into just a warning (\pkgopt[warn]{seenoindex}) or
+ignore it (\pkgopt[ignore]{seenoindex}) if, for example, you want
+to temporarily comment out \cs{makeglossaries} to speed up the
+compilation of a draft document by omitting the indexing.
+
+\item[\pkgoptdef{nomain}] This suppresses the creation of the main
+glossary and associated \texttt{.glo} file, if unrequired. Note that
+if you use this option, you must create another glossary in which to
+put all your entries (either via the \pkgopt{acronym} (or
+\pkgopt{acronyms}) package option described in
+\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols},
+\pkgopt{numbers} or \pkgopt{index} options described in
+\sectionref{sec:pkgopts-other} or via \ics{newglossary} described in
+\sectionref{sec:newglossary}).
+
+\begin{important}
+If you don't use the main glossary and you don't use this option,
+\gls{makeglossaries} will produce a warning.
+\end{important}
+\begin{alltt}
+Warning: File '\emph{filename}.glo' is empty.
+Have you used any entries defined in glossary
+'main'?
+Remember to use package option 'nomain' if
+you don't want to use the main glossary.
+\end{alltt}
+If you did actually want to use the main glossary and you see this
+warning, check that you have referenced the entries in that glossary
+via commands such as \ics{gls}.
+
+\item[\pkgoptdef{sanitizesort}] This is a boolean option that
+determines whether or not to \gls{sanitize} the sort value when
+writing to the external glossary file. For example, suppose you
+define an entry as follows:
+\begin{verbatim}
+\newglossaryentry{hash}{name={\#},sort={#},
+ description={hash symbol}}
+\end{verbatim}
+The sort value (\verb|#|) must be sanitized before writing it to the
+glossary file, otherwise \LaTeX\ will try to interpret it as a
+parameter reference. If, on the other hand, you want the sort value
+expanded, you need to switch off the sanitization. For example,
+suppose you do:
+\begin{verbatim}
+\newcommand{\mysortvalue}{AAA}
+\newglossaryentry{sample}{%
+ name={sample},
+ sort={\mysortvalue},
+ description={an example}}
+\end{verbatim}
+and you actually want \cs{mysortvalue} expanded, so that the entry
+is sorted according to \texttt{AAA}, then use the package option
+\pkgopt[false]{sanitizesort}.
+
+The default for \optsand23 is \pkgopt[true]{sanitizesort}, and the
+default for \opt1 is \pkgopt[false]{sanitizesort}.
+
+\item[\pkgoptdef{savewrites}] This is a boolean option to minimise 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.
+
+\begin{important}
+This option can significantly slow document compilation and may
+cause the indexing to fail. Page numbers in the \gls{numberlist}
+will be incorrect on page boundaries due to \TeX's asynchronous
+output routine. As an alternative, you can use the \sty{scrwfile}
+package (part of the KOMA-Script bundle) and not use this option.
+\end{important}
+
+You can also reduce the number of write registers by using
+\optsor14 or by ensuring you define all your glossary entries in the
+preamble.
+
+\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}
+In general, this package option is best avoided.
+
+\item[\pkgoptdef{translate}] This can take the following values:
+
+ \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.
+ (Note that \sty{babel} provides the command \ics{glossaryname}
+ so that will still be translated if you have loaded \sty{babel}.)
+
+ \item[{\pkgopt[babel]{translate}}] Don't load the \sty{translator}
+package. Instead load \sty{glossaries-babel}.
+
+\begin{important}
+I recommend you use \pkgopt[babel]{translate} if you have any
+problems with the translations or with PDF bookmarks, but to maintain backward
+compatibility, if \sty{babel} has been loaded the default is
+\pkgopt[true]{translate}.
+\end{important}
+
+ \end{description}
+
+ If \pkgopt{translate} is specified without a value,
+ \pkgopt[true]{translate} is assumed. If \pkgopt{translate} isn't
+specified, \pkgopt[true]{translate} is assumed if \sty{babel},
+\sty{polyglossia} or \sty{translator} have been loaded. Otherwise
+\pkgopt[false]{translate} is assumed.
+
+See \sectionref{sec:fixednames} for further details.
+
+\item[\pkgoptdef{notranslate}] This is equivalent to
+\pkgopt[false]{translate} and may be passed via the document class
+options.
+
+\item[\pkgoptdef{nohypertypes}] Use this option if you have multiple
+glossaries and you want to suppress the entry hyperlinks for a
+particular glossary or glossaries. The value of this option should
+be a comma-separated list of glossary types where \ics{gls} etc
+shouldn't have hyperlinks by default. Make sure you enclose the
+value in braces if it contains any commas. Example:
+\begin{verbatim}
+\usepackage[acronym,nohypertypes={acronym,notation}]
+ {glossaries}
+\newglossary[nlg]{notation}{not}{ntn}{Notation}
+\end{verbatim}
+The values must be fully expanded, so \textbf{don't} try
+\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use
+\begin{definition}
+\ics{GlsDeclareNoHyperList}\marg{list}
+\end{definition}
+instead or additionally.
+See \sectionref{sec:glslink} for further details.
+
+\item[\pkgoptdef{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*} or by identifying the glossary with
+\pkgopt{nohypertypes}, described above). Note that
+\pkgopt{nohypertypes} overrides \pkgopt[true]{hyperfirst}.
+This option only affects commands that check the \firstuseflag, such
+as the \glslike\ commands (for example, \ics{gls} or
+\ics{glsdisp}), but not the \glstextlike\ commands
+(for example, \ics{glslink} or \ics{glstext}).
+
+The \pkgopt{hyperfirst} setting applies to
+all glossary types (unless identified by \pkgopt{nohypertypes} or
+defined with \ics{newignoredglossary}). It can be overridden on an
+individual basis by explicitly setting the \gloskey[glslink]{hyper} key
+when referencing an entry (or by using the plus or starred
+version of the referencing command).
+
+It may be that you only want to apply this to just the acronyms
+(where the first use explains the meaning of the acronym) but not
+for ordinary glossary entries (where the first use is identical to
+subsequent uses). In this case, you can use \pkgopt[false]{hyperfirst} and
+apply \cs{glsunsetall} to all the regular (non-acronym) glossaries.
+For example:
+\begin{verbatim}
+ \usepackage[acronym,hyperfirst=false]{glossaries}
+ % acronym and glossary entry definitions
+
+ % at the end of the preamble
+ \glsunsetall[main]
+\end{verbatim}
+
+Alternatively you can redefine the hook
+\begin{definition}[\DescribeMacro\glslinkcheckfirsthyperhook]
+\cs{glslinkcheckfirsthyperhook}
+\end{definition}
+which is used by the commands that check the \firstuseflag, such
+as \ics{gls}. Within the definition of this command, you can use
+\ics{glslabel} to reference the entry label and \ics{glstype} to
+reference the glossary type. You can also use \ics{ifglsused}
+to determine if the entry has been used. You can test if an entry is
+an acronym by checking if it has the \gloskey{long} key set using
+\ics{ifglshaslong}. For example, to switch off the hyperlink on
+first use just for acronyms:
+\begin{verbatim}
+\renewcommand*{\glslinkcheckfirsthyperhook}{%
+ \ifglsused{\glslabel}{}%
+ {%
+ \ifglshaslong{\glslabel}{\setkeys{glslink}{hyper=false}}{}%
+ }%
+}
+\end{verbatim}
+
+Note that this hook isn't used by the commands that don't check the
+\firstuseflag, such as \ics{glstext}. (You can, instead, redefine
+\ics{glslinkpostsetkeys}, which is used by both the \glslike\ and
+\glstextlike\ commands.)
+
+\item[\pkgoptdef{indexonlyfirst}] This is a boolean option that specifies
+whether to only add information to the external glossary file on
+\gls{firstuse}. The default is \pkgopt[false]{indexonlyfirst},
+which will add a line to the file every time one of the
+\glslike\ or \glstextlike\ commands are used. Note that \ics{glsadd}
+will always add information to the external glossary
+file\footnote{bug fix in v4.16 has corrected the code to ensure
+this.}\ (since that's the purpose of that command).
+
+You can customise this by redefining
+\begin{definition}[\DescribeMacro\glswriteentry]
+\cs{glswriteentry}\marg{label}\marg{wr-code}
+\end{definition}
+where \meta{label} is the entry's label and \meta{wr-code} is the
+code that writes the entry's information to the external file.
+The default definition of \cs{glswriteentry} is:
+\begin{verbatim}
+\newcommand*{\glswriteentry}[2]{%
+ \ifglsindexonlyfirst
+ \ifglsused{#1}{}{#2}%
+ \else
+ #2%
+ \fi
+}
+\end{verbatim}
+This checks the \pkgopt{indexonlyfirst} package option (using
+\cs{ifglsindexonlyfirst}) and does \meta{wr-code} if this is
+\pkgoptfmt{false} otherwise it only does \meta{wr-code} of the entry
+hasn't been used.
+
+For example, suppose you only want to index the first use for
+entries in the \texttt{acronym} glossary and not in the
+\texttt{main} (or any other) glossary:
+\begin{verbatim}
+\renewcommand*{\glswriteentry}[2]{%
+ \ifthenelse{\equal{\glsentrytype{#1}}{acronym}}
+ {\ifglsused{#1}{}{#2}}%
+ {#2}%
+}
+\end{verbatim}
+Here I've used \cs{ifthenelse} to ensure the arguments of
+\cs{equal} are fully expanded before the comparison is made.
+
+\item[\pkgoptdef{savenumberlist}] This is a boolean option that
+specifies whether or not to gather and store the \gls{numberlist}
+for each entry. The default is \pkgopt[false]{savenumberlist}. (See
+\ics{glsentrynumberlist} and \ics{glsdisplaynumberlist} in
+\sectionref{sec:glsnolink}.) This is always true if you
+use \opt1.
+
+\end{description}
+
+\section{Sectioning, Headings and TOC Options}
+\label{sec:pkgopts-sec}
+
+\begin{description}
+\item[\pkgoptdef{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[\pkgoptdef{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[\pkgoptdef{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{\glsglossarymark}]
+\cs{glsglossarymark}\marg{glossary title}
+\end{definition}
+By default this uses \cs{@mkboth}\footnote{unless \cls{memoir} is
+loaded, which case it uses \ics{markboth}} but you may
+need to redefine it.
+For example, to only change the right header:
+\begin{verbatim}
+\renewcommand{\glsglossarymark}[1]{\markright{#1}}
+\end{verbatim}
+or to prevent it from changing the headers:
+\begin{verbatim}
+\renewcommand{\glsglossarymark}[1]{}
+\end{verbatim}
+If you want \cs{glsglossarymark} to use \cs{MakeUppercase} in the header, use the
+\pkgopt{ucmark} option described below.
+
+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 \DescribeMacro\glsclearpage\cs{glsclearpage}:
+\begin{verbatim}
+\renewcommand*{\glsclearpage}{\clearpage}
+\end{verbatim}
+
+\item[\pkgoptdef{ucmark}] This is a boolean option (default:
+\pkgopt[false]{ucmark}, unless \cls{memoir} has been loaded, in
+which case it defaults to \pkgopt[true]{ucmark}). If
+set, \ics{glsglossarymark} uses
+\ics{MakeTextUppercase}\footnote{Actually it uses
+\ics{mfirstucMakeUppercase} which is set to \sty{textcase}'s \cs{MakeTextUppercase}
+by the
+\styfmt{glossaries} package. This makes it consistent with
+\ics{makefirstuc}. (The \sty{textcase} package is automatically
+loaded by \styfmt{glossaries}.)}.
+You can test whether this option has been set or not using
+\begin{definition}[\DescribeMacro\ifglsucmark]
+\cs{ifglsucmark} \meta{true part}\cs{else} \meta{false part}\cs{fi}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand{\glsglossarymark}[1]{%
+ \ifglsucmark
+ \markright{\MakeTextUppercase{#1}}%
+ \else
+ \markright{#1}%
+ \fi}
+\end{verbatim}
+If \cls{memoir} has been loaded and \pkgopt{ucfirst} is set, then
+\cls{memoir}'s \ics{memUChead} is used.
+
+\item[\pkgoptdef{numberedsection}]
+The glossaries are placed in unnumbered sectional units by default,
+but this can be changed using \pkgopt{numberedsection}. This option can take
+one of the following values:
+\begin{itemize}
+\item \pkgoptval{false}{numberedsection}: no number, i.e.\ use starred form
+of sectioning command (e.g.\ \cs{chapter*} or \cs{section*});
+
+\item \pkgoptval{nolabel}{numberedsection}:
+use a numbered section, i.e.\ the unstarred form of sectioning
+command (e.g.\ \cs{chapter} or \cs{section}), but
+the section not labelled;
+
+\item \pkgoptval{autolabel}{numberedsection}: numbered with automatic
+labelling. Each glossary uses the unstarred form of a sectioning
+command (e.g.\ \cs{chapter} or \cs{section}) and is assigned a label
+(via \ics{label}). The label is formed from
+\begin{definition}[\DescribeMacro{\glsautoprefix}]
+\cs{glsautoprefix} \meta{type}
+\end{definition}
+where
+\meta{type} is the label identifying that glossary. The default
+value of \cs{glsautoprefix} is empty. 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}
+You can redefine the prefix if the default label clashes with
+another label in your document.
+For example:
+\begin{verbatim}
+\renewcommand*{\glsautoprefix}{glo:}
+\end{verbatim}
+will add \texttt{glo:} to the automatically generated label, so
+you can then, for example, refer to the list of acronyms as follows:
+\begin{verbatim}
+The list of acronyms is in
+section~\ref{glo:\acronymtype}.
+\end{verbatim}
+Or, if you are undecided on a prefix:
+\begin{verbatim}
+The list of acronyms is in
+section~\ref{\glsautoprefix\acronymtype}.
+\end{verbatim}
+
+\item \pkgoptval{nameref}{numberedsection}: this is like
+\pkgoptval{autolabel}{numberedsection} but uses an unnumbered
+sectioning command (e.g.\ \ics{chapter*} or \ics{section*}). It's
+designed for use with the \sty{nameref} package. For example:
+\begin{verbatim}
+\usepackage{nameref}
+\usepackage[numberedsection=nameref]{glossaries}
+\end{verbatim}
+Now \verb|\nameref{main}| will display the (TOC) section title
+associated with the \texttt{main} glossary. As above, you can
+redefine \cs{glsautoprefix} to provide a prefix for the label.
+\end{itemize}
+
+\end{description}
+
+\section{Glossary Appearance Options}
+\label{sec:pkgopts-printglos}
+
+\begin{description}
+\item[\pkgoptdef{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.
+The labelling systems uses \meta{prefix}\meta{label}, where
+\meta{label} is the entry's label and \meta{prefix} is given by
+\begin{definition}[\DescribeMacro\GlsEntryCounterLabelPrefix]
+\cs{GlsEntryCounterLabelPrefix}
+\end{definition}
+(which defaults to \texttt{glsentry-}).
+
+\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[\pkgoptdef{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.
+\end{important}
+
+If you want the counter reset at the start of each glossary, you can
+redefine \ics{glossarypreamble} to use
+\begin{definition}[\DescribeMacro{\glsresetentrycounter}]
+\cs{glsresetentrycounter}
+\end{definition}
+which sets \ctr{glossaryentry} to zero:
+\begin{verbatim}
+\renewcommand{\glossarypreamble}{%
+ \glsresetentrycounter
+}
+\end{verbatim}
+or if you are using \ics{setglossarypreamble}, add it to each
+glossary preamble, as required. For example:
+\begin{verbatim}
+\setglossarypreamble[acronym]{%
+ \glsresetentrycounter
+ The preamble text here for the list of acronyms.
+}
+\setglossarypreamble{%
+ \glsresetentrycounter
+ The preamble text here for the main glossary.
+}
+\end{verbatim}
+
+\item[\pkgoptdef{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.
+
+\item[\pkgoptdef{style}] This is a \meta{key}=\meta{value} option.
+(Default is \pkgopt[list]{style}, unless \sty{classicthesis}
+has been loaded, in which case the default is \pkgopt[index]{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}. Alternatively, you can
+set the style using
+\begin{definition}
+\cs{setglossarystyle}\marg{style name}
+\end{definition}
+(See \sectionref{sec:styles} for further details.)
+
+\item[\pkgoptdef{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 (unless
+you explicitly load \sty{glossary-long}).
+
+\item[\pkgoptdef{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
+(unless you explicitly load \sty{glossary-super}).
+
+\item[\pkgoptdef{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
+(unless you explicitly load \sty{glossary-list}).
+Note that since the default style is \glostyle{list} (unless
+\sty{classicthesis} has been loaded), you will
+also need to use the \pkgopt{style} option to set the style to
+something else.
+
+\item[\pkgoptdef{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
+(unless you explicitly load \sty{glossary-tree}). Note that if
+\sty{classicthesis} has been loaded, the default style is
+\glostyle{index}, which is provided by \sty{glossary-tree}.
+
+\item[\pkgoptdef{nostyles}] This prevents all the predefined styles
+from being loaded. If you use this option, you need to load a
+glossary style package (such as \sty{glossary-mcols}). Also if you
+use this option, you can't use the \pkgopt{style} package option.
+Instead you must either use \ics{setglossarystyle}\marg{style} or the
+\gloskey[printglossary]{style} key in the optional argument to
+\ics{printglossary}. Example:
+\begin{verbatim}
+\usepackage[nostyles]{glossaries}
+\usepackage{glossary-mcols}
+\setglossarystyle{mcoltree}
+\end{verbatim}
+
+\item[\pkgoptdef{esclocations}] This is a boolean option. (The default
+is \pkgopt[true]{esclocations}, but \ics{makenoidxglossaries}
+changes it to \pkgopt[false]{esclocations}.) Both \gls{makeindex} and \gls{xindy}
+are fussy about the location formats (\gls{makeindex} more so than
+\gls{xindy}) so the \styfmt{glossaries} package tries to ensure that
+special characters are escaped and allows for the location to be
+substituted for a format that's more acceptable to the indexing
+application. This requires a bit of trickery to circumvent the
+problem posed by \TeX's asynchronous output routine, which can go
+wrong and also adds to the complexity of the document build.
+
+If you're sure that your locations will always expand to an
+acceptable format (or you're prepared to post-process the glossary
+file before passing it to the relevant indexing application) then
+use \pkgopt[false]{esclocations} to avoid the complex escaping
+of location values. (See \ifpdf section~\ref*{sec:wrgloss}\fi \qt{Writing information to associated files} in the documented
+code for further details.)
+
+\item[\pkgoptdef{nonumberlist}] This option will suppress the
+associated \glspl{numberlist} in the glossaries (see also
+\sectionref{sec:numberlists}). Note that if you use \optsor23
+(\gls{makeindex} or \gls{xindy}) then the locations must still be
+valid. This package option merely prevents the \gls{numberlist}
+from being displayed, but both \gls{makeindex} and \gls{xindy}
+still require a location or cross-reference for each term that's
+indexed. Remember that \gls{numberlist} includes any
+cross-references, so suppressing the \gls{numberlist} will also hide
+the cross-references (see below).
+
+\item[\pkgoptdef{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[\pkgoptdef{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}).
+
+\item[\pkgoptdef{nopostdot}] This is a boolean option. If no value is
+specified, \texttt{true} is assumed. When set to \texttt{true}, this
+option suppresses the default post description dot used by some of
+the predefined styles. The default setting is
+\pkgopt[false]{nopostdot}.
+
+\item[\pkgoptdef{nogroupskip}] This is a boolean option. If no value is
+specified, \texttt{true} is assumed. When set to \texttt{true}, this
+option suppresses the default vertical gap between groups used by
+some of the predefined styles. The default setting is
+\pkgopt[false]{nogroupskip}.
+
+\end{description}
+
+\section{Sorting Options}
+\label{sec:pkgopts-sort}
+
+\begin{description}
+\item[\pkgoptdef{sort}] If you use \optsor23, this package option is
+the only way of specifying how to sort the glossaries. Only \opt1
+allows you to specify sort methods for individual glossaries
+via the \gloskey[printnoidxglossary]{sort} key in the optional
+argument of \ics{printnoidxglossary}. If you have multiple
+glossaries in your document and you are using \opt1, only use
+the package options
+\pkgopt[def]{sort} or \pkgopt[use]{sort} if you want to set this
+sort method for \emph{all} your glossaries.
+
+This is a \meta{key}=\meta{value} option where
+\meta{value} may be one of the following:
+\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).
+
+Both \pkgopt[def]{sort} and \pkgopt[use]{sort} set the sort key to a
+six digit number via
+\begin{definition}[\DescribeMacro\glssortnumberfmt]
+\cs{glssortnumberfmt}\marg{number}
+\end{definition}
+(padded with leading zeros, where necessary). This can be
+redefined, if required, before the entries are defined (in the
+case of \pkgopt[def]{sort}) or before the entries are used
+(in the case of \pkgopt[use]{sort}).
+
+\item \pkgoptval{none}{sort} : this setting is new to version 4.30
+and is only for documents that don't use \cs{makeglossaries} (\optsor23)
+or \cs{makenoidxglossaries} (\opt1). It omits the code used to sanitize
+or escape the sort value, since it's not required. This can help to
+improve the document build speed, especially if there are a large
+number of entries. This option
+can't be used with \cs{printglossary} or \cs{printnoidxglossary}
+(or the iterative versions \cs{printglossaries} or
+\cs{printnoidxglossaries}). It may be used with
+\sty{glossaries-extra}'s \cs{printunsrtglossary} (\opt5).
+\end{itemize}
+Note that the group styles (such as \glostyle{listgroup}) are
+incompatible with the \pkgopt[use]{sort} and \pkgopt[def]{sort}
+options.
+
+The default is \pkgopt[standard]{sort}. When the standard sort
+option is in use, you can hook into the sort mechanism by
+redefining:
+\begin{definition}[\DescribeMacro{\glsprestandardsort}]
+\cs{glsprestandardsort}\marg{sort cs}\marg{type}\marg{label}
+\end{definition}
+where \meta{sort cs} is a temporary control sequence that stores the
+sort value (which was either explicitly set via the \gloskey{sort}
+key or implicitly set via the \gloskey{name} key) before any escaping of the
+\gls{makeindex}\slash\gls{xindy} special characters is performed.
+By default \cs{glsprestandardsort} just does:
+\begin{definition}[\DescribeMacro{\glsdosanitizesort}]
+\cs{glsdosanitizesort}
+\end{definition}
+which \gls{sanitize}[s] \meta{sort cs} if the \pkgopt{sanitizesort} package
+option is set (or does nothing if the package option
+\pkgopt[false]{sanitizesort} is used).
+
+The other arguments, \meta{type} and \meta{label}, are the
+glossary type and the entry label for the current entry. Note that
+\meta{type} will always be a control sequence, but \meta{label} will
+be in the form used in the first argument of \ics{newglossaryentry}.
+
+\begin{important}
+Redefining \cs{glsprestandardsort} won't affect any entries that
+have already been defined and will have no effect at all if you
+are using \pkgopt[def]{sort} or \pkgopt[use]{sort}.
+\end{important}
+
+\begin{example}{Mixing Alphabetical and Order of Definition Sorting}{ex:diffsorts}
+Suppose I have three glossaries: \texttt{main},
+\texttt{acronym} and \texttt{notation}, and let's suppose
+I want the \texttt{main} and \texttt{acronym} glossaries to be
+sorted alphabetically, but the \texttt{notation} type should be
+sorted in order of definition.
+
+For \opt1, I~just need to set the \gloskey[printnoidxglossary]{sort} key in
+the optional argument of \ics{printnoidxglossary}:
+\begin{verbatim}
+\printnoidxglossary[sort=word]
+\printnoidxglossary[type=acronym,sort=word]
+\printnoidxglossary[type=notation,sort=def]
+\end{verbatim}
+
+For \optsor23, I can set the sort to \texttt{standard}
+(which is the default, but can be explicitly set via the
+package option \pkgopt[standard]{sort}), and I can either define
+all my \texttt{main} and \texttt{acronym} entries, then
+redefine \cs{glsprestandardsort} to set \meta{sort cs} to
+an incremented integer, and then define all my
+\texttt{notation} entries. Alternatively, I can redefine
+\cs{glsprestandardsort} to check for the glossary type and only
+modify \meta{sort cs} if \meta{type} is \texttt{notation}.
+
+The first option can be achieved as follows:
+\begin{verbatim}
+\newcounter{sortcount}
+
+\renewcommand{\glsprestandardsort}[3]{%
+ \stepcounter{sortcount}%
+ \edef#1{\glssortnumberfmt{\arabic{sortcount}}}%
+}
+\end{verbatim}
+The second option can be achieved as follows:
+\begin{verbatim}
+\newcounter{sortcount}
+
+\renewcommand{\glsprestandardsort}[3]{%
+ \ifdefstring{#2}{notation}%
+ {%
+ \stepcounter{sortcount}%
+ \edef#1{\glssortnumberfmt{\arabic{sortcount}}}%
+ }%
+ {%
+ \glsdosanitizesort
+ }%
+}
+\end{verbatim}
+(\cs{ifdefstring} is defined by the \sty{etoolbox} package.)
+For a complete document, see the sample file \samplefile{Sort}.
+\end{example}
+
+\begin{example}{Customizing Standard Sort (Options 2 or 3)}{ex:customsort}
+Suppose you want a glossary of people and you want the names listed
+as \meta{first-name} \meta{surname} in the glossary, but you want the names
+sorted by \meta{surname}, \meta{first-name}. You can do this by
+defining a command called, say,
+\cs{name}\marg{first-name}\marg{surname} that you can use in the
+\gloskey{name} key when you define the entry, but hook into the
+standard sort mechanism to temporarily redefine \cs{name} while the
+sort value is being set.
+
+First, define two commands to set the person's name:
+\begin{verbatim}
+\newcommand{\sortname}[2]{#2, #1}
+\newcommand{\textname}[2]{#1 #2}
+\end{verbatim}
+and \cs{name} needs to be initialised to \cs{textname}:
+\begin{verbatim}
+\let\name\textname
+\end{verbatim}
+Now redefine \cs{glsprestandardsort} so that it temporarily sets
+\cs{name} to \cs{sortname} and expands the sort value, then sets
+\cs{name} to \cs{textname} so that the person's name appears as
+\meta{first-name} \meta{surname} in the text:
+\begin{verbatim}
+\renewcommand{\glsprestandardsort}[3]{%
+ \let\name\sortname
+ \edef#1{\expandafter\expandonce\expandafter{#1}}%
+ \let\name\textname
+ \glsdosanitizesort
+}
+\end{verbatim}
+(The somewhat complicate use of \cs{expandafter} etc helps to
+protect fragile commands, but care is still needed.)
+
+Now the entries can be defined:
+\begin{verbatim}
+\newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}},
+ description={some information about Joe Bloggs}}
+
+\newglossaryentry{johnsmith}{name={\name{John}{Smith}},
+ description={some information about John Smith}}
+\end{verbatim}
+For a complete document, see the sample file \samplefile{People}.
+\end{example}
+
+\item[\pkgoptdef{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}
+
+If you use \opt1, this setting will be used if you use
+\gloskey[printnoidxglossary]{sort}\texttt{=standard} in
+the optional argument of \ics{printnoidxglossary}:
+\begin{verbatim}
+\printnoidxglossary[sort=standard]
+\end{verbatim}
+Alternatively, you can specify the order for individual glossaries:
+\begin{verbatim}
+\printnoidxglossary[sort=word]
+\printnoidxglossary[type=acronym,sort=letter]
+\end{verbatim}
+
+\item[\pkgoptdef{makeindex}] (\opt2) 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.
+
+You may omit this package option if you are using \opt2 as this is the
+default. It's available in case you need to override the effect of an earlier
+occurrence of \pkgopt{xindy} in the package option list.
+
+\item[\pkgoptdef{xindy}] (\opt3) 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.
+
+This 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}
+If no value is supplied to this package option (either simply
+writing \texttt{xindy} or writing \verb|xindy={}|) then the
+language, codepage and number group settings are unchanged. See
+\sectionref{sec:xindy} for further details on using \gls{xindy} with
+the \styfmt{glossaries} package.
+
+\item[\pkgoptdef{xindygloss}] (\opt3) This is equivalent to
+\verb|xindy={}| (that is, the \pkgopt{xindy} option without any value
+supplied) and may be used as a document class option. The language
+and code page can be set via \ics{GlsSetXdyLanguage} and
+\ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.)
+
+\item[\pkgoptdef{xindynoglsnumbers}] (\opt3) This is equivalent to
+\verb|xindy={glsnumbers=false}| and may be used as a document class
+option.
+
+\item[\pkgoptdef{automake}] This is option was introduced to
+version 4.08 as a boolean option. As from version 4.42 it may now
+take three values: \texttt{false} (default), \texttt{true}
+or \texttt{immediate}. If no option is supplied, \texttt{immediate}
+is assumed.
+The option \pkgopt[true]{automake} will attempt to run \gls{makeindex} or \gls{xindy} using
+\TeX's \ics{write18} mechanism at the end of the document.
+The option \pkgopt[immediate]{automake} will attempt to
+run \gls{makeindex} or \gls{xindy} at the start of
+\ics{makeglossaries} using \cs{immediate} (before the glossary files have been opened).
+
+In the case of \pkgopt[true]{automake}, the associated files
+are created at the end of the document ready for the next \LaTeX\
+run. Since there is a possibility of commands such as \cs{gls}
+occurring on the last page of the document, it's not possible
+to use \cs{immediate} to close the associated file or with
+\cs{write18} since the writing of the final indexing lines may
+have been delayed. In certain situations this can mean that
+the \cs{write18} fails. In such cases, you will need to use
+\pkgopt[immediate]{automake} instead.
+
+With \pkgopt[immediate]{automake}, you will get a warning on
+the first \LaTeX\ run as the associated glossary files don't exist
+yet.
+
+Since this mechanism can be a security risk, some \TeX\
+distributions disable it completely, in which case this option won't
+have an effect. (If this option doesn't appear to work, search the
+log file for \qt{runsystem} and see if it is followed by
+\qt{enabled} or \qt{disabled}.)
+
+Some distributions allow \cs{write18} in a restricted mode.
+This mode has a~limited number of trusted applications, which
+usually includes \gls{makeindex} but may not include \gls{xindy}. So
+if you have the restricted mode on, \pkgopt{automake} should work
+with \gls*{makeindex} but may not work with \gls{xindy}.
+
+However even in unrestricted mode this option may not work with
+\gls*{xindy} as \gls*{xindy} uses language names that don't always
+correspond with \ics{babel}'s language names. (The
+\gls{makeglossaries} script applies mappings to assist you.)
+Note that you still need at least two \LaTeX\ runs to ensure the document
+is up-to-date with this setting.
+
+Since this package option attempts to run the \gls{indexingapp} on
+every \LaTeX\ run, its use should be considered a last resort for
+those who can't work out how to incorporate the \gls*{indexingapp}
+into their document build. The default value for this option is
+\pkgopt[false]{automake}.
+
+\end{description}
+
+\section{Acronym Options}
+\label{sec:pkgopts-acronym}
+
+\begin{description}
+\item[\pkgoptdef{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}
+It will also define
+\begin{definition}[\DescribeMacro\printacronyms]
+\cs{printacronyms}\oarg{options}
+\end{definition}
+that's equivalent to
+\begin{alltt}
+\ics{printglossary}[type=acronym,\meta{options}]
+\end{alltt}
+(unless that command is already defined before the beginning of the
+document or the package option \pkgopt{compatible-3.07} is used).
+
+If you are using \opt1, you need to use
+\begin{alltt}
+\ics{printnoidxglossary}[type=acronym,\meta{options}]
+\end{alltt}
+to display the list of acronyms.
+
+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} unless the \pkgopt{nomain} option has been used.}
+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.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{acronym} glossary. (That is, you
+don't intend to use the \texttt{main} glossary.)
+\end{important}
+
+\item[\pkgoptdef{acronyms}] This is equivalent to
+\pkgopt[true]{acronym} and may be used in the document class option
+list.
+
+\item[\pkgoptdef{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}
+You can use
+\begin{definition}[\DescribeMacro\DeclareAcronymList]
+\cs{DeclareAcronymList}\marg{list}
+\end{definition}
+instead of or in addition to the \pkgopt{acronymlists} option.
+This will add the glossaries given in \meta{list} to the list of glossaries
+that are identified as lists of acronyms. To replace the list of acronym lists
+with a new list use:
+\begin{definition}[\DescribeMacro\SetAcronymLists]
+\cs{SetAcronymLists}\marg{list}
+\end{definition}
+
+You can determine if a glossary has been identified as being a list
+of acronyms using:
+\begin{definition}[\DescribeMacro\glsIfListOfAcronyms]
+\cs{glsIfListOfAcronyms}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+
+\item[\pkgoptdef{shortcuts}] This option provides shortcut commands
+for acronyms. See \sectionref{sec:acronyms} for further details.
+Alternatively you can use:
+\begin{definition}[\DescribeMacro\DefineAcronymSynonyms]
+\cs{DefineAcronymSynonyms}
+\end{definition}
+\end{description}
+
+\subsection{Deprecated Acronym Style Options}
+\label{sec:pkgopts-old-acronym}
+
+The package options listed in this section are now deprecated but
+are kept for backward-compatibility. Use \ics{setacronymstyle}
+instead. See \sectionref{sec:acronyms} for further details.
+
+\begin{description}
+\item[\pkgoptdef{description}] This option changes the definition of
+\ics{newacronym} to allow a description.
+This option may be replaced by
+\begin{verbatim}
+\setacronymstyle{long-short-desc}
+\end{verbatim}
+or (with \pkgopt{smallcaps})
+\begin{verbatim}
+\setacronymstyle{long-sc-short-desc}
+\end{verbatim}
+or (with \pkgopt{smaller})
+\begin{verbatim}
+\setacronymstyle{long-sm-short-desc}
+\end{verbatim}
+or (with \pkgopt{footnote})
+\begin{verbatim}
+\setacronymstyle{footnote-desc}
+\end{verbatim}
+or (with \pkgopt{footnote} and \pkgopt{smallcaps})
+\begin{verbatim}
+\setacronymstyle{footnote-sc-desc}
+\end{verbatim}
+or (with \pkgopt{footnote} and \pkgopt{smaller})
+\begin{verbatim}
+\setacronymstyle{footnote-sm-desc}
+\end{verbatim}
+or (with \pkgopt{dua})
+\begin{verbatim}
+\setacronymstyle{dua-desc}
+\end{verbatim}
+
+\item[\pkgoptdef{smallcaps}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed.
+This option may be replaced by:
+\begin{verbatim}
+\setacronymstyle{long-sc-short}
+\end{verbatim}
+or (with \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{long-sc-short-desc}
+\end{verbatim}
+or (with \pkgopt{description} and \pkgopt{footnote})
+\begin{verbatim}
+\setacronymstyle{footnote-sc-desc}
+\end{verbatim}
+
+\item[\pkgoptdef{smaller}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed.
+\begin{important}
+If you use this option, you will need to include the \sty{relsize}
+package or otherwise define \ics{textsmaller} or redefine
+\ics{acronymfont}.
+\end{important}
+This option may be replaced by:
+\begin{verbatim}
+\setacronymstyle{long-sm-short}
+\end{verbatim}
+or (with \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{long-sm-short-desc}
+\end{verbatim}
+or (with \pkgopt{description} and \pkgopt{footnote})
+\begin{verbatim}
+\setacronymstyle{footnote-sm-desc}
+\end{verbatim}
+
+\item[\pkgoptdef{footnote}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed.
+This option may be replaced by:
+\begin{verbatim}
+\setacronymstyle{footnote}
+\end{verbatim}
+or (with \pkgopt{smallcaps})
+\begin{verbatim}
+\setacronymstyle{footnote-sc}
+\end{verbatim}
+or (with \pkgopt{smaller})
+\begin{verbatim}
+\setacronymstyle{footnote-sm}
+\end{verbatim}
+or (with \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{footnote-desc}
+\end{verbatim}
+or (with \pkgopt{smallcaps} and \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{footnote-sc-desc}
+\end{verbatim}
+or (with \pkgopt{smaller} and \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{footnote-sm-desc}
+\end{verbatim}
+
+
+\item[\pkgoptdef{dua}] This option changes the definition of
+\ics{newacronym} so that acronyms are always expanded.
+This option may be replaced by:
+\begin{verbatim}
+\setacronymstyle{dua}
+\end{verbatim}
+or (with \pkgopt{description})
+\begin{verbatim}
+\setacronymstyle{dua-desc}
+\end{verbatim}
+
+\end{description}
+
+\section{Other Options}
+\label{sec:pkgopts-other}
+
+Other available options that don't fit any of the above categories
+are:
+\begin{description}
+\item[\pkgoptdef{symbols}] This option defines a new glossary type with
+the label \texttt{symbols} via
+\begin{verbatim}
+\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
+\end{verbatim}
+It also defines
+\begin{definition}[\DescribeMacro\printsymbols]
+\cs{printsymbols}\oarg{options}
+\end{definition}
+which is a synonym for
+\begin{alltt}
+\ics{printglossary}[type=symbols,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=symbols,\meta{options}]
+\end{alltt}
+to display the list of symbols.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{symbols} glossary and don't intend
+to use the \texttt{main} glossary.
+\end{important}
+
+The \styfmt{glossaries-extra} package has a slightly modified
+version of this option which additionally provides \ics{glsxtrnewsymbol}
+as a convenient shortcut method for defining symbols. See the
+\styfmt{glossaries-extra} manual for further details.
+
+\item[\pkgoptdef{numbers}] This option defines a new glossary type with
+the label \texttt{numbers} via
+\begin{verbatim}
+\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
+\end{verbatim}
+It also defines
+\begin{definition}[\DescribeMacro\printnumbers]
+\cs{printnumbers}\oarg{options}
+\end{definition}
+which is a synonym for
+\begin{alltt}
+\ics{printglossary}[type=numbers,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=numbers,\meta{options}]
+\end{alltt}
+to display the list of numbers.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{numbers} glossary and don't intend
+to use the \texttt{main} glossary.
+\end{important}
+
+The \styfmt{glossaries-extra} package has a slightly modified
+version of this option which additionally provides \ics{glsxtrnewnumber}
+as a convenient shortcut method for defining numbers. See the
+\styfmt{glossaries-extra} manual for further details.
+
+\item[\pkgoptdef{index}] This option defines a new glossary type with
+the label \texttt{index} via
+\begin{verbatim}
+\newglossary[ilg]{index}{ind}{idx}{\indexname}%
+\end{verbatim}
+It also defines
+\begin{definition}[\DescribeMacro\newterm]
+\cs{newterm}\oarg{options}\marg{term}
+\end{definition}
+which is a synonym for
+\begin{alltt}
+\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},%
+description=\ics{nopostdesc},\meta{options}]
+\end{alltt}
+and
+\begin{definition}[\DescribeMacro\printindex]
+\cs{printindex}\oarg{options}
+\end{definition}
+which is a synonym for
+\begin{alltt}
+\ics{printglossary}[type=index,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=index,\meta{options}]
+\end{alltt}
+to display this glossary.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{index} glossary and don't intend to
+use the \texttt{main} glossary. Note that you
+can't mix this option with \ics{index}. Either use
+\styfmt{glossaries} for the indexing or use a~custom indexing
+package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}.
+(You can, of course, load one of those packages and
+load \styfmt{glossaries} without the \pkgopt{index} package option.)
+\end{important}
+
+Since the index isn't designed for terms with descriptions, you
+might also want to disable the hyperlinks for this glossary using
+the package option \pkgopt[index]{nohypertypes} or the command
+\begin{display}
+\ics{GlsDeclareNoHyperList}\verb|{index}|
+\end{display}
+
+The example file \samplefile{-index} illustrates the use of the
+\pkgopt{index} package option.
+
+\item[\pkgoptdef{noglossaryindex}] This option switches off \pkgopt{index}
+if \pkgopt{index} has been passed implicitly (for example,
+through global document options). This option can't be used
+in \cs{setupglossaries}.
+
+\item[\pkgoptdef{compatible-2.07}] Compatibility mode for old documents
+created using version 2.07 or below.
+
+\item[\pkgoptdef{compatible-3.07}] Compatibility mode for old documents
+created using version 3.07 or below.
+
+\item[\pkgoptdef{kernelglossredefs}] As a legacy from the precursor
+\sty{glossary} package, the standard glossary commands provided
+by the \LaTeX\ kernel (\cs{makeglossary} and \cs{glossary}) are
+redefined in terms of the \styfmt{glossaries} package's commands.
+However, they were never documented in this user manual, and the
+conversion guide (\htmldoc{Upgrading from the glossary package to the
+glossaries package}{glossary2glossaries}) explicitly discourages
+their use.
+
+The use of those kernel commands (instead of the appropriate
+commands documented in this user guide) are deprecated, and you will
+now get a warning if you try using them.
+
+In the event that you require the original form of these kernel
+commands, for example, if you need to use the \styfmt{glossaries}
+package with another class or package that also performs
+glossary-style indexing, then you can restore these commands to
+their previous definition (that is, their definitions prior to
+loading the \styfmt{glossaries} package) with the package option
+\pkgopt[false]{kernelglossredefs}. You may also need to use the
+\pkgopt{nomain} option in the event of file extension conflicts.
+(In which case, you must provide a new default glossary for use with
+the \sty{glossaries} package.)
+
+This option may take one of three values: \pkgoptfmt{true}
+(redefine with warnings, default), \pkgoptfmt{false} (restore
+previous definitions) or \pkgoptfmt{nowarn} (redefine without
+warnings, not recommended).
+
+Note that the only glossary-related commands provided by the \LaTeX\
+kernel are \cs{makeglossary} and \cs{glossary}. Other packages
+or classes may provide additional glossary-related commands or
+environments that conflict with \styfmt{glossaries} (such as
+\cs{printglossary} and \env{theglossary}). These non-kernel commands
+aren't affected by this package option, and you will have to find
+some way to resolve the conflict if you require both glossary
+mechanisms. (The \sty{glossaries} package will override the existing
+definitions of \cs{printglossary} and \env{theglossary}.)
+
+In general, if possible, it's best to stick with just one package that
+provides a glossary mechanism. (The \styfmt{glossaries} package does
+check for the \sty{doc} package and patches \cs{PrintChanges}.)
+
+\end{description}
+
+\section{Setting Options After the Package is Loaded}
+\label{sec:setupglossaries}
+
+Some of the options described above may also be set after the
+\styfmt{glossaries} package has been loaded using
+\begin{definition}[\DescribeMacro{\setupglossaries}]
+\cs{setupglossaries}\marg{key-val list}
+\end{definition}
+The following package options \textbf{can't} be used in
+\cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss},
+\pkgopt{xindynoglsnumbers}, \pkgopt{makeindex},
+\pkgopt{nolong}, \pkgopt{nosuper}, \pkgopt{nolist},
+\pkgopt{notree}, \pkgopt{nostyles}, \pkgopt{nomain},
+\pkgopt{compatible-2.07}, \pkgopt{translate}, \pkgopt{notranslate},
+\pkgopt{acronym}. These options have to be set while the package is
+loading, except for the \pkgopt{xindy} sub-options which can be set
+using commands like \ics{GlsSetXdyLanguage} (see
+\sectionref{sec:xindy} for further details).
+
+\begin{important}
+If you need to use this command, use it as soon as
+possible after loading \styfmt{glossaries} otherwise you might
+end up using it too late for the change to take effect. For example,
+if you try changing the acronym styles (such as \pkgopt{smallcaps})
+after you have started defining your acronyms, you are likely to get
+unexpected results. If you try changing the sort option after you have
+started to define entries, you may get unexpected results.
+\end{important}
+
+\chapter{Setting Up}
+\label{sec:setup}
+
+In the preamble you need to indicate whether you want to use \opt1,
+\opt2 or \opt3. It's not possible to mix these options within
+a~document, although some combinations are possible with
+\gls*{glossaries-extra}. (For \optsand45 see the \gls{bib2gls} and
+\gls{glossaries-extra} manuals.)
+
+\section[Option 1]{\ifpdf\opt1\else Option 1\fi}
+\label{sec:setupopt1}
+
+The command
+\begin{definition}[\DescribeMacro{\makenoidxglossaries}]
+\cs{makenoidxglossaries}
+\end{definition}
+must be placed in the preamble. This sets up the internal commands
+required to make \opt1 work.
+\textbf{If you omit \cs{makenoidxglossaries} none of
+the glossaries will be displayed.}
+
+\section[Options 2 and 3]{\ifpdf\optsand23\else Options 2 and 3\fi}
+\label{sec:setupopt23}
+
+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 (for \optsor23, respectively) and to ensure that glossary
+entries are written to the appropriate output files.
+\textbf{If you omit \cs{makeglossaries} none of
+the glossary files will be created.}
+
+\begin{important}
+Note that some of the commands provided by the \styfmt{glossaries}
+package must not be used after \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.
+
+Similarly, there are some commands that must not be used before
+\cs{makeglossaries}.
+\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}
+That this command must not be used after \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} (\opt2) or
+\ics{jobname}\filetype{.xdy} (\opt3). 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 not be used after
+\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}
+This command must not be used after \cs{makeglossaries}.
+
+If you use \opt3, you can have a different compositor for page
+numbers starting with an upper case alphabetical character using:
+\begin{definition}[\DescribeMacro{\glsSetAlphaCompositor}]
+\cs{glsSetAlphaCompositor}\marg{symbol}
+\end{definition}
+This command has no effect if you use \opt2. 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}.
+
+\chapter{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. In fact, some
+commands such as \cs{longnewglossaryentry}
+may only be used in the preamble. See \sectionref{sec:docdefs} for
+a discussion of the problems with defining entries within the
+document instead of in the preamble. (The \gls{glossaries-extra}
+package has an option that provides a restricted form of document
+definitions that avoids some of the issues discussed in
+\sectionref{sec:docdefs}.)
+\begin{important}
+\opt1 enforces the preamble-only restriction on
+\ics{newglossaryentry}. \opt4 requires that definitions are provided
+in \texttt{.bib} format. \opt5 requires either preamble-only
+definitions or the use of the \sty{glossaries-extra} package option
+\optfmt{docdef=restricted}.
+\end{important}
+
+Only those entries that are indexed 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. See
+\sectionref{sec:printglossary} to find out how to display the
+glossary.
+
+
+New glossary entries are defined using the command:
+\begin{definition}[\DescribeMacro{\newglossaryentry}]
+\cs{newglossaryentry}\marg{label}\marg{key=value list}
+\end{definition}
+This is a short command, so values in \meta{key-val list} can't
+contain any paragraph breaks. Take care to enclose values containing
+any commas (\texttt{,}) or equal signs (\texttt{=}) with braces to hide them
+from the key=value list parser. Be careful to ensure that no
+spurious spaces are included at the start and end of the braces.
+
+If you have a long description that
+needs to span multiple paragraphs, use
+\begin{definition}[\DescribeMacro{\longnewglossaryentry}]
+\cs{longnewglossaryentry}\marg{label}\marg{key=value
+list}\marg{long description}
+\end{definition}
+instead. Note that this command may only be used in the preamble.
+Be careful of unwanted spaces. \cs{longnewglossaryentry}
+will remove trailing spaces in the description (via \cs{unskip})
+but won't remove leading spaces (otherwise it would interfere with
+commands like \cs{Glsentrydesc}). This command also appends
+\cs{nopostdesc} to the end of the description, which suppresses the
+post-description hook. The \sty{glossaries-extra} package provides
+a starred version of \cs{longnewglossaryentry} that doesn't append
+either \cs{unskip} or \cs{nopostdesc}.
+
+There are also commands that will only define the entry if it
+hasn't already been defined:
+\begin{definition}[\DescribeMacro\provideglossaryentry]
+\cs{provideglossaryentry}\marg{label}\marg{key=value list}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\longprovideglossaryentry]
+\cs{longprovideglossaryentry}\marg{label}\marg{key=value
+list}\marg{long description}
+\end{definition}
+(These are both preamble-only commands.)
+
+For all the above commands, the first argument, \meta{label}, must be
+a~unique label with which to identify this entry. \textbf{This can't contain
+any non-expandable commands or active characters.} The reason for
+this restriction is that the label is used to construct internal commands
+that store the associated information (similarly to commands
+like \cs{label}) and therefore must be able to expand to a valid
+control sequence name.
+
+\begin{important}
+Note that although an \gls{exlatinchar} or other \gls{nonlatinchar},
+such as \'e or \ss, looks like a plain character in your
+\texttt{.tex} file, it's actually a~macro (an active character) and
+therefore can't be used in the label. (This applies to \LaTeX\
+rather than \XeLaTeX.) Also be careful of
+\sty{babel}'s options that change certain punctuation characters
+(such as \texttt{:} or \texttt{-}) to active characters.
+\end{important}
+
+The second argument, \meta{key=value 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}.
+The description is set in the third argument of
+\cs{longnewglossaryentry} and \cs{longprovideglossaryentry}. With
+the other commands it's set via the \gloskey{description} key.
+As is typical with \meta{key}=\meta{value} lists, values that contain
+a comma or equal sign must be enclosed in braces. Available fields
+are listed below. Additional fields are provided by the
+supplementary packages \sty{glossaries-prefix}
+(\sectionref{sec:prefix}) and \sty{glossaries-accsupp}
+(\sectionref{sec:accsupp}) and also by \gls{glossaries-extra}.
+You can also define your own custom keys (see
+\sectionref{sec:addkey}).
+
+\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.
+
+\begin{important}
+If the \gloskey{name} key contains any commands, you must also
+use the \gloskey{sort} key (described below) if you intend sorting the entries
+alphabetically, otherwise the entries can't be sorted correctly.
+\end{important}
+
+\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}
+or, better, use \cs{longnewglossaryentry}.
+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, if required. If omitted, the value
+is set to the same as the \gloskey{description} key.
+
+\item[{\gloskey{text}}] How this entry will appear in the document text
+when using \ics{gls} (or one of its upper case 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 upper case
+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 upper case 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
+upper case 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.
+
+\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 this entry should
+be sorted. If omitted, the value is given
+by the \gloskey{name} field unless one of the package options
+\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. In
+general, it's best to use the \gloskey{sort} key if the
+\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|).
+You can also override the \gloskey{sort} key by redefining
+\ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}).
+
+\opt1 by default strips the \glslink{latexexlatinchar}{standard
+\LaTeX\ accents} (that is, accents generated by core \LaTeX\ commands) from the
+\gloskey{name} key when it sets the \gloskey{sort} key. So with
+\opt1:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people}
+}
+\end{verbatim}
+This is equivalent to:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people},
+ sort={elite}
+}
+\end{verbatim}
+Unless you use the package option \pkgopt[true]{sanitizesort}, in
+which case it's equivalent to:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people},
+ sort={\'elite}
+}
+\end{verbatim}
+This will place the entry before the \qt{A} letter group since the
+sort value starts with a symbol.
+
+Similarly if you use the \sty{inputenc} package:
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|
+\verb|}|
+\end{alltt}
+This is equivalent to
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|,
+ sort=elite
+\verb|}|
+\end{alltt}
+Unless you use the package option \pkgopt[true]{sanitizesort}, in
+which case it's equivalent to:
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|,
+ sort=\'elite
+\verb|}|
+\end{alltt}
+Again, this will place the entry before the \qt{A} group.
+
+With \optsand23, the default value of \gloskey{sort} will either be
+set to the \gloskey{name} key (if \pkgopt[true]{sanitizesort}) or it
+will set it to the expansion of the \gloskey{name} key (if
+\pkgopt[false]{sanitizesort}).
+
+\begin{important}
+Take care with \gls{xindy} (\opt3): if you have entries with the same
+\gloskey{sort} value they will be treated as the
+same entry. If you use \gls{xindy} and aren't using the \texttt{def}
+or \texttt{use} sort methods, \textbf{always} use the \gloskey{sort}
+key for entries where the name just consists of a control sequence
+(for example \texttt{name=\{\cs{alpha}\}}).
+
+Take care if you use \opt1 and the \gloskey{name} contains fragile
+commands. You will either need to explicitly set the \gloskey{sort}
+key or use the \pkgopt[true]{sanitizesort} package option (unless
+you use the \texttt{def} or \texttt{use} sort methods).
+\end{important}
+
+\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.) Alternatively, you can
+add new keys using \ics{glsaddkey} or \ics{glsaddstoragekey} (see \sectionref{sec:addkey}).
+
+\item[{\gloskey{nonumberlist}}] A boolean key. If the value is
+missing or is \texttt{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 \emph{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}|. \textbf{Note that if you have
+suppressed the \gls{numberlist}, the cross-referencing information
+won't appear in the glossary, as it forms part of the
+\gls*{numberlist}.} 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}.
+
+This key essentially provides a convenient shortcut that performs
+\begin{alltt}
+\cs{glssee}\oarg{tag}\marg{label}\marg{xr-label list}
+\end{alltt}
+after the entry has been defined.
+
+\begin{important}
+For \optsand23, \ics{makeglossaries} must be used before any occurrence of
+\ics{newglossaryentry} that contains the \gloskey{see} key. This key
+should not be used with entries defined in the \env{document} environment.
+\end{important}
+Since it's useful to suppress the indexing while working on a draft
+document, consider using the \pkgopt{seenoindex} package option to
+warn or ignore the \gloskey{see} key while \cs{makeglossaries} is
+commented out.
+
+If you use the \gloskey{see} key, you may want to consider using the
+\gls{glossaries-extra} package which additionally
+provides a \texttt{seealso} and \texttt{alias} key. If you want to
+avoid the automatic indexing triggered by the \gloskey{see} key,
+consider using \opt4.
+
+\end{description}
+
+The following keys are reserved for \ics{newacronym} (see
+\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural},
+\gloskey{short} and \gloskey{shortplural}.
+
+\begin{important}
+Avoid using any of the \glslike\ or \glstextlike\ commands within
+the \gloskey{text}, \gloskey{first}, \gloskey{short} or
+\gloskey{long} keys (or their plural equivalent) or any
+other key that you plan to access through those commands.
+(For example, the \gloskey{symbol} key if you intend to use
+\cs{glssymbol}.) Otherwise you end up with nested links, which
+can cause complications and they won't work with the case-changing
+commands. You can use them within the value of keys
+that won't be accessed through those commands. For example,
+the \gloskey{description} key if you don't use \cs{glsdesc}.
+Additionally, they'll confuse the entry formatting commands, such as
+\cs{glslabel}.
+\end{important}
+
+Note that if the name starts with
+\gls{nonlatinchar}, 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{alltt}
+\verb|\newglossaryentry{elite}{name={{|\'e\verb|}lite},|
+description=\verb|{select group or class}}|
+\end{alltt}
+(This doesn't apply for \XeLaTeX\ documents using the \sty{fontspec}
+package. For further details, see the \qt{UTF-8} section in the
+\sty{mfirstuc} user manual.)
+
+Note that in both of the above examples, you will also need to
+supply the \gloskey{sort} key if you are using \opt2
+whereas \gls{xindy} (\opt3) is usually able to sort
+\glspl{nonlatinchar}
+correctly. \opt1 discards accents from
+\glspl{latexexlatinchar} unless you use the \pkgopt[true]{sanitizesort}.
+
+
+\section{Plurals}
+\label{sec: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
+second plural. Alternatively, you can define your own keys using
+\ics{glsaddkey}, described in \sectionref{sec:addkey}.
+
+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).
+
+\section{Other Grammatical Constructs}
+\label{sec:grammar}
+
+You can use the six user keys to provide alternatives, such as
+participles. For example:
+\begin{verbatim}
+\let\glsing\glsuseri
+\let\glsd\glsuserii
+
+\newcommand*{\ingkey}{user1}
+\newcommand*{\edkey}{user2}
+
+\newcommand*{\newword}[3][]{%
+ \newglossaryentry{#2}{%
+ name={#2},%
+ description={#3},%
+ \edkey={#2ed},%
+ \ingkey={#2ing},#1%
+ }%
+}
+\end{verbatim}
+With the above definitions, I can now define terms like this:
+\begin{verbatim}
+\newword{play}{to take part in activities for enjoyment}
+\newword[\edkey={ran},\ingkey={running}]{run}{to move fast using
+the legs}
+\end{verbatim}
+and use them in the text:
+\begin{verbatim}
+Peter is \glsing{play} in the park today.
+
+Jane \glsd{play} in the park yesterday.
+
+Peter and Jane \glsd{run} in the park last week.
+\end{verbatim}
+
+Alternatively, you can define your own keys using
+\ics{glsaddkey}, described below in \sectionref{sec:addkey}.
+
+\section{Additional Keys}
+\label{sec:addkey}
+
+You can now also define your own custom keys using the
+commands described in this section. There are two types of keys:
+those for use within the document and those to store information
+used behind the scenes by other commands.
+
+For example, if you want to add a key that indicates the associated
+unit for a~term, you might want to reference this unit in your
+document. In this case use \cs{glsaddkey} described in
+\sectionref{sec:glsaddkey}. If, on the other hand, you want to add a
+key to indicate to a glossary style or acronym style that this entry
+should be formatted differently to other entries, then you can use
+\cs{glsaddstoragekey} described in \sectionref{sec:glsaddstoragekey}.
+
+In both cases, a new command \meta{no link cs} will be defined that
+can be used to access the value of this key (analogous to commands
+such as \cs{glsentrytext}). This can be used in an expandable
+context (provided any fragile commands stored in the key have been
+protected). The new keys must be added using \cs{glsaddkey} or
+\cs{glsaddstoragekey} before glossary entries are defined.
+
+\subsection{Document Keys}
+\label{sec:glsaddkey}
+
+A custom key that can be used in the document is defined using:
+\begin{definition}[\DescribeMacro\glsaddkey]
+\cs{glsaddkey}\marg{key}%
+\marg{default value}%
+\marg{no link cs}%
+\marg{no link ucfirst cs}%
+\marg{link cs}%
+\marg{link ucfirst cs}%
+\marg{link allcaps cs}
+\end{definition}
+where:
+\begin{description}
+\item[\meta{key}] is the new key to use in \ics{newglossaryentry}
+(or similar commands such as \ics{longnewglossaryentry});
+\item[\meta{default value}] is the default value to use if this key
+isn't used in an entry definition (this may reference the current
+entry label via \cs{glslabel}, but you will have to switch on
+expansion via the starred version of \cs{glsaddkey} and protect
+fragile commands);
+\item[\meta{no link cs}] is the control sequence to use analogous
+to commands like \ics{glsentrytext};
+\item[\meta{no link ucfirst cs}] is the control sequence to use analogous
+to commands like \ics{Glsentrytext};
+\item[\meta{link cs}] is the control sequence to use analogous
+to commands like \ics{glstext};
+\item[\meta{link ucfirst cs}] is the control sequence to use analogous
+to commands like \ics{Glstext};
+\item[\meta{link allcaps cs}] is the control sequence to use analogous
+to commands like \ics{GLStext}.
+\end{description}
+The starred version of \cs{glsaddkey} switches on expansion for this
+key. The unstarred version doesn't override the current expansion
+setting.
+
+\begin{example}{Defining Custom Keys}{ex:addkey}
+Suppose I want to define two new keys, \texttt{ed} and \texttt{ing},
+that default to the entry text followed by \qt{ed} and \qt{ing},
+respectively. The default value will need expanding in both cases, so
+I need to use the starred form:
+\begin{verbatim}
+ % Define "ed" key:
+ \glsaddkey*
+ {ed}% key
+ {\glsentrytext{\glslabel}ed}% default value
+ {\glsentryed}% command analogous to \glsentrytext
+ {\Glsentryed}% command analogous to \Glsentrytext
+ {\glsed}% command analogous to \glstext
+ {\Glsed}% command analogous to \Glstext
+ {\GLSed}% command analogous to \GLStext
+
+ % Define "ing" key:
+ \glsaddkey*
+ {ing}% key
+ {\glsentrytext{\glslabel}ing}% default value
+ {\glsentrying}% command analogous to \glsentrytext
+ {\Glsentrying}% command analogous to \Glsentrytext
+ {\glsing}% command analogous to \glstext
+ {\Glsing}% command analogous to \Glstext
+ {\GLSing}% command analogous to \GLStext
+\end{verbatim}
+Now I can define some entries:
+\begin{verbatim}
+ % No need to override defaults for this entry:
+
+ \newglossaryentry{jump}{name={jump},description={}}
+
+ % Need to override defaults on these entries:
+
+ \newglossaryentry{run}{name={run},%
+ ed={ran},%
+ ing={running},%
+ description={}}
+
+ \newglossaryentry{waddle}{name={waddle},%
+ ed={waddled},%
+ ing={waddling},%
+ description={}}
+\end{verbatim}
+
+These entries can later be used in the document:
+\begin{verbatim}
+The dog \glsed{jump} over the duck.
+
+The duck was \glsing{waddle} round the dog.
+
+The dog \glsed{run} away from the duck.
+\end{verbatim}
+For a complete document, see the sample file \samplefile{-newkeys}.
+\end{example}
+
+\subsection{Storage Keys}
+\label{sec:glsaddstoragekey}
+
+A custom key that can be used for simply storing information is
+defined using:
+\begin{definition}[\DescribeMacro\glsaddstoragekey]
+\cs{glsaddstoragekey}\marg{key}\marg{default value}\marg{no link cs}
+\end{definition}
+where the arguments are as the first three arguments of
+\cs{glsaddkey}, described above in \sectionref{sec:glsaddkey}.
+
+This is essentially the same as \cs{glsaddkey} except that it
+doesn't define the additional commands. You can access or update
+the value of your new field using the commands described in
+\sectionref{sec:fetchset}.
+
+\begin{example}{Defining Custom Storage Key (Acronyms and Initialisms)}{ex:addstoragekey}
+Suppose I want to define acronyms and other forms of abbreviations,
+such as initialisms, but I want them all in the same glossary and I
+want the acronyms on first use to be displayed with the short form followed by
+the long form in parentheses, but the opposite way round for other
+forms of abbreviations. (The \gls{glossaries-extra} package
+provides a simpler way of achieving this.)
+
+Here I can define a new key that determines whether the term is
+actually an acronym rather than some other form of abbreviation. I'm
+going to call this key \texttt{abbrtype} (since \texttt{type}
+already exists):
+\begin{verbatim}
+\glsaddstoragekey
+ {abbrtype}% key/field name
+ {word}% default value if not explicitly set
+ {\abbrtype}% custom command to access the value if required
+\end{verbatim}
+
+Now I can define a style that looks up the value of this new key to
+determine how to display the full form:
+\begin{verbatim}
+\newacronymstyle
+ {mystyle}% style name
+ {% Use the generic display
+ \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+ }
+ {% Put the long form in the description
+ \renewcommand*{\GenericAcronymFields}{%
+ description={\the\glslongtok}}%
+ % For the full format, test the value of the "abbrtype" key.
+ % If it's set to "word" put the short form first with
+ % the long form in brackets.
+ \renewcommand*{\genacrfullformat}[2]{%
+ \ifglsfieldeq{##1}{abbrtype}{word}
+ {% is a proper acronym
+ \protect\firstacronymfont{\glsentryshort{##1}}##2\space
+ (\glsentrylong{##1})%
+ }
+ {% is another form of abbreviation
+ \glsentrylong{##1}##2\space
+ (\protect\firstacronymfont{\glsentryshort{##1}})%
+ }%
+ }%
+ % first letter upper case version:
+ \renewcommand*{\Genacrfullformat}[2]{%
+ \ifglsfieldeq{##1}{abbrtype}{word}
+ {% is a proper acronym
+ \protect\firstacronymfont{\Glsentryshort{##1}}##2\space
+ (\glsentrylong{##1})%
+ }
+ {% is another form of abbreviation
+ \Glsentrylong{##1}##2\space
+ (\protect\firstacronymfont{\glsentryshort{##1}})%
+ }%
+ }%
+ % plural
+ \renewcommand*{\genplacrfullformat}[2]{%
+ \ifglsfieldeq{##1}{abbrtype}{word}
+ {% is a proper acronym
+ \protect\firstacronymfont{\glsentryshortpl{##1}}##2\space
+ (\glsentrylong{##1})%
+ }
+ {% is another form of abbreviation
+ \glsentrylongpl{##1}##2\space
+ (\protect\firstacronymfont{\glsentryshortpl{##1}})%
+ }%
+ }%
+ % plural and first letter upper case
+ \renewcommand*{\Genplacrfullformat}[2]{%
+ \ifglsfieldeq{##1}{abbrtype}{word}
+ {% is a proper acronym
+ \protect\firstacronymfont{\Glsentryshortpl{##1}}##2\space
+ (\glsentrylong{##1})%
+ }
+ {% is another form of abbreviation
+ \Glsentrylongpl{##1}##2\space
+ (\protect\firstacronymfont{\glsentryshortpl{##1}})%
+ }%
+ }%
+ % Just use the short form as the name part in the glossary:
+ \renewcommand*{\acronymentry}[1]{%
+ \acronymfont{\glsentryshort{##1}}}%
+ % Sort by the short form:
+ \renewcommand*{\acronymsort}[2]{##1}%
+ % Just use the surrounding font for the short form:
+ \renewcommand*{\acronymfont}[1]{##1}%
+ % Same for first use:
+ \renewcommand*{\firstacronymfont}[1]{\acronymfont{##1}}%
+ % Default plural suffix if the plural isn't explicitly set
+ \renewcommand*{\acrpluralsuffix}{\glspluralsuffix}%
+ }
+\end{verbatim}
+Remember that the new style needs to be set before defining any
+terms:
+\begin{verbatim}
+\setacronymstyle{mystyle}
+\end{verbatim}
+
+Since it's a bit confusing to use \ics{newacronym} for something
+that's not technically an acronym, let's define a new command for
+initialisms:
+\begin{verbatim}
+\newcommand*{\newinitialism}[4][]{%
+ \newacronym[abbrtype=initialism,#1]{#2}{#3}{#4}%
+}
+\end{verbatim}
+Now the entries can all be defined:
+\begin{verbatim}
+\newacronym{radar}{radar}{radio detecting and ranging}
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+\newacronym{scuba}{scuba}{self-contained underwater breathing
+apparatus}
+\newinitialism{dsp}{DSP}{digital signal processing}
+\newinitialism{atm}{ATM}{automated teller machine}
+\end{verbatim}
+On \gls{firstuse}, \verb|\gls{radar}| will produce \qt{radar (radio
+detecting and ranging)} but \verb|\gls{dsp}| will produce \qt{DSP
+(digital signal processing)}.
+
+For a complete document, see the sample file
+\samplefile{-storage-abbr}.
+\end{example}
+
+In the above example, if \cs{newglossaryentry} is explicitly used
+(instead of through \cs{newacronym}) the \texttt{abbrtype} key will
+be set to its default value of \qt{word} but the \cs{ifglshaslong}
+test in the custom acronym style will be false (since the
+\gloskey{long} key hasn't been set) so the display style will switch
+to that given by \cs{glsgenentryfmt} and they'll be no test
+performed on the \texttt{abbrtype} field.
+
+\begin{example}{Defining Custom Storage Key (Acronyms and
+Non-Acronyms with Descriptions)}{ex:addstoragekey2}
+The previous example can be modified if the \gloskey{description}
+also needs to be provided. Here I've changed \qt{word} to
+\qt{acronym}:
+\begin{verbatim}
+\glsaddstoragekey
+ {abbrtype}% key/field name
+ {acronym}% default value if not explicitly set
+ {\abbrtype}% custom command to access the value if required
+\end{verbatim}
+This may seem a little odd for non-abbreviated entries defined using
+\cs{newglossaryentry} directly, but \ics{ifglshaslong} can be used
+to determine whether or not to reference the value of this new
+\texttt{abbrtype} field.
+
+The new acronym style has a~minor modification that forces the user
+to specify a description. In the previous example, the line:
+\begin{verbatim}
+ \renewcommand*{\GenericAcronymFields}{%
+ description={\the\glslongtok}}%
+\end{verbatim}
+needs to be changed to:
+\begin{verbatim}
+ \renewcommand*{\GenericAcronymFields}{}%
+\end{verbatim}
+Additionally, to accommodate the change in the default value of the
+\texttt{abbrtype} key, all instances of
+\begin{verbatim}
+ \ifglsfieldeq{##1}{abbrtype}{word}
+\end{verbatim}
+need to be changed to:
+\begin{verbatim}
+ \ifglsfieldeq{##1}{abbrtype}{acronym}
+\end{verbatim}
+
+Once this new style has been set, the new acronyms can be defined
+using the optional argument to set the description:
+\begin{verbatim}
+\newacronym[description={system for detecting the position and
+speed of aircraft, ships, etc}]{radar}{radar}{radio detecting
+and ranging}
+\end{verbatim}
+
+No change is required for the definition of \cs{newinitialism} but
+again the optional argument is required to set the description:
+\begin{verbatim}
+\newinitialism[description={mathematical manipulation of an
+information signal}]{dsp}{DSP}{digital signal processing}
+\end{verbatim}
+
+We can also accommodate contractions in a similar manner to the
+initialisms:
+\begin{verbatim}
+\newcommand*{\newcontraction}[4][]{%
+ \newacronym[abbrtype=contraction,#1]{#2}{#3}{#4}%
+}
+\end{verbatim}
+The contractions can similarly been defined using this new command:
+\begin{verbatim}
+\newcontraction[description={front part of a ship below the
+deck}]{focsle}{fo'c's'le}{forecastle}
+\end{verbatim}
+
+Since the custom acronym style just checks if \texttt{abbrtype} is
+\texttt{acronym}, the contractions will be treated the same as the
+initialisms, but the style could be modified by a further test of
+the \texttt{abbrtype} value if required.
+
+To test regular non-abbreviated entries, I've also defined a simple
+word:
+\begin{verbatim}
+\newglossaryentry{apple}{name={apple},description={a fruit}}
+\end{verbatim}
+
+Now for a new glossary style that provides information about the
+abbreviation (in addition to the description):
+\begin{verbatim}
+\newglossarystyle
+ {mystyle}% style name
+ {% base it on the "list" style
+ \setglossarystyle{list}%
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{##1}%
+ \glstarget{##1}{\glossentryname{##1}}]
+ \ifglshaslong{##1}%
+ { (\abbrtype{##1}: \glsentrylong{##1})\space}{}%
+ \glossentrydesc{##1}\glspostdescription\space ##2}%
+ }
+\end{verbatim}
+This uses \ics{ifglshaslong} to determine whether or not the term is
+an abbreviation. If it has an abbreviation, the full form is
+supplied in parentheses and \cs{abbrtype} (defined by
+\cs{glsaddstoragekey} earlier) is used to indicate the type of
+abbreviation.
+
+With this style set, the \texttt{apple} entry is simply displayed in
+the glossary as
+\begin{description}
+\item[apple] a fruit.
+\end{description}
+but the abbreviations are displayed in the form
+\begin{description}
+\item[laser] (acronym: light amplification by
+stimulated emission of radiation) device that creates a narrow beam
+of intense light.
+\end{description}
+(for acronyms) or
+\begin{description}
+\item[DSP] (initialism: digital signal processing) mathematical
+manipulation of an information signal.
+\end{description}
+(for initalisms) or
+\begin{description}
+\item[fo'c's'le] (contraction: forecastle) front part of a ship
+below the deck.
+\end{description}
+(for contractions).
+
+For a complete document, see \samplefile{-storage-abbr-desc}.
+\end{example}
+
+\section{Expansion}
+\label{sec:expansion}
+
+When you define new glossary entries expansion is performed by
+default, except for the \gloskey{name}, \gloskey{description},
+\gloskey{descriptionplural}, \gloskey{symbol}, \gloskey{symbolplural}
+and \gloskey{sort} keys (these keys all have expansion suppressed via
+\cs{glssetnoexpandfield}).
+
+You can switch expansion on or off for individual keys using
+\begin{definition}[\DescribeMacro\glssetexpandfield]
+\cs{glssetexpandfield}\marg{field}
+\end{definition}
+or
+\begin{definition}[\DescribeMacro\glssetnoexpandfield]
+\cs{glssetnoexpandfield}\marg{field}
+\end{definition}
+respectively, where \meta{field} is the field tag corresponding to
+the key. In most cases, this is the same as the name of the key
+except for those listed in \tableref{tab:fieldmap}.
+
+\begin{table}[htbp]
+\caption{Key to Field Mappings}
+\label{tab:fieldmap}
+\centering
+\begin{tabular}{ll}
+\bfseries Key & \bfseries Field\\
+\gloskey{sort} & \ttfamily sortvalue\\
+\gloskey{firstplural} & \ttfamily firstpl\\
+\gloskey{description} & \ttfamily desc\\
+\gloskey{descriptionplural} & \ttfamily descplural\\
+\gloskey{user1} & \ttfamily useri\\
+\gloskey{user2} & \ttfamily userii\\
+\gloskey{user3} & \ttfamily useriii\\
+\gloskey{user4} & \ttfamily useriv\\
+\gloskey{user5} & \ttfamily userv\\
+\gloskey{user6} & \ttfamily uservi\\
+\gloskey{longplural} & \ttfamily longpl\\
+\gloskey{shortplural} & \ttfamily shortpl
+\end{tabular}
+\end{table}
+
+Any keys that haven't had the expansion explicitly set using
+\cs{glssetexpandfield} or \cs{glssetnoexpandfield} are governed by
+\begin{definition}[\DescribeMacro\glsexpandfields]
+\cs{glsexpandfields}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glsnoexpandfields]
+\cs{glsnoexpandfields}
+\end{definition}
+
+If your entries contain any fragile commands, I recommend you switch
+off expansion via \cs{glsnoexpandfields}. (This should be used
+before you define the entries.)
+
+\section{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.
+
+\subsection{Hierarchical Categories}
+\label{sec:hierarchical}
+
+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.
+
+\begin{example}{Hierarchical Categories---Greek and Roman
+Mathematical Symbols}{ex:hierarchical}
+
+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}
+For a complete document, see the sample file \samplefile{tree}.
+\end{example}
+
+\subsection{Homographs}
+\label{sec: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 (see
+\sectionref{sec:pkgopts-sort}). 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}
+
+
+\section{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} or \ics{longnewglossaryentry} 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).
+
+This is a~preamble-only command. You may also use \ics{input} to load
+the file but don't use \ics{include}. If you find that your file is
+becoming unmanageably large, you may want to consider switching to
+\gls{bib2gls} and use an application such as JabRef to manage the
+entry definitions.
+
+\begin{important}
+If you want to use \ics{AtBeginDocument} to \cs{input} all your entries
+automatically at the start of the document, add the
+\cs{AtBeginDocument} command \emph{before} you load the
+\sty{glossaries} package (and \sty{babel}, if you are also loading
+that) to avoid the creation of the
+\filetype{.glsdefs} file and any associated problems that are caused
+by defining commands in the \env{document} environment.
+(See \sectionref{sec:docdefs}.)
+\end{important}
+
+\begin{example}{Loading Entries from Another File}{ex:loadgls}
+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}.
+\end{example}
+
+\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
+\renewcommand{\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.
+
+Remember that you can use \ics{provideglossaryentry} rather than
+\ics{newglossaryentry}. Suppose you want to maintain a large database
+of acronyms or terms that you're likely to use in your documents,
+but you may want to use a modified version of some of those entries.
+(Suppose, for example, one document may require a more detailed
+description.) Then if you define the entries using
+\cs{provideglossaryentry} in your database file, you can override
+the definition by simply using \cs{newglossaryentry} before loading
+the file. For example, suppose your file (called, say,
+\texttt{terms.tex}) contains:
+\begin{verbatim}
+\provideglossaryentry{mallard}{name=mallard,
+ description={a type of duck}}
+\end{verbatim}
+but suppose your document requires a more detailed description, you
+can do:
+\begin{verbatim}
+\usepackage{glossaries}
+\makeglossaries
+
+\newglossaryentry{mallard}{name=mallard,
+ description={a dabbling duck where the male has a green head}}
+
+\loadglsentries{terms}
+\end{verbatim}
+Now the \texttt{mallard} definition in the \texttt{terms.tex} file
+will be ignored.
+
+\section{Moving Entries to Another Glossary}
+\label{sec:moveentry}
+
+As from version~3.02, you can move an entry from one glossary to
+another using:
+\begin{definition}[\DescribeMacro{\glsmoveentry}]
+\cs{glsmoveentry}\marg{label}\marg{target glossary label}
+\end{definition}
+where \meta{label} is the unique label identifying the required
+entry and \meta{target glossary label} is the unique label
+identifying the glossary in which to put the entry.
+
+Note that no check is performed to determine the existence of
+the target glossary. If you want to move an entry to a glossary
+that's skipped by \ics{printglossaries}, then define an ignored
+glossary with \ics{newignoredglossary}. (See
+\sectionref{sec:newglossary}.)
+
+\begin{important}
+Unpredictable results may occur if you move an entry to a different
+glossary from its parent or children.
+\end{important}
+
+\section{Drawbacks With Defining Entries in the Document Environment}
+\label{sec:docdefs}
+
+Originally, \ics{newglossaryentry} (and \ics{newacronym}) could only be
+used in the preamble. I reluctantly removed this restriction in version 1.13,
+but there are issues with defining commands in the \env{document}
+environment instead of the preamble, which is why the restriction is
+maintained for newer commands. This restriction is also reimposed
+for \cs{newglossaryentry} by the new \opt1. (The
+\gls{glossaries-extra} package automatically reimposes this restriction for
+\optsand23 but provides a package option to allow document
+definitions.)
+
+\subsection{Technical Issues}
+\label{sec:techissues}
+
+\begin{enumerate}
+ \item If you define an entry mid-way through your document, but
+subsequently shuffle sections around, you could end up using an
+entry before it has been defined.
+
+ \item Entry information is required when displaying the glossary.
+If this occurs at the start of the document, but the entries aren't
+defined until later, then the entry details are
+being looked up before the entry has been defined.
+
+ \item If you use a package, such as \sty{babel}, that makes
+certain characters active at the start of the \env{document}
+environment, there will be a~problem if those characters have
+a~special significance when defining glossary entries.
+These characters include the double-quote \verb|"| character, the
+exclamation mark \texttt{!} character, the question mark \verb|?|
+character, and the pipe \verb"|" character. They
+must not be active when defining a~glossary entry where they occur
+in the \gloskey{sort} key (and they should be avoided in the label
+if they may be active at any point in the document). Additionally,
+the comma \texttt{,} character and the equals \texttt{=} character
+should not be active when using commands that have
+\meta{key}=\meta{value} arguments.
+
+\end{enumerate}
+
+To overcome the first two problems, as from version 4.0 the
+\styfmt{glossaries} package modifies the definition of
+\cs{newglossaryentry} at the beginning of the \env{document}
+environment so that the definitions are written to an external file
+(\cs{jobname}\filetype{.glsdefs}) which is then read in at the start
+of the document on the next run. The entry will then only be defined
+in the \env{document} environment if it doesn't already exist. This
+means that the entry can now be looked up in the glossary, even if
+the glossary occurs at the beginning of the document.
+
+There are drawbacks to this mechanism: if you modify an entry
+definition, you need a second run to see the effect of your
+modification; this method requires an extra \cs{newwrite}, which may
+exceed \TeX's maximum allocation; unexpected expansion issues could
+occur; the \gloskey{see} key isn't stored, which means it can't be
+added to the \filetype{.glsdefs} file when it's created at the end of the
+document (and therefore won't be present on subsequent runs).
+
+The \gls{glossaries-extra} package provides a setting (but only for
+\optsand23) that allows \cs{newglossaryentry} to occur in the
+document environment but doesn't create the \filetype{.glsdefs}
+file. This circumvents some problems but it means that you can't
+display any of the glossaries before all the entries have been
+defined (so it's all right if all the glossaries are at the end of
+the document but not if any occur in the front matter).
+
+\subsection{Good Practice Issues}
+\label{sec:goodpractice}
+
+The above section covers technical issues that can cause your document to have
+compilation errors or produce incorrect output. This section
+focuses on good writing practice. The main reason cited by users
+wanting to define entries within the \env{document} environment rather
+than in the preamble is that they want to write the definition as
+they type in their document text. This suggests a \qt{stream of
+consciousness} style of writing that may be acceptable in certain
+literary genres but is inappropriate for factual documents.
+
+When you write technical documents, regardless of whether it's a PhD
+thesis or an article for a~journal or proceedings, you must plan what you write
+in advance. If you plan in advance, you should have a fairly good
+idea of the type of terminology that your document will contain,
+so while you are planning, create a new file with all your entry
+definitions. If, while you're writing your document, you remember
+another term you need, then you can switch over to your definition file and
+add it. Most text editors have the ability to have more than one
+file open at a time. The other advantage to this approach is that if
+you forget the label, you can look it up in the definition file
+rather than searching through your document text to find the
+definition.
+
+\chapter{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 indexed (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}}.
+
+\Glspl{numberlist} are more common with indexes rather than
+glossaries (although you can use the \styfmt{glossaries} package for
+indexes as well). However, the \styfmt{glossaries} package makes use
+of \gls{makeindex} or \gls{xindy} to hierarchically sort and collate the
+entries since they are readily available with most modern \TeX\
+distributions. Since these are both designed as \glspl{indexingapp}
+they both require that terms either have a valid location or a
+cross-reference. Even if you use \pkgopt{nonumberlist}, the
+locations must still be provided and acceptable to the
+\gls{indexingapp} or they will cause an error during the indexing
+stage, which will interrupt the document build. However, if you're
+not interested in the locations, each entry only needs to be indexed
+once, so consider using \pkgopt{indexonlyfirst}, which can improve the
+document build time by only indexing the \gls{firstuse} of each term.
+
+The \ics{glsaddall} command (see \sectionref{sec:glsadd}), which is used to
+automatically index all entries, iterates over all defined entries
+and does \cs{glsadd}\marg{label} for each entry (where \meta{label}
+is that entry's label). This means that \cs{glsaddall} automatically
+adds the same location to every entry's \gls{numberlist}, which
+looks weird if the \gls*{numberlist} hasn't been suppressed.
+
+With \opt4, the indexing is performed by \gls{bib2gls}, which was
+specifically designed for the \gls{glossaries-extra} package. So it
+will allow any location format, and its \texttt{selection=all}
+option will select all entries without adding an unwanted location to the
+\gls{numberlist}. If \gls{bib2gls} can deduce a numerical value for
+a location, it will attempt to form a range over consecutive
+locations, otherwise it won't try to form a range and the
+location will just form an individual item in the list.
+\opt1 also allows any location but it doesn't form ranges.
+
+\section{Encap Values}
+\label{sec:encap}
+
+Each location in the \gls{numberlist} is encapsulated with a
+command formed from the \termdef{encap} value. By
+default this is the \ics{glsnumberformat} command, which corresponds
+to the encap \texttt{glsnumberformat}, but this may be
+overridden using the \gloskey[glslink]{format} key in the optional
+argument to commands like \cs{gls}. (See \sectionref{sec:glslink}.)
+For example, you may want the location to appear in bold to indicate
+the principle use of a term or symbol. If the encap starts with an
+open parenthesis~\verb|(| this signifies the start of a range and if
+the encap starts with close parenthesis~\verb|)| this signifies the
+end of a range. These must always occur in matching pairs.
+
+The \styfmt{glossaries} package provides the command \ics{glsignore}
+which ignores its argument. This is the format used by
+\cs{glsaddallunused} to suppress the location, which works fine as
+long as no other locations are added to the \gls{numberlist}. For
+example, if you use \verb|\gls{sample}| on page~2 then reset the
+\gls{firstuseflag} and then use \cs{glsaddallunused} on page~10, the
+\gls{numberlist} for \texttt{sample} will be \verb|2, \glsignore{10}|
+which will result in \qt{2,~} which has a spurious comma.
+
+This isn't a problem with \gls{bib2gls} because you'd use
+\texttt{selection=all} instead of \cs{glsaddallunused}, but even if
+you explicitly had, for example,
+\cs{gls}\texttt{[format=glsignore]}\marg{label}
+for some reason, \gls{bib2gls} will recognise \texttt{glsignore} as
+a special encap indicating an ignored location, so it will select
+the entry but not add that location to the \gls{numberlist}. It's a
+problem for all the other options (except \opt5, which doesn't
+perform any indexing).
+
+Complications can arise if you use different encap values for the
+same location. For example, suppose on page~10 you have both the
+default \texttt{glsnumberformat} and \texttt{textbf} encaps. While it may
+seem apparent that \texttt{textbf} should override \texttt{glsnumberformat}
+in this situation, the \gls{indexingapp} may not know it.
+This is therefore something you need to be careful about if you use the
+\gloskey[glslink]{format} key or if you use a command that
+implicitly sets it.
+
+In the case of \gls{xindy}, it only accepts one encap (according to
+the order of precedence given in the \gls{xindy} module) and discards the
+others for identical locations (for the same entry). This can cause
+a problem if a discarded location forms the start or end of a range.
+
+In the case of \gls{makeindex}, it accepts different encaps for the
+same location, but warns about it. This leads to a \gls{numberlist}
+with the same location repeated in different formats. If you use
+the \gls{makeglossaries} Perl script with \opt2 it will detect
+\gls{makeindex}'s warning and attempt to fix the problem, ensuring
+that the \texttt{glsnumberformat} encap always has the least precedence
+unless it includes a range identifier. Other conflicting encaps will
+have the last one override earlier ones for the same location with
+range identifiers taking priority.
+
+No discard occurs with \opt1 so again you get the same location
+repeated in different formats. With \opt4, \gls{bib2gls} will discard
+according to order of precedence, giving priority to start and end
+range encaps. (See the \gls{bib2gls} manual for further details.)
+
+\section{Locations}
+\label{sec:locationsyntax}
+
+Neither \opt1 nor \opt4 care about the location syntax as long as
+it's valid \LaTeX\ code (and doesn't contain fragile commands). In
+both cases, the indexing is performed by writing a line to the
+\texttt{.aux} file. The write operation is deferred to avoid the
+problems associated with \TeX's asynchronous output routine.
+(See, for example,
+\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding
+if you're on an odd or an even page} for more details on this issue.)
+Unfortunately \optsand23 are far more problematic and need some
+complex code to deal with awkward locations.
+
+If you know that your locations will always expand to a format
+acceptable to your chosen \gls{indexingapp} then use the package
+option \pkgopt[false]{esclocations} to bypass this operation. This setting
+only affects \optsand23 as the problem doesn't arise with the other
+indexing options.
+
+Both \gls{makeindex} and \gls{xindy} are fussy about the syntax of
+the locations. In the case of \gls{makeindex}, only the numbering
+system obtained with \cs{arabic}, \cs{roman}, \cs{Roman}, \cs{alph}
+and \cs{Alph} or composites formed from them with the same separator
+(set with \cs{glsSetCompositor}\marg{char}) are accepted.
+(\gls{makeindex} won't accept an empty location.) In the case of
+\gls{xindy}, you can define your own location classes, but if the
+location contains a robust command then the leading backslash must
+be escaped. The \sty{glossaries} package tries to do this, but it's
+caught between two conflicting requirements:
+\begin{enumerate}
+\item The location must be fully expanded before \verb|\| can be
+converted to \verb|\\| (there's no point converting \verb|\thepage|
+to \verb|\\thepage|);
+\item The page number can't be expanded until the deferred write
+operation (so \verb|\c@page| mustn't expand in the previous step
+but \verb|\the\c@page| mustn't be converted to \verb|\\the\\c@page|
+and \verb|\number\c@page| mustn't be converted to
+\verb|\\number\\c@page| etc).
+\end{enumerate}
+There's a certain amount of trickery needed to deal with this
+conflict and the code requires the location to be in a form that
+doesn't embed the counter's internal register in commands like
+\cs{value}. For example, suppose you have a robust command called
+\cs{tallynum} that takes a number as the argument and an expandable
+command called \cs{tally} that converts a counter name into the
+associated register or number to pass to \cs{tallynum}. Let's
+suppose that this command is used to represent the page number:
+\begin{verbatim}
+\renewcommand{\thepage}{\tally{page}}
+\end{verbatim}
+Now let's suppose that a term is indexed at the beginning of page~2
+at the end of a paragraph that started on page~1. With \gls{xindy},
+the location \verb|\tally{page}| needs to be written to the file
+as \verb|\\tallynum{2}|. If it's written as \verb|\tallynum{2}| then
+\gls{xindy} will interpret \verb|\t| as the character \qt{t}
+(which means the location would appear as \qt{tallynum2}). So
+\sty{glossaries} tries to expand \cs{thepage} without expanding
+\cs{c@page} and then escapes all the backslashes, except for the
+page counter's internal command. The following definitions of
+\cs{tally} will work:
+\begin{itemize}
+\item In the following, \cs{arabic} works as its internal command \cs{c@arabic} is
+temporarily redefined to check for \cs{c@page}:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
+\end{verbatim}
+
+\item The form \verb|\expandafter\the\csname c@|\meta{counter}\verb|\endcsname|
+also works (provided \cs{the} is allowed to be temporarily redefined,
+see below):
+\begin{verbatim}
+\newcommand{\tally}[1]{%
+ \tallynum{\expandafter\the\csname c@#1\endcsname}}
+\end{verbatim}
+
+\item \verb|\expandafter\the\value|\marg{counter} now also works
+(with the same condition as above):
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\expandafter\the\value{#1}}}
+\end{verbatim}
+
+\item Another variation that will work:
+\begin{verbatim}
+\newcommand{\tally}[1]{%
+ \expandafter\tallynum\expandafter{\the\csname c@#1\endcsname}}
+\end{verbatim}
+
+\item and also:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\the\csname c@#1\endcsname}}
+\end{verbatim}
+\end{itemize}
+The following \emph{don't work}:
+\begin{itemize}
+\item This definition leads to the premature expansion of \cs{c@page}
+to \qt{1} when, in this case, it should be \qt{2}:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\the\value{#1}}}
+\end{verbatim}
+\item This definition leads to \verb|\\c@page| in the glossary file:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\csname c@#1\endcsname}}
+\end{verbatim}
+\end{itemize}
+If you have a numbering system where
+\verb|\|\meta{cs name}\verb|{page}| expands to
+\verb|\|\meta{internal cs name}\cs{c@page} (for example, if
+\verb|\tally{page}| expands to \verb|\tallynum\c@page|) then you
+need to use:
+\begin{definition}[\DescribeMacro\glsaddprotectedpagefmt]
+\cs{glsaddprotectedpagefmt}\marg{internal cs name}
+\end{definition}
+Note that the backslash must be omitted from \meta{internal cs name}
+and the corresponding command must be able to process a count
+register as the (sole) argument.
+
+For example, suppose you have a style \texttt{samplenum} that is
+implemented as follows:
+\begin{verbatim}
+ \newcommand*{\samplenum}[1]{%
+ \expandafter\@samplenum\csname c@#1\endcsname}
+ \newcommand*{\@samplenum}[1]{\two@digits{#1}}
+
+\end{verbatim}
+(That is, it displays the value of the counter as a two-digit
+number.) Then to ensure the location is correct for entries in
+page-spanning paragraphs, you need to do:
+\begin{verbatim}
+\glsaddprotectedpagefmt{@samplenum}
+\end{verbatim}
+(If you are using a different counter for the location, such as
+\texttt{section} or \texttt{equation}, you don't need to worry about
+this provided the inner command is expandable.)
+
+If the inner macro (as given by \verb|\|\meta{internal cs name}) contains
+non-expandable commands then you may need to redefine
+\cs{gls}\meta{internal cs name}\texttt{page} after using
+\cs{glsaddprotectedpagefmt}\marg{internal cs name}. This command doesn't take any arguments
+as \emph{the location is assumed to be given by \cs{c@page}} because
+that's the only occasion this command should be used. For example,
+suppose now my page counter format uses small caps Roman numerals:
+\begin{verbatim}
+ \newcommand*{\samplenum}[1]{%
+ \expandafter\@samplenum\csname c@#1\endcsname}
+ \newcommand*{\@samplenum}[1]{\textsc{\romannumeral#1}}
+\end{verbatim}
+Again, the inner macro needs to be identified using:
+\begin{verbatim}
+\glsaddprotectedpagefmt{@samplenum}
+\end{verbatim}
+However, since \cs{textsc} isn't fully expandable, the location
+is written to the file as \verb|\textsc {i}| (for page~1),
+\verb|\textsc {ii}| (for page~2), etc. This format may cause a problem for
+the \gls{indexingapp} (particularly for \gls{makeindex}).
+To compensate for this, the \cs{gls}\meta{internal cs
+name}\texttt{page} command may be redefined so that it expands to a
+format that's acceptable to the \gls*{indexingapp}. For example:
+\begin{verbatim}
+\renewcommand*{\gls@samplenumpage}{\romannumeral\c@page}
+\end{verbatim}
+While this modification means that the \gls{numberlist} in the glossary
+won't exactly match the format of the page numbers (displaying
+lower case Roman numbers instead of small cap Roman numerals)
+this method will at least work correctly for both \gls{makeindex}
+and \gls{xindy}. If you are using \gls{xindy}, the following
+definition:
+\begin{verbatim}
+ \renewcommand*{\gls@samplenumpage}{%
+ \glsbackslash\string\textsc{\romannumeral\c@page}}
+\end{verbatim}
+combined with
+\begin{verbatim}
+\GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace"
+ "roman-numbers-lowercase" :sep "\glsclosebrace"}
+\end{verbatim}
+will now have lowercase Roman numerals in the location list
+(see \sectionref{sec:xindyloc} for further details on that command).
+Take care of the backslashes. The location (which ends up in
+the ":locref" attribute) needs \verb|\\| but the location class
+(identified with \cs{GlsAddXdyLocation}) just has a single
+backslash. Note that this example will cause problems if your
+locations should be hyperlinks.
+
+Another possibility that may work with both \gls{makeindex} and
+\gls{xindy} is to redefine \cs{gls}\meta{internal cs
+name}\texttt{page} (\cs{gls@samplenumpage} in this example)
+to just expand to the decimal page number (\verb|\number\c@page|) and redefine
+\ics{glsnumberformat} to change the displayed format:
+\begin{verbatim}
+\renewcommand*{\gls@samplenumpage}{\number\c@page}
+\renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}}
+\end{verbatim}
+
+\begin{important}
+If you redefine \cs{gls}\meta{internal cs name}\texttt{page},
+you must make sure that \cs{c@page} is expanded when it's written to
+the file. (So don't, for example, hide \cs{c@page} inside a robust
+command.)
+\end{important}
+
+The mechanism that allows this to work temporarily redefines
+\ics{the} and \ics{number} while it processes the location. If this
+causes a problem you can disallow it using
+\begin{definition}[\DescribeMacro\glswrallowprimitivemodsfalse]
+\cs{glswrallowprimitivemodsfalse}
+\end{definition}
+but you will need to find some other way to ensure the location expands
+correctly.
+
+\section{Range Formations}
+\label{sec:ranges}
+
+Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a
+sequence of~3 or more consecutive pages into~a range. With
+\gls*{xindy} (\opt3) 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 (see \sectionref{sec:xindyloc} for
+further details).
+
+\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} (\optsand23), 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} (\opt3), 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}
+
+It's also possible to concatenate a sequence of consecutive
+locations into a range or have suffixes with \opt4, but with
+\gls{bib2gls} these implicit ranges can't be merged with explicit
+ranges (created with the \verb|(| and \verb|)| encaps). See
+the \gls{bib2gls} manual for further details.
+
+\opt1 doesn't form ranges. However, with this option you
+can iterate over an entry's \gls{numberlist} using:
+\begin{definition}[\DescribeMacro\glsnumberlistloop]
+\cs{glsnumberlistloop}\marg{label}\marg{handler cs}\marg{xr handler
+cs}
+\end{definition}
+where \meta{label} is the entry's label and \meta{handler cs} is a
+handler control sequence of the form:
+\begin{definition}
+\meta{handler cs}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+where \meta{prefix} is the \sty{hyperref} prefix, \meta{counter} is
+the name of the counter used for the location, \meta{format} is the
+format used to display the location (e.g.\ \texttt{textbf})
+and \meta{location} is the location. The third argument is the
+control sequence to use for any cross-references in the list. This
+handler should have the syntax:
+\begin{definition}
+\meta{xr handler cs}\oarg{tag}\marg{xr list}
+\end{definition}
+where \meta{tag} is the cross-referenced text (e.g.\ \qt{see}) and
+\meta{xr list} is a~comma-separated list of labels. (This actually
+has a third argument but it's always empty when used with \opt1.)
+
+For example, if on page~12
+I~have used
+\begin{verbatim}
+\gls[format=textbf]{apple}
+\end{verbatim}
+and on page~18 I~have used
+\begin{verbatim}
+\gls[format=emph]{apple}
+\end{verbatim}
+then
+\begin{verbatim}
+\glsnumberlistloop{apple}{\myhandler}
+\end{verbatim}
+will be equivalent to:
+\begin{verbatim}
+\myhandler{}{page}{textbf}{12}%
+\myhandler{}{page}{emph}{18}%
+\end{verbatim}
+There is a predefined handler that's used to display the
+\gls{numberlist} in the glossary:
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+The predefined handler used for the cross-references in the glossary is:
+\begin{definition}
+\cs{glsseeformat}\oarg{tag}\marg{xr list}\marg{location}
+\end{definition}
+which is described in \sectionref{sec:customxr}.
+
+\begin{important}
+\cs{glsnumberlistloop} is not available for \optsand23.
+\end{important}
+
+\section{Style Hook}
+\label{sec:isthook}
+
+As from version 4.24, there's a hook that's used near the end of
+\ics{writeist} before the file is closed. You can set the code
+to be performed then using:
+\begin{definition}[\DescribeMacro\GlsSetWriteIstHook]
+\cs{GlsSetWriteIstHook}\marg{code}
+\end{definition}
+If you want the \meta{code} to write any information to the
+file, you need to use
+\begin{definition}[\DescribeMacro\glswrite]
+\cs{write}\cs{glswrite}\marg{style information}
+\end{definition}
+Make sure you use the correct format within \meta{style
+information}. For example, if you are using \app{makeindex}:
+\begin{verbatim}
+\GlsSetWriteIstHook{%
+ \write\glswrite{page_precedence "arnAR"}%
+ \write\glswrite{line_max 80}%
+}
+\end{verbatim}
+This changes the page type precedence\index{page type precedence} and the maximum line length
+used by \app{makeindex}.
+
+Remember that if you switch to \app{xindy}, this will no longer be
+valid code.
+
+\chapter{Links to Glossary Entries}
+\label{sec:glslink}
+
+Once you have defined a glossary entry using \ics{newglossaryentry}
+(\sectionref{sec:newglosentry}) or \ics{newacronym} (see
+\sectionref{sec:acronyms}), you can refer to that entry in the
+document using one of the commands listed in
+\sectionref{sec:gls-like} or \sectionref{sec:glstext-like}. 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). These commands also add a line to an external file that
+is used 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}. These external files need to be
+post-processed by \gls{makeindex} or \gls{xindy} unless you have
+chosen \optsor14. If you don't use \ics{makeglossaries} these external
+files won't be created. (\optsand14 write the information to the
+\filetype{.aux} file.)
+
+Note that repeated use of these commands for the same entry can
+cause the \gls{numberlist} to become quite long, which may not be
+particular helpful to the reader. In this case, you can use the
+non-indexing commands described in \sectionref{sec:glsnolink} or
+you can use the supplemental \gls{glossaries-extra} package, which
+provides a means to suppress the automated indexing of the commands listed
+in this chapter.
+
+\begin{important}
+I strongly recommend that you don't use the commands
+defined in this chapter in the arguments of sectioning or caption
+commands or any other command that has a moving argument.
+
+Aside from problems with expansion issues, PDF bookmarks and
+possible nested hyperlinks in the table of contents (or list of
+whatever) any use of the commands described in \sectionref{sec:gls-like}
+will have their \firstuseflag\ unset when they appear in the table
+of contents (or list of whatever).
+\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 \emph{expandable} commands listed in
+\sectionref{sec:glsnolink} (such as \ics{glsentrytext} \emph{but
+not} the non-expandable
+case changing versions like \ics{Glsentrytext}). Alternatively, provide an
+alternative via the optional argument to the sectioning\slash caption
+command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples:
+\begin{verbatim}
+\chapter{An overview of \glsentrytext{perl}}
+\chapter[An overview of Perl]{An overview of \gls{perl}}
+\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
+\end{verbatim}
+If you want to retain the formatting that's available through
+commands like \cs{acrshort} (for example, if you are using one of
+the small caps styles), then you might want to consider the
+\gls{glossaries-extra} package which provides commands
+for this purpose.
+
+If you want the \gls{linktext} to produce a hyperlink to the
+corresponding entry details in the glossary, you should load the
+\sty{hyperref} package \emph{before} the \styfmt{glossaries}
+package. That's what I've done in this document, so if you see a
+hyperlinked term, such as \gls{linktext}, you can click on the word
+or phrase and it will take you to a brief description in this
+document's glossary.
+
+\begin{important}
+If you use the \sty{hyperref} package, I strongly recommend you use
+\app{pdflatex} rather than \app{latex} to compile your document, if
+possible. The DVI format of \LaTeX\ has limitations with the
+hyperlinks that can cause a problem when used with the
+\styfmt{glossaries} package. Firstly, the DVI format can't break a
+hyperlink across a line whereas PDF\LaTeX\ can. This means that long
+glossary entries (for example, the full form of an acronym) won't be
+able to break across a line with the DVI format. Secondly, the DVI
+format doesn't correctly size hyperlinks in subscripts or
+superscripts. This means that if you define a term that may be used
+as a subscript or superscript, if you use the DVI format, it won't
+come out the correct size.
+
+These are limitations of the DVI format not of the \sty{glossaries}
+package.
+\end{important}
+
+It may be that you only want terms in certain glossaries to have
+hyperlinks, but not for other glossaries. In this case, you can use the
+package option \pkgopt{nohypertypes} to identify the glossary lists
+that shouldn't have hyperlinked \gls{linktext}. See
+\sectionref{sec:pkgopts-general} for further details.
+
+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}
+Further customisation can be done via \ics{defglsentryfmt} or by
+redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for
+further details.
+
+Each entry has an associated conditional referred to as the
+\firstuseflag. Some of the commands described in this chapter
+automatically unset this flag and can also use it
+to determine what text should be displayed. These types of commands
+are the \glslike\ commands and are described in
+\sectionref{sec:gls-like}. The commands that don't reference or change
+the \firstuseflag\ are \glstextlike\ commands and are described
+in \sectionref{sec:glstext-like}. See \sectionref{sec:glsunset} for
+commands that unset (mark the entry as having been used) or reset
+(mark the entry as not used) the \firstuseflag\ without referencing
+the entries.
+
+The \glslike\ and \glstextlike\ commands all take a first
+optional argument that is a comma-separated list of
+\meta{key}=\meta{value} options, described below. They also have a
+star-variant, which inserts \texttt{hyper=false} at the start of the
+list of options and a plus-variant, which inserts
+\texttt{hyper=true} at the start of the list of options. For example
+\verb|\gls*{sample}| is the same as \verb|\gls[hyper=false]{sample}|
+and \verb|\gls+{sample}| is the same as
+\verb|\gls[hyper=true]{sample}|, whereas just \verb|\gls{sample}|
+will use the default hyperlink setting which depends on a number of
+factors (such as whether the entry is in a glossary that has been
+identified in the \pkgopt{nohypertypes} list). You can override the
+\gloskey[glslink]{hyper} key in the variant's optional argument, for
+example, \verb|\gls*[hyper=true]{sample}| but this creates
+redundancy and is best avoided. The \gls{glossaries-extra} package
+provides the option to add a third custom variant.
+
+\begin{important}
+Avoid nesting these commands. For example don't do
+\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}}
+as this is likely to cause problems. By implication, this
+means that you should avoid using any of these commands within
+the \gloskey{text}, \gloskey{first}, \gloskey{short} or
+\gloskey{long} keys (or their plural equivalent) or any
+other key that you plan to access through these commands.
+(For example, the \gloskey{symbol} key if you intend to use
+\cs{glssymbol}.)
+\end{important}
+
+The keys listed below are available for the optional argument.
+The \gls{glossaries-extra} package provides additional keys.
+(See the \gls*{glossaries-extra} manual for further details.)
+\begin{description}
+\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can
+be used to enable\slash disable the hyperlink to the relevant entry
+in the glossary. If this key is omitted, the value is determined by current
+settings, as indicated above. For example, when used with a \glslike\ command, if this is the first
+use and the \pkgopt[false]{hyperfirst} package option has been used,
+then the default value is \texttt{hyper=false}. The hyperlink can be
+forced on using \texttt{hyper=true} unless the hyperlinks have been
+suppressed using \ics{glsdisablehyper}. You must load the
+\sty{hyperref} package before the \sty{glossaries} package to
+ensure the hyperlinks work.
+
+\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 and they must be in matching
+pairs. (For example, \verb|\gls[format={(}]{sample}| on one page
+to start the range and later \verb|\gls[format={)}]{sample}| to close
+the 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}. You can combine a range
+and format using \verb|(|\meta{format} to start the range and
+\verb|)|\meta{format} to end the range. The \meta{format} part must
+match. For example, \verb|format={(emph}| and \verb|format={)emph}|.
+
+\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}
+
+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.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi
+\qt{Displaying the glossary} in the documented code,
+\texttt{glossaries-code.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]{local}}] This is a boolean key that only
+makes a difference when used with \glslike\ commands that change the
+entry's \gls{firstuseflag}. If \texttt{local=true}, the change to
+the \gls*{firstuseflag} will be localised to the current scope. The
+default is \texttt{local=false}.
+
+\end{description}
+
+\begin{important}
+The \gls{linktext} isn't scoped by default. Any unscoped
+declarations in the \gls{linktext} may affect subsequent text.
+\end{important}
+
+\section{The \cs{gls}-Like Commands (First Use Flag Queried)}
+\label{sec:gls-like}
+
+This section describes the commands that unset (mark as used) the \firstuseflag\ on
+completion, and in most cases they use the current state of the flag
+to determine the text to be displayed. As described above, these
+commands all have a star-variant (\texttt{hyper=false}) and
+a plus-variant (\texttt{hyper=true}) and have an
+optional first argument that is a \meta{key}=\meta{value} list.
+
+These commands use \ics{glsentryfmt} or the equivalent definition provided by
+\ics{defglsentryfmt} to determine the automatically generated text
+and its format (see \sectionref{sec:glsdisplay}).
+
+Apart from \ics{glsdisp}, the commands described in this section
+also have a \emph{final} optional argument \meta{insert} which may
+be used to insert material into the automatically generated text.
+
+\begin{important}
+Since the commands have a final optional argument, take care if
+you actually want to display an open square bracket after the command
+when the final optional argument is absent. Insert an empty set of
+braces \verb|{}| immediately before the opening square bracket to
+prevent it from being interpreted as the final argument. For
+example:
+\begin{verbatim}
+\gls{sample} {}[Editor's comment]
+\end{verbatim}
+
+Don't use any of the \glslike\ or \glstextlike\ commands in the
+\meta{insert} argument.
+\end{important}
+
+Take care using these commands within commands or environments that
+are processed multiple times as this can confuse the first use flag
+query and state change. This includes frames with overlays in
+\cls{beamer} and the \envfmt{tabularx} environment provided by \sty{tabularx}.
+The \styfmt{glossaries} package automatically deals with this issue
+in \sty{amsmath}'s \envfmt{align} environment. You can apply a patch
+to \sty{tabularx} by placing the following command (new to v4.28) in
+the preamble:
+\begin{definition}[\DescribeMacro\glspatchtabularx]
+\cs{glspatchtabularx}
+\end{definition}
+This does nothing if \sty{tabularx} hasn't been loaded. There's no
+patch available for \cls{beamer}. See \sectionref{sec:glsunset} for
+more details.
+
+\begin{definition}[\DescribeMacro{\gls}]
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command typically determines the \gls{linktext} from the values
+of the \gloskey{text} or \gloskey{first} keys supplied when the
+entry was defined using \ics{newglossaryentry}. However, if the
+entry was defined using \ics{newacronym} and \ics{setacronymstyle} was
+used, then the \gls*{linktext} will usually be determined from the \gloskey{long} or
+\gloskey{short} keys.
+
+There are two upper case 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
+upper case, respectively. For the former, the uppercasing of the
+first letter is performed by \ics{makefirstuc}.
+
+\begin{important}
+The first letter uppercasing command \cs{makefirstuc} has
+limitations which must be taken into account if you use \cs{Gls} or
+any of the other commands that convert the first letter to
+uppercase.
+\end{important}
+The upper casing is performed as follows:
+\begin{itemize}
+\item If the first thing in the \gls{linktext} is a command follow
+by a group, the upper casing is performed on the first object of the
+group. For example, if an entry has been defined as
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\emph{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext}
+to\footnote{I've used \cs{MakeUppercase} in all the examples for clarity, but it
+will actually use \cs{mfirstucMakeUppercase}.}
+\begin{verbatim}
+\emph{\MakeUppercase sample} phrase
+\end{verbatim}
+which will appear as \emph{\MakeUppercase sample} phrase.
+
+\item If the first thing in the \gls{linktext} isn't a command or is
+a command but isn't followed by a group, then the upper casing will
+be performed on that first thing. For example, if an entry has been
+defined as:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\oe-ligature},
+ sort={oe-ligature},
+ description={an example}
+}
+\end{verbatim}
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} to
+\begin{verbatim}
+\MakeUppercase \oe-ligature
+\end{verbatim}
+which will appear as \MakeUppercase \oe-ligature.
+
+\item If you have \sty{mfirstuc} v2.01 or above, an extra case is
+added. If the first thing is \cs{protect} it will be discarded and
+the above rules will then be tried.
+
+\end{itemize}
+(Note the use of the \gloskey{sort} key in the above examples.)
+
+There are hundreds of \LaTeX\ packages that altogether define
+thousands of commands with various syntax and it's impossible for
+\sty{mfirstuc} to take them all into account. The above rules are quite
+simplistic and are designed for \gls{linktext} that starts with
+a~text-block command (such as \cs{emph}) or a command that produces
+a character (such as \cs{oe}). This means that if your \gls{linktext}
+starts with something that doesn't adhere to \sty{mfirstuc}'s assumptions
+then things are likely to go wrong.
+
+For example, starting with a math-shift symbol:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={$a$},
+ sort={a},
+ description={an example}
+}
+\end{verbatim}
+This falls into case~2 above, so the \gls{linktext} will be set to
+\begin{verbatim}
+\MakeUppercase $a$
+\end{verbatim}
+This attempts to uppercase the math-shift \verb|$|, which will go
+wrong. In this case it's not appropriate to perform any
+case-changing, but it may be that you want to use \cs{Gls}
+programmatically without checking if the text contains any maths.
+In this case, the simplest solution is to insert an empty brace at
+the start:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={{}$a$},
+ sort={a},
+ description={an example}
+}
+\end{verbatim}
+Now the \gls{linktext} will be set to
+\begin{verbatim}
+\MakeUppercase{}$a$
+\end{verbatim}
+and the \cs{uppercase} becomes harmless.
+
+Another issue occurs when the \gls{linktext} starts with a command
+followed by an argument (case~1) but the argument is a label,
+identifier or something else that shouldn't have a case-change.
+A common example is when the \gls{linktext} starts with one of the
+commands described in this chapter. (But you haven't done that, have
+you? What with the warning not to do it at the beginning of the chapter.)
+Or when the \gls{linktext} starts with one of the non-linking
+commands described in \sectionref{sec:glsnolink}. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+ name={\glsentrytext{sample} two},
+ sort={sample two},
+ description={another example}
+ }
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\glsentrytext{\MakeUppercase sample} two
+\end{verbatim}
+This will generate an error because there's no entry with the label
+given by \verb|\MakeUppercase sample|. The best solution here is to
+write the term out in the \gloskey{text} field and use the command
+in the \gloskey{name} field. If you don't use \cs{glsname} anywhere
+in your document, you can use \cs{gls} in the \gloskey{name} field:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+ name={\gls{sample} two},
+ sort={sample two},
+ text={sample two},
+ description={another example}
+ }
+\end{verbatim}
+
+If the \gls{linktext} starts with a command that has an optional
+argument or with multiple arguments where the actual text isn't in
+the first argument, then \cs{makefirstuc} will also fail. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\textcolor{blue}{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\textcolor{\MakeUppercase blue}{sample} phrase
+\end{verbatim}
+This won't work because \verb|\MakeUppercase blue| isn't a recognised
+colour name. In this case you will have to define a helper command where
+the first argument is the text. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\blue}[1]{\textcolor{blue}{#1}}
+ name={\blue{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+In fact, since the whole design ethos of \LaTeX\ is the separation
+of content and style, it's better to use a semantic command. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\keyword}[1]{\textcolor{blue}{#1}}
+ name={\keyword{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+For further details see the \sty{mfirstuc} user manual.
+
+There are plural forms that are analogous to \cs{gls}:
+\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 typically determine the link text from the \gloskey{plural} or
+\gloskey{firstplural} keys supplied when the entry was
+defined using \ics{newglossaryentry} or, if the entry is an
+abbreviation and \cs{setacronymstyle} was used, from the \gloskey{longplural} or
+\gloskey{shortplural} keys.
+
+\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}
+
+\begin{definition}[\DescribeMacro{\glsdisp}]
+\cs{glsdisp}\oarg{options}\marg{label}\marg{link text}
+\end{definition}
+This behaves in the same way as the above commands, except
+that the \meta{link text} is explicitly set. There's no final
+optional argument as any inserted material can be added to the
+\meta{link text} argument.
+
+\begin{important}
+Don't use any of the \glslike\ or \glstextlike\ commands in the
+\meta{link text} argument of \cs{glsdisp}.
+\end{important}
+
+\section{The \cs{glstext}-Like Commands (First Use Flag Not Queried)}
+\label{sec:glstext-like}
+
+This section describes the commands that don't change or reference
+the \firstuseflag. As described above, these commands all have a
+star-variant (\texttt{hyper=false}) and a plus-variant
+(\texttt{hyper=true}) and have an optional first argument
+that is a \meta{key}=\meta{value} list. These commands also don't
+use \ics{glsentryfmt} or the equivalent definition provided by
+\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}).
+Additional commands for abbreviations are described in
+\sectionref{sec:acronyms}.
+
+Apart from \ics{glslink}, the commands described in this section
+also have a \emph{final} optional argument \meta{insert} which may
+be used to insert material into the automatically generated text.
+See the caveat above in \sectionref{sec:gls-like}.
+
+\begin{definition}[\DescribeMacro{\glslink}]
+\cs{glslink}\oarg{options}\marg{label}\marg{link text}
+\end{definition}
+This command explicitly sets the \gls{linktext} as given in the
+final argument.
+
+\begin{important}
+Don't use any of the \glslike\ or \glstextlike\ commands in the
+argument of \cs{glslink}. By extension, this means that you can't
+use them in the value of fields that are used to form
+\gls{linktext}.
+\end{important}
+
+\begin{definition}[\DescribeMacro{\glstext}]
+\cs{glstext}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{text} key as the
+\gls{linktext}.
+
+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}
+These convert the first character or all the characters to
+uppercase, respectively. See the note on \cs{Gls} above for details
+on the limitations of converting the first letter to upper case.
+
+There's no equivalent command for title-casing, but you
+can use the more generic command \ics{glsentrytitlecase}
+in combination with \cs{glslink}. For example:
+\begin{verbatim}
+\glslink{sample}{\glsentrytitlecase{sample}{text}}
+\end{verbatim}
+(See \sectionref{sec:glsnolink}.)
+
+\begin{definition}[\DescribeMacro{\glsfirst}]
+\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{first} key as the
+\gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+\begin{important}
+The value of the \gloskey{first} key (and \gloskey{firstplural} key)
+doesn't necessarily match the text produced by \ics{gls} (or \ics{glspl}) on
+\firstuse\ as the \gls{linktext} used by \ics{gls} may be modified
+through commands like \ics{defglsentry}. (Similarly, the value of the
+\gloskey{text} and \gloskey{plural} keys don't necessarily match
+the \gls*{linktext} used by \cs{gls} or \cs{glspl} on subsequent
+use.)
+\end{important}
+
+\begin{definition}[\DescribeMacro{\glsplural}]
+\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{plural} key as the
+\gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+\begin{definition}[\DescribeMacro{\glsfirstplural}]
+\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{firstplural} key as the
+\gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+\begin{definition}[\DescribeMacro{\glsname}]
+\cs{glsname}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{name} key as the
+\gls{linktext}. Note that this may be different from the values of
+the \gloskey{text} or \gloskey{first} keys. In general it's better
+to use \cs{glstext} or \cs{glsfirst} instead of \cs{glsname}.
+
+There are also analogous uppercasing 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}
+
+\begin{important}
+In general it's best to avoid \cs{Glsname} with acronyms. Instead,
+consider using \cs{Acrlong}, \cs{Acrshort} or \cs{Acrfull}.
+\end{important}
+
+\begin{definition}[\DescribeMacro{\glssymbol}]
+\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{symbol} key as the
+\gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+\begin{definition}[\DescribeMacro{\glsdesc}]
+\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{description} key as the
+\gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+If you want the title case version you can use
+\begin{verbatim}
+\glslink{sample}{\glsentrytitlecase{sample}{desc}}
+\end{verbatim}
+
+\begin{definition}[\DescribeMacro{\glsuseri}]
+\cs{glsuseri}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the
+\gloskey{user1} key as the \gls{linktext}.
+
+There are also analogous uppercasing 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}
+
+\begin{definition}[\DescribeMacro{\glsuserii}]
+\cs{glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the
+\gloskey{user2} key as the \gls{linktext}.
+
+There are also analogous uppercasing commands:
+\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}
+This command always uses the value of the
+\gloskey{user3} key as the \gls{linktext}.
+
+There are also analogous uppercasing commands:
+\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}
+This command always uses the value of the
+\gloskey{user4} key as the \gls{linktext}.
+
+There are also analogous uppercasing commands:
+\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}
+This command always uses the value of the
+\gloskey{user5} key as the \gls{linktext}.
+
+There are also analogous uppercasing commands:
+\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}
+This command always uses the value of the
+\gloskey{user6} key as the \gls{linktext}.
+
+There are also analogous uppercasing commands:
+\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}
+
+\section{Changing the format of the link text}
+\label{sec:glsdisplay}
+
+The default format of the \gls{linktext} for the \glslike\ commands
+is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now
+deprecated. Backwards compatibility should be preserved but
+you may need to use the \pkgopt{compatible-3.07} option}:
+\begin{definition}[\DescribeMacro{\glsentryfmt}]
+\cs{glsentryfmt}
+\end{definition}
+This may be redefined but if you only want the change the display style
+for a given glossary, then you need to use
+\begin{definition}[\DescribeMacro{\defglsentryfmt}]
+\cs{defglsentryfmt}\oarg{type}\marg{definition}
+\end{definition}
+instead of redefining \cs{glsentryfmt}. The optional first argument
+\meta{type} is the glossary type. This defaults to
+\ics{glsdefaulttype} if omitted. The second argument is the
+entry format definition.
+
+\begin{important}
+Note that \cs{glsentryfmt} is the default display format for
+entries. Once the display format has been changed for an individual
+glossary using \ics{defglsentryfmt}, redefining \cs{glsentryfmt}
+won't have an effect on that glossary, you must instead use
+\cs{defglsentryfmt} again. Note that glossaries that have
+been identified as lists of acronyms (via the package option
+\pkgopt{acronymlists} or the command \ics{DeclareAcronymList},
+see \sectionref{sec:pkgopts-acronym}) use
+\cs{defglsentryfmt} to set their display style.
+\end{important}
+
+Within the \meta{definition} argument of \cs{defglsentryfmt}, or if you
+want to redefine \cs{glsentryfmt}, you may use the following
+commands:
+
+\begin{definition}[\DescribeMacro{\glslabel}]
+\cs{glslabel}
+\end{definition}
+This is the label of the entry being referenced. As from version
+4.08, you can also access the glossary entry type using:
+\begin{definition}[\DescribeMacro{\glstype}]
+\cs{glstype}
+\end{definition}
+This is defined using \ics{edef} so the replacement text is the
+actual glossary type rather than \verb|\glsentrytype{\glslabel}|.
+
+\begin{definition}[\DescribeMacro{\glscustomtext}]
+\cs{glscustomtext}
+\end{definition}
+This is the custom text supplied in \cs{glsdisp}. It's always empty
+for \ics{gls}, \ics{glspl} and their upper case variants. (You can
+use \sty{etoolbox}'s \cs{ifdefempty} to determine if
+\cs{glscustomtext} is empty.)
+
+\begin{definition}[\DescribeMacro{\glsinsert}]
+\cs{glsinsert}
+\end{definition}
+The custom text supplied in the final optional argument to \cs{gls},
+\cs{glspl} and their upper case variants.
+
+\begin{definition}[\DescribeMacro{\glsifplural}]
+\cs{glsifplural}\marg{true text}\marg{false text}
+\end{definition}
+If \cs{glspl}, \cs{Glspl} or \cs{GLSpl} was used, this command does
+\meta{true text} otherwise it does \meta{false text}.
+
+\begin{definition}[\DescribeMacro{\glscapscase}]
+\cs{glscapscase}\marg{no case}\marg{first uc}\marg{all caps}
+\end{definition}
+If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no
+case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first
+uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}.
+
+\begin{definition}[\DescribeMacro\glsifhyperon]
+\cs{glsifhyperon}\marg{hyper true}\marg{hyper false}
+\end{definition}
+This will do \meta{hyper true} if the hyperlinks are on for the
+current reference, otherwise it will do \meta{hyper false}. The
+hyperlink may be off even if it wasn't explicitly switched off with
+the \gloskey[glslink]{hyper} key or the use of a starred command.
+It may be off because the \sty{hyperref} package hasn't been loaded
+or because \ics{glsdisablehyper} has been used or because the entry
+is in a glossary type that's had the hyperlinks switched off (using
+\pkgopt{nohypertypes}) or because it's the \firstuse\ and the
+hyperlinks have been suppressed on first use.
+
+Note that \ics{glsifhyper} is now deprecated.
+If you want to know if the command used to reference
+this entry was used with the star or plus variant, you can use:
+\begin{definition}[\DescribeMacro\glslinkvar]
+\cs{glslinkvar}\marg{unmodified}\marg{star}\marg{plus}
+\end{definition}
+This will do \meta{unmodified} if the unmodified version was used,
+or will do \meta{star} if the starred version was used, or
+will do \meta{plus} if the plus version was used.
+Note that this doesn't take into account if the
+\gloskey[glslink]{hyper} key was used to override the default
+setting, so this command shouldn't be used to guess whether or not
+the hyperlink is on for this reference.
+
+Note that you can also use commands such as \ics{ifglsused} within
+the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}).
+
+The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural},
+\ics{glscapscase}, \ics{glscustomtext} and \ics{glsinsert} are
+typically updated at the start of the \glslike\ and \glstextlike\
+commands so they can usually be accessed in the hook user commands,
+such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}.
+
+\begin{important}
+This means that using commands like \ics{gls} within the fields
+that are accessed using the \glslike\ or \glstextlike\ commands
+(such as the \gloskey{first}, \gloskey{text}, \gloskey{long}
+or \gloskey{short} keys) will cause a problem. The entry formatting
+performed by \cs{glsentryfmt} and related commands isn't scoped
+(otherwise if would cause problems for \cs{glspostlinkhook} which
+may need to look ahead as well as look behind).
+This means that any nested commands will, at the very least, change
+the label stored in \cs{glslabel}.
+\end{important}
+
+If you only want to make minor modifications to \cs{glsentryfmt},
+you can use
+\begin{definition}[\DescribeMacro{\glsgenentryfmt}]
+\cs{glsgenentryfmt}
+\end{definition}
+This uses the above commands to display just the \gloskey{first},
+\gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys
+(or the custom text) with the insert text appended.
+
+Alternatively, if want to change the entry format for abbreviations
+(defined via \ics{newacronym}) you can use:
+\begin{definition}[\DescribeMacro{\glsgenacfmt}]
+\cs{glsgenacfmt}
+\end{definition}
+This uses the values from the \gloskey{long}, \gloskey{short},
+\gloskey{longplural} and \gloskey{shortplural} keys, rather than
+using the \gloskey{text}, \gloskey{plural}, \gloskey{first}
+and \gloskey{firstplural} keys. The first use singular text is obtained via:
+\begin{definition}[\DescribeMacro{\genacrfullformat}]
+\cs{genacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+instead of from the \gloskey{first} key, and the first use plural
+text is obtained via:
+\begin{definition}[\DescribeMacro{\genplacrfullformat}]
+\cs{genplacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+instead of from the \gloskey{firstplural} key.
+In both cases, \meta{label} is the entry's label and \meta{insert}
+is the insert text provided in the final optional argument of
+commands like \ics{gls}. The default behaviour is to do the long
+form (or plural long form) followed by \meta{insert} and a~space and the short form (or plural
+short form) in parentheses, where the short form is in the argument
+of \ics{firstacronymfont}. There are also first letter upper case
+versions:
+\begin{definition}[\DescribeMacro{\Genacrfullformat}]
+\cs{Genacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\Genplacrfullformat}]
+\cs{Genplacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+By default these perform a protected expansion on their no-case-change
+equivalents and then use \ics{makefirstuc} to convert the first
+character to upper case. If there are issues caused by this
+expansion, you will need to redefine those commands to explicitly
+use commands like \ics{Glsentrylong} (which is what the predefined
+acronym styles, such as \acrstyle{long-short}, do). Otherwise, you
+only need to redefine \ics{genacrfullformat} and
+\ics{genplacrfullformat} to change the behaviour of
+\ics{glsgenacfmt}. See \sectionref{sec:acronyms} for further details
+on changing the style of acronyms.
+
+\begin{important}
+Note that \cs{glsentryfmt} (or the formatting given by \cs{defglsentryfmt})
+is not used by the \glstextlike\ commands.
+\end{important}
+
+As from version 4.16, both the \glslike\ and \glstextlike\ commands
+use
+\begin{definition}[\DescribeMacro\glslinkpostsetkeys]
+\cs{glslinkpostsetkeys}
+\end{definition}
+after the \meta{options} are set. This macro does nothing by default
+but can be redefined. (For example, to switch off the hyperlink
+under certain conditions.) This version also introduces
+\begin{definition}[\DescribeMacro\glspostlinkhook]
+\cs{glspostlinkhook}
+\end{definition}
+which is done after the link text has been displayed and also
+\emph{after} the \firstuseflag\ has been unset (see
+example~\ref{ex:dotabbr}).
+
+\begin{example}{Custom Entry Display in Text}{ex:customfmt}
+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
+\ics{glsentryfmt} as follows:
+\begin{verbatim}
+\renewcommand*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}%
+}
+\end{verbatim}
+
+(Note that I've used \ics{glsentrysymbol} rather than \ics{glssymbol}
+to avoid nested hyperlinks.)
+
+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*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}%
+}
+\end{verbatim}
+then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}.
+
+For a complete document, see the sample file \samplefile{-entryfmt}.
+\end{example}
+
+\begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt}
+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}
+\defglsentryfmt[notation]{\glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space
+ (denoted \glsentrysymbol{\glslabel})}}
+\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).
+
+Alternatively, if you expect all the symbols to be set in math mode,
+you can do:
+\begin{verbatim}
+\defglsentryfmt[notation]{\glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space
+ (denoted $\glsentrysymbol{\glslabel}$)}}
+\end{verbatim}
+and define entries like this:
+\begin{verbatim}
+\newglossaryentry{set}{type=notation,
+ name=set,
+ description={A collection of objects},
+ symbol={S}
+}
+\end{verbatim}
+\end{example}
+
+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.
+
+\section{Enabling and disabling hyperlinks to glossary entries}
+\label{sec:disablehyperlinks}
+
+If you load the \sty{hyperref} or \sty{html} packages prior to
+loading the \styfmt{glossaries} package, the \glslike\ and
+\glstextlike\ commands will automatically have hyperlinks
+to the relevant glossary entry, unless the \gloskey[glslink]{hyper}
+option has been switched off (either explicitly or through
+implicit means, such as via the \pkgopt{nohypertypes} package option).
+
+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 the \glslike\ commands that recognise the \firstuseflag.
+
+\begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc}
+Suppose I want the \gls*{firstuse} to have a hyperlink to the
+description in a footnote instead of hyperlinking to the relevant
+place in the glossary. First I need to disable the hyperlinks on
+first use via the package option \pkgopt[false]{hyperfirst}:
+\begin{verbatim}
+\usepackage[hyperfirst=false]{glossaries}
+\end{verbatim}
+Now I need to redefine \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}):
+\begin{verbatim}
+\renewcommand*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}%
+}
+\end{verbatim}
+
+Now the first use won't have hyperlinked text, but will be followed
+by a footnote.
+See the sample file \samplefile{-FnDesc} for a complete document.
+\end{example}
+
+Note that the \pkgopt{hyperfirst} option applies to all defined glossaries. It
+may be that you only want to disable the hyperlinks on
+\gls{firstuse} for glossaries that have a different form on
+\gls*{firstuse}. This can be achieved by noting that since the
+entries that require hyperlinking for all instances have identical
+first and subsequent text, they can be unset via \ics{glsunsetall}
+(see \sectionref{sec:glsunset}) so that the \pkgopt{hyperfirst}
+option doesn't get applied.
+
+\begin{example}{Suppressing Hyperlinks on First Use Just For
+Acronyms}{ex:hyperfirst}
+Suppose I want to suppress the hyperlink on \gls{firstuse} for
+acronyms but not for entries in the main glossary. I~can load
+the \styfmt{glossaries} package using:
+\begin{verbatim}
+\usepackage[hyperfirst=false,acronym]{glossaries}
+\end{verbatim}
+Once all glossary entries have been defined I~then do:
+\begin{verbatim}
+\glsunsetall[main]
+\end{verbatim}
+
+\end{example}
+
+For more complex requirements, you might find it easier to switch
+off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks
+(where required) within the definition of \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}) via \ics{glshyperlink} (see
+\sectionref{sec:glsnolink}).
+
+\begin{example}{Only Hyperlink in Text Mode Not Math
+Mode}{ex:nomathhyper}
+This is a bit of a contrived example, but suppose, for some reason,
+I only want the \glslike\ commands to have
+hyperlinks when used in text mode, but not in math mode. I~can do
+this by adding the glossary to the list of nohypertypes and redefining
+\ics{glsentryfmt}:
+\begin{verbatim}
+\GlsDeclareNoHyperList{main}
+
+\renewcommand*{\glsentryfmt}{%
+ \ifmmode
+ \glsgenentryfmt
+ \else
+ \glsifhyperon
+ {\glsgenentryfmt}% hyperlink already on
+ {\glshyperlink[\glsgenentryfmt]{\glslabel}}%
+ \fi
+}
+\end{verbatim}
+Note that this doesn't affect the \glstextlike\ commands, which will
+have the hyperlinks off unless they're forced on using the plus
+variant.
+
+See the sample file \samplefile{-nomathhyper} for a complete
+document.
+\end{example}
+
+\begin{example}{One Hyper Link Per Entry Per Chapter}{ex:chap-hyperfirst}
+Here's a more complicated example that will only have the hyperlink
+on the first time an entry is used per chapter. This doesn't involve
+resetting the \firstuseflag. Instead it adds a~new key using
+\ics{glsaddstoragekey} (see \sectionref{sec:glsaddstoragekey}) that
+keeps track of the chapter number that the entry was last used in:
+\begin{verbatim}
+\glsaddstoragekey{chapter}{0}{\glschapnum}
+\end{verbatim}
+This creates a new user command called \cs{glschapnum} that's
+analogous to \cs{glsentrytext}. The default value for this key is~0.
+I~then define my glossary entries as usual.
+
+Next I redefine the hook \ics{glslinkpostsetkeys}
+(see \sectionref{sec:glsdisplay}) so that it determines the current
+chapter number (which is stored in \cs{currentchap} using
+\cs{edef}). This value is then compared with the value of the
+entry's \texttt{chapter} key that I defined earlier. If they're the
+same, this entry has already been used in this chapter so the
+hyperlink is switched off using \sty{xkeyval}'s \cs{setkeys}
+command. If the chapter number isn't the same, then this entry
+hasn't been used in the current chapter. The \texttt{chapter} field
+is updated using \ics{glsfieldxdef} (\sectionref{sec:fetchset})
+provided the user hasn't switched off the hyperlink.
+(This test is performed using \cs{glsifhyperon}.
+\begin{verbatim}
+\renewcommand*{\glslinkpostsetkeys}{%
+ \edef\currentchap{\arabic{chapter}}%
+ \ifnum\currentchap=\glschapnum{\glslabel}\relax
+ \setkeys{glslink}{hyper=false}%
+ \else
+ \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}%
+ \fi
+}
+\end{verbatim}
+Note that this will be confused if you use \cs{gls} etc when the
+chapter counter is~0. (That is, before the first \cs{chapter}.)
+
+See the sample file \samplefile{-chap-hyperfirst} for a complete
+document.
+\end{example}
+
+\chapter{Adding an Entry to the Glossary Without Generating Text}
+\label{sec:glsadd}
+
+It is possible to add a line to 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 the \glstextlike\ commands, 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 \glstextlike\ commands 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 \gls{numberlist}. 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}
+
+There is now a variation of \cs{glsaddall} that skips any entries
+that have already been used:
+\begin{definition}[\DescribeMacro\glsaddallunused]
+\cs{glsaddallunused}\oarg{list}
+\end{definition}
+This command uses \cs{glsadd}\texttt{[format=@gobble]} which will
+ignore this location in the number list. The optional argument
+\meta{list} is a comma-separated list of glossary types. If omitted,
+it defaults to the list of all defined glossaries.
+
+If you want to use \cs{glsaddallunused}, it's best to place the
+command at the end of the document to ensure that all the commands
+you intend to use have already been used. Otherwise you could end up
+with a spurious comma or dash in the location list.
+
+\begin{example}{Dual Entries}{ex:dual}
+The example 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\glsadd{#2}},%
+ description={#5},%
+ #1
+ }%
+ \newacronym{#2}{#3\glsadd{main-#2}}{#4}%
+}
+\end{verbatim}
+This has the following syntax:
+\begin{alltt}
+\ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description}
+\end{alltt}
+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}|.
+\end{example}
+
+\chapter{Cross-Referencing Entries}
+\label{sec:crossref}
+
+\begin{important}
+You must use \ics{makeglossaries} (\optsor23) or
+\ics{makenoidxglossaries} (\opt1) \emph{before} defining any
+terms that cross-reference entries. If any of the terms that you have
+cross-referenced don't appear in the glossary, check that you have
+put \cs{makeglossaries}\slash\cs{makenoidxglossaries} before all
+entry definitions. The \gls{glossaries-extra} package provides
+better cross-reference handling.
+\end{important}
+
+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}
+
+\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}
+Take care if you want to use the optional argument of commands such
+as \ics{newacronym} or \ics{newterm} as the value will need to be
+grouped. For example:
+\begin{verbatim}
+\newterm{seal}
+\newterm[see={[see also]seal}]{sea lion}
+\end{verbatim}
+Similarly if the value contains a list. For example:
+\begin{verbatim}
+\glossaryentry{lemon}{
+ name={lemon},
+ description={Yellow citrus fruit}
+}
+\glossaryentry{lime}
+{
+ name={lime},
+ description={Green citrus fruit}
+}
+\glossaryentry{citrus}
+{
+ name={citrus},
+ description={Plant in the Rutaceae family},
+ see={lemon,lime}
+}
+\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.
+
+\section{Customising Cross-reference Text}
+\label{sec:customxr}
+
+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
+\qt{\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 could cause
+problems when the \gloskey{name} key was \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}
+
+\chapter{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{important}
+Commands that aren't expandable will be ignored by PDF bookmarks, so
+you will need to provide an alternative via \sty{hyperref}'s
+\cs{texorpdfstring} if you want to use them in sectioning commands.
+(This isn't specific to the \styfmt{glossaries} package.) See the
+\sty{hyperref} documentation for further details. All the commands
+that convert the first letter to upper case aren't expandable.
+The other commands depend on whether their corresponding keys were
+assigned non-expandable values.
+\end{important}
+
+If you want to title case a field, you can use:
+\begin{definition}[\DescribeMacro\glsentrytitlecase]
+\cs{glsentrytitlecase}\marg{label}\marg{field}
+\end{definition}
+where \meta{label} is the label identifying the glossary entry,
+\meta{field} is the field label (see \tableref{tab:fieldmap}).
+For example:
+\begin{verbatim}
+\glsentrytitlecase{sample}{desc}
+\end{verbatim}
+(If you want title-casing in your glossary style, you might want to
+investigate the \sty{glossaries-extra} package.)
+
+Note that this command has the same limitations as \cs{makefirstuc} which is
+used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case
+the first letter (see the notes about \cs{Gls} in \sectionref{sec:gls-like}).
+
+\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 upper case.
+Neither of these commands check for the existence of \meta{label}.
+The first form \cs{glsentryname} is expandable (unless the name
+contains unexpandable commands). Note that this may be different from the values of
+the \gloskey{text} or \gloskey{first} keys. In general it's better
+to use \cs{glsentrytext} or \cs{glsentryfirst} instead of
+\cs{glsentryname}.
+
+\begin{important}
+In general it's best to avoid \cs{Glsentryname} with abbreviations. Instead,
+consider using \cs{Glsentrylong}, \cs{Glsentryshort} or \cs{Glsentryfull}.
+\end{important}
+
+\begin{definition}[\DescribeMacro{\glossentryname}]
+\cs{glossentryname}\marg{label}
+\end{definition}
+This is like \cs{glsnamefont}\{\cs{glsentryname\marg{label}}\}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles, so if
+you want to change the way the name is formatted in the glossary,
+you can redefine \cs{glsnamefont} to use the required fonts. For
+example:
+\begin{verbatim}
+\renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}}
+\end{verbatim}
+\begin{definition}[\DescribeMacro{\Glossentryname}]
+\cs{Glossentryname}\marg{label}
+\end{definition}
+This is like \cs{glossentryname} but makes the first letter of the
+name upper case.
+
+\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 upper case.
+The first form is expandable (unless the text contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\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
+upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\begin{definition}[\DescribeMacro{\glossentrydesc}]
+\cs{glossentrydesc}\marg{label}
+\end{definition}
+This is like \cs{glsentrydesc}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles to
+display the description.
+\begin{definition}[\DescribeMacro{\Glossentrydesc}]
+\cs{Glossentrydesc}\marg{label}
+\end{definition}
+This is like \cs{glossentrydesc} but converts the first letter to
+upper case. This command is not expandable.
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+
+\begin{definition}[\DescribeMacro\glsletentryfield]
+\cs{glsletentryfield}\marg{cs}\marg{label}\marg{field}
+\end{definition}
+This command doesn't display anything. It merely fetches the
+value associated with the given field (where the available field names
+are listed in \tableref{tab:fieldmap}) and stores the result
+in the control sequence \meta{cs}. For example, to store
+the description for the entry whose label is \qt{apple} in the
+control sequence \verb|\tmp|:
+\begin{verbatim}
+\glsletentryfield{\tmp}{apple}{desc}
+\end{verbatim}
+
+\begin{definition}[\DescribeMacro{\glossentrysymbol}]
+\cs{glossentrysymbol}\marg{label}
+\end{definition}
+This is like \cs{glsentrysymbol}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in some of the predefined glossary styles to
+display the symbol.
+\begin{definition}[\DescribeMacro{\Glossentrysymbol}]
+\cs{Glossentrysymbol}\marg{label}
+\end{definition}
+This is like \cs{glossentrysymbol} but converts the first letter to
+upper case. This command is not expandable.
+
+\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 upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\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}.
+The lower case forms are expandable (unless the value of the key
+contains unexpandable commands). The commands beginning with an
+upper case letter convert the first letter of the required value to
+upper case and are not expandable. None of these commands check for
+the existence of \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 could cause
+problems when \gloskey{name} had been \glsd{sanitize}.}, but can be
+overridden using the optional argument. Note that the hyperlink will
+be suppressed if you have used \ics{glsdisablehyper} or if you
+haven't loaded the \sty{hyperref} package.
+
+\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}
+
+The next two commands are only available with \opt1 or with the
+\pkgopt{savenumberlist} package option:
+\begin{definition}[\DescribeMacro{\glsentrynumberlist}]
+\cs{glsentrynumberlist}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsdisplaynumberlist}]
+\cs{glsdisplaynumberlist}\marg{label}
+\end{definition}
+Both display the \gls{numberlist} for the entry given by
+\meta{label}. When used with \opt1 a~rerun is required to ensure
+this list is up-to-date, when used with \optsor23
+a run of \gls{makeglossaries} (or \gls{makeindex}\slash\gls{xindy})
+followed by one or two runs of \LaTeX\ is required.
+
+The first command, \cs{glsentrynumberlist}, simply displays
+the number list as is. The second command,
+\cs{glsdisplaynumberlist}, formats the list using:
+\begin{definition}[\DescribeMacro{\glsnumlistsep}]
+\cs{glsnumlistsep}
+\end{definition}
+as the separator between all but the last two elements and
+\begin{definition}[\DescribeMacro{\glsnumlistlastsep}]
+\cs{glsnumlistlastsep}
+\end{definition}
+between the final two elements. The defaults are
+\verb*|, | and \verb*| \& |, respectively.
+
+\begin{important}
+\cs{glsdisplaynumberlist} is fairly experimental. It works with
+\opt1, but for \optsor23 it only works when the default counter
+format is used (that is, when the \gloskey[glslink]{format} key is
+set to \texttt{glsnumberformat}). This command will only work with
+\sty{hyperref} if you choose \opt1. If you try using this command
+with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be
+used instead.
+\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-code.pdf}).
+
+\chapter{Displaying a glossary}
+\label{sec:printglossary}
+
+All defined glossaries may be displayed using:
+\begin{description}
+\itempar{\opt1:}
+\begin{definition}[\DescribeMacro{\printnoidxglossaries}]
+\cs{printnoidxglossaries}
+\end{definition}
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+
+\itempar{\optsand23:}
+\begin{definition}[\DescribeMacro{\printglossaries}]
+\cs{printglossaries}
+\end{definition}
+(Must be used with \ics{makeglossaries} in the preamble.)
+\end{description}
+
+These commands will display all the glossaries in the order in which
+they were defined. Note that, in the case of \optsand23, no
+glossaries will appear until you have either used the Perl script
+\gls{makeglossaries} or Lua script \gls{makeglossaries-lite.lua} or
+have directly used \gls{makeindex} or \gls{xindy} (as described in
+\sectionref{sec:makeglossaries}). (While the external files are
+missing, these commands will just do \cs{null} for each missing
+glossary to assist dictionary style documents that just use
+\cs{glsaddall} without inserting any text. If you use
+\gls{glossaries-extra}, it will insert a heading and boilerplate text when the
+external files are missing. The extension package also provides
+\cs{printunsrtglossaries} as an alternative. See the
+\gls{glossaries-extra} manual for further details.)
+
+If the glossary still does not appear after you re-\LaTeX\ your
+document, check the \gls*{makeindex}\slash\gls*{xindy} log files to
+see if there is a problem. With \opt1, you just need two \LaTeX\
+runs to make the glossaries appear, but you may need further runs to
+make the \glspl{numberlist} up-to-date.
+
+An individual glossary can be displayed using:
+\begin{description}
+\itempar{\opt1:}
+\begin{definition}[\DescribeMacro{\printnoidxglossary}]
+\cs{printnoidxglossary}\oarg{options}
+\end{definition}
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+
+\itempar{\optsand23:}
+\begin{definition}[\DescribeMacro{\printglossary}]
+\cs{printglossary}\oarg{options}
+\end{definition}
+(Must be used with \ics{makeglossaries} in the preamble.)
+\end{description}
+where \meta{options} is a \meta{key}=\meta{value} list of options.
+(Again, when the associated external file is missing, \cs{null} is
+inserted into the document.)
+
+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}
+Note that you can't display an ignored glossary, so don't try
+setting \gloskey[printglossary]{type} to the name of a glossary that
+was defined using \ics{newignoredglossary}, described in
+\sectionref{sec:newglossary}. (You can display an ignored glossary
+with \cs{printunsrtglossary} provided by \gls{glossaries-extra}.)
+
+\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.
+
+\item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean
+key. If true the vertical gap between groups
+is suppressed for this glossary.
+
+\item[{\gloskey[printglossary]{nopostdot}}] This is a boolean
+key. If true the full stop after the description
+is suppressed for this glossary.
+
+\item[{\gloskey[printglossary]{entrycounter}}] This is a boolean
+key. Behaves similar to the package option of the same name.
+The corresponding package option must be used to make \ics{glsrefentry}
+work correctly.
+
+\item[{\gloskey[printglossary]{subentrycounter}}] This is a boolean
+key. Behaves similar to the package option of the same name. If you
+want to set both \gloskey{entrycounter} and
+\gloskey{subentrycounter}, make sure you specify
+\gloskey{entrycounter} first. The corresponding package option must
+be used to make \ics{glsrefentry} work correctly.
+
+\item[{\gloskey[printnoidxglossary]{sort}}] This key is only
+available for \opt1. Possible values are: \texttt{word} (word
+order), \texttt{letter} (letter order), \texttt{standard} (word or
+letter ordering taken from the \pkgopt{order} package option),
+\texttt{use} (order of use), \texttt{def} (order of definition)
+\texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive).
+Note that the word and letter comparisons (that is, everything other
+than \texttt{sort=use} and \texttt{sort=def}) just use a simple
+character code comparison. For a locale-sensitive sort, you must use
+either \gls{xindy} (\opt3) or \gls{bib2gls} (\opt4). Note that \gls{bib2gls}
+provides many other sort options.
+
+\begin{important}
+If you use the \texttt{use} or \texttt{def} values make sure
+that you select a glossary style that doesn't have a visual
+indicator between groups, as the grouping no longer makes sense.
+Consider using the \pkgopt{nogroupskip} option.
+\end{important}
+
+{\raggedright
+The word and letter order sort methods use
+\sty{datatool}'s
+\ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers.
+The case-insensitive sort method uses \sty{datatool}'s
+\ics{dtlicompare} handler. The case-sensitive sort method uses
+\sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool}
+documentation for further details.
+\par}
+
+If you don't get an error with \texttt{sort=use} and
+\texttt{sort=def} but you do get an error with one of the other sort
+options, then you probably need to use the
+\pkgopt[true]{sanitizesort} package option or make sure none of the
+entries have fragile commands in their \gloskey{sort} field.
+\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
+\begin{definition}[\DescribeMacro\glsglossarymark]
+\ics{glsglossarymark}\marg{title}
+\end{definition}
+If this mechanism is unsuitable for your chosen class file or page
+style package, you will need to redefine \ics{glsglossarymark}. 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.
+
+If you want a different preamble per glossary you can use
+\begin{definition}[\DescribeMacro{\setglossarypreamble}]
+\cs{setglossarypreamble}\oarg{type}\marg{preamble text}
+\end{definition}
+If \meta{type} is omitted, \cs{glsdefaulttype} is used.
+
+For example:
+\begin{verbatim}
+\setglossarypreamble{Numbers in italic
+indicate primary definitions.}
+\end{verbatim}
+This will print the given preamble text for the main glossary,
+but not have any preamble text for any other glossaries.
+
+There is an analogous command to \cs{glossarypreamble} called
+\begin{definition}[\DescribeMacro{\glossarypostamble}]
+\cs{glossarypostamble}
+\end{definition}
+which is placed at the end of each glossary.
+
+\begin{example}{Switch to Two Column Mode for Glossary}{ex:twocolumn}
+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[{\chapter*{#2}}]%
+ \setlength\glsdescwidth{0.6\linewidth}%
+ \glsglossarymark{\glossarytoctitle}%
+}
+
+\renewcommand*{\glossarypostamble}{\onecolumn}
+\end{verbatim}
+
+\end{example}
+
+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.
+
+If you want to change the font for the description, or if you
+only want to change the name font for some types of entries
+but not others, you might want to consider using the
+\sty{glossaries-extra} package.
+
+\begin{example}{Changing the Font Used to Display Entry Names in the
+Glossary}{ex:glsnamefont}
+Suppose you want all the entry names to appear in
+medium weight small caps in your glossaries, then you can do:
+\begin{verbatim}
+\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
+\end{verbatim}
+\end{example}
+
+\chapter[Xindy (Option 3)]{Xindy (\ifpdf\opt3\else Option 3\fi)}
+\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
+\gls{indexingapp}, and \sectionref{sec:locationsyntax} covers the
+issues involved in the location syntax. 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.) Similarly, you can write a percent
+character using:
+\begin{definition}[\DescribeMacro{\glspercentchar}]
+\cs{glspercentchar}
+\end{definition}
+and a tilde character using:
+\begin{definition}[\DescribeMacro{\glstildechar}]
+\cs{glstildechar}
+\end{definition}
+For example, a newline character is specified in a \gls{xindy} style
+file using \verb|~n| so you can use \texttt{\cs{glstildechar} n}
+to write this correctly (or you can do \verb|\string~n|).
+A backslash can be written to a file using
+\begin{definition}[\DescribeMacro{\glsbackslash}]
+\cs{glsbackslash}
+\end{definition}
+
+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. I'm sorry I can't provide any assistance
+with writing \gls*{xindy} style files. If you need help, I recommend
+you ask on the \gls*{xindy} mailing list
+(\url{http://xindy.sourceforge.net/mailing-list.html}).
+
+\section{Language and Encodings}
+\label{sec:langenc}
+
+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 \gls{makeglossaries} script attempts to
+find the root language given your document settings, but in the
+event that it gets it wrong or if \gls*{xindy} doesn't support
+that language, then you can specify the required 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
+\xdyopt{L} and \xdyopt{C} switches.
+\end{important}
+
+\section{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.
+
+Take care if you have multiple instances of the same location with
+different formats. The duplicate locations will be discarded
+according to the order in which the attributes are listed. Consider
+defining semantic commands to use for primary references. For
+example:
+\begin{verbatim}
+\newcommand*{\primary}[1]{\textbf{#1}}
+\GlsAddXdyAttribute{primary}
+\end{verbatim}
+Then in the document:
+\begin{verbatim}
+A \gls[format=primary]{duck} is an aquatic bird.
+There are lots of different types of \gls{duck}.
+\end{verbatim}
+This will give the \verb|format=primary| instance preference over
+the next use that doesn't use the \gloskey[glslink]{format} key.
+
+\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit}
+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}
+Now I can use it in the optional argument of commands like
+\ics{gls}:
+\begin{verbatim}
+Here is a \gls[format=hyperbfit]{sample} entry.
+\end{verbatim}
+(where \texttt{sample} is the label of the required entry).
+\end{example}
+
+\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 include formatting commands, 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}.
+Be sure to also read \sectionref{sec:locationsyntax} for some issues
+that you may encounter.
+
+\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}
+
+\begin{example}{Custom Numbering System for Locations}{ex:customloc}
+Suppose I decide to use a somewhat eccentric numbering
+system for sections where I redefine \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}
+This example is illustrated in the sample file
+\samplefile{xdy2}.
+\end{example}
+
+\begin{example}{Locations as Dice}{ex:dice}
+Suppose I want a rather eccentric page numbering system that's
+represented by the number of dots on dice. The \sty{stix} package
+provides \cs{dicei}, \ldots, \cs{dicevi} that represent the six
+sides of a die. I can define a command that takes a number as its
+argument. If the number is less than seven, the appropriate
+\cs{dice}\meta{n} command is used otherwise it does \cs{dicevi} the
+required number of times with the leftover in a final
+\cs{dice}\meta{n}. For example, the number 16 is represented by
+\verb|\dicevi\dicevi\diceiv| ($6+6+4=16$). I've called this command
+\cs{tallynum} to match the example given earlier in
+\sectionref{sec:locationsyntax}:
+\begin{verbatim}
+\newrobustcmd{\tallynum}[1]{%
+ \ifnum\number#1<7
+ $\csname dice\romannumeral#1\endcsname$%
+ \else
+ $\dicevi$%
+ \expandafter\tallynum\expandafter{\numexpr#1-6}%
+ \fi
+}
+\end{verbatim}
+Here's the counter command:
+\begin{verbatim}
+newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
+\end{verbatim}
+The \ctr{page} counter representation (\cs{thepage}) needs to be
+changed to use this command:
+\begin{verbatim}
+\renewcommand*{\thepage}{\tally{page}}
+\end{verbatim}
+The \cs{tally} command expands to \cs{tallynum} \marg{number} so
+this needs a location class that matches this format:
+\begin{verbatim}
+\GlsAddXdyLocation{tally}{%
+ :sep "\string\tallynum\space\glsopenbrace"
+ "arabic-numbers"
+ :sep "\glsclosebrace"
+}
+\end{verbatim}
+The space between \cs{tallynum} and \marg{number} is
+significant to \gls{xindy} so \cs{space} is required.
+
+Note that \cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define
+commands in the form:
+\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{theH}\meta{counter}
+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{tallynum}, as
+illustrated above, is defined to make the page numbers appear as
+dice. 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}[2]{\hyperlink{page.#2}{#1{#2}}}
+\end{verbatim}
+Note that the second argument of \cs{glsXpageXglsnumberformat} is
+in the format \cs{tallynum}\marg{n} so the line
+\begin{verbatim}
+ \linkpagenumber#2%
+\end{verbatim}
+does
+\begin{alltt}
+ \cs{linkpagenumber}\cs{tallynum}\marg{number}
+\end{alltt}
+so \cs{tallynum} is the first argument of \cs{linkpagenumber}
+and \meta{number} is the second argument.
+\end{example}
+
+\begin{important}
+This method is very sensitive to the internal definition of the
+location command.
+\end{important}
+
+\begin{example}{Locations as Words not Digits}{ex:fmtcount}
+Suppose I want the page numbers written as words
+rather than digits and I~use the \sty{fmtcount} package to
+do this. I~can redefine \ics{thepage} as follows:
+\begin{verbatim}
+\renewcommand*{\thepage}{\Numberstring{page}}
+\end{verbatim}
+This \emph{used} to get expanded to \verb|\protect \Numberstringnum |\marg{n}
+where \meta{n} is the Arabic page number. This means that I~needed to
+define a new location with the form:
+\begin{verbatim}
+\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
+ \string\Numberstringnum\space\glsopenbrace"
+ "arabic-numbers" :sep "\glsclosebrace"}
+\end{verbatim}
+and if I'd used the \cs{linkpagenumber} command from the previous
+example, it would need \emph{three} arguments (the first being
+\cs{protect}):
+\begin{verbatim}
+\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
+\end{verbatim}
+
+The internal definition of \cs{Numberstring} has since changed
+so that it now expands to \verb|\Numberstringnum |\marg{n}
+(no \cs{protect}). This means that the location class definition
+must be changed to:
+\begin{verbatim}
+\GlsAddXdyLocation{Numberstring}{% no \protect now!
+ :sep "\string\Numberstringnum\space\glsopenbrace"
+ "arabic-numbers" :sep "\glsclosebrace"}
+\end{verbatim}
+and \cs{linkpagenumber} goes back to only two arguments:
+\begin{verbatim}
+\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
+\end{verbatim}
+The other change is that \cs{Numberstring} uses
+\begin{alltt}
+\cs{the}\cs{value}\marg{counter}
+\end{alltt}
+instead of
+\begin{alltt}
+\cs{expandafter}\cs{the}\cs{csname} c@\meta{counter}\cs{endcsname}
+\end{alltt}
+so it hides \cs{c@page} from the location escaping mechanism
+(see \sectionref{sec:locationsyntax}). This means that the page
+number may be incorrect if the indexing occurs during the output
+routine.
+
+A more recent change to \sty{fmtcount} (v3.03) now puts three
+instances of \cs{expandafter} before \verb|\the\value| which
+no longer hides \cs{c@page} from the location escaping mechanism, so
+the page numbers should once more be correct. Further changes
+to the \sty{fmtcount} package may cause a problem again.
+
+\begin{important}
+When dealing with custom formats where the internal definitions
+are outside of your control and liable to change, it's best
+to provide a wrapper command.
+\end{important}
+
+Instead of directly using \cs{Numberstring} in the definition of
+\cs{thepage}, I can provide a custom command in the same form
+as the earlier \cs{tally} command:
+\begin{verbatim}
+\newcommand{\customfmt}[1]{\customfmtnum{\arabic{#1}}}
+\newrobustcmd{\customfmtnum}[1]{\Numberstringnum{#1}}
+\end{verbatim}
+This ensures that the location will always be written to
+the indexing file in the form:
+\begin{alltt}
+:locref "\glsopenbrace\glsclosebrace\glsopenbrace\string\\customfmtnum \marg{n}\glsclosebrace"
+\end{alltt}
+So the location class can be defined as:
+\begin{verbatim}
+\GlsAddXdyLocation{customfmt}{
+ :sep "\string\customfmtnum\space\glsopenbrace"
+ "arabic-numbers"
+ :sep "\glsclosebrace"}
+\end{verbatim}
+
+The sample file
+\samplefile{xdy3} illustrates this.
+\end{example}
+
+In the \gls{numberlist}, the locations are sorted according to the list
+of provided location classes. The default ordering is:
+\texttt{roman-page-numbers} (i, ii, \ldots), \texttt{arabic-page-numbers}
+(1, 2, \ldots), \texttt{arabic-section-numbers} (for example, 1.1 if the
+compositor is a full stop or 1-1 if the compositor is a
+hyphen\footnote{see \ics{glsSetCompositor} described in
+\sectionref{sec:setup}}), \texttt{alpha-page-numbers} (a, b, \ldots),
+\texttt{Roman-page-numbers} (I, II, \ldots), \texttt{Alpha-page-numbers}
+(A, B, \ldots), \texttt{Appendix-page-numbers} (for example, A.1 if the Alpha
+compositor is a full stop or A-1 if the Alpha compositor is a
+hyphen\footnote{see \ics{glsSetAlphaCompositor} described in
+\sectionref{sec:setup}}), user defined location names (as specified
+by \ics{GlsAddXdyLocation} in the order in which they were defined),
+and finally \texttt{see} (cross-referenced entries).\footnote{With
+\gls{glossaries-extra} \texttt{seealso} is appended to the end of
+the list.} This ordering can be changed using:
+
+\begin{definition}[\DescribeMacro\GlsSetXdyLocationClassOrder]
+\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}
+(Remember to add \verb|"seealso"| if you're using
+\gls{glossaries-extra}.)
+
+\begin{important}
+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 also \sectionref{sec:ranges}.
+
+\section{Glossary Groups}
+\label{sec: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 want \gls{xindy}
+to sort the number group numerically (rather than by a string sort)
+then you need to use \gls{xindy}['s] \texttt{numeric-sort} module:
+\begin{verbatim}
+\GlsAddXdyStyle{numeric-sort}
+\end{verbatim}
+
+If you don't use \texttt{glsnumbers=false}, the default behaviour is to locate
+the number group before the \qt{A} letter group. If you are not using a
+Roman alphabet, you need to change this using:
+
+
+\begin{definition}[\DescribeMacro\GlsSetXdyFirstLetterAfterDigits]
+\cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter}
+\end{definition}
+where \meta{letter} is the first letter of your alphabet. Take care
+if you're using \sty{inputenc} as non-ASCII characters are actually
+active characters that expand. (This isn't a problem with the native
+UTF-8 engines and \sty{fontspec}.) The starred form will sanitize
+the argument to prevent expansion.
+Alternatively you can use:
+
+
+\begin{definition}[\DescribeMacro\GlsSetXdyNumberGroupOrder]
+\cs{GlsSetXdyNumberGroupOrder}\marg{relative location}
+\end{definition}
+to change the default
+\begin{alltt}
+:before \cs{string}"\meta{letter}\cs{string}"
+\end{alltt}
+to \meta{relative location}. For example:
+\begin{verbatim}
+\GlsSetXdyNumberGroupOrder{:after \string"Z\string"}
+\end{verbatim}
+will put the number group after the \qt{Z} letter group.
+Again take care of active characters. There's a starred version
+that sanitizes the argument (so don't use \cs{string} in it).
+\begin{alltt}
+\cs{GlsSetXdyNumberGroupOrder}*\{:after "\"O"\}
+\end{alltt}
+
+\begin{important}
+Note that these commands have no effect if
+\ics{noist} is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyFirstLetterAfterDigits} must be used before
+\ics{makeglossaries}.\par
+\end{important}
+
+
+\chapter{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}\linebreak\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} (\opt2) or \gls{xindy} (\opt3)
+transcript file (this information is only used by
+\gls{makeglossaries} which picks up the information from the
+auxiliary file). If you use \opt1, the \meta{log-ext},
+\meta{in-ext} and \meta{out-ext} arguments are ignored.
+
+\begin{important}
+The glossary label \meta{name} must not contain any active
+characters. It's generally best to stick with just characters that
+have category code~11 (typically the non-extended \glspl{latinchar}
+for standard \LaTeX).
+\end{important}
+
+There is also a starred version (new to v4.08):
+\begin{definition}[\DescribeMacro{\newglossary*}]
+\cs{newglossary*}\marg{name}\marg{title}\oarg{counter}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{newglossary}[\meta{name}-glg]\marg{name}\{\meta{name}-gls\}\{\meta{name}-glo\}\ifpdf\linebreak\fi\marg{title}\oarg{counter}
+\end{alltt}
+or you can also use:
+\begin{definition}[\DescribeMacro{\altnewglossary}]
+\cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter}
+\end{alltt}
+
+It may be that you have some terms that are so common
+that they don't need to be listed. In this case, you can define
+a~special type of glossary that doesn't create any associated files.
+This is referred to as an \qt{ignored glossary} and it's ignored by
+commands that iterate over all the glossaries, such as
+\ics{printglossaries}. To define an ignored glossary, use
+\begin{definition}[\DescribeMacro\newignoredglossary]
+\cs{newignoredglossary}\marg{name}
+\end{definition}
+where \meta{name} is the name of the glossary (as above). This
+glossary type will automatically be added to the
+\pkgopt{nohypertypes} list, since there are no hypertargets for
+the entries in an ignored glossary.
+(The sample file \samplefile{-entryfmt} defines an ignored glossary.)
+
+You can test if a glossary is an ignored one using:
+\begin{definition}[\DescribeMacro\ifignoredglossary]
+\cs{ifignoredglossary}\marg{name}\marg{true}\marg{false}
+\end{definition}
+This does \meta{true} if \meta{name} was defined as an ignored
+glossary, otherwise it does \meta{false}.
+
+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}.
+
+The \pkgopt{symbols} package option creates a new glossary with the
+label \texttt{symbols} using:
+\begin{verbatim}
+\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
+\end{verbatim}
+The \pkgopt{numbers} package option creates a new glossary with
+the label \texttt{numbers} using:
+\begin{verbatim}
+\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
+\end{verbatim}
+The \pkgopt{index} package option creates a new glossary with
+the label \texttt{index} using:
+\begin{verbatim}
+\newglossary[ilg]{index}{ind}{idx}{\indexname}
+\end{verbatim}
+
+\begin{important}
+\optsand23: all glossaries must be defined before \ics{makeglossaries} to
+ensure that the relevant output files are opened.
+
+See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname},
+especially if you are using \sty{babel} or \sty{translator}.
+(Similarly for \cs{glssymbolsgroupname} and
+\cs{glsnumbersgroupname}.) If you want to redefine \ics{indexname},
+just follow the advice in
+\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fixnam}{How to
+change LaTeX’s \qt{fixed names}}.
+\end{important}
+
+\chapter{Acronyms and Other Abbreviations}
+\label{sec:acronyms}
+
+The \sty{glossaries-extra} package provides superior
+abbreviation handling. You may want to consider using that
+package instead of the commands described here.
+
+\begin{important}
+Note that although this chapter uses the term \qt{acronym}, you can also
+use the commands described here for initialisms or contractions
+(as in the case of some of the examples given below).
+If the glossary title is no longer applicable (for example, it
+should be \qt{Abbreviations} rather than \qt{Acronyms}) then
+you can change the title either by redefining \ics{acronymname} (see
+\sectionref{sec:languages}) or by using the \gloskey[printglossary]{title}
+in the optional argument of \ics{printglossary} (or
+\ics{printacronym}). Alternatively consider using the
+\sty{glossaries-extra} package's \pkgoptfmt{abbreviations}
+option instead.
+\end{important}
+
+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 abbreviations. 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}. You can specify a
+different glossary using the \gloskey{type} key within the optional
+argument. The \cs{newacronym} command also uses the \gloskey{long},
+\gloskey{longplural}, \gloskey{short} and \gloskey{shortplural} keys
+in \cs{newglossaryentry} to store the long and abbreviated forms and
+their plurals.
+
+Note that the same restrictions on the entry \meta{label}
+in \ics{newglossaryentry} also apply to \cs{newacronym}
+(see \sectionref{sec:newglosentry}).
+
+\begin{important}
+If you haven't identified the specified glossary type as a list of
+acronyms (via the package option
+\pkgopt{acronymlists} or the command \ics{DeclareAcronymList},
+see \sectionref{sec:pkgopts-acronym}) \cs{newacronym} will add it to
+the list and \emph{reset the display style} for that glossary via
+\ics{defglsentryfmt}. If you have a mixture of acronyms and regular
+entries within the same glossary, care is needed if you want to
+change the display style: you must first identify that glossary as a
+list of acronyms and then use \ics{defglsentryfmt} (not redefine
+\ics{glsentryfmt}) before defining your entries.
+\end{important}
+
+The optional argument \marg{key-val list} allows you to specify
+additional information. Any key that can be used in the second
+argument of \ics{newglossaryentry} can also be used here in \meta{key-val
+list}.
+For example, \gloskey{description} (when used with one of the styles that
+require a description, described in
+\sectionref{sec:setacronymstyle}) 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). If you want to use
+the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend
+you use \ics{setacronymstyle} to set the display style rather than
+using one of the pre-version 4.02 acronym styles.
+
+As with \gloskey{plural} and \gloskey{firstplural}, if
+\gloskey{longplural} is missing, it's obtained by appended
+\ics{glspluralsuffix} to the singular form. The short plural
+\gloskey{shortplural} is obtained (is not explicitly set) by appending
+\ics{glsacrpluralsuffix} to the short form. These commands may be
+changed by the associated language files, but they can't be added to
+the usual caption hooks as there's no guarantee when they'll be
+expanded (as \hyperref[pluralsuffix]{discussed earlier}).
+A different approach is used by \styfmt{glossaries-extra}, which has
+category attributes to determine whether or not to append a suffix
+when forming the default value of \gloskey{shortplural}.
+
+Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
+commands like \ics{gls} and \ics{glsreset} as with any other
+glossary entry.
+
+\begin{important}
+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}
+
+\begin{example}{Defining an Abbreviation}{ex:newacronym}
+The following defines the abbreviation 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 one
+of the smallcaps acronym styles, described in
+\sectionref{sec:setacronymstyle}, 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.
+\end{example}
+
+\begin{important}
+Avoid nested definitions.
+\end{important}
+
+Recall from the warning in
+\sectionref{sec:newglosentry} that you should avoid using
+the \glslike\ and \glstextlike\ commands within the value of
+keys like \gloskey{text} and \gloskey{first} due to complications
+arising from nested links. The same applies to abbreviations
+defined using \cs{newacronym}.
+
+For example, suppose you have defined:
+\begin{verbatim}
+\newacronym{ssi}{SSI}{server side includes}
+\newacronym{html}{HTML}{hypertext markup language}
+\end{verbatim}
+you may be tempted to do:
+\begin{verbatim}
+\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
+\end{verbatim}
+\textbf{Don't!} This will break the case-changing commands, such
+as \ics{Gls}, it will cause inconsistencies on \firstuse, and,
+if hyperlinks are enabled, will cause nested hyperlinks. It will
+also confuse the commands used by the entry formatting (such as
+\ics{glslabel}).
+
+Instead, consider doing:
+\begin{verbatim}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}{SSI enabled HTML}
+\end{verbatim}
+or
+\begin{verbatim}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}
+ {server side includes enabled hypertext markup language}
+\end{verbatim}
+Similarly for the \glstextlike\ commands.
+
+Other approaches are available with \sty{glossaries-extra}.
+See the section \qt{Nested Links} in the \styfmt{glossaries-extra}
+user manual.
+
+\begin{important}
+The commands described below are similar to the \glstextlike\
+commands in that they don't modify the \firstuseflag.
+However, their display is governed by \ics{defentryfmt} with
+\ics{glscustomtext} set as appropriate. All caveats that apply to
+the \glstextlike\ commands also apply to the following commands.
+(Including the warning immediately above this box.)
+\end{important}
+
+The optional arguments are the same as those for the \glstextlike\
+commands, and there are similar star and plus variants that switch
+off or on the hyperlinks. As with the \glstextlike\ commands, the
+\gls{linktext} is placed in the argument of \ics{glstextformat}.
+
+\begin{definition}[\DescribeMacro{\acrshort}]
+\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This sets the \gls{linktext} to the short form (within the argument
+of \ics{acronymfont}) for the entry given by \meta{label}. The short
+form is as supplied by the \gloskey{short} key, which
+\ics{newacronym} implicitly sets.
+
+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}
+There are also plural versions:
+\begin{definition}[\DescribeMacro\acrshortpl]
+\cs{acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrshortpl]
+\cs{Acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRshortpl]
+\cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+The short plural form is as supplied
+by the \gloskey{shortplural} key, which \ics{newacronym} implicitly sets.
+
+\begin{definition}[\DescribeMacro{\acrlong}]
+\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This sets the \gls{linktext} to the long form for the entry given by
+\meta{label}. The long form is as supplied
+by the \gloskey{long} key, which \ics{newacronym} implicitly sets.
+
+There are also analogous upper case variants:
+\begin{definition}[\DescribeMacro{\Acrlong}]
+\cs{Acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRlong}]
+\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+Again there are also plural versions:
+\begin{definition}[\DescribeMacro{\acrlongpl}]
+\cs{acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Acrlongpl}]
+\cs{Acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRlongpl}]
+\cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+The long plural form is as supplied by the \gloskey{longplural} key,
+which \ics{newacronym} implicitly sets.
+
+The commands below display the full form of the acronym, but note
+that this isn't necessarily the same as the form used on \firstuse.
+These full-form commands are shortcuts that use the above commands,
+rather than creating the \gls{linktext} from the complete full form.
+These full-form commands have star and plus variants and optional
+arguments that are passed to the above commands.
+
+\begin{definition}[\DescribeMacro{\acrfull}]
+\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is a shortcut for
+\begin{definition}[\DescribeMacro{\acrfullfmt}]
+\cs{acrfullfmt}\marg{options}\marg{label}\marg{insert}
+\end{definition}
+which by default does
+\begin{alltt}
+\cs{acrfullformat}
+ \{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}\}
+ \{\cs{acrshort}\oarg{options}\marg{label}\}
+\end{alltt}
+where
+\begin{definition}[\DescribeMacro\acrfullformat]
+\cs{acrfullformat}\marg{long}\marg{short}
+\end{definition}
+by default does \meta{long} (\meta{short}). This command is now
+deprecated for new acronym styles but is used by the default for
+backward compatibility if \cs{setacronymstyle}
+(\sectionref{sec:setacronymstyle}) hasn't been used. (For further
+details of these format commands see \ifpdf
+section~\ref*{sec:code:acronym} in \fi the documented code,
+\texttt{glossaries-code.pdf}.)
+
+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}
+and plural versions:
+\begin{definition}[\DescribeMacro\acrfullpl]
+\cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrfullpl]
+\cs{Acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRfullpl]
+\cs{ACRfullpl}\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 \pkgoptfmt{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}).
+
+\begin{important}
+The commands that convert the first letter to upper case come with
+the same caveats as those for analogous commands like
+\ics{Glsentrytext} (non-expandable, can't be used in PDF bookmarks,
+care needs to be taken if the first letter is an accented character
+etc). See \sectionref{sec:glsnolink}.
+\end{important}
+
+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 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}
+These again use \ics{acrfullformat} by default, but
+the new styles described in the section below use different
+formatting commands.
+
+\section{Changing the Abbreviation Style}
+\label{sec:setacronymstyle}
+
+It may be that the default style doesn't suit your requirements in
+which case you can switch to another style using
+\begin{definition}[\DescribeMacro{\setacronymstyle}]
+\cs{setacronymstyle}\marg{style name}
+\end{definition}
+where \meta{style name} is the name of the required style.
+
+\begin{important}
+You must use \cs{setacronymstyle} \emph{before} you define the
+acronyms with \cs{newacronym}.
+\end{important}
+
+For example:
+\begin{verbatim}
+\usepackage[acronym]{glossaries}
+
+\makeglossaries
+
+\setacronymstyle{long-sc-short}
+
+\newacronym{html}{html}{hypertext markup language}
+\newacronym{xml}{xml}{extensible markup language}
+\end{verbatim}
+Unpredictable results can occur if you try to use multiple styles.
+
+\begin{important}
+If you need multiple abbreviation styles, then try
+using the \gls{glossaries-extra} package, which has better
+abbreviation management.
+\end{important}
+
+Note that unlike the default behaviour of \cs{newacronym}, the
+styles used via \cs{setacronymstyle} don't use the \gloskey{first}
+or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to
+set a~custom format that uses the \gloskey{long} and \gloskey{short}
+keys (or their plural equivalents). This means that these styles
+cope better with plurals that aren't formed by simply appending the
+singular form with the letter \qt{s}. In fact, most of the predefined
+styles use \ics{glsgenacfmt} and modify the definitions of commands
+like \ics{genacrfullformat}.
+
+Note that when you use \cs{setacronymstyle} the \gloskey{name} key
+is set to
+\begin{definition}[\DescribeMacro{\acronymentry}]
+\cs{acronymentry}\marg{label}
+\end{definition}
+and the \gloskey{sort} key is set to
+\begin{definition}[\DescribeMacro{\acronymsort}]
+\cs{acronymsort}\marg{short}\marg{long}
+\end{definition}
+These commands are redefined by the acronym styles. However, you can
+redefine them again after the style has been set but before you use
+\cs{newacronym}. Protected expansion is performed on \cs{acronymsort}
+when the entry is defined.
+
+\subsection{Predefined Acronym Styles}
+\label{sec:predefinedacrstyles}
+
+The \styfmt{glossaries} package provides a~number of predefined
+styles. These styles apply
+\begin{definition}[\DescribeMacro{\firstacronymfont}]
+\cs{firstacronymfont}\marg{text}
+\end{definition}
+to the short form on first use and
+\begin{definition}[\DescribeMacro{\acronymfont}]
+\cs{acronymfont}\marg{text}
+\end{definition}
+on subsequent use. The styles modify the definition of
+\cs{acronymfont} as required, but \ics{firstacronymfont} is only set
+once by the package when it's loaded. By default
+\ics{firstacronymfont}\marg{text} is the same as
+\ics{acronymfont}\marg{text}.
+If you want the short form displayed differently on first use, you
+can redefine \ics{firstacronymfont} independently of the acronym
+style.
+
+The predefined styles that contain \texttt{sc} in their name (for
+example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to use
+\ics{textsc}, which means that the short form needs to be specified
+in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces
+\textsc{abc} but \verb|\textsc{ABC}| produces \textsc{ABC}.\fi
+
+\hypertarget{boldsc}{}%
+\begin{important}%
+Some fonts don't support bold smallcaps, so you may need to redefine
+\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to
+medium weight if you are using a glossary style that displays entry
+names in bold and you have chosen an acronym style that uses
+\ics{textsc}.
+\end{important}
+
+The predefined styles that contain \texttt{sm} in their name
+(for example \acrstyle{long-sm-short}) redefine \cs{acronymfont} to
+use \ics{textsmaller}.
+
+\hypertarget{smaller}{}%
+\begin{important}
+Note that the \styfmt{glossaries} package doesn't define or load any package that
+defines \ics{textsmaller}. If you use one of the acronym styles that
+set \ics{acronymfont} to \cs{textsmaller} you must
+explicitly load the \sty{relsize} package or otherwise define
+\cs{textsmaller}.
+\end{important}
+
+The remaining predefined styles redefine \cs{acronymfont}\marg{text}
+to simply do its argument \meta{text}.
+
+\begin{important}
+In most cases, the predefined styles adjust \ics{acrfull} and
+\ics{glsentryfull} (and their plural and upper case variants) to
+reflect the style. The only exceptions to this are the
+\acrstyle{dua} and \acrstyle{footnote} styles (and their variants).
+\end{important}
+
+The following styles are supplied by the \styfmt{glossaries}
+package:
+\begin{itemize}
+\item \acrstyle{long-short}, \acrstyle{long-sc-short},
+\acrstyle{long-sm-short}, \acrstyle{long-sp-short}:
+
+With these three styles, acronyms are displayed in the form
+\begin{definition}
+\meta{long} (\ics{firstacronymfont}\marg{short})
+\end{definition}
+on first use and
+\begin{definition}
+\ics{acronymfont}\marg{short}
+\end{definition}
+on subsequent use.
+They also set \cs{acronymsort}\marg{short}\marg{long} to just
+\meta{short}. This means that the acronyms are sorted according to
+their short form. In addition, \cs{acronymentry}\marg{label} is set
+to just the short form (enclosed in \cs{acronymfont}) and the
+\gloskey{description} key is set to the long form.
+
+The \acrstyle{long-sp-short} style was introduced in version~4.16
+and uses
+\begin{definition}[\DescribeMacro\glsacspace]
+\cs{glsacspace}\marg{label}
+\end{definition}
+for the space between the long and short forms. This defaults to
+a~non-breakable space (\verb|~|) if
+(\cs{acronymfont}\marg{short}) is less than 3em, otherwise it uses
+a~normal space. This may be redefined as required. For example, to
+always use a~non-breakable space:
+\begin{verbatim}
+\renewcommand*{\glsacspace}[1]{~}
+\end{verbatim}
+
+\item \acrstyle{short-long}, \acrstyle{sc-short-long},
+\acrstyle{sm-short-long}:
+
+These three styles are analogous to the above three styles, except
+the display order is swapped to
+\begin{definition}
+\ics{firstacronymfont}\marg{short} (\meta{long})
+\end{definition}
+on first use.
+
+Note, however, that \ics{acronymsort} and \ics{acronymentry} are the
+same as for the \meta{long} (\meta{short}) styles above, so the
+acronyms are still sorted according to the short form.
+
+\item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc},
+\acrstyle{long-sm-short-desc}, \acrstyle{long-sp-short-desc}:
+
+These are like the \acrstyle{long-short}, \acrstyle{long-sc-short},
+\acrstyle{long-sm-short} and \acrstyle{long-sp-short} styles described above, except that the
+\gloskey{description} key must be supplied in the optional argument
+of \ics{newacronym}. They also redefine \ics{acronymentry} to
+\marg{long} (\cs{acronymfont}\marg{short}) and redefine
+\ics{acronymsort}\marg{short}\marg{long} to just \meta{long}.
+This means that the acronyms are sorted according to the long form,
+and in the list of acronyms the name field has the long form
+followed by the short form in parentheses. I~recommend you use
+a~glossary style such as \glostyle{altlist} with these acronym
+styles to allow for the long name field.
+
+\item \acrstyle{short-long-desc}, \acrstyle{sc-short-long-desc},
+\acrstyle{sm-short-long-desc}:
+
+These styles are analogous to the above three styles, but the first
+use display style is:
+\begin{definition}
+\cs{firstacronymfont}\marg{short} (\meta{long})
+\end{definition}
+The definitions of \cs{acronymsort} and \cs{acronymentry} are the
+same as those for \acrstyle{long-short-desc} etc.
+
+\item \acrstyle{dua}, \acrstyle{dua-desc}:
+
+With these styles, the \glslike\ commands always display the long form
+regardless of whether the entry has been used or not. However, \ics{acrfull}
+and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case
+of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to
+the short form and the description is set to the long form. In the
+case of \acrstyle{dua-desc}, the \gloskey{name} and \gloskey{sort}
+keys are set to the long form and the description is supplied in the
+optional argument of \ics{newacronym}.
+
+\item \acrstyle{footnote}, \acrstyle{footnote-sc},
+\acrstyle{footnote-sm}:
+
+With these three styles, on first use the \glslike\ commands display:
+\begin{definition}
+\cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long}
+\end{definition}
+However, \ics{acrfull} and \ics{glsentryfull} are set to
+\cs{acronymfont}\marg{short} (\meta{long}). On subsequent use the display is:
+\begin{definition}
+\cs{acronymfont}\marg{short}
+\end{definition}
+The \gloskey{sort} and \gloskey{name} keys are set to
+the short form, and the \gloskey{description} is set to the long
+form.
+
+\begin{important}
+In order to avoid nested hyperlinks on \firstuse\ the footnote
+styles automatically implement \pkgopt[false]{hyperfirst} for the
+acronym lists.
+\end{important}
+
+\item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc},
+\acrstyle{footnote-sm-desc}:
+
+These three styles are similar to the previous three styles, but the
+description has to be supplied in the optional argument of
+\ics{newacronym}. The \gloskey{name} key is set to the long form
+followed by the short form in parentheses and the \gloskey{sort} key
+is set to the long form. This means that the acronyms will be sorted
+according to the long form. In addition, since the \gloskey{name}
+will typically be quite wide it's best to choose a glossary style
+that can accommodate this, such as \glostyle{altlist}.
+
+\end{itemize}
+
+\begin{example}{Adapting a Predefined Acronym Style}{ex:acrstyle}
+Suppose I~want to use the \acrstyle{footnote-sc-desc} style, but
+I~want the \gloskey{name} key set to the short form followed by the
+long form in parentheses and the \gloskey{sort} key set to the short
+form. Then I need to specify the \acrstyle{footnote-sc-desc} style:
+\begin{verbatim}
+\setacronymstyle{footnote-sc-desc}
+\end{verbatim}
+and then redefine \ics{acronymsort} and \ics{acronymentry}:
+\begin{verbatim}
+\renewcommand*{\acronymsort}[2]{#1}% sort by short form
+\renewcommand*{\acronymentry}[1]{%
+ \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}%
+\end{verbatim}
+(I've used \cs{space} for extra clarity, but you can just use an
+actual space instead.)
+
+Since the default Computer Modern fonts don't support bold
+smallcaps, I'm also going to redefine \ics{acronymfont} so that it
+always switches to medium weight to ensure the smallcaps setting is
+used:
+\begin{verbatim}
+\renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}}
+\end{verbatim}
+This isn't necessary if you use a font that supports bold smallcaps.
+
+The sample file \samplefile{FnAcrDesc} illustrates this
+example.
+\end{example}
+
+\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 using:
+\begin{definition}[\DescribeMacro{\newacronymstyle}]
+\cs{newacronymstyle}\marg{style name}\marg{display}\marg{definitions}
+\end{definition}
+where \meta{style name} is the name of the new style (avoid active
+characters). The second argument, \meta{display}, is equivalent to
+the mandatory argument of \ics{defglsentryfmt}. You can simply use
+\ics{glsgenacfmt} or you can customize the display using commands
+like \ics{ifglsused}, \ics{glsifplural} and \ics{glscapscase}.
+(See \sectionref{sec:glsdisplay} for further details.)
+If the style is likely to be used with a mixed glossary (that is entries in
+that glossary are defined both with \ics{newacronym} and
+\ics{newglossaryentry}) then you can test if the entry is an acronym
+and use \ics{glsgenacfmt} if it is or \ics{glsgenentryfmt} if it
+isn't. For example, the \acrstyle{long-short} style sets
+\meta{display} as
+\begin{verbatim}
+\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+\end{verbatim}
+(You can use \ics{ifglshasshort} instead of \ics{ifglshaslong} to
+test if the entry is an acronym if you prefer.)
+
+The third argument, \meta{definitions}, can be used to redefine the
+commands that affect the display style, such as \ics{acronymfont}
+or, if \meta{display} uses \cs{glsgenacfmt}, \ics{genacrfullformat}
+and its variants.
+
+Note that \ics{setacronymstyle} redefines \ics{glsentryfull} and
+\ics{acrfullfmt} to use \ics{genacrfullformat} (and similarly for
+the plural and upper case variants). If this isn't appropriate for the
+style (as in the case of styles like \acrstyle{footnote} and
+\acrstyle{dua}) \cs{newacronymstyle} should redefine these commands
+within \meta{definitions}.
+
+
+Within \cs{newacronymstyle}'s \meta{definitions} argument you
+can also redefine
+\begin{definition}[\DescribeMacro{\GenericAcronymFields}]
+\cs{GenericAcronymFields}
+\end{definition}
+This is a list of additional fields to be set in \ics{newacronym}.
+You can use the following token registers to access the entry label,
+long form and short form: \DescribeMacro{\glslabeltok}\cs{glslabeltok},
+\DescribeMacro{\glslongtok}\cs{glslongtok} and
+\DescribeMacro{\glsshorttok}\cs{glsshorttok}. As with all \TeX\
+registers, you can access their values by preceding the register
+with \ics{the}. For example, the \acrstyle{long-short} style does:
+\begin{verbatim}
+\renewcommand*{\GenericAcronymFields}{%
+ description={\the\glslongtok}}%
+\end{verbatim}
+which sets the \gloskey{description} field to the long form of the
+acronym whereas the \acrstyle{long-short-desc} style does:
+\begin{verbatim}
+\renewcommand*{\GenericAcronymFields}{}%
+\end{verbatim}
+since the description needs to be specified by the user.
+
+It may be that you want to define a new acronym style that's based
+on an existing style. Within \meta{display} you can use
+\begin{definition}[\DescribeMacro\GlsUseAcrEntryDispStyle]
+\cs{GlsUseAcrEntryDispStyle}\marg{style name}
+\end{definition}
+to use the \meta{display} definition from the style given by
+\meta{style name}. Within \meta{definitions} you can use
+\begin{definition}[\DescribeMacro{\GlsUseAcrStyleDefs}]
+\cs{GlsUseAcrStyleDefs}\marg{style name}
+\end{definition}
+to use the \meta{definitions} from the style given by \meta{style
+name}. For example, the \acrstyle{long-sc-short} acronym style is
+based on the \acrstyle{long-short} style with minor
+modifications (remember to use \verb|##| instead of \verb|#| within
+\meta{definitions}):
+\begin{verbatim}
+\newacronymstyle{long-sc-short}%
+{% use the same display as "long-short"
+ \GlsUseAcrEntryDispStyle{long-short}%
+}%
+{% use the same definitions as "long-short"
+ \GlsUseAcrStyleDefs{long-short}%
+ % Minor modifications:
+ \renewcommand{\acronymfont}[1]{\textsc{##1}}%
+ \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+}
+\end{verbatim}
+(\DescribeMacro{\glstextup}\cs{glstextup} is used to cancel the effect
+of \ics{textsc}. This defaults to \ics{textulc}, if defined,
+otherwise \ics{textup}. For example, the plural of \textsc{svm}
+should be rendered as \textsc{svm}s rather than \textsc{svms}.)
+
+\begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle}
+Suppose I want my acronym on \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}
+
+Let's suppose it's possible that I may have a mixed glossary. I can
+check this in the second argument of \ics{newacronymstyle} using:
+\begin{verbatim}
+\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+\end{verbatim}
+This will use \ics{glsgenentryfmt} if the entry isn't an acronym,
+otherwise it will use \ics{glsgenacfmt}. The third argument
+(\meta{definitions}) of
+\ics{newacronymstyle} needs to redefine \ics{genacrfullformat} etc
+so that the \firstuse\ displays the short form in the text with the
+long form in a footnote followed by the description. This is done as
+follows (remember to use \verb|##| instead of \verb|#|):
+\begin{verbatim}
+ % No case change, singular first use:
+ \renewcommand*{\genacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshort{##1}}##2%
+ \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+ }%
+ % First letter upper case, singular first use:
+ \renewcommand*{\Genacrfullformat}[2]{%
+ \firstacronymfont{\Glsentryshort{##1}}##2%
+ \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+ }%
+ % No case change, plural first use:
+ \renewcommand*{\genplacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshortpl{##1}}##2%
+ \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+ }%
+ % First letter upper case, plural first use:
+ \renewcommand*{\Genplacrfullformat}[2]{%
+ \firstacronymfont{\Glsentryshortpl{##1}}##2%
+ \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+ }%
+\end{verbatim}
+If you think it inappropriate for the short form to be capitalised
+at the start of a sentence you can change the above to:
+\begin{verbatim}
+ % No case change, singular first use:
+ \renewcommand*{\genacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshort{##1}}##2%
+ \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+ }%
+ % No case change, plural first use:
+ \renewcommand*{\genplacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshortpl{##1}}##2%
+ \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+ }%
+ \let\Genacrfullformat\genacrfullformat
+ \let\Genplacrfullformat\genplacrfullformat
+\end{verbatim}
+Another variation is to use \ics{Glsentrylong} and
+\ics{Glsentrylongpl} in the footnote instead of \ics{glsentrylong} and
+\ics{glsentrylongpl}.
+
+Now let's suppose that commands such as \ics{glsentryfull} and
+\ics{acrfull} shouldn't
+use a~footnote, but instead use the format: \meta{long}
+(\meta{short}).
+This means that the style needs to redefine \cs{glsentryfull},
+\ics{acrfullfmt} and their plural and upper case variants.
+
+First, the non-linking commands:
+\begin{verbatim}
+ \renewcommand*{\glsentryfull}[1]{%
+ \glsentrylong{##1}\space
+ (\acronymfont{\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\Glsentryfull}[1]{%
+ \Glsentrylong{##1}\space
+ (\acronymfont{\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\glsentryfullpl}[1]{%
+ \glsentrylongpl{##1}\space
+ (\acronymfont{\glsentryshortpl{##1}})%
+ }%
+ \renewcommand*{\Glsentryfullpl}[1]{%
+ \Glsentrylongpl{##1}\space
+ (\acronymfont{\glsentryshortpl{##1}})%
+ }%
+\end{verbatim}
+Now for the linking commands:
+\begin{verbatim}
+ \renewcommand*{\acrfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ \renewcommand*{\Acrfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \Glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ \renewcommand*{\ACRfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \MakeTextUppercase{%
+ \glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ }%
+ \renewcommand*{\acrfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ \renewcommand*{\Acrfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \Glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ \renewcommand*{\ACRfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \MakeTextUppercase{%
+ \glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ }%
+\end{verbatim}
+(This may cause problems with long hyperlinks, in which case adjust
+the definitions so that, for example, only the short form is inside
+the argument of \ics{glslink}.)
+
+The style also needs to redefine \ics{acronymsort} so that the
+acronyms are sorted according to the long form:
+\begin{verbatim}
+ \renewcommand*{\acronymsort}[2]{##2}%
+\end{verbatim}
+If you prefer them to be sorted according to the short form you can
+change the above to:
+\begin{verbatim}
+ \renewcommand*{\acronymsort}[2]{##1}%
+\end{verbatim}
+The acronym font needs to be set to \ics{textsc} and the plural
+suffix adjusted so that the \qt{s} suffix in the plural short form
+doesn't get converted to smallcaps:
+\begin{verbatim}
+ \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
+ \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+\end{verbatim}
+There are a number of ways of dealing with the format in the list of
+acronyms. The simplest way is to redefine \ics{acronymentry} to the
+long form followed by the upper case short form in parentheses:
+\begin{verbatim}
+ \renewcommand*{\acronymentry}[1]{%
+ \Glsentrylong{##1}\space
+ (\MakeTextUppercase{\glsentryshort{##1}})}%
+\end{verbatim}
+(I've used \ics{Glsentrylong} instead of \ics{glsentrylong} to
+capitalise the name in the glossary.)
+
+An alternative approach is to set \ics{acronymentry} to just the
+long form and redefine \ics{GenericAcronymFields} to set the
+\gloskey{symbol} key to the short form and use a glossary style that
+displays the symbol in parentheses after the \gloskey{name} (such as
+the \glostyle{tree} style) like this:
+\begin{verbatim}
+ \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}%
+ \renewcommand*{\GenericAcronymFields}{%
+ symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}%
+\end{verbatim}
+I'm going to use the first approach and set
+\ics{GenericAcronymFields} to do nothing:
+\begin{verbatim}
+ \renewcommand*{\GenericAcronymFields}{}%
+\end{verbatim}
+
+Finally, this style needs to switch off hyperlinks on first use to
+avoid nested links:
+\begin{verbatim}
+ \glshyperfirstfalse
+\end{verbatim}
+Putting this all together:
+\begin{verbatim}
+\newacronymstyle{custom-fn}% new style name
+{%
+ \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+}%
+{%
+ \renewcommand*{\GenericAcronymFields}{}%
+ \glshyperfirstfalse
+ \renewcommand*{\genacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshort{##1}}##2%
+ \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+ }%
+ \renewcommand*{\Genacrfullformat}[2]{%
+ \firstacronymfont{\Glsentryshort{##1}}##2%
+ \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+ }%
+ \renewcommand*{\genplacrfullformat}[2]{%
+ \firstacronymfont{\glsentryshortpl{##1}}##2%
+ \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+ }%
+ \renewcommand*{\Genplacrfullformat}[2]{%
+ \firstacronymfont{\Glsentryshortpl{##1}}##2%
+ \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+ }%
+ \renewcommand*{\glsentryfull}[1]{%
+ \glsentrylong{##1}\space
+ (\acronymfont{\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\Glsentryfull}[1]{%
+ \Glsentrylong{##1}\space
+ (\acronymfont{\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\glsentryfullpl}[1]{%
+ \glsentrylongpl{##1}\space
+ (\acronymfont{\glsentryshortpl{##1}})%
+ }%
+ \renewcommand*{\Glsentryfullpl}[1]{%
+ \Glsentrylongpl{##1}\space
+ (\acronymfont{\glsentryshortpl{##1}})%
+ }%
+ \renewcommand*{\acrfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ \renewcommand*{\Acrfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \Glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ \renewcommand*{\ACRfullfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \MakeTextUppercase{%
+ \glsentrylong{##2}##3\space
+ (\acronymfont{\glsentryshort{##2}})%
+ }%
+ }%
+ }%
+ \renewcommand*{\acrfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ \renewcommand*{\Acrfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \Glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ \renewcommand*{\ACRfullplfmt}[3]{%
+ \glslink[##1]{##2}{%
+ \MakeTextUppercase{%
+ \glsentrylongpl{##2}##3\space
+ (\acronymfont{\glsentryshortpl{##2}})%
+ }%
+ }%
+ }%
+ \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
+ \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+ \renewcommand*{\acronymsort}[2]{##2}%
+ \renewcommand*{\acronymentry}[1]{%
+ \Glsentrylong{##1}\space
+ (\MakeTextUppercase{\glsentryshort{##1}})}%
+}
+\end{verbatim}
+
+Now I need to specify that I want to use this new style:
+\begin{verbatim}
+\setacronymstyle{custom-fn}
+\end{verbatim}
+I also need to use a glossary style that suits this acronym style,
+for example \glostyle{altlist}:
+\begin{verbatim}
+\setglossarystyle{altlist}
+\end{verbatim}
+
+Once the acronym style has been set, 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}
+
+The sample file \samplefile{-custom-acronym} illustrates this
+example.
+\end{example}
+
+\begin{example}{Italic and Upright Abbreviations}{ex:font-abbr}
+Suppose I~want to have some abbreviations in italic and some that
+just use the surrounding font. Hard-coding this into the
+\meta{short} argument of \cs{newacronym} can cause complications.
+
+This example uses \ics{glsaddstoragekey} to add an extra field that
+can be used to store the formatting declaration (such as \cs{em}).
+\begin{verbatim}
+\glsaddstoragekey{font}{}{\entryfont}
+\end{verbatim}
+This defines a~new field/key called \texttt{font}, which defaults to
+nothing if it's not explicitly set. This also defines a command
+called \cs{entryfont} that's analogous to \cs{glsentrytext}. A~new
+style is then created to format abbreviations that access this field.
+
+There are two ways to do this. The first is to create a style that
+doesn't use \ics{glsgenacfmt} but instead provides a~modified
+version that doesn't use \cs{acronymfont}\marg{short}
+but instead uses
+\verb|{|\cs{entryfont}\verb|{\glslabel}|\meta{short}\verb|}|.
+The full format given by commands such as \cs{genacrfullformat}
+need to be similarly adjusted. For example:
+\begin{verbatim}
+ \renewcommand*{\genacrfullformat}[2]{%
+ \glsentrylong{##1}##2\space
+ ({\entryfont{##1}\glsentryshort{##1}})%
+ }%
+\end{verbatim}
+This will deal with commands like \ics{gls} but not commands like
+\ics{acrshort} which still use \ics{acronymfont}. Another approach
+is to redefine \cs{acronymfont} to look up the required font
+declaration. Since \cs{acronymfont} doesn't take the entry label as
+an argument, the following will only work if \cs{acronymfont} is
+used in a~context where the label is provided by \ics{glslabel}.
+This is true in \cs{gls}, \cs{acrshort} and \cs{acrfull}. The
+redefinition is now:
+\begin{verbatim}
+\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}%
+\end{verbatim}
+So the new style can be defined as:
+\begin{verbatim}
+\newacronymstyle{long-font-short}
+{%
+ \GlsUseAcrEntryDispStyle{long-short}%
+}
+{%
+ \GlsUseAcrStyleDefs{long-short}%
+ \renewcommand*{\genacrfullformat}[2]{%
+ \glsentrylong{##1}##2\space
+ ({\entryfont{##1}\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\Genacrfullformat}[2]{%
+ \Glsentrylong{##1}##2\space
+ ({\entryfont{##1}\glsentryshort{##1}})%
+ }%
+ \renewcommand*{\genplacrfullformat}[2]{%
+ \glsentrylongpl{##1}##2\space
+ ({\entryfont{##1}\glsentryshortpl{##1}})%
+ }%
+ \renewcommand*{\Genplacrfullformat}[2]{%
+ \Glsentrylongpl{##1}##2\space
+ ({\entryfont{##1}\glsentryshortpl{##1}})%
+ }%
+ \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}%
+ \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}%
+}
+\end{verbatim}
+Remember the style needs to be set before defining the entries:
+\begin{verbatim}
+\setacronymstyle{long-font-short}
+\end{verbatim}
+
+The complete document is contained in the sample file
+\samplefile{-font-abbr}.
+\end{example}
+
+Some writers and publishing houses have started to drop full stops
+(periods) from upper case initials but may still retain them for
+lower case abbreviations, while others may still use them for both
+upper and lower case. This can cause complications. Chapter~12 of
+\emph{The \TeX{}book} discusses the spacing between words but,
+briefly, the default behaviour of \TeX\ is to assume that an upper
+case character followed by a~full stop and space is an abbreviation,
+so the space is the default inter-word space whereas a~lower case
+character followed by a~full stop and space is a word occurring at
+the end of a~sentence. In the event that this isn't true, you need
+to make a~manual adjustment using \verb*| | (back slash space) in
+place of just a~space character for an inter-word mid-sentence space
+and use \verb|\@| before the full stop to indicate the end of the
+sentence.
+
+For example:
+\begin{verbatim}
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{verbatim}
+is typeset as
+\begin{display}
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{display}
+The spacing is more noticeable with the typewriter font:
+\begin{verbatim}
+\ttfamily
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{verbatim}
+is typeset as
+\begin{display}\ttfamily
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{display}
+The lower case letter at the end of ``B.Sc.''\ is confusing \TeX\
+into thinking that the full stop after it marks the end of the
+sentence. Whereas the upper case letter at the end of ``Ph.D.'' has
+confused \TeX\ into thinking that the following full stop is just
+part of the abbreviation. These can be corrected:
+\begin{verbatim}
+I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.)
+\end{verbatim}
+
+This situation is a bit problematic for \styfmt{glossaries}. The
+full stops can form part of the \meta{short} argument of
+\cs{newacronym} and the \verb*|B.Sc.\ | part can be dealt with by
+remembering to add \verb*|\ | (for example, \verb*|\gls{bsc}\ |)
+but the end of sentence case is more troublesome as you need to omit
+the sentence terminating full stop (to avoid two dots) which can
+make the source code look a little strange but you also need to
+adjust the space factor, which is usually done by inserting \cs{@}
+before the full stop.
+
+The next example shows one way of achieving this.
+(Note that the supplemental \gls{glossaries-extra} package provides a much
+simpler way of doing this, which you may prefer to use. See the
+\href{http://www.dickimaw-books.com/gallery/sample-initialisms.shtml}{initialisms
+example}.)
+
+\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr}
+As from version 4.16, there's now a hook (\ics{glspostlinkhook})
+that's called at the very end of the \glslike\ and \glstextlike\
+commands. This can be redefined to check if the following character
+is a full stop. The \sty{amsgen} package (which is automatically
+loaded by \styfmt{glossaries}) provides an internal command
+called \cs{new@ifnextchar} that can be used to determine if the
+given character appears next. (For more information see the
+\sty{amsgen} documentation.)
+
+It's possible that I~may also want acronyms or contractions in my
+document, so I~need some way to differentiate between them.
+Here I'm going to use the same method as in
+example~\ref{ex:addstoragekey} where a~new field is defined
+to indicate the type of abbreviation:
+\begin{verbatim}
+\glsaddstoragekey{abbrtype}{word}{\abbrtype}
+
+\newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]}
+\end{verbatim}
+Now I just use \ics{newacronym} for the acronyms, for example,
+\begin{verbatim}
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+\end{verbatim}
+and my new command \cs{newabbr} for initials, for example,
+\begin{verbatim}
+\newabbr{eg}{e.g.}{exempli gratia}
+\newabbr{ie}{i.e.}{id est}
+\newabbr{bsc}{B.Sc.}{Bachelor of Science}
+\newabbr{ba}{B.A.}{Bachelor of Arts}
+\newabbr{agm}{A.G.M.}{annual general meeting}
+\end{verbatim}
+Within \cs{glspostlinkhook} the entry's label can be accessed using
+\ics{glslabel} and \ics{ifglsfieldeq} can be used to determine if
+the current entry has the new \texttt{abbrtype} field set to
+\qt{initials}. If it doesn't, then nothing needs to happen, but if
+it does, a~check is performed to see if the next character is a~full
+stop. If it is, this signals the end of a~sentence otherwise it's
+mid-sentence.
+
+Remember that internal commands within the document file (rather
+than in a~class or package) need to be placed between
+\ics{makeatletter} and \ics{makeatother}:
+\begin{verbatim}
+\makeatletter
+\renewcommand{\glspostlinkhook}{%
+ \ifglsfieldeq{\glslabel}{abbrtype}{initials}%
+ {\new@ifnextchar.\doendsentence\doendword}
+ {}%
+}
+\makeatother
+\end{verbatim}
+In the event that a full stop is found \cs{doendsentence} is
+performed but it will be followed by the full stop, which needs to
+be discarded. Otherwise \cs{doendword} will be done but it won't be
+followed by a full stop so there's nothing to discard. The
+definitions for these commands are:
+\begin{verbatim}
+\newcommand{\doendsentence}[1]{\spacefactor=10000{}}
+\newcommand{\doendword}{\spacefactor=1000{}}
+\end{verbatim}
+Now, I can just do \verb|\gls{bsc}| mid-sentence and
+\verb|\gls{phd}.| at the end of the sentence. The terminating full
+stop will be discarded in the latter case, but it won't be discarded
+in, say, \verb|\gls{laser}.| as that doesn't have the
+\texttt{abbrtype} field set to \qt{initials}.
+
+This also works on first use when the style is set to one of the
+\meta{long} (\meta{short}) styles but it will fail with the
+\meta{short} (\meta{long}) styles as in this case the terminating
+full stop shouldn't be discarded. Since \ics{glspostlinkhook} is
+used after the \firstuseflag\ has been unset for the entry, this
+can't be fixed by simply checking with \ics{ifglsused}. One possible
+solution to this is to redefine \ics{glslinkpostsetkeys} to check
+for the \firstuseflag\ and define a macro that can then be used in
+\ics{glspostlinkhook}.
+
+The other thing to consider is what to do with plurals. One
+possibility is to check for plural use within \cs{doendsentence}
+(using \ics{glsifplural}) and put the full stop back if the plural
+has been used.
+
+The complete document is contained in the sample file
+\samplefile{-dot-abbr}.
+\end{example}
+
+\section{Displaying the List of Acronyms}
+\label{sec:disploa}
+
+The list of acronyms is just like any other type of glossary and can
+be displayed on its own using:
+\begin{description}
+\itempar{\opt1:}
+\begin{alltt}
+\ics{printnoidxglossary}[type=\ics{acronymtype}]
+\end{alltt}
+
+\itempar{\optsand23:}
+\begin{alltt}
+\ics{printglossary}[type=\ics{acronymtype}]
+\end{alltt}
+
+(If you use the
+\pkgopt{acronym} package option you can also use
+\begin{alltt}
+\ics{printacronyms}\oarg{options}
+\end{alltt}
+as a synonym for
+\begin{alltt}
+\ics{printglossary}[type=\ics{acronymtype},\meta{options}]
+\end{alltt}
+See \sectionref{sec:pkgopts-acronym}.)
+
+\end{description}
+Alternatively the list of acronyms can be displayed with all the other
+glossaries using:
+\begin{description}
+\item[\opt1:] \ics{printnoidxglossaries}
+
+\item[\optsand23:] \ics{printglossaries}
+\end{description}
+
+However, care must be taken to choose a glossary style that's
+appropriate to your acronym style.
+Alternatively, you can define your own custom style (see
+\sectionref{sec:newglossarystyle} for further details).
+
+\section{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:
+\begin{display}
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
+\end{display}
+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, but be aware that there are some issues with
+using \sty{xspace}.\footnotemark
+\end{important}
+\footnotetext{See David Carlisle's explanation in
+\url{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}}
+
+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}
+
+\chapter{Unsetting and Resetting Entry Flags}
+\label{sec:glsunset}
+
+When using the \glslike\ commands 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
+(except for the ignored ones).
+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.
+
+\begin{important}
+Be careful when using \glslike\ commands within an
+environment or command argument that gets processed multiple times
+as it can cause unwanted side-effects when the first use displayed
+text is different from subsequent use.
+\end{important}
+
+For example, the \env{frame} environment in \cls{beamer} processes
+its argument for each overlay. This means that the \firstuseflag\
+will be unset on the first overlay and subsequent overlays will use
+the non-first use form.
+
+Consider the following example:
+\begin{verbatim}
+\documentclass{beamer}
+
+\usepackage{glossaries}
+
+\newacronym{svm}{SVM}{support vector machine}
+
+\begin{document}
+
+\begin{frame}
+ \frametitle{Frame 1}
+
+ \begin{itemize}
+ \item<+-> \gls{svm}
+ \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
+
+\end{document}
+\end{verbatim}
+
+On the first overlay, \verb|\gls{svm}| produces \qt{support vector
+machine (SVM)} and then unsets the \firstuseflag. When the second
+overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which
+is unlikely to be the desired effect. I~don't know anyway around
+this and I can only offer two suggestions.
+
+Firstly, unset all acronyms at the start of the document and
+explicitly use \ics{acrfull} when you want the full version to be
+displayed:
+\begin{verbatim}
+\documentclass{beamer}
+
+\usepackage{glossaries}
+
+\newacronym{svm}{SVM}{support vector machine}
+
+\glsunsetall
+
+\begin{document}
+\begin{frame}
+ \frametitle{Frame 1}
+
+ \begin{itemize}
+ \item<+-> \acrfull{svm}
+ \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
+\end{document}
+\end{verbatim}
+
+Secondly, explicitly reset each acronym on first use:
+\begin{verbatim}
+\begin{frame}
+ \frametitle{Frame 1}
+
+ \begin{itemize}
+ \item<+-> \glsreset{svm}\gls{svm}
+ \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
+\end{verbatim}
+These are non-optimal, but the \cls{beamer} class is too complex for
+me to provide a programmatic solution. Other potentially problematic
+environments are some \env{tabular}-like environments (but not
+\env{tabular} itself) that process the contents in order to work out
+the column widths and then reprocess the contents to do the actual
+typesetting.
+
+The \sty{amsmath} environments, such as \env{align}, also process
+their contents multiple times, but the \styfmt{glossaries} package now
+checks for this. For \sty{tabularx}, you need to explicitly patch it
+by placing \cs{glspatchtabularx} in the preamble (or anywhere
+before the problematic use of \envfmt{tabularx}).
+
+\section{Counting the Number of Times an Entry has been Used (First Use
+Flag Unset)}
+\label{sec:enableentrycount}
+
+As from version 4.14, it's now possible to keep track of how many
+times an entry is used. That is, how many times the \firstuseflag\
+is unset. Note that the supplemental \gls{glossaries-extra} package improves
+this function and also provides per-unit counting, which isn't
+available with the \styfmt{glossaries} package.
+
+\begin{important}
+This function is disabled by default as it adds extra
+overhead to the document build time and also switches
+\ics{newglossaryentry} (and therefore \ics{newacronym}) into
+a~preamble-only command.
+\end{important}
+
+To enable this function, use
+\begin{definition}[\DescribeMacro\glsenableentrycount]
+\cs{glsenableentrycount}
+\end{definition}
+before defining your entries. This adds two extra (internal) fields
+to entries: \texttt{currcount} and \texttt{prevcount}.
+
+The \texttt{currcount} field keeps track of how many times
+\cs{glsunset} is used within the document. A~local unset (using
+\cs{glslocalunset}) performs a~local rather than global increment to
+\texttt{currcount}. Remember that not all commands use
+\cs{glsunset}. Only the \glslike\ commands do this. The reset
+commands \cs{glsreset} and \cs{glslocalreset} reset this field back
+to zero (where \cs{glslocalreset} performs a~local change).
+
+The \texttt{prevcount} field stores the final value of the
+\texttt{currcount} field \emph{from the previous run}. This value is
+read from the \texttt{.aux} file at the beginning of the
+\env{document} environment.
+
+You can access these fields using
+\begin{definition}[\DescribeMacro\glsentrycurrcount]
+\cs{glsentrycurrcount}\marg{label}
+\end{definition}
+for the \texttt{currcount} field, and
+\begin{definition}[\DescribeMacro\glsentryprevcount]
+\cs{glsentryprevcount}\marg{label}
+\end{definition}
+for the \texttt{prevcount} field. \textbf{These commands are
+only defined if you have used \cs{glsenableentrycount}.}
+
+For example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries
+
+\glsenableentrycount
+
+\newglossaryentry{apple}{name=apple,description={a fruit}}
+
+\begin{document}
+Total usage on previous run: \glsentryprevcount{apple}.
+
+\gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}.
+\glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}.
+
+Number of times apple has been used: \glsentrycurrcount{apple}.
+\end{document}
+\end{verbatim}
+On the first \LaTeX\ run, \verb|\glsentryprevcount{apple}|
+produces~0. At the end of the document,
+\verb|\glsentrycurrcount{apple}| produces~4. This is because
+the only commands that have incremented the entry count are those
+that use \cs{glsunset}. That is: \cs{gls}, \cs{glsdisp} and
+\cs{Gls}. The other commands used in the above example, \cs{glsadd},
+\cs{glsentrytext} and \cs{glslink}, don't use \cs{glsunset} so they
+don't increment the entry count. On the \emph{next} \LaTeX\ run,
+\verb|\glsentryprevcount{apple}| now produces~4 as that was the
+value of the \texttt{currcount} field for the \texttt{apple} entry
+at the end of the document on the previous run.
+
+When you enable the entry count using \cs{glsenableentrycount}, you
+also enable the following commands:
+\begin{definition}[\DescribeMacro\cgls]
+\cs{cgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(no case-change, singular)
+\begin{definition}[\DescribeMacro\cglspl]
+\cs{cglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(no case-change, plural)
+\begin{definition}[\DescribeMacro\cGls]
+\cs{cGls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(first letter uppercase, singular), and
+\begin{definition}[\DescribeMacro\cGlspl]
+\cs{cGlspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(first letter uppercase, plural).
+These all have plus and starred variants like the analogous
+\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl} commands.
+
+If you don't use \cs{glsenableentrycount}, these commands behave
+like \cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl},
+respectively, only there will be a warning that you haven't enabled
+entry counting. If you have enabled entry counting with
+\cs{glsenableentrycount} then these commands test if
+\cs{glsentryprevcount}\marg{label} equals~1. If it doesn't then the
+analogous \cs{gls} etc will be used. If it does, then the first optional
+argument will be ignored and
+\begin{alltt}
+\meta{cs format}\marg{label}\marg{insert}\cs{glsunset}\marg{label}
+\end{alltt}
+will be performed, where \meta{cs format} is a command that takes
+two arguments. The command used depends whether you have used
+\cs{cgls}, \cs{cglspl}, \cs{cGls} or \cs{cGlspl}.
+
+\begin{definition}[\DescribeMacro\cglsformat]
+\cs{cglsformat}\marg{label}\marg{insert}
+\end{definition}
+This command is used by \cs{cgls} and defaults to
+\begin{alltt}
+\cs{glsentrylong}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by
+\meta{label} has a~long form or
+\begin{alltt}
+\cs{glsentryfirst}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
+
+\begin{definition}[\DescribeMacro\cglsplformat]
+\cs{cglsplformat}\marg{label}\marg{insert}
+\end{definition}
+This command is used by \cs{cglspl} and defaults to
+\begin{alltt}
+\cs{glsentrylongpl}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by
+\meta{label} has a~long form or
+\begin{alltt}
+\cs{glsentryfirstplural}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
+
+\begin{definition}[\DescribeMacro\cGlsformat]
+\cs{cGlsformat}\marg{label}\marg{insert}
+\end{definition}
+This command is used by \cs{cGls} and defaults to
+\begin{alltt}
+\cs{Glsentrylong}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by \meta{label} has a~long form or
+\begin{alltt}
+\cs{Glsentryfirst}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
+
+\begin{definition}[\DescribeMacro\cGlsplformat]
+\cs{cGlsplformat}\marg{label}\marg{insert}
+\end{definition}
+This command is used by \cs{cGlspl} and defaults to
+\begin{alltt}
+\cs{Glsentrylongpl}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by \meta{label} has a~long form or
+\begin{alltt}
+\cs{Glsentryfirstplural}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
+
+This means that if the previous count for the given entry was~1, the
+entry won't be hyperlinked with the \cs{cgls}-like commands and they
+won't add a~line to the external glossary file. If you haven't used
+any of the other commands that add information to glossary file
+(such as \cs{glsadd} or the \glstextlike\ commands) then the entry
+won't appear in the glossary.
+
+Remember that since these commands use \cs{glsentryprevcount} you
+need to run \LaTeX\ twice to ensure they work correctly. The
+document build order is now (at least): \texttt{(pdf)latex},
+\texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}.
+
+\begin{example}{Don't index entries that are only used once}{sec:entrycount}
+In this example, the abbreviations that have only been used once (on the previous run)
+only have their long form shown with \cs{cgls}.
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[acronym]{glossaries}
+\makeglossaries
+
+\glsenableentrycount
+
+\setacronymstyle{long-short}
+
+\newacronym{html}{HTML}{hypertext markup language}
+\newacronym{css}{CSS}{cascading style sheets}
+\newacronym{xml}{XML}{extensible markup language}
+\newacronym{sql}{SQL}{structured query language}
+\newacronym{rdbms}{RDBMS}{relational database management system}
+\newacronym{rdsms}{RDSMS}{relational data stream management system}
+
+\begin{document}
+These entries are only used once: \cgls{sql}, \cgls{rdbms},
+\cgls{xml}. These entries are used multiple times:
+\cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css},
+\cgls{rdsms}, \cgls{rdsms}.
+
+\printglossaries
+\end{document}
+\end{verbatim}
+After a complete document build (\texttt{latex}, \texttt{latex},
+\texttt{makeglossaries}, \texttt{latex}) the list of abbrevaitions only
+includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and
+XML
+only have their long forms displayed and don't have a~hyperlink.
+\end{example}
+
+Remember that if you don't like typing \cs{cgls} you can create a
+synonym. For example
+\begin{verbatim}
+\let\ac\cgls
+\end{verbatim}
+
+\chapter{Glossary Styles}
+\label{sec:styles}
+
+Glossaries vary from lists that simply contain a symbol with a terse
+description to lists of terms or phrases with lengthy descriptions.
+Some glossaries may have terms with associated symbols. Some may
+have hierarchical entries. There is therefore no single style that
+fits every type of glossary. The \styfmt{glossaries} package comes
+with a number of pre-defined glossary styles, described in
+\sectionref{sec:predefinedstyles}. You can choose one of these that
+best suits your type of glossary or, if none of them suit your
+document, you can defined your own style (see
+\sectionref{sec:newglossarystyle}). There are some examples
+of glossary styles available at
+\url{http://www.dickimaw-books.com/gallery/#glossaries}.
+
+The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
+argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary}
+(\optsand23) or using the command:
+\begin{definition}[\DescribeMacro{\setglossarystyle}]
+\cs{setglossarystyle}\marg{style-name}
+\end{definition}
+(before the glossary is displayed).
+
+Some of the predefined 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.
+
+You can use the lorum ipsum dummy entries provided in the
+accompanying
+\texttt{example-glossaries-*.tex} files (described in
+\sectionref{sec:lipsum}) to test the different styles.
+
+\section{Predefined Styles}
+\label{sec:predefinedstyles}
+
+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}. There is a summary
+of available styles in \tableref{tab:styles}.
+You can view samples of all the predefined styles at
+\url{http://www.dickimaw-books.com/gallery/glossaries-styles/}.
+Note that \gls{glossaries-extra} provides additional styles
+in the supplementary packages \sty{glossary-bookindex} and
+\sty{glossary-longnoloc}. See the \gls{glossaries-extra} manual for
+further details.
+
+\begin{important}
+Note that the group styles (such as \glostyle{listgroup}) will
+have unexpected results if used with the \pkgopt[def]{sort}
+or \pkgopt[use]{sort} options. If you don't sort your entries
+alphabetically, it's best to set the \pkgopt{nogroupskip}
+package option to prevent odd vertical gaps appearing.
+\end{important}
+
+The group title is obtained using \cs{glsgetgrouptitle}\marg{label},
+which is described in \sectionref{sec:newglossarystyle}.
+
+\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} (\opt2) 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 *alttree* & --- & & \tick\\
+\ttfamily *tree* & --- & & \tick\\
+\ttfamily inline & 1 & \tick &
+\end{tabular}
+\par
+\end{table}
+
+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 it's better to use \ics{newline} instead of
+\verb|\\|.
+
+\begin{important}
+Remember that a cell within a tabular-like environment can't
+be broken across a page, so even if a tabular-like style, such as
+\glostyle{long}, allows multilined descriptions, you'll probably encounter
+page-breaking problems if you have entries with long descriptions.
+You may want to consider using the \glostyle{alttree} style instead.
+\end{important}
+
+Note that if you use the \gloskey[printglossary]{style} key in the
+optional argument to \ics{printnoidxglossary} (\opt1) or
+\ics{printglossary} (\optsand23), 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{setglossarystyle} will also
+override any previous style definitions, so, again
+\begin{verbatim}
+\renewcommand*{\glsgroupskip}{}
+\setglossarystyle{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{setglossarystyle}, e.g.:
+\begin{verbatim}
+\setglossarystyle{long}
+\renewcommand*{\glsgroupskip}{}
+\end{verbatim}
+As from version 3.03, you can now use the package option
+\pkgopt{nogroupskip} to suppress the gap between groups for the
+default styles instead of redefining \cs{glsgroupskip}.
+
+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.
+Note that \ics{longnewglossaryentry} puts \cs{nopostdesc} at the end
+of the description. The \sty{glossaries-extra} package provides a
+starred version that doesn't.
+
+As from version 3.03 you can now use the package option
+\pkgopt{nopostdot} to suppress this full stop. This is the better
+option if you want to use the \sty{glossaries-extra} package.
+The \sty{glossaries-extra-stylemods} package provides some
+adjustments some of to the predefined styles listed here, allowing
+for greater flexibility. See the \sty{glossaries-extra}
+documentation for further details.
+
+\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{important}
+Note that, except for the \glostyle{listdotted} style, these
+list styles are incompatible with \sty{classicthesis}. They
+may also be incompatible with other classes or packages that
+modify the \env{description} environment.
+\end{important}
+
+\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 usually 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}.
+
+The closest matching non-list style is the \glostyle{index} style.
+
+\item[listgroup] The \glostyle{listgroup} style is like
+\glostyle{list} but the glossary groups have headings
+obtained using \cs{glsgetgrouptitle}\marg{label},
+which is described in \sectionref{sec:newglossarystyle}.
+
+\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 cause a problem
+if the navigation line is too long.
+As from v4.22, if you need to adjust this, you can redefine
+\begin{definition}[\DescribeMacro\glslistnavigationitem]
+\cs{glslistnavigationitem}\marg{navigation line}
+\end{definition}
+The default definition is \cs{item}\oarg{navigation line} but may
+be redefined independently of setting the style. For example:
+\begin{verbatim}
+\renewcommand*{\glslistnavigationitem}[1]{\item \textbf{#1}}
+\end{verbatim}
+
+You may prefer to use the tree-like styles, such as
+\glostyle{treehypergroup} instead.
+
+\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.
+
+The closest matching non-list style is the \glostyle{index}
+style with the following adjustment:
+\begin{verbatim}
+\renewcommand{\glstreepredesc}{%
+ \glstreeitem\parindent\hangindent}
+\end{verbatim}
+
+
+\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.
+
+A non-list alternative is to use the \glostyle{index} style
+with
+\begin{verbatim}
+\renewcommand{\glstreepredesc}{\dotfill}
+\renewcommand{\glstreechildpredesc}{\dotfill}
+\end{verbatim}
+Note that this doesn't use \cs{glslistdottedwidth} and causes
+the description to be flush-right and will display the
+symbol, if provided. (It also doesn't suppress
+the \gls*{numberlist}, but that can be achieved with the
+\pkgopt{nonumberlist} option.)
+
+\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}. Unlike the
+\glostyle{listdotted} style, this style is incompatible with
+\sty{classicthesis}.
+\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}.
+If you want to incorporate rules from the \sty{booktabs} package,
+try the styles described in \sectionref{sec:longbooktabsstyles}.
+
+\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.
+If you want to incorporate rules from the \sty{booktabs} package,
+try the styles described in \sectionref{sec:longbooktabsstyles}.
+
+\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{Longtable Styles (\styfmt{booktabs})}
+\label{sec:longbooktabsstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-longbooktabs}.
+
+Since these styles all use the
+\env{longtable} environment, they are governed by the same
+parameters as that environment. The \sty{glossary-longbooktabs}
+package automatically loads the \sty{glossary-long}
+(\sectionref{sec:longstyles})
+and \sty{glossary-longragged} (\sectionref{sec:longraggedstyles}) packages. Note that
+these styles will only be available if you explicitly load
+\sty{glossary-longbooktabs}:
+\begin{verbatim}
+\usepackage{glossaries}
+\usepackage{glossary-longbooktabs}
+\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.
+
+These styles are similar to the
+\qt{header} styles in the \sty{glossary-long} and
+\sty{glossary-ragged} packages, but they add the rules
+provided by the \sty{booktabs} package, \ics{toprule}, \ics{midrule} and
+\ics{bottomrule}. Additionally these styles patch the
+\env{longtable} environment to check for instances of the group
+skip occurring at a page break. If you don't want this patch to
+affect any other use of \env{longtable} in your document, you can
+scope the effect by only setting the style through the
+\gloskey[printglossary]{style} key in the optional argument of
+\cs{printglossary}. (The \pkgopt{nogroupskip} package option
+is checked by these styles.)
+
+Alternatively, you can restore the original \env{longtable}
+behaviour with:
+\begin{definition}[\DescribeMacro\glsrestoreLToutput]
+\cs{glsrestoreLToutput}
+\end{definition}
+For more information about the patch, see the documented code
+(\texttt{glossaries-code.pdf}).
+
+\begin{description}
+\item[\glostyle{long-booktabs}] This style is similar to
+the \glostyle{longheader} style but adds rules above and below the
+header (\cs{toprule} and \cs{midrule}) and inserts a rule at the
+bottom of the table (\cs{bottomrule}).
+
+\item[\glostyle{long3col-booktabs}] This style is similar to
+the \glostyle{long3colheader} style but adds rules as per
+\glostyle{long-booktabs}.
+
+\item[\glostyle{long4col-booktabs}] This style is similar to
+the \glostyle{long4colheader} style but adds rules as above.
+
+\item[\glostyle{altlong4col-booktabs}] This style is similar to
+the \glostyle{altlong4colheader} style but adds rules as above.
+
+\item[\glostyle{longragged-booktabs}] This style is similar to
+the \glostyle{longraggedheader} style but adds rules as above.
+
+\item[\glostyle{longragged3col-booktabs}] This style is similar to
+the \glostyle{longragged3colheader} style but adds rules as above.
+
+\item[\glostyle{altlongragged4col-booktabs}] This style is similar to
+the \glostyle{altlongragged4colheader} style but adds rules as above.
+
+\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 the \glostyle{super3colheader} style 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 the \glostyle{super4colheader} style 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.
+
+These styles all format the entry name using:
+\begin{definition}[\DescribeMacro\glstreenamefmt]
+\cs{glstreenamefmt}\marg{name}
+\end{definition}
+This defaults to \cs{textbf}\marg{name}, but note that \meta{name}
+includes \ics{glsnamefont} so the bold setting in \cs{glstreenamefont}
+may be counteracted by another font change in \cs{glsnamefont} (or
+in \cs{acronymfont}). The tree-like styles that also display the
+header use
+\begin{definition}[\DescribeMacro\glstreegroupheaderfmt]
+\cs{glstreegroupheaderfmt}\marg{text}
+\end{definition}
+to format the heading. This defaults to
+\cs{glstreenamefmt}\marg{text}. The tree-like styles that display
+navigation links to the groups (such as \glostyle{indexhypergroup}), format
+the navigation line using
+\begin{definition}[\DescribeMacro\glstreenavigationfmt]
+\cs{glstreenavigationfmt}\marg{text}
+\end{definition}
+which defaults to \cs{glstreenamefmt}\marg{text}. Note that this is
+different from \cs{glslistnavigationitem}, provided with the styles
+such as \glostyle{listhypergroup}, as that also includes \cs{item}.
+
+With the exception of the \glostyle{alttree} style (and those
+derived from it), the space before the description for top-level
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreepredesc]
+\cs{glstreepredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+With the exception of the \glostyle{treenoname} and
+\glostyle{alttree} styles (and those derived from them), the
+space before the description for child
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreechildpredesc]
+\cs{glstreechildpredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+\begin{important}
+Most of these styles are not designed for multi-paragraph
+descriptions. (The \glostyle{tree} style isn't too bad for
+multi-paragraph top-level entry descriptions, or you can use the
+\glostyle{index} style with the adjustment shown below.)
+\end{important}
+
+\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}.
+
+Each main level item is started with
+\begin{definition}[\DescribeMacro\glstreeitem]
+\cs{glstreeitem}
+\end{definition}
+The level~1 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubitem]
+\cs{glstreesubitem}
+\end{definition}
+
+The level~2 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubsubitem]
+\cs{glstreesubsubitem}
+\end{definition}
+
+Note that the \glostyle{index} style automatically sets
+\begin{verbatim}
+\let\item\glstreeitem
+\let\subitem\glstreesubitem
+\let\subsubitem\glstreesubsubitem
+\end{verbatim}
+at the start of the glossary for backward compatibility.
+
+The \glostyle{index} style isn't suitable for multi-paragraph
+descriptions, but this limitation can be overcome by redefining
+the above commands. For example:
+\begin{verbatim}
+\renewcommand{\glstreeitem}{%
+ \parindent0pt\par\hangindent40pt
+ \everypar{\parindent50pt\hangindent40pt}}
+\end{verbatim}
+
+\item[indexgroup] The \glostyle{indexgroup} style is similar to
+the \glostyle{index} style except that each group has a heading
+obtained using \cs{glsgetgrouptitle}\marg{label},
+which is described in \sectionref{sec:newglossarystyle}.
+
+\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, but is formatted using
+\cs{glstreenavigationfmt}.
+
+\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, but is formatted using
+\cs{glstreenavigationfmt}.
+
+\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, but is formatted using
+\cs{glstreenavigationfmt}.
+
+\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.
+
+As from v4.22, the \sty{glossary-tree} package also provides
+\begin{definition}[\DescribeMacro\glsfindwidesttoplevelname]
+\cs{glsfindwidesttoplevelname}\oarg{glossary list}
+\end{definition}
+This iterates over all parentless entries in the given glossary
+lists and determines the widest entry. If the optional argument is
+omitted, all glossaries are assumed (as per \cs{forallglossaries}).
+
+For example, to have the same name width for all glossaries:
+\begin{verbatim}
+\glsfindwidesttoplevelname
+\setglossarystyle{alttree}
+\printglossaries
+\end{verbatim}
+Alternatively, to compute the widest entry for each glossary
+before it's displayed:
+\begin{verbatim}
+\renewcommand{\glossarypreamble}{%
+ \glsfindwidesttoplevelname[\currentglossary]}
+\setglossarystyle{alttree}
+\printglossaries
+\end{verbatim}
+
+\begin{important}
+These commands only affects the \glostyle{alttree} styles, including those
+listed below and the ones in the \sty{glossary-mcols} package.
+If you forget to set the widest entry name, the description will
+overwrite the name.
+\end{important}
+
+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.
+
+The name is placed inside a left-aligned \cs{makebox}. As from
+v4.19, this can now be adjusted by redefining
+\begin{definition}[\DescribeMacro\glstreenamebox]
+\cs{glstreenamebox}\marg{width}\marg{text}
+\end{definition}
+where \meta{width} is the width of the box and \meta{text} is the
+contents of the box. For example, to make the name right-aligned:
+\begin{verbatim}
+\renewcommand*{\glstreenamebox}[2]{%
+ \makebox[#1][r]{#2}%
+}
+\end{verbatim}
+
+\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}
+
+\subsection{Multicols Style}
+\label{sec:mcolstyles}
+
+The \sty{glossary-mcols} package provides tree-like styles that are
+in the \env{multicols} environment (defined by the \sty{multicol}
+package). The style names are as their analogous tree styles (as
+defined in \sectionref{sec:treestyles}) but are prefixed with
+\qt{mcol}.
+For example, the \glostyle{mcolindex} style is essentially the
+\glostyle{index} style but put in a \env{multicols} environment.
+For the complete list, see \tableref{tab:mcols}. The
+\sty{glossary-tree} package is automatically loaded by
+\sty{glossary-mcols} (even if the \pkgopt{notree} package option is
+used when loading \styfmt{glossaries}). The formatting commands
+\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
+\cs{glstreenavigationfmt} are all used by the corresponding
+\sty{glossary-mcols} styles.
+
+\begin{important}
+Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If
+you want to use any of the multicol styles in that package you need
+to load it explicitly with \cs{usepackage} and set the required glossary
+style using \ics{setglossarystyle}.
+\end{important}
+
+The default number of columns is 2, but can be changed by redefining
+\begin{definition}[\DescribeMacro{\glsmcols}]
+\cs{glsmcols}
+\end{definition}
+to the required number. For example, for a three column glossary:
+\begin{verbatim}
+\usepackage{glossary-mcols}
+\renewcommand*{\glsmcols}{3}
+\setglossarystyle{mcolindex}
+\end{verbatim}
+
+\begin{table}[htbp]
+\caption{Multicolumn Styles}
+\label{tab:mcols}
+\centering
+\begin{tabular}{ll}
+\bfseries
+\sty{glossary-mcols} Style &
+\bfseries
+Analogous Tree Style\\
+\glostyle{mcolindex} & \glostyle{index}\\
+\glostyle{mcolindexgroup} & \glostyle{indexgroup}\\
+\glostyle{mcolindexhypergroup} or \glostyle{mcolindexspannav} & \glostyle{indexhypergroup}\\
+\glostyle{mcoltree} & \glostyle{tree}\\
+\glostyle{mcoltreegroup} & \glostyle{treegroup}\\
+\glostyle{mcoltreehypergroup} or \glostyle{mcoltreespannav} & \glostyle{treehypergroup}\\
+\glostyle{mcoltreenoname} & \glostyle{treenoname}\\
+\glostyle{mcoltreenonamegroup} & \glostyle{treenonamegroup}\\
+\glostyle{mcoltreenonamehypergroup} or
+\glostyle{mcoltreenonamespannav} & \glostyle{treenonamehypergroup}\\
+\glostyle{mcolalttree} & \glostyle{alttree}\\
+\glostyle{mcolalttreegroup} & \glostyle{alttreegroup}\\
+\glostyle{mcolalttreehypergroup} or \glostyle{mcolalttreespannav} & \glostyle{alttreehypergroup}
+\end{tabular}
+\end{table}
+
+The styles with a navigation line, such as
+\glostyle{mcoltreehypergroup}, now have a variant (as from v4.22)
+with \qt{hypergroup} replaced with \qt{spannav} in the style name.
+The original \qt{hypergroup} styles place the navigation line at the
+start of the first column. The newer \qt{spannav} styles put the
+navigation line in the optional argument of the \env{multicols}
+environment so that it spans across all the columns.
+
+\subsection{In-Line Style}
+\label{sec:inline}
+
+This section covers the \sty{glossary-inline} package that supplies
+the \glostyle{inline} style. This is a style that is designed for
+in-line use (as opposed to block styles, such as lists or tables).
+This style doesn't display the \gls{numberlist}.
+
+You will most likely need to redefine \ics{glossarysection} with
+this style. For example, suppose you are required to have your
+glossaries and list of acronyms in a footnote, you can do:
+\begin{verbatim}
+ \usepackage{glossary-inline}
+
+ \renewcommand*{\glossarysection}[2][]{\textbf{#1}: }
+ \setglossarystyle{inline}
+\end{verbatim}
+
+\begin{important}
+Note that you need to include \sty{glossary-inline} with
+\cs{usepackage} as it's not automatically included by the
+\styfmt{glossaries} package and then set the style using
+\ics{setglossarystyle}.
+\end{important}
+
+Where you need to include your glossaries as a footnote you can do:
+\begin{verbatim}
+\footnote{\printglossaries}
+\end{verbatim}
+
+The \glostyle{inline} style is governed by the following:
+\begin{definition}[\DescribeMacro{\glsinlineseparator}]
+\ics{glsinlineseparator}
+\end{definition}
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used between
+main (i.e.\ level~0) entries.
+\begin{definition}[\DescribeMacro{\glsinlinesubseparator}]
+\ics{glsinlinesubseparator}
+\end{definition}
+This defaults to \qt{\texttt{\glsinlinesubseparator}} and is used between
+sub-entries.
+\begin{definition}[\DescribeMacro{\glsinlineparentchildseparator}]
+\ics{glsinlineparentchildseparator}
+\end{definition}
+This defaults to \qt{\texttt{\glsinlineparentchildseparator}} and is used between
+a parent main entry and its first sub-entry.
+\begin{definition}[\DescribeMacro{\glspostinline}]
+\ics{glspostinline}
+\end{definition}
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used at the end
+of the glossary.
+\begin{definition}[\DescribeMacro\glsinlinenameformat]
+\cs{glsinlinenameformat}\marg{label}\marg{name}
+\end{definition}
+This is used to format the entry name and defaults to
+\cs{glstarget}\marg{label}\marg{name}, where \meta{name} is provided
+in the form \cs{glossentryname}\marg{label} and \meta{label} is the
+entry's label. For example, if you want the name to appear in
+smallcaps:
+\begin{verbatim}
+\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}}
+\end{verbatim}
+Sub-entry names are formatted according to
+\begin{definition}[\DescribeMacro\glsinlinesubnameformat]
+\cs{glsinlinesubnameformat}\marg{label}\marg{name}
+\end{definition}
+This defaults to \cs{glstarget}\marg{label}\verb|{}| so the
+sub-entry name is ignored.
+
+If the description has been suppressed (according to
+\cs{ifglsdescsuppressed}) then
+\begin{definition}[\DescribeMacro\glsinlineemptydescformat]
+\cs{glsinlineemptydescformat}\marg{symbol}\marg{number list}
+\end{definition}
+(which defaults to nothing) is used,
+otherwise the description is formatted according to
+\begin{definition}[\DescribeMacro\glsinlinedescformat]
+\cs{glsinlinedescformat}\marg{description}\marg{symbol}\marg{number
+list}
+\end{definition}
+This defaults to just \cs{space}\meta{description} so the symbol and
+location list are ignored. If the description is missing (according
+to \cs{ifglshasdesc}), then \cs{glsinlineemptydescformat} is used
+instead.
+
+For example, if you want a colon between the name and the
+description:
+\begin{verbatim}
+\renewcommand*{\glsinlinedescformat}[3]{: #1}
+\end{verbatim}
+
+The sub-entry description is formatted according to:
+\begin{definition}[\DescribeMacro\glsinlinesubdescformat]
+\cs{glsinlinesubdescformat}\marg{description}\marg{symbol}\marg{number
+list}
+\end{definition}
+This defaults to just \meta{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{setglossarystyle}). 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 \meta{label} consists of a
+single non-active character or \meta{label} is equal to
+\texttt{glssymbols} or \texttt{glsnumbers} and
+\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the
+title, otherwise the title is just \meta{label}. (The \qt{symbols}
+group has the label \texttt{glssymbols}, so the command
+\ics{glssymbolsgroupname} is used, and the \qt{numbers} group has the
+label \texttt{glsnumbers}, so the command \ics{glsnumbersgrouptitle}
+is used.) If you are using \gls{xindy}, \meta{label} may be an
+active character (for example \o), in which case the title will be
+set to just \meta{label}. You can redefine \cs{glsgetgrouptitle} if
+this is unsuitable for your document.
+
+A navigation hypertarget can be created using
+\begin{definition}[\DescribeMacro{\glsnavhypertarget}]
+\cs{glsnavhypertarget}\marg{label}\marg{text}
+\end{definition}
+This typically requires \cs{glossaryheader} to be redefined to use
+\begin{definition}[\DescribeMacro\glsnavigation]
+\cs{glsnavigation}
+\end{definition}
+which displays the navigation line.
+
+For further details about \cs{glsnavhypertarget}, see
+\ifpdf section~\ref*{sec:code:hypernav} in \fi the documented code
+(\texttt{glossaries-code.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.
+
+As from version 3.03, the package option \pkgopt{nogroupskip} can be
+used to suppress this default gap for the predefined styles.
+
+\begin{definition}[\DescribeMacro{\glossentry}]
+\cs{glossentry}\marg{label}\marg{number list}
+\end{definition}
+This macro indicates what to do for each top-level (level~0) glossary entry.
+The entry label is given by \meta{label} and the associated
+\gls{numberlist} is given by \meta{number list}. You can redefine
+\ics{glossentry} to use commands like \ics{glossentryname}\marg{label},
+\ics{glossentrydesc}\marg{label} and \ics{glossentrysymbol}\marg{label}
+to display the name, description and symbol fields, or to access
+other fields, use commands like \ics{glsentryuseri}\marg{label}.
+(See \sectionref{sec:glsnolink} for further details.) You can also
+use the following commands:
+
+\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{glossentry} 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{glossentry} 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{glossentry} as follows:
+\begin{verbatim}
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{##1}%
+ \glstarget{##1}{\glossentryname{##1}}]
+ \glossentrydesc{##1}\glspostdescription\space ##2}
+\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 \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{\subglossentry}]
+\cs{subglossentry}\marg{level}\marg{label}\marg{number list}
+\end{definition}
+This 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{glossentry} 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 option has
+been used. This macro is typically called by \cs{subglossentry}
+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-code.pdf}).
+
+\begin{example}{Creating a completely new style}{sec:exnewstyle}
+
+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*{\glossentry}[2]{%
+ \item % bullet point
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \space (\glossentrysymbol{##1})% the symbol in brackets
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
+ }%
+ % set how sub-entries appear:
+ \renewcommand*{\subglossentry}[3]{%
+ \glossentry{##2}{##3}}%
+ }
+\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.
+
+Variations:
+\begin{itemize}
+\item You might want the entry name to be capitalised, in
+which case use \ics{Glossentryname} instead of \ics{glossentryname}.
+
+\item You might want to check if the symbol hasn't been set and omit
+the parentheses if the symbol is absent. In this case you can use
+\ics{ifglshassymbol} (see \sectionref{sec:utilities}):
+\begin{verbatim}
+ \renewcommand*{\glossentry}[2]{%
+ \item % bullet point
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \ifglshassymbol{##1}% check if symbol exists
+ {%
+ \space (\glossentrysymbol{##1})% the symbol in brackets
+ }%
+ {}% no symbol so do nothing
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
+ }%
+\end{verbatim}
+\end{itemize}
+\end{example}
+
+\begin{example}{Creating a new glossary style based on an
+existing style}{sec:exadaptstyle}
+
+If you want to define a new style that is a slightly modified
+version of an existing style, you can use \ics{setglossarystyle}
+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}{%
+\setglossarystyle{list}% base this style on the list style
+\renewcommand{\glsgroupskip}{}% make nothing happen
+ % between groups
+}
+\end{verbatim}
+(In this case, you can actually achieve the same effect using the
+\glostyle{list} style in combination with the package option
+\pkgopt{nogroupskip}.)
+\end{example}
+
+\begin{example}{Example: creating a glossary style that uses the
+\texorpdfstring{\gloskey{user1}}{user1}, \ldots,
+\texorpdfstring{\gloskey{user6}}{user6} keys}{sec:exuserstyle}
+
+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*{\glossentry}[2]{%
+ \glsentryitem{##1}% Entry number if required
+ \glstarget{##1}{\glossentryname{##1}}% Name
+ & \glossentrydesc{##1}% Description
+ & \glossentrysymbol{##1}% Symbol
+ & \glsentryuseri{##1}% Units
+ & \glsentryuserii{##1}% Dimensions
+ & ##2% Page list
+ \tabularnewline % end of row
+ }%
+ % Similarly for sub-entries (no sub-entry numbers):
+ \renewcommand*{\subglossentry}[3]{%
+ % ignoring first argument (sub-level)
+ \glstarget{##2}{\glossentryname{##2}}% Name
+ & \glossentrydesc{##2}% Description
+ & \glossentrysymbol{##2}% Symbol
+ & \glsentryuseri{##2}% Units
+ & \glsentryuserii{##2}% Dimensions
+ & ##3% Page list
+ \tabularnewline % end of row
+ }%
+ % Nothing between groups:
+ \renewcommand*{\glsgroupskip}{}%
+}
+\end{verbatim}
+\end{example}
+
+\chapter{Utilities}
+\label{sec:utilities}
+
+This section describes some utility commands. Additional commands
+can be found in the documented code (glossaries-code.pdf).
+
+\section{Loops}
+\label{sec:loops}
+
+\begin{important}
+Some of the commands described here take a comma-separated list as
+an argument. As with \LaTeX's \cs{@for} command, make sure your list
+doesn't have any unwanted spaces in it as they don't get stripped.
+(Discussed in more detail in
+\href{http://www.dickimaw-books.com/latex/admin/html/docsvlist.shtml#spacesinlists}{\S2.7.2 of \qt{\LaTeX\ for Administrative
+Work}}.)
+\end{important}
+
+\begin{definition}[\DescribeMacro{\forallglossaries}]
+\cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body}
+\end{definition}
+This iterates through \meta{glossary list}, a comma-separated list
+of glossary labels (as supplied when the glossary was defined).
+At each iteration \meta{cs} (which must be a control sequence) is
+set to the glossary label for the current iteration and \meta{body}
+is performed. If \meta{glossary list} is omitted, the default is to
+iterate over all glossaries (except the ignored ones).
+
+\begin{definition}[\DescribeMacro{\forallacronyms}]
+\cs{forallacronyms}\marg{cs}\marg{body}
+\end{definition}
+This is like \cs{forallglossaries} but only iterates over the
+lists of acronyms (that have previously been declared using
+\ics{DeclareAcronymList} or the \pkgopt{acronymlists} package
+option). This command doesn't have an optional argument. If you want
+to explicitly say which lists to iterate over, just use the optional
+argument of \cs{forallglossaries}.
+
+\begin{definition}[\DescribeMacro{\forglsentries}]
+\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body}
+\end{definition}
+This iterates through all entries in the glossary given by
+\meta{glossary label}. At each iteration \meta{cs} (which must be a
+control sequence) is set to the entry label for the current
+iteration and \meta{body} is performed. If \meta{glossary label} is
+omitted, \ics{glsdefaulttype} (usually the main glossary) is used.
+
+\begin{definition}[\DescribeMacro{\forallglsentries}]
+\cs{forallglsentries}\oarg{glossary list}\marg{cs}\marg{body}
+\end{definition}
+This is like \cs{forglsentries} but for each glossary in
+\meta{glossary list} (a comma-separated list of glossary labels). If
+\meta{glossary list} is omitted, the default is the list of all
+defined glossaries (except the ignored ones). At each iteration
+\meta{cs} is set to the entry label and \meta{body} is performed.
+(The current glossary label can be obtained using
+\cs{glsentrytype}\marg{cs} within \meta{body}.)
+
+\section{Conditionals}
+\label{sec:conditionals}
+
+\begin{definition}[\DescribeMacro{\ifglossaryexists}]
+\cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false
+part}}
+\end{definition}
+This checks if the glossary given by \meta{label} exists. If it
+does \meta{true part} is performed, otherwise \meta{false part}.
+
+\begin{definition}[\DescribeMacro{\ifglsentryexists}]
+\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false
+part}}
+\end{definition}
+This checks if the glossary entry given by \meta{label} exists. If it
+does \meta{true part} is performed, otherwise \meta{false part}.
+(Note that \cs{ifglsentryexists} will always be true after the
+containing glossary has been displayed via \ics{printglossary}
+or \ics{printglossaries} even if the entry is explicitly defined
+later in the document. This is because the entry has to be defined
+before it can be displayed in the glossary, see \sectionref{sec:techissues} for
+further details.)
+
+\begin{definition}[\DescribeMacro{\glsdoifexists}]
+\cs{glsdoifexists}\marg{label}\marg{code}
+\end{definition}
+Does \meta{code} if the entry given by \meta{label} exists. If it
+doesn't exist, an error is generated. (This command uses
+\cs{ifglsentryexists}.)
+
+\begin{definition}[\DescribeMacro{\glsdoifnoexists}]
+\cs{glsdoifnoexists}\marg{label}\marg{code}
+\end{definition}
+Does the reverse of \cs{glsdoifexists}. (This command uses
+\cs{ifglsentryexists}.)
+
+\begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}]
+\cs{glsdoifexistsorwarn}\marg{label}\marg{code}
+\end{definition}
+As \cs{glsdoifexists} but issues a warning rather than an error if
+the entry doesn't exist.
+
+\begin{definition}[\DescribeMacro{\glsdoifexistsordo}]
+\cs{glsdoifexistsordo}\marg{label}\marg{code}\marg{else code}
+\end{definition}
+Does \meta{code} if the entry given by \meta{label} exists otherwise
+generate an error and do \meta{else code}.
+
+\begin{definition}[\DescribeMacro{\glsdoifnoexistsordo}]
+\cs{glsdoifnoexistsordo}\marg{label}\marg{code}\marg{else code}
+\end{definition}
+Does \meta{code} if the entry given by \meta{label} doesn't exist otherwise
+generate an error and do \meta{else code}.
+
+\begin{definition}[\DescribeMacro{\ifglsused}]
+\cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false
+part}}
+\end{definition}
+See \sectionref{sec:glsunset}.
+
+\begin{definition}[\DescribeMacro{\ifglshaschildren}]
+\cs{ifglshaschildren}{\meta{label}}{\meta{true part}}{\meta{false
+part}}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has any
+sub-entries. If it does, \meta{true part} is performed, otherwise
+\meta{false part}.
+
+\begin{definition}[\DescribeMacro{\ifglshasparent}]
+\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false
+part}}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has a parent
+entry. If it does, \meta{true part} is performed, otherwise
+\meta{false part}.
+
+\begin{definition}[\DescribeMacro{\ifglshassymbol}]
+\cs{ifglshassymbol}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{symbol} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}.
+
+\begin{definition}[\DescribeMacro{\ifglshaslong}]
+\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{long} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}. This should be true for any entry that
+has been defined via \ics{newacronym}.
+There is no check for the existence of \meta{label}.
+
+\begin{definition}[\DescribeMacro{\ifglshasshort}]
+\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{short} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}. This should be true for any entry that
+has been defined via \ics{newacronym}.
+There is no check for the existence of \meta{label}.
+
+\begin{definition}[\DescribeMacro{\ifglshasdesc}]
+\cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the \gloskey{description} field is non-empty for
+the entry given by \meta{label}. If it has, \meta{true part} is
+performed, otherwise \meta{false part}. Compare with:
+\begin{definition}[\DescribeMacro{\ifglsdescsuppressed}]
+\cs{ifglsdescsuppressed}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the \gloskey{description} field has been set to just
+\ics{nopostdesc} for the entry given by \meta{label}. If it has,
+\meta{true part} is performed, otherwise \meta{false part}.
+There is no check for the existence of \meta{label}.
+
+For all other fields you can use:
+\begin{definition}[\DescribeMacro\ifglshasfield]
+\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false
+part}
+\end{definition}
+This tests the value of the field given by \meta{field} for the entry
+identified by \meta{label}. If the value is empty \emph{or the default
+value}, then \meta{false part} is performed, otherwise \meta{true
+part} is performed. If the field supplied is unrecognised \meta{false part}
+is performed and a warning is issued. Unlike the above commands,
+such as \cs{ifglshasshort}, an error occurs if the entry is
+undefined.
+
+As from version 4.23, within \meta{true part} you can use
+\begin{definition}[\DescribeMacro\glscurrentfieldvalue]
+\cs{glscurrentfieldvalue}
+\end{definition}
+to access the field value. This command is
+initially defined to nothing but has
+no relevance outside \meta{true part}. This saves re-accessing the
+field if the test is true. For example:
+\begin{verbatim}
+\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{}
+\end{verbatim}
+will insert a comma, space and the field value if the
+\gloskey{user1} key has been set for
+the entry whose label is \texttt{sample}.
+
+You can test if the value of the field is equal to a given string
+using:
+\begin{definition}[\DescribeMacro\ifglsfieldeq]
+\cs{ifglsfieldeq}\marg{label}\marg{field}\marg{string}\marg{true}\marg{false}
+\end{definition}
+In this case the \meta{field} must be the field name not the key
+(see \tableref{tab:fieldmap}). If the field isn't recognised, an
+error will occur. This command internally uses
+\sty{etoolbox}'s \cs{ifcsstring} to perform the comparison. \emph{The
+string is not expanded during the test.}
+
+The result may vary depending on whether or not expansion is on for
+the given field (when the entry was defined). For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+
+\newcommand*{\foo}{FOO}
+
+\newglossaryentry{sample1}{name={sample1},description={an example},
+user1={FOO}}
+\newglossaryentry{sample2}{name={sample2},description={an example},
+user1={\foo}}
+
+\begin{document}
+\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}.
+
+\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}.
+\end{document}
+\end{verbatim}
+This will produce \qt{TRUE} in both cases since expansion is on, so
+\cs{foo} was expanded to \qt{FOO} when \texttt{sample2} was defined.
+If the tests are changed to:
+\begin{verbatim}
+\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}.
+
+\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}.
+\end{verbatim}
+then this will produce \qt{FALSE} in both cases. Now suppose
+expansion is switched off for the \gloskey{user1} key:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+
+\newcommand*{\foo}{FOO}
+
+\glssetnoexpandfield{useri}
+
+\newglossaryentry{sample1}{name={sample1},description={an example},
+user1={FOO}}
+\newglossaryentry{sample2}{name={sample2},description={an example},
+user1={\foo}}
+
+\begin{document}
+\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}.
+
+\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}.
+\end{document}
+\end{verbatim}
+This now produces \qt{TRUE} for the first case (comparing \qt{FOO}
+with \qt{FOO}) and \qt{FALSE} for the second case (comparing
+\qt{\cs{foo}} with \qt{FOO}).
+
+The reverse happens in the following:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+
+\newcommand*{\foo}{FOO}
+
+\glssetnoexpandfield{useri}
+
+\newglossaryentry{sample1}{name={sample1},description={an example},
+user1={FOO}}
+\newglossaryentry{sample2}{name={sample2},description={an example},
+user1={\foo}}
+
+\begin{document}
+\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}.
+
+\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}.
+\end{document}
+\end{verbatim}
+This now produces \qt{FALSE} for the first case (comparing \qt{FOO}
+with \qt{\cs{foo}}) and \qt{TRUE} for the second case (comparing
+\qt{\cs{foo}} with \qt{\cs{foo}}).
+
+You can test if the value of a field is equal to the replacement
+text of a command using:
+\begin{definition}[\DescribeMacro\ifglsfielddefeq]
+\cs{ifglsfielddefeq}\marg{label}\marg{field}\marg{command}\marg{true}\marg{false}
+\end{definition}
+This internally uses \sty{etoolbox}'s \cs{ifdefstrequal} command to
+perform the comparison. The argument \meta{command} must be a macro.
+
+For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+
+\newcommand*{\foo}{FOO}
+
+\glssetnoexpandfield{useri}
+
+\newglossaryentry{sample1}{name={sample1},description={an example},
+user1={FOO}}
+\newglossaryentry{sample2}{name={sample2},description={an example},
+user1={\foo}}
+
+\begin{document}
+\ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}.
+
+\ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}.
+\end{document}
+\end{verbatim}
+Here, the first case produces \qt{TRUE} since the value of the
+\texttt{useri} field (\qt{FOO}) is the same as the replacement text
+(definition) of \cs{foo} (\qt{FOO}). We have the result
+\qt{\texttt{FOO}} is equal to \qt{\texttt{FOO}}.
+
+The second case produces \qt{FALSE} since the value of the
+\texttt{useri} field (\qt{\cs{foo}}) is not the same as the replacement
+text (definition) of \cs{foo} (\qt{FOO}). No expansion has been
+performed on the value of the \texttt{useri} field. We have the
+result \qt{\cs{foo}} is not equal to \qt{\texttt{FOO}}.
+
+If we add:
+\begin{verbatim}
+\newcommand{\FOO}{\foo}
+\ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}.
+\end{verbatim}
+we now get \qt{TRUE} since the value of the
+\texttt{useri} field (\qt{\cs{foo}}) is the same as the replacement
+text (definition) of \cs{FOO} (\qt{\cs{foo}}). We have the result \qt{\cs{foo}}
+is equal to \qt{\cs{foo}}.
+
+There is a similar command that requires the control sequence name
+(without the leading backslash) instead of the actual control sequence:
+\begin{definition}[\DescribeMacro\ifglsfieldcseq]
+\cs{ifglsfieldcseq}\marg{label}\marg{field}\marg{csname}\marg{true}\marg{false}
+\end{definition}
+This internally uses \sty{etoolbox}'s \cs{ifcsstrequal} command
+instead of \cs{ifdefstrequal}.
+
+\section{Fetching and Updating the Value of a Field}
+\label{sec:fetchset}
+
+You can fetch the value of a given field and store it in a control
+sequence using:
+\begin{definition}[\DescribeMacro\glsfieldfetch]
+\cs{glsfieldfetch}\marg{label}\marg{field}\marg{cs}
+\end{definition}
+where \meta{label} is the label identifying the glossary entry,
+\meta{field} is the field label (see \tableref{tab:fieldmap})
+and \meta{cs} is the control sequence in which to store the value.
+Remember that \meta{field} is the internal label and is not
+necessarily the same as the key used to set that field in the
+argument of \cs{newglossaryentry} (or the optional argument of
+\cs{newacronym}).
+
+You can change the value of a given field using one of the following
+commands. Note that these commands only change the value of the
+given field. They have no affect on any related field. For example,
+if you change the value of the \gloskey{text} field, it won't modify the
+value given by the \gloskey{name}, \gloskey{plural}, \gloskey{first} or any other related key.
+
+In all the four related commands below, \meta{label} and
+\meta{field} are as above and \meta{definition} is the new value
+of the field.
+
+\begin{definition}[\DescribeMacro\glsfielddef]
+\cs{glsfielddef}\marg{label}\marg{field}\marg{definition}
+\end{definition}
+This uses \cs{def} to change the value of the field (so it will be
+localised by any grouping).
+
+\begin{definition}[\DescribeMacro\glsfieldedef]
+\cs{glsfieldedef}\marg{label}\marg{field}\marg{definition}
+\end{definition}
+This uses \cs{edef} to change the value of the field (so it will be
+localised by any grouping). Any fragile commands contained in the
+\meta{definition} must be protected.
+
+\begin{definition}[\DescribeMacro\glsfieldgdef]
+\cs{glsfieldgdef}\marg{label}\marg{field}\marg{definition}
+\end{definition}
+This uses \cs{gdef} to change the value of the field.
+
+\begin{definition}[\DescribeMacro\glsfieldxdef]
+\cs{glsfieldxdef}\marg{label}\marg{field}\marg{definition}
+\end{definition}
+This uses \cs{xdef} to change the value of the field. Any fragile
+commands contained in the \meta{definition} must be protected.
+
+
+\chapter{Prefixes or Determiners}\label{sec:prefix}
+
+The \sty{glossaries-prefix} package that comes with the
+\styfmt{glossaries} package provides
+additional keys that can be used as prefixes. For example, if you
+want to specify determiners (such
+as \qt{a}, \qt{an} or \qt{the}). The \styfmt{glossaries-prefix}
+package automatically loads the \styfmt{glossaries} package and has
+the same package options.
+
+The extra keys for \ics{newglossaryentry} are as follows:
+\begin{description}
+\item[\gloskey{prefix}] The prefix associated with the
+\gloskey{text} key. This defaults to nothing.
+
+\item[\gloskey{prefixplural}] The prefix associated with the
+\gloskey{plural} key. This defaults to nothing.
+
+\item[\gloskey{prefixfirst}] The prefix associated with the
+\gloskey{first} key. If omitted, this defaults to the value of the
+\gloskey{prefix} key.
+
+\item[\gloskey{prefixfirstplural}] The prefix associated with the
+\gloskey{firstplural} key. If omitted, this defaults to the value of
+the \gloskey{prefixplural} key.
+\end{description}
+
+\begin{example}{Defining Determiners}{ex:determiners}
+Here's the start of my example document:
+\begin{verbatim}
+documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[toc,acronym]{glossaries-prefix}
+\end{verbatim}
+Note that I've simply replaced \styfmt{glossaries} from previous
+sample documents with \styfmt{glossaries-prefix}. Now for a sample
+definition\footnote{Single letter words, such as \qt{a} and \qt{I}
+should typically not appear at the end of a line, hence the
+non-breakable space after \qt{a} in the \gloskey{prefix} field.}:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},%
+ description={an example},%
+ prefix={a~},%
+ prefixplural={the\space}%
+}
+\end{verbatim}
+Note that I've had to explicitly insert a~space after the prefix.
+This allows for the possibility of prefixes that shouldn't have a~space,
+such as:
+\begin{verbatim}
+\newglossaryentry{oeil}{name={oeil},
+ plural={yeux},
+ description={eye},
+ prefix={l'},
+ prefixplural={les\space}}
+\end{verbatim}
+Where a space is required at the end of the prefix, you must use
+a~spacing command, such as \cs{space}, \verb*|\ | (backslash space) or
+\verb|~| due to the automatic spacing trimming performed in
+\meta{key}=\meta{value} options.
+
+The prefixes can also be used with acronyms. For example:
+\begin{verbatim}
+\newacronym
+ [%
+ prefix={an\space},prefixfirst={a~}%
+ ]{svm}{SVM}{support vector machine}
+\end{verbatim}
+\end{example}
+
+The \sty{glossaries-prefix} package provides convenient commands to
+use these prefixes with commands such as \ics{gls}. Note that the
+prefix is not considered part of the \gls{linktext}, so it's not
+included in the hyperlink (where hyperlinks are enabled). The
+options and any star or plus modifier are passed on to the \glslike\
+command. (See \sectionref{sec:glslink} for further details.)
+
+\begin{definition}[\DescribeMacro\pgls]
+\cs{pgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is inserts the value of the \gloskey{prefix} key (or
+\gloskey{prefixfirst} key, on \gls{firstuse}) in front of
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\Pgls]
+\cs{Pgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+If the \gloskey{prefix} key (or \gloskey{prefixfirst}, on
+\gls*{firstuse}) has been set, this displays the value of that key
+with the first letter converted to upper case followed by
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't
+been set, this is equivalent to
+\ics{Gls}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\PGLS]
+\cs{PGLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+As \cs{pgls} but converts the prefix to upper case and uses
+\ics{GLS} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\pglspl]
+\cs{pglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is inserts the value of the \gloskey{prefixplural} key (or
+\gloskey{prefixfirstplural} key, on \gls{firstuse}) in front of
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\Pglspl]
+\cs{Pglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+If the \gloskey{prefixplural} key (or \gloskey{prefixfirstplural}, on
+\gls*{firstuse}) has been set, this displays the value of that key
+with the first letter converted to upper case followed by
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't
+been set, this is equivalent to
+\ics{Glspl}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\PGLSpl]
+\cs{PGLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+As \cs{pglspl} but converts the prefix to upper case and uses
+\ics{GLSpl} instead of \cs{glspl}.
+
+\begin{example}{Using Prefixes}{ex:prefixes}
+Continuing from Example~\ref{ex:determiners}, now that I've defined
+my entries, I~can use them in the text via the above commands:
+\begin{verbatim}
+First use: \pgls{svm}. Next use: \pgls{svm}.
+Singular: \pgls{sample}, \pgls{oeil}.
+Plural: \pglspl{sample}, \pglspl{oeil}.
+\end{verbatim}
+which produces:
+\begin{quote}
+First use: a~support vector machine (SVM). Next
+use: an SVM.
+Singular: a~sample, l'oeil. Plural: the samples, les yeux.
+\end{quote}
+For a complete document, see \samplefile{-prefix}.
+\end{example}
+
+This package also provides the commands described below, none of
+which perform any check to determine the entry's existence.
+
+\begin{definition}[\DescribeMacro\ifglshasprefix]
+\cs{ifglshasprefix}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefix} key.
+
+This package also provides the following commands:
+\begin{definition}[\DescribeMacro\ifglshasprefixplural]
+\cs{ifglshasprefixplural}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixplural} key.
+
+\begin{definition}[\DescribeMacro\ifglshasprefixfirst]
+\cs{ifglshasprefixfirst}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixfirst} key.
+
+\begin{definition}[\DescribeMacro\ifglshasprefixfirstplural]
+\cs{ifglshasprefixfirstplural}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixfirstplural} key.
+
+\begin{definition}[\DescribeMacro\glsentryprefix]
+\cs{glsentryprefix}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefix} key for the entry given
+by \meta{label}.
+
+\begin{definition}[\DescribeMacro\glsentryprefixfirst]
+\cs{glsentryprefixfirst}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixfirst} key for the entry given
+by \meta{label}.
+
+\begin{definition}[\DescribeMacro\glsentryprefixplural]
+\cs{glsentryprefixplural}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixplural} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+\begin{definition}[\DescribeMacro\glsentryprefixfirstplural]
+\cs{glsentryprefixfirstplural}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixfirstplural} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+There are also variants that convert the first letter to upper
+case\footnote{The earlier caveats about initial non-Latin characters
+apply.}:
+\begin{definition}[\DescribeMacro\Glsentryprefix]
+\cs{Glsentryprefix}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsentryprefixfirst]
+\cs{Glsentryprefixfirst}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsentryprefixplural]
+\cs{Glsentryprefixplural}\marg{label}
+\end{definition}
+
+\begin{definition}[\DescribeMacro\Glsentryprefixfirstplural]
+\cs{Glsentryprefixfirstplural}\marg{label}
+\end{definition}
+
+\begin{important}
+As with analogous commands such as \ics{Glsentrytext}, these
+commands aren't expandable so can't be used in PDF bookmarks.
+\end{important}
+
+\begin{example}{Adding Determiner to Glossary Style}{ex:plist}
+You can use the above commands to define a new glossary style that
+uses the determiner. For example, the following style is a slight
+modification of the \glostyle{list} style that inserts the prefix
+before the name:
+\begin{verbatim}
+\newglossarystyle{plist}{%
+ \setglossarystyle{list}%
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{##1}%
+ \Glsentryprefix{##1}%
+ \glstarget{##1}{\glossentryname{##1}}]
+ \glossentrydesc{##1}\glspostdescription\space ##2}%
+}
+\end{verbatim}
+\end{example}
+
+\chapter{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-code.pdf}) for further details. I~recommend
+that you also read the \sty{accsupp} documentation.
+
+\chapter{Troubleshooting}
+\label{sec:trouble}
+
+In addition to the sample files listed in \sectionref{sec:samples},
+the \styfmt{glossaries} package comes with some minimal example
+files, \texttt{minimalgls.tex}, \texttt{mwe-gls.tex},
+\texttt{mwe-acr.tex} and \texttt{mwe-acr-desc.tex}, which can be
+used for testing. These 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\slash local\slash texlive\slash
+2014\slash texmf-dist\slash doc\slash latex\slash glossaries/}.
+The \gls{makeglossariesgui} application can also be used to test for
+various problems.
+Further information on debugging \LaTeX\ code is available at
+\url{http://www.dickimaw-books.com/latex/minexample/}.
+
+If you have any problems, please first consult the
+\urlfootref{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ}. If that
+doesn't help, try posting your query to somewhere like the
+\texttt{comp.text.tex} newsgroup, the
+\urlfootref{http://www.latex-community.org/}{\LaTeX\ Community Forum} or
+\urlfootref{http://tex.stackexchange.com/}{\TeX\ on StackExchange}.
+Bug reports can be submitted via
+\urlfootref{http://www.dickimaw-books.com/bug-report.html}{my package bug report form}.
+
+\PrintIndex
+
+\end{document}