summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.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-extra/glossaries-extra-manual.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex12125
1 files changed, 12125 insertions, 0 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
new file mode 100644
index 0000000000..674b704722
--- /dev/null
+++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
@@ -0,0 +1,12125 @@
+\documentclass[report,inlinetitle,widecs]{nlctdoc}
+
+\makeatletter
+\@ifpackageloaded{tex4ht}
+{
+ \DeclareUnicodeCharacter{00FE}{\HCode{&\#x00FE;}}
+ \DeclareUnicodeCharacter{00D0}{\HCode{&\#x00D0;}}
+ \DeclareUnicodeCharacter{01F7}{\HCode{&\#x01F7;}}
+ \DeclareUnicodeCharacter{A77D}{\HCode{&\#xA77D;}}
+ \DeclareUnicodeCharacter{017F}{\HCode{&\#x017F;}}
+ \DeclareUnicodeCharacter{018F}{\HCode{&\#x018F;}}
+}
+{
+ \usepackage{fontspec}
+ \setmainfont{FreeSerif}
+}
+\makeatother
+
+\usepackage{alltt}
+\usepackage{hologo}
+\usepackage[colorlinks,
+ hyperindex=false,
+ pdfauthor={Nicola L.C. Talbot},
+ pdftitle={glossaries-extra.sty: an extension to the glossaries
+package},
+ pdfkeywords={LaTeX,package,glossary,abbreviations}]{hyperref}
+\usepackage[nogroupskip,nonumberlist]{glossaries-extra}
+
+\makeglossaries
+
+\GlsXtrEnableEntryUnitCounting{general}{0}{page}
+
+\renewcommand*{\glsxtrifcounttrigger}[3]{#3}
+
+\renewcommand*{\glslinkcheckfirsthyperhook}{%
+ \ifnum\glsentrycurrcount\glslabel>0
+ \setkeys{glslink}{hyper=false}%
+ \fi
+}
+
+\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}}
+\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}}
+\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}}
+
+\IndexPrologue{\chapter*{\indexname}
+ \addcontentsline{toc}{chapter}{\indexname}%
+ \markboth{\indexname}{\indexname}}
+
+\renewcommand*{\main}[1]{\hyperpage{#1}}
+\newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}}
+
+\glssetcategoryattribute{general}{indexname}{htextbf}
+\glssetcategoryattribute{general}{dualindex}{main}
+
+\newglossaryentry{xindy}{
+ name={\appfmt{xindy}},
+ sort={xindy},
+ description={An flexible indexing application with multilingual
+ support written in Perl.}
+}
+
+\newglossaryentry{makeindex}{%
+ name={\appfmt{makeindex}},%
+ sort={makeindex},%
+ description={An indexing application.},
+}
+
+\newglossaryentry{makeglossaries}{%
+name={\appfmt{makeglossaries}},%
+sort={makeglossaries},%
+description={A custom designed Perl script interface
+provided with the \styfmt{glossaries} package
+to run \gls{xindy} or \gls{makeindex} according to
+the document settings.}}
+
+\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 distributed in the source code
+on CTAN 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, and
+\TeX\ distributions on Windows convert the script to an executable
+\texttt{makeglossaries-lite.exe}.}
+}
+
+\newglossaryentry{bib2gls}{%
+name={\appfmt{bib2gls}},%
+sort={bib2gls},%
+description={A command line Java application that selects
+entries from a .bib file and converts them to glossary
+definitions (like \appfmt{bibtex} but also performs hierarchical
+sorting and collation, thus omitting the need for \gls{xindy} or
+\gls{makeindex}). Further details at:
+\url{http://www.dickimaw-books.com/software/bib2gls/}.}%
+}
+
+\newglossaryentry{numberlist}{%
+name={number list},%
+description={A list of \glspl{entrylocation} (also
+called a location list). The number list can be suppressed using the
+\pkgopt{nonumberlist} package option.}
+}
+
+\newglossaryentry{entrylocation}{%
+name={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},%
+description={A list of \glspl{entrylocation}.
+See \gls{numberlist}.}%
+}
+
+\newglossaryentry{linktext}{%
+name={link-text},
+description={The text produced by commands such as \ics{gls}. It may
+or may not have a hyperlink to the glossary.}
+}
+
+\let\glsd\glsuseri
+\let\glsation\glsuserii
+
+\newglossaryentry{firstuseflag}{%
+name={first use flag},
+description={A conditional that determines whether or not the entry
+has been used according to the rules of \gls{firstuse}.}%
+}
+
+\newglossaryentry{firstusetext}{%
+name={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}.)}%
+}
+
+\newglossaryentry{firstuse}{%
+ name={first use},
+ user1={first used},
+ see={firstuseflag,firstusetext},
+ description={The first time a glossary entry is used (from the start
+ of the document or after a reset) with one of the
+ following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl},
+ \ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}.}%
+}
+
+\setcounter{IndexColumns}{2}
+
+\newrobustcmd*{\eq}{\protect=}% hide from makeindex
+
+\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
+\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+\newcommand*{\optfmt}[1]{\textsf{#1}}
+
+\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym
+styles (glossaries):>#1={\protect\ttfamily#1}|main}}
+
+\newcommand*{\abbrstylenolink}[1]{%
+ \textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\abbrstyle}[1]{%
+ \hyperlink{abbrstyle.#1}{\textsf{#1}}%
+ \index{abbreviation styles:>#1={\protect\sffamily#1}|main}%
+}
+
+\makeatletter
+\newcommand{\htarget}[2]{\Hy@raisedlink{\hypertarget{#1}{}}#2}
+\makeatother
+
+\newcommand*{\abbrstyledef}[1]{%
+ \htarget{abbrstyle.#1}{\textsf{#1}}%
+ \index{abbreviation styles:>#1={\protect\sffamily#1}|main}%
+}
+
+\newcommand*{\depabbrstyle}[1]{\textsf{#1}\index{abbreviation styles (deprecated):>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\category}[1]{\textsf{#1}\index{categories:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\catattrnolink}[1]{%
+ \textsf{#1}\index{category attributes:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\catattr}[1]{%
+ \hyperlink{catattr.#1}{\textsf{#1}}%
+ \index{category attributes:>#1={\protect\sffamily#1}|main}%
+}
+
+\newcommand*{\catattrdef}[1]{%
+ \htarget{catattr.#1}{\textsf{#1}}%
+ \index{category attributes:>#1={\protect\sffamily#1}|main}%
+}
+
+\newcommand*{\postlinkcat}{%
+ \cs{glsxtrpostlink}\meta{category}%
+ \index{glsxtrpostlinkcategory=\cs{glsxtrpostlink}\meta{category}|hyperpage}%
+}
+
+\renewcommand*{\pkgopt}[2][]{%
+ \hyperlink{styopt.#2}{\pkgoptfmt{#2}}%
+ \ifstrempty{#1}{}{\pkgoptfmt{=#1}}%
+ \ipkgopt[#1]{#2}%
+}
+
+\newcommand*{\pkgoptdef}[1]{%
+ \htarget{styopt.#1}{\pkgoptfmt{#1}}%
+ \ipkgopt{#1}%
+}
+
+\setlength\marginparwidth{70pt}
+
+\begin{document}
+\DeleteShortVerb{\|}
+\MakeShortVerb{"}
+
+ \title{glossaries-extra.sty v1.41:
+ an extension to the glossaries package}
+ \author{Nicola L.C. Talbot\\[10pt]
+Dickimaw Books\\
+\url{http://www.dickimaw-books.com/}}
+
+ \date{2019-04-09}
+ \maketitle
+
+\begin{abstract}
+The \styfmt{glossaries-extra} package is an extension to the
+\styfmt{glossaries} package, providing additional features.
+Some of the features provided by this package are only available
+with \styfmt{glossaries} version 4.19 (or above).
+This document assumes familiarity with the \styfmt{glossaries} package.
+
+The file \texttt{example-glossaries-xr.tex} contains dummy
+entries with cross-references that may be used for creating
+minimal working examples for testing the \styfmt{glossaries-extra}
+package. (The base \styfmt{glossaries} package provides additional files,
+but this one needs \styfmt{glossaries-extra}.) There are equivalent
+\texttt{.bib} files for use with \gls{bib2gls}.
+
+\end{abstract}
+
+\begin{important}
+Since \styfmt{glossaries-extra} internally loads the \styfmt{glossaries}
+package, you also need to have \styfmt{glossaries} installed and
+all the packages that \styfmt{glossaries} depends on (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} and \sty{amsgen}. These
+packages are all available in the current \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
+\href{http://tex.stackexchange.com/questions/14925/updating-tex-on-linux}{Updating
+\TeX\ on Linux}.)
+\end{important}
+
+Additional resources:
+\begin{itemize}
+\item The \styfmt{glossaries-extra} documented code
+\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf}{glossaries-extra-code.pdf}.
+
+\item The
+\href{http://www.dickimaw-books.com/gallery/#glossaries-extra}{\styfmt{glossaries-extra} gallery}.
+
+\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{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating
+makeglossaries or makeglossaries-lite or bib2gls into the document
+build}.
+
+\item The
+\href{http://www.dickimaw-books.com/software/bib2gls}{\appfmt{bib2gls}}
+application.
+
+\item The base \href{https://ctan.org/pkg/glossaries}{\styfmt{glossaries}} package.
+\end{itemize}
+
+\tableofcontents
+
+\chapter{Introduction}
+\label{sec:intro}
+
+The \styfmt{glossaries} package is a flexible package, but it's also a
+heavy-weight package that uses a lot of resources. As package
+developer, I'm caught between those users who complain about the
+drawbacks of a heavy-weight package with a large user manual and
+those users who want more features (which necessarily adds to the
+package weight and manual size).
+
+The \styfmt{glossaries-extra} package is an attempt to provide
+a~compromise for this
+conflict. Version 4.22 of the \styfmt{glossaries} package is
+the last version to incorporate new features.\footnote{4.21 was
+originally intended as the last release of \styfmt{glossaries} to
+incorporate new features, but a few new minor features slipped in with
+some bug fixes in v4.21.} Future versions of
+\styfmt{glossaries} will just be bug fixes. New features will
+instead be added to \styfmt{glossaries-extra}.
+This means that the base \styfmt{glossaries} package won't increase
+in terms of package loading time and allocation of resources, but
+those users who do want extra features available will have more of a
+chance of getting their feature requests accepted.
+
+\section{Package Defaults}
+\label{sec:defaults}
+
+I'm not happy with some of the default settings assumed by the
+\styfmt{glossaries} package, and, judging from code I've seen, other
+users also seem unhappy with them, as certain package options are
+often used in questions posted on various sites. I can't change the default
+behaviour of \styfmt{glossaries} as it would break backward
+compatibility, but since \styfmt{glossaries-extra} is a separate
+package, I have decided to implement some of these commonly-used
+options by default. You can switch them back if they're not
+appropriate.
+
+The new defaults are:
+\begin{itemize}
+\item \pkgopt[true]{toc} (add the glossaries to the table of
+contents). Use \pkgopt[false]{toc} to switch this back off.
+
+\item \pkgopt[true]{nopostdot} (suppress the terminating full stop
+after the description in the glossary). Use
+\pkgopt[false]{nopostdot} or just \pkgopt{postdot} to restore the
+terminating full stop (period).
+
+\item \pkgopt[true]{noredefwarn} (suppress the warnings that occur when
+the \env{theglossary} environment and \cs{printglossary} are redefined while
+\styfmt{glossaries} is loading). To restore the warnings, use
+\pkgopt[false]{noredefwarn}. Note that this won't have any effect if
+the \styfmt{glossaries} package has already been loaded before you use
+the \styfmt{glossaries-extra} package.
+
+\item If \sty{babel} has been loaded, the \pkgopt[babel]{translate}
+option is switched on. To revert to using the \sty{translator}
+interface, use \pkgopt[true]{translate}. There is no change to the
+default if \sty{babel} hasn't been loaded.
+
+\end{itemize}
+
+The examples below illustrate the difference in explicit
+package options between \styfmt{glossaries} and
+\styfmt{glossaries-extra}. There may be other differences
+resulting from modifications to commands provided by
+\styfmt{glossaries} (see \sectionref{sec:modifications}).
+
+\begin{enumerate}
+\item
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries-extra}
+\end{verbatim}
+This is like:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[toc,nopostdot]{glossaries}
+\usepackage{glossaries-extra}
+\end{verbatim}
+
+\item
+\begin{verbatim}
+\documentclass[british]{article}
+\usepackage{babel}
+\usepackage{glossaries-extra}
+\end{verbatim}
+This is like:
+\begin{verbatim}
+\documentclass[british]{article}
+\usepackage{babel}
+\usepackage[toc,nopostdot,translate=babel]{glossaries}
+\usepackage{glossaries-extra}
+\end{verbatim}
+
+\item
+\begin{verbatim}
+\documentclass{memoir}
+\usepackage{glossaries-extra}
+\end{verbatim}
+This is like:
+\begin{verbatim}
+\documentclass{memoir}
+\usepackage[toc,nopostdot,noredefwarn]{glossaries}
+\usepackage{glossaries-extra}
+\end{verbatim}
+\emph{However}
+\begin{verbatim}
+\documentclass{memoir}
+\usepackage{glossaries}
+\usepackage{glossaries-extra}
+\end{verbatim}
+This is like:
+\begin{verbatim}
+\documentclass{memoir}
+\usepackage[toc,nopostdot]{glossaries}
+\usepackage{glossaries-extra}
+\end{verbatim}
+Since by the time \styfmt{glossaries-extra} has been loaded,
+\styfmt{glossaries} has already redefined \cls{memoir}'s
+glossary-related commands.
+\end{enumerate}
+
+Another noticeable change is that by default \cs{printglossary}
+will now display information text in the document if the external
+glossary file doesn't exist. This is explanatory text to help new
+users who can't work out what to do next to complete the document
+build. Once the document is set up correctly and the external files
+have been generated, this text will disappear.
+
+This change is mostly likely to be noticed by users
+with one or more redundant empty glossaries who ignore
+transcript messages, explicitly use \gls{makeindex}\slash\gls{xindy}
+on just the non-empty glossary (or glossaries) and use
+the iterative
+\ics{printglossaries} command instead of \ics{printglossary}. For example,
+consider the following:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[acronym]{glossaries}
+
+\makeglossaries
+
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+
+\begin{document}
+
+\gls{laser}
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+The above document will only display the list of
+acronyms at the place where \ics{printglossaries} occurs. However it
+will also attempt to input the \texttt{.gls} file associated with
+the \texttt{main} glossary.
+
+If you use \gls{makeglossaries}, you'll get the warning message:
+\begin{verbatim}
+Warning: File 'test.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{verbatim}
+(where the original file is called \texttt{test.tex})
+but if you simply call \gls{makeindex} directly to generate the
+\texttt{.acr} file (without attempting to create the \texttt{.gls}
+file) then the transcript file will always contain the message:
+\begin{verbatim}
+No file test.gls.
+\end{verbatim}
+This doesn't occur with \gls{makeglossaries} as it will create
+the \texttt{.gls} file containing the single command \cs{null}.
+
+If you simply change from \styfmt{glossaries} to
+\styfmt{glossaries-extra} in this document, you'll find a change in the
+resulting PDF if you don't use \gls{makeglossaries} and you only
+generate the \texttt{.acr} file with \gls{makeindex}.
+
+The transcript file will still contain the message
+about the missing \texttt{.gls}, but now you'll also see
+information in the actual PDF document. The simplest remedy is to
+follow the advice inserted into the document at that point, which is
+to add the \pkgopt{nomain} package option:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[nomain,acronym,postdot]{glossaries-extra}
+
+\makeglossaries
+
+\setabbreviationstyle[acronym]{long-short}
+
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+
+\begin{document}
+
+\gls{laser}
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+(Note the need to set the acronym style using
+\cs{setabbreviationstyle} before \cs{newacronym}.
+See \sectionref{sec:abbreviations} for further details.)
+
+\section{New or Modified Package Options}
+\label{sec:pkgopts}
+
+If you haven't already loaded \styfmt{glossaries}, you can use any of
+the package options provided by \styfmt{glossaries} when you load
+\styfmt{glossaries-extra} and they will automatically be passed to
+\styfmt{glossaries} (which \styfmt{glossaries-extra} will load). If
+\styfmt{glossaries} has already been loaded, then those options will be
+passed to \ics{setupglossaries}, but remember that not all of the
+\styfmt{glossaries} package options may be used in that command.
+
+\begin{important}
+This section only lists options that are either unrecognised by
+the \styfmt{glossaries} package or are a modified version of options
+of the same name provided by \styfmt{glossaries}. See the
+\styfmt{glossaries} user manual for details about the unmodified
+options.
+\end{important}
+
+The new and modified options provided by \styfmt{glossaries-extra}
+are described below:
+
+\begin{description}
+
+\item[{\pkgoptdef{debug}}] The \styfmt{glossaries} package
+has a \pkgoptfmt{debug} option that allows the values
+\pkgoptfmt{false}, \pkgoptfmt{true} and \pkgoptfmt{showtargets}.
+The \pkgopt[showtargets]{debug} option was introduced to
+\styfmt{glossaries} v4.32, so if you want to use this option
+with \styfmt{glossaries-extra} you must make sure that
+your version of \styfmt{glossaries} supports it.
+
+The \styfmt{glossaries-extra} package extends this option
+to provide the additional values \pkgopt[showwrgloss]{debug}
+and \pkgopt[all]{debug}.
+
+The \pkgopt[showwrgloss]{debug} option implements
+\pkgopt[true]{debug} and uses
+\begin{definition}[\DescribeMacro\glsxtrwrglossmark]
+\cs{glsxtrwrglossmark}
+\end{definition}
+to show a mark \ensuremath{\cdot} just before the write operation
+performed by the indexing commands. If you use
+\pkgopt[alsoindex]{record} there will be a mark for the
+write operation to the \texttt{.aux} file for \gls{bib2gls}
+and a mark for the write operation to the associated glossary
+file for \gls{makeindex} or \gls{xindy}.
+
+The \pkgopt[all]{debug} option implements both \pkgopt[showtargets]{debug}
+and \pkgopt[showwrgloss]{debug}.
+
+\item[{\pkgoptdef{postdot}}] (New to version 1.12.)
+This option is just a shortcut for \pkgopt[false]{nopostdot}.
+
+\item[{\pkgoptdef{postpunc}}] (New to version 1.21.)
+This option sets the post-description punctuation to the given
+value. For example: \pkgoptfmt{postpunc={;}} does
+\begin{verbatim}
+\renewcommand{\glspostdescription}{;}
+\end{verbatim}
+The value may also be one of the following keywords:
+\begin{description}
+\item[\texttt{comma}:] \pkgopt[comma]{postpunc} is
+equivalent to
+\begin{verbatim}
+\renewcommand{\glspostdescription}{,}
+\end{verbatim}
+
+\item[\texttt{dot}:] \pkgopt[dot]{postpunc} is
+equivalent to
+\begin{verbatim}
+\renewcommand{\glspostdescription}{.\spacefactor\sfcode`\. }
+\end{verbatim}
+
+\item[\texttt{none}:] \pkgopt[none]{postpunc} is
+equivalent to
+\begin{verbatim}
+\renewcommand{\glspostdescription}{}
+\end{verbatim}
+\end{description}
+The default definition is
+\begin{verbatim}
+\newcommand*{\glspostdescription}{%
+ \ifglsnopostdot\else.\spacefactor\sfcode`\. \fi
+}
+\end{verbatim}
+where the conditional is determined by the \pkgopt{nopostdot}
+package option. The \pkgopt{postpunc} option removes the conditional
+from the definition of \cs{glspostdescription}. The package options
+\pkgopt{nopostdot} and \pkgopt{postdot} will restore the original definition of
+\cs{glspostdescription}.
+
+The \sty{glossaries-extra-stylemods} package adjusts
+the predefined styles that had a hard-coded \cs{space}
+before the \gls{numberlist} so that they use \cs{glsxtrprelocation}
+instead (which is defined to \cs{space}). You can therefore
+redefine this command in combination with \pkgopt{postpunc}
+to alter the separator before the \gls{numberlist}.
+For example, to have a comma followed by \cs{hfil}:
+\begin{verbatim}
+\usepackage[postpunc=comma,stylemods]{glossaries-extra}
+\renewcommand{\glsxtrprelocation}{\hfil}
+\end{verbatim}
+Be careful with doing this as it will look odd if the \gls{numberlist} is
+missing. (With \gls{bib2gls} you can instead redefine
+\cs{glsxtrprelocation} to do nothing and set the
+location prefixes with \texttt{loc-prefix} which will only
+apply if the entry has a \gls{numberlist}.)
+
+\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp}
+package (if not already loaded).
+
+If you want to define styles that can interface with the
+accessibility support provided by \sty{glossaries-accsupp} use
+the \cs{glsaccess\meta{xxx}} type of commands instead of
+\cs{glsentry\meta{xxx}} (for example, \ics{glsaccesstext} instead of
+\ics{glsentrytext}). If \sty{glossaries-accsupp} hasn't been loaded
+those commands are equivalent (for example, \cs{glsaccesstext}
+just does \cs{glsentrytext}) but if it has been loaded, then the
+\cs{glsaccess\meta{xxx}} commands will add the accessibility
+information. (See \sectionref{sec:accsupp} for further details.)
+
+Note that the \pkgopt{accsupp} option can only be used as
+a~package option (and can't be set with \ics{glossariesextrasetup}) since the \sty{glossaries-accsupp}
+package must be loaded before \styfmt{glossaries-extra} if it's
+required.
+
+\item[{\pkgoptdef{stylemods}}] This is a
+\meta{key}=\meta{value} option used to load the
+\sty{glossaries-extra-stylemods} package. The value may be a
+comma-separated list of options to pass to that package. (Remember
+to group \meta{value} if it contains any commas.) The value may be
+omitted if no options need to be passed. See \sectionref{sec:glosstylemods}
+for further details. There are two special keyword values:
+\pkgopt[default]{stylemods} (equivalent to omitting the value)
+and \pkgopt[all]{stylemods}, which loads all the
+predefined styles.
+
+\item[{\pkgoptdef{undefaction}}] This is a \meta{key}=\meta{value}
+option, which has two allowed values: \pkgoptfmt{warn} and
+\pkgoptfmt{error}. This indicates what to do if an undefined
+glossary entry is referenced. The default behaviour is
+\pkgopt[error]{undefaction}, which produces an error message (the
+default for \styfmt{glossaries}). You can switch this to a warning
+message (and ?? appearing in the text) with
+\pkgopt[warn]{undefaction}.
+
+\begin{important}
+Undefined entries can't be picked up by any commands that iterate
+over a glossary list. This includes \ics{forglsentries} and
+\ics{glsaddall}.
+\end{important}
+
+Note that \ics{ifglsused} will display ?? in the document text with
+\pkgopt[warn]{undefaction} if the entry hasn't been defined, as the
+underlying boolean variable doesn't exist and so is neither true nor
+false. (There will also be a warning in the transcript.) See
+\sectionref{sec:glsunset} for further details.
+
+\item[{\pkgoptdef{indexcrossrefs}}] This is a boolean option.
+If \pkgoptfmt{true}, this will automatically index any
+cross-referenced entries that haven't been marked as used at
+the end of the document. Note that this necessarily adds to
+the overall document build time, especially if you have defined
+a large number of entries, so this defaults to \pkgoptfmt{false},
+but it will be automatically switched on if you use the \gloskey{see}
+or \gloskey{seealso} keys in any entries (unless
+\pkgopt[false]{autoseeindex}). To force it off, even if you use the
+\gloskey{see} or \gloskey{seealso} key, you
+need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
+
+Note that \gls{bib2gls} can automatically find dependent
+entries when it parses the \texttt{.bib} source file.
+The \pkgopt{record} option automatically implements
+\pkgopt[false]{indexcrossrefs}.
+
+\item[{\pkgoptdef{autoseeindex}}]\label{opt:autoseeindex} (New to
+v1.16.) This is a boolean option. If true (default), this makes
+the \gloskey{see} and \gloskey{seealso} keys automatically index the
+cross-reference when an entry is defined. If false, the value
+of those keys will still be stored in their corresponding fields
+(and can be accessed using commands like \cs{glsxtrusesee} and
+\cs{glsxtruseseealso}) but cross-reference won't be automatically
+indexed.
+
+Note that the \pkgopt[only]{record} option automatically implements
+\pkgopt[false]{autoseeindex}.
+
+For example, if an entry is defined as
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={},see={bar,baz}}
+\end{verbatim}
+then with \texttt{autoseeindex=true}, this is equivalent to
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={}}
+\glssee{foo}{bar,baz}
+\glossariesextrasetup{indexcrossrefs=true}
+\GlsXtrSetField{foo}{see}{bar,baz}
+\end{verbatim}
+but with \texttt{autoseeindex=false}, this is equivalent to
+\begin{verbatim}
+\newglossaryentry{foo}{name={foo},description={}}
+\GlsXtrSetField{foo}{see}{bar,baz}
+\end{verbatim}
+Note that \pkgopt{indexcrossrefs} isn't automatically implemented
+by the presence of the \gloskey{see} key when \pkgopt{autoseeindex}
+is false.
+
+It's therefore possible to remove the cross-references from the
+location lists and set their position within the glossary style.
+
+Another method of preventing the automatic indexing is to
+define the entries before the external indexing files have been
+opened with \cs{makeglossaries}. Since the appropriate file isn't
+open, the information can't be written to it. This will need
+the package option \pkgoptfmt{seenoindex=ignore} (provided by
+\styfmt{glossaries}) to prevent an error occurring.
+
+\item[{\pkgoptdef{record}}]\label{opt:record}(New to v1.08.) This is
+a \meta{key}=\meta{value} option provided for the benefit of
+\gls{bib2gls} (see \sectionref{sec:bib2gls}).
+
+The option may only be set in the preamble and can't be used after
+\cs{GlsXtrLoadResources}. If the value is missing
+\pkgopt[only]{record} is assumed. Permitted values:
+\begin{description}
+\item[\pkgoptfmt{off}] This is the default setting. The indexing
+is performed as normal using either \cs{makeglossaries}
+or \cs{makenoidxglossaries}. This setting implements \pkgopt[error]{undefaction}.
+
+\item[\pkgoptfmt{only}] The indexing is performed by
+\gls{bib2gls} (see \sectionref{sec:bib2gls}). Neither
+\cs{makeglossaries} nor \cs{makenoidxglossaries} is permitted.
+This setting implements \pkgopt[warn]{undefaction} and automatically
+loads the supplementary \sty{glossaries-extra-bib2gls} package.
+(There should be no need to explicitly load \sty{glossaries-extra-bib2gls}.)
+
+The glossaries should be displayed using \cs{printunsrtglossary}
+(or \cs{printunsrtglossaries}).
+
+The document build process is (assuming the file is called
+\texttt{myDoc.tex}):
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{verbatim}
+
+Note that \pkgopt[only]{record} will prevent the \gloskey{see} from
+automatically implementing \cs{glssee}. (\gls{bib2gls} deals with the
+\gloskey{see} field.) You may explicitly use \cs{glssee} in the
+document, but \gls{bib2gls} will ignore the cross-reference if the
+\gloskey{see} field was already set for that entry.
+
+The \pkgopt[only]{record} option will automatically set
+the \styfmt{glossaries} package's \pkgopt[none]{sort} option
+if available. (That option value was only introduced to
+\styfmt{glossaries} v4.30.)
+
+\item[\pkgoptfmt{nameref}] (New to v1.37 and requires \gls{bib2gls}
+v1.8+.) This option is like \pkgopt[only]{record} but additionally
+records the current label information given by \cs{@currentlabel}
+and \cs{@currentHref}, and provides a more reliable way of saving
+the \cs{theH}\meta{counter} for the given location. This option
+requires \sty{hyperref} otherwise it will fall back on the usual
+location records. Remember that \cs{@currentHref} is always globally
+updated whenever \cs{refstepcounter} is used, but \cs{@currentlabel}
+isn't. This can cause some undesired side-effects with some settings. Remember also that the \pkgopt{indexcounter} option
+increments the associated counter every time an entry is indexed,
+which affects this option. See \sectionref{sec:recordnameref} for
+further details.
+
+This option is best used with \pkgopt[chapter]{counter} or
+\pkgopt[section]{counter} if you want the title included in the
+location list. If the indexing counter is the default
+\ctr{page}, only the location number is shown. Similarly for
+\pkgopt[equation]{counter} (or \pkgopt[true]{equations}).
+
+\item[\pkgoptfmt{alsoindex}] This is a hybrid setting
+that uses \gls{bib2gls} to fetch entry information from
+\texttt{.bib} files, but uses \gls{makeindex} or \gls{xindy}
+to create the glossary files. This option should be used
+with \cs{makeglossaries} but not with its optional argument.
+This option should not be used with \cs{makenoidxglossaries}.
+You may need to change the transcript file used by \gls{bib2gls}
+to avoid a clash with the transcript file used by
+\gls{makeindex} or \gls{xindy}. (This can be done with
+\gls{bib2gls}['s] \verb|--log-file| or \verb|-t| option.)
+
+The glossaries should be displayed using \cs{printglossary}
+(or \cs{printglossaries}). This option is expected to be used with
+\gls{bib2gls}'s \texttt{sort=none} setting and so
+\sty{glossaries-extra-bib2gls} is not automatically loaded.
+
+The document build process is (assuming the file is called
+\texttt{myDoc.tex}):
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+makeglossaries myDoc
+pdflatex myDoc
+\end{verbatim}
+\end{description}
+
+With the recording on (\pkgopt[only]{record} or
+\pkgopt[alsoindex]{record}), any of the commands that would typically
+index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd})
+will add a \cs{glsxtr@record} entry to the \texttt{.aux} file.
+\gls{bib2gls} can then read these lines to find
+out which entries have been used. (Remember that commands like
+\cs{glsentryname} don't index, so any use of these commands won't
+add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux}
+file.) See \sectionref{sec:bib2gls} for further details.
+
+\item[{\pkgoptdef{equations}}] (New to v1.37.) This option will
+cause the default location counter to automatically switch
+to \ctr{equation} when inside a numbered equation environment, such
+as \env{equation} or \env{align}. The counter can be explicitly
+overridden with \gloskey[glslink]{counter} in the optional
+arguments of commands like \cs{glslink} or \cs{gls} as usual.
+
+\item[{\pkgoptdef{floats}}] (New to v1.37.) This option will
+cause the default location counter to automatically switch
+to the corresponding counter when inside a floating environment,
+such as \env{figure} or \env{table}. The counter can be explicitly
+overridden with \gloskey[glslink]{counter} in the optional
+arguments of commands like \cs{glslink} or \cs{gls} as usual.
+Remember that within floats it's the \cs{caption} command that actually uses
+\cs{refstepcounter}, so indexing before the caption will result in
+the wrong reference. The commands for use in captions and sections,
+such as \cs{glsfmttext} and \cs{glsfmtshort}, don't index. (See
+\sectionref{sec:headtitle}). You may
+want to consider using \cs{glsadd} after the caption (not before). For example:
+\begin{verbatim}
+\begin{figure}[htbp]
+ \centering
+ \includegraphics{example-image}
+ \caption{Sample \glsfmttext{foobar} figure}
+ \glsadd{foobar}
+\end{figure}
+\end{verbatim}
+
+\item[{\pkgoptdef{indexcounter}}] (New to v1.29.) This option (which
+doesn't take a value) is primarily intended for use with
+\gls{bib2gls} (v1.4+) and \sty{hyperref}. It can be used with
+\gls{makeindex} or \gls{xindy} but it will interfere with the
+\gls{numberlist} collation, so you won't have ranges and you'll have
+duplicate page numbers present (but each page number will link to
+the relevant part of the page where the indexing occurred). This
+option automatically implements \pkgopt[wrglossary]{counter}.
+
+\begin{important}
+This option works by incrementing \ctr{wrglossary} and
+adding \ics{label}. This can cause a problem if the indexing
+occurs in an \env{equation} environment as \sty{amsmath}
+forbids multiple occurrences of \cs{label} (resulting in the
+\qt{Multiple \cs{label}'s} error). It's best to change the counter
+to \ctr{page} or \ctr{equation} when in maths mode with this option.
+For example:
+\begin{verbatim}
+\renewcommand{\glslinkpresetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpresetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+\end{important}
+
+By default (with \sty{hyperref}), the page numbers in
+\glspl{numberlist} link back to the top of the relevant page
+(provided the format uses \cs{glshypernumber}). The
+\pkgopt{indexcounter} option is designed to link back to the place
+within the page where the indexing occurred. It does this by
+creating a new counter (called \ctr{wrglossary}) that's incremented
+with \cs{refstepcounter} every time an entry is indexed (but not via
+cross-referencing commands, such as \cs{glssee}). A \cs{label} is
+placed immediately after the increment command allowing the
+back-referenced to be obtained with \cs{pageref}. The location, as
+seen by the indexing application, is the value of the
+\ctr{wrglossary} counter but this value is substituted with the page
+reference when \gls{numberlist} is typeset. Since the counter is
+used by all entries and is incremented every time any indexing
+occurs, neither \gls{makeindex} nor \gls{xindy} can correctly
+collate the lists. For example, if the first term to be referenced
+is indexed three times on page~5 without any intervening terms then
+the actual locations obtained from \ctr{wrglossary} will be 1, 2 and
+3, which \gls{xindy} and \gls{makeindex} will try to form into the
+range 1--3, but they should actually all simply appear as page~5,
+whereas it can actually end up with 5--5. Conversely, a range may
+not be formed where it would naturally occur if just the \ctr{page}
+counter was used.
+
+Since \gls{bib2gls} is designed specifically to work with
+\styfmt{glossaries-extra}, \gls{bib2gls} (v1.4+) will check for
+\ctr{wrglossary} locations. If the default
+\texttt{--merge-wrglossary-records} is on, then any records for the
+same page for a given entry will be merged. In the above example
+with three references on page~5, only a single record for page~5 for
+that entry will be added to the \gls{numberlist} and it will link
+back to the first instance on that page. Whereas if you use the
+\texttt{--no-merge-wrglossary-records} switch, the \gls{numberlist}
+will contain three instance of page~5, with each linking to the
+corresponding place on that page. In both cases, consecutive pages
+can form ranges, but it may look strange in the second case.
+
+See the \gls{bib2gls} documentation for the
+\texttt{save-index-counter} resource option for more details.
+
+\item[{\pkgoptdef{docdef}}] This option governs the use of
+\cs{newglossaryentry}. It was originally a boolean option,
+but as from version 1.06, it can now take one of the following values (if
+the value is omitted, \pkgoptfmt{true} is assumed):
+\begin{itemize}
+\item[{\pkgopt[false]{docdef}}] \ics{newglossaryentry} is not
+permitted in the \env{document} environment (default).
+
+\item[{\pkgopt[true]{docdef}}] \cs{newglossaryentry} behaves as it
+does in the base \styfmt{glossaries} package. That is, where
+its use is permitted in the \env{document} environment, it
+uses the \texttt{.glsdefs} temporary file to store the entry
+definitions so that on the next \LaTeX\ run the entries are
+defined at the beginning of the \env{document} environment.
+This allows the entry information to be referenced in the glossary,
+even if the glossary occurs before \cs{newglossaryentry}.
+(For example, when the glossary is displayed in the front matter.)
+This method of saving the definitions for the next \LaTeX\ run
+has drawbacks that are detailed in the \styfmt{glossaries} user
+manual.
+
+Remember that if \cs{newglossaryentry} wouldn't be allowed
+in the \env{document} environment with the
+base \styfmt{glossaries} package, then it still won't
+be allowed with \pkgopt[true]{docdefs}.
+If your glossaries occur at the end of the document, consider using
+\pkgopt[restricted]{docdef} instead.
+
+\item[{\pkgopt[restricted]{docdef}}] (new to version 1.06)
+\ics{newglossaryentry} is permitted in the \env{document}
+environment without using the \texttt{.glsdefs} file. This means
+that all entries must be defined before the glossary is displayed,
+but it avoids the complications associated with saving the
+entry details in a temporary file. You will still need to take
+care about any changes made to characters that are required
+by the \meta{key}=\meta{value} mechanism (that is, the comma and
+equal sign) and any \gls{makeindex} or \gls{xindy} character that
+occurs in the \gloskey{sort} key or label. If any of those
+characters are made active in the document, then it can cause
+problems with the entry definition. This option will allow
+\cs{newglossaryentry} to be used in the document with
+\cs{makenoidxglossaries}, but note that \cs{longnewglossaryentry}
+remains a preamble-only command.
+
+With this option, if an entry appears in the glossary before
+it has been defined, an error will occur (or a warning if
+the \pkgopt[warn]{undefaction} option is used.) If you edit your
+document and either remove an entry or change its label, you may
+need to delete the document's temporary files (such as the
+\texttt{.aux} and \texttt{.gls} files).
+
+\item[{\pkgopt[atom]{docdef}}] (new to version 1.34)
+This option behaves like \pkgopt[restricted]{docdef} but creates the
+\texttt{.glsdefs} file for
+\href{https://atom.io/packages/autocomplete-glossaries}{atom's
+autocomplete support}. This file isn't input by
+\styfmt{glossaries-extra} and so associated problems with the use of
+this file are avoided, but it allows the autocomplete support to
+find the labels in the file. As with \pkgopt[restricted]{docdef},
+entries may be defined in the preamble or anywhere in the document,
+but they may only be referenced after they have been defined.
+Entries must be defined before the associated glossary is displayed.
+
+\end{itemize}
+
+The \styfmt{glossaries} package allows
+\cs{newglossaryentry} within the \env{document} environment (when
+used with \gls{makeindex} or \gls{xindy}) but the user manual warns
+against this usage. By default the \styfmt{glossaries-extra} package
+\emph{prohibits} this, only allowing definitions within the
+preamble. If you are really determined to define entries in the
+\env{document} environment, despite all the associated drawbacks,
+you can restore this with \pkgopt[true]{docdef}. Note that this
+doesn't change the prohibitions that the \styfmt{glossaries}
+package has in certain circumstances (for example, when using
+\qt{option~1}). See the \styfmt{glossaries} user manual for further
+details. A better option if document definitions are required
+is \pkgopt[restricted]{docdef}. Only use \pkgopt[true]{docdef}
+if document definitions are necessary and one or more of the
+glossaries occurs in the front matter.
+
+\begin{sloppypar}
+This option affects commands that internally use
+\cs{newglossaryentry}, such as \cs{newabbreviation}, but not
+the \qt{on-the-fly} commands described in \sectionref{sec:onthefly}.
+\end{sloppypar}
+
+\item[{\pkgoptdef{nomissingglstext}}] This is a boolean option.
+If true, this will suppress the warning written to the transcript
+and the warning text that will appear in the
+document if the external glossary files haven't been generated due
+to an incomplete document build. However, it's probably simpler
+just to fix whatever has caused the failure to build the external
+file or files.
+
+\item[{\pkgoptdef{abbreviations}}] This option has no value and can't
+be cancelled. If used,
+it will automatically create a new glossary with the label
+\texttt{abbreviations} and redefines \cs{glsxtrabbrvtype} to this
+label. In addition, it defines a shortcut command
+\begin{definition}[\DescribeMacro\printabbreviations]
+\cs{printabbreviations}\oarg{options}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{printglossary}[type=\cs{glsxtrabbrvtype},\meta{options}]
+\end{alltt}
+If \sty{glossaries-extra-bib2gls} is also loaded then this option
+will additionally provide:
+\begin{definition}[\DescribeMacro\printunsrtabbreviations]
+\cs{printunsrtabbreviations}\oarg{options}
+\end{definition}
+which uses \ics{printunsrtglossary}.
+
+The title of the new glossary is given by
+\begin{definition}[\DescribeMacro\abbreviationsname]
+\cs{abbreviationsname}
+\end{definition}
+If this command is already defined, it's left unchanged. Otherwise
+it's defined to \qt{Abbreviations} if \sty{babel} hasn't been loaded
+or \cs{acronymname} if \sty{babel} has been loaded. However, if
+you're using \sty{babel} it's likely you will need to change this.
+(See \sectionref{sec:lang} for further details.)
+
+\begin{important}
+If you don't use the \pkgopt{abbreviations} package option,
+the \cs{abbreviationsname} command won't be defined (unless it's
+defined by an included language file).
+\end{important}
+
+If the \pkgopt{abbreviations} option is used and the
+\pkgopt{acronym} option provided by the \styfmt{glossaries}
+package hasn't been used, then \ics{acronymtype}
+will be set to \ics{glsxtrabbrvtype} so that acronyms defined with
+\ics{newacronym} can be added to the list of abbreviations. If you
+want acronyms in the \texttt{main} glossary and other abbreviations in the
+\texttt{abbreviations} glossary then you will need to redefine
+\cs{acronymtype} to \texttt{main}:
+\begin{verbatim}
+\renewcommand*{\acronymtype}{main}
+\end{verbatim}
+
+Note that there are no analogous options to the \styfmt{glossaries}
+package's \pkgopt{acronymlists} option (or associated commands)
+as the abbreviation mechanism is handled differently with
+\styfmt{glossaries-extra}.
+
+\item[{\pkgoptdef{symbols}}] This is passed to \styfmt{glossaries} but
+will additionally define
+\begin{definition}[\DescribeMacro\glsxtrnewsymbol]
+\cs{glsxtrnewsymbol}\oarg{options}\marg{label}\marg{symbol}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{newglossaryentry}\marg{label}\{name=\marg{symbol},
+ sort=\marg{label},type=symbols,category=symbol,\meta{options}\}
+\end{alltt}
+Note that the \gloskey{sort} key is set to the \meta{label}
+not the \meta{symbol} as the symbol will likely contain commands.
+
+If \sty{glossaries-extra-bib2gls} is also loaded then this option
+will additionally provide:
+\begin{definition}[\DescribeMacro\printunsrtsymbols]
+\cs{printunsrtsymbols}\oarg{options}
+\end{definition}
+which uses \ics{printunsrtglossary}.
+
+\item[{\pkgoptdef{numbers}}] This is passed to \styfmt{glossaries} but
+will additionally define
+\begin{definition}[\DescribeMacro\glsxtrnewnumber]
+\cs{glsxtrnewnumber}\oarg{options}\marg{number}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{newglossaryentry}\marg{label}\{name=\marg{number},
+ sort=\marg{label},type=numbers,category=number,\meta{options}\}
+\end{alltt}
+
+If \sty{glossaries-extra-bib2gls} is also loaded then this option
+will additionally provide:
+\begin{definition}[\DescribeMacro\printunsrtnumbers]
+\cs{printunsrtnumbers}\oarg{options}
+\end{definition}
+which uses \ics{printunsrtglossary}.
+
+\item[{\pkgoptdef{acronyms} (or \pkgoptdef{acronym})}] This is
+passed to \styfmt{glossaries} but if
+\sty{glossaries-extra-bib2gls} is also loaded then this option
+will additionally provide:
+\begin{definition}[\DescribeMacro\printunsrtacronyms]
+\cs{printunsrtacronyms}\oarg{options}
+\end{definition}
+which uses \ics{printunsrtglossary}.
+
+\begin{important}
+This option defines a new glossary with the label \texttt{acronym}
+not \texttt{acronyms}. You may find it easier to reference it
+with the command \ics{acronymtype}.
+\end{important}
+
+\item[{\pkgoptdef{index}}] This is
+passed to \styfmt{glossaries} but if
+\sty{glossaries-extra-bib2gls} is also loaded then this option
+will additionally provide:
+\begin{definition}[\DescribeMacro\printunsrtindex]
+\cs{printunsrtindex}\oarg{options}
+\end{definition}
+which uses \ics{printunsrtglossary}.
+
+\item[{\pkgoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package
+option of the same name, this option isn't boolean but has multiple
+values:
+\begin{itemize}
+\item \pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}):
+set the shortcuts provided by the \styfmt{glossaries} package for
+acronyms (such as \cs{ac}). Note that the short and long forms don't
+use \cs{glsxtrshort} and \cs{glsxtrlong} but use the original
+\cs{acrshort} and \cs{acrlong}, which don't recognise multiple
+abbreviation styles. The better option with \styfmt{glossaries-extra}
+is \pkgopt[ac]{shortcuts}.
+
+\item \pkgopt[ac]{shortcuts}:
+set the shortcuts provided by the \styfmt{glossaries} package for
+acronyms (such as \cs{ac}) but uses the \styfmt{glossaries-extra}
+interface (such as \cs{glsxtrshort} rather than \cs{acrshort}).
+In this case \cs{ac} is defined as \cs{cgls} rather than
+\cs{gls}.
+
+\item \pkgopt[abbreviations]{shortcuts} (or
+\pkgopt[abbr]{shortcuts}):
+set the abbreviation shortcuts provided by \styfmt{glossaries-extra}. (See
+\sectionref{sec:abbrshortcuts}.) These settings don't switch on the
+acronym shortcuts provided by the \styfmt{glossaries} package.
+
+\item \pkgopt[other]{shortcuts}: set the \qt{other}
+shortcut commands, but not the shortcut commands for abbreviations
+or the acronym shortcuts provided by \styfmt{glossaries}.
+The \qt{other} shortcuts are:
+\begin{itemize}
+\item \ics{newentry} equivalent to \ics{newglossaryentry}
+\item \ics{newsym} equivalent to \ics{glsxtrnewsymbol} (see the
+\pkgopt{symbols} option).
+\item \ics{newnum} equivalent to \ics{glsxtrnewnumber} (see the
+\pkgopt{numbers} option).
+\end{itemize}
+
+\item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}):
+implements \pkgopt[ac]{shortcuts}, \pkgopt[abbreviations]{shortcuts}
+and \pkgopt[other]{shortcuts}.
+
+\item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}):
+don't define any of the shortcut commands (default).
+\end{itemize}
+
+Note that multiple invocations of the \pkgopt{shortcuts} option
+\emph{within the same option list} will override each other.
+\end{description}
+
+After the \styfmt{glossaries-extra} package has been loaded, you can
+set available options using
+\begin{definition}[\DescribeMacro\glossariesextrasetup]
+\cs{glossariesextrasetup}\marg{options}
+\end{definition}
+The \pkgopt{abbreviations} and \pkgopt{docdef} options may only be
+used in the preamble. Additionally, \pkgopt{docdef} can't be used
+after \ics{makenoidxglossaries}.
+
+\chapter{Modifications to Existing Commands and Styles}
+\label{sec:modifications}
+
+The \styfmt{glossaries} package provides \ics{nopostdesc}
+which may be used in the \gloskey{description} to suppress
+the post-description hook. The \styfmt{glossaries-extra} package
+provides another command
+\begin{definition}[\DescribeMacro\glsxtrnopostpunc]
+\cs{glsxtrnopostpunc}
+\end{definition}
+which has a similar function but only suppresses the
+post-description punctuation. It doesn't suppress the use of
+\cs{glsxtrpostdescription} which allows the use of
+category-dependent post-description hooks. (Note that the
+punctuation, which is in the original base hook \cs{glspostdescription},
+comes after the extended post-description hook
+\cs{glsxtrpostdescription} not before.) The post-description hook
+can counter-act the effect of \cs{glsxtrnopostpunc} using
+\begin{definition}[\DescribeMacro\glsxtrrestorepostpunc]
+\cs{glsxtrrestorepostpunc}
+\end{definition}
+These commands have no effect outside of the glossary (except with
+standalone entries that use \cs{glsxtractivatenopost} and
+\cs{glspostdescription}, see \sectionref{sec:glossentry}).
+
+The \styfmt{glossaries} package provides
+\begin{definition}[\DescribeMacro\glsseeitemformat]
+\cs{glsseeitemformat}\marg{label}
+\end{definition}
+to format items in a cross-reference list (identified with the
+\gloskey{see} key or \cs{glssee}). This was originally defined to
+use \cs{glsentryname}\marg{label} since it makes more sense for the
+cross-reference to match the way the term appears in the glossary.
+Unfortunately this caused a problem when the \gloskey{name} field
+was sanitized, which used to be the default setting, so
+\styfmt{glossaries} v3.0 changed the default definition of this
+command to use \cs{glsentrytext} instead. Since the \gloskey{name}
+and \gloskey{text} field are quite often the same, this change
+usually doesn't have a noticeable effect. However, now that the
+\gloskey{name} field is no longer sanitized (following the redesign
+of \styfmt{glossaries} v4.0) it makes more sense to restore this
+command to its original behaviour, but to take account of
+abbreviations \styfmt{glossaries-extra} redefines this as:
+\begin{verbatim}
+\renewcommand*{\glsseeitemformat}[1]{%
+ \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}%
+}
+\end{verbatim}
+If you want to restore the \styfmt{glossaries} v3.0+ definition just do:
+\begin{verbatim}
+\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}}
+\end{verbatim}
+The \sty{glossaries-extra} package provides \ics{glsxtrhiername}
+and its case-changing variants that may be used within
+the definition of \cs{glsseeitemformat} if required. These
+display the hierarchy for sub-entries rather than just the name,
+which may be more helpful in cross-references. See
+\sectionref{sec:see} for further details.
+
+The commands used by \styfmt{glossaries} to automatically produce an
+error if an entry is undefined (such as \ics{glsdoifexists}) are
+changed to take the \pkgopt{undefaction} option into account.
+
+The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
+version that doesn't automatically switch off the hyperlinks.
+This starred version may be used with the \catattr{targeturl}
+attribute to create a link to an external URL. (See
+\sectionref{sec:categories} for further details.)
+As from v1.12 both the starred and unstarred version check
+that the glossary doesn't already exist. (The \styfmt{glossaries}
+package omits this check.)
+
+You can now provide an ignored glossary with:
+\begin{definition}[\DescribeMacro\provideignoredglossary]
+\cs{provideignoredglossary}\marg{type}
+\end{definition}
+which will only define the glossary if it doesn't already exist.
+This also has a starred version that doesn't automatically switch
+off hyperlinks.
+
+The individual glossary displaying commands \ics{printglossary},
+\ics{printnoidxglossary} and \cs{printunsrtglossary} have two extra
+keys:
+
+\begin{itemize}
+\item \gloskey[printglossary]{target}. This is a boolean key which can
+be used to switch off the automatic hypertarget for each entry.
+Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so
+any cross-references within the glossary won't be affected. This is
+a way of avoiding duplicate target warnings if a glossary needs to
+be displayed multiple times.
+\item
+\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way
+of avoiding duplicate target names is to set a prefix
+used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect
+any hyperlinks (such as those created with \cs{gls}).
+\item
+\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do
+actually want to locally change \cs{glolinkprefix}, you can use
+the \gloskey{prefix} key instead. You need to use the matching
+\gloskey[glslink]{prefix} key in commands like \cs{gls}.
+
+\item
+\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels
+the glossary with \texttt{\cs{label}\marg{label}} and also
+defines \cs{@currentlabelname} to the glossary's TOC title
+(to provide text for \cs{nameref}). You can also set the
+label before the glossary using:
+\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel]
+\cs{glsxtrsetglossarylabel}\marg{label}
+\end{definition}
+but take care of duplicate labels if it's not scoped.
+\end{itemize}
+
+The \cs{newglossaryentry} command has three new keys:
+\begin{itemize}
+\item \gloskey{category}, which sets the category label for the given
+entry. By default this is \texttt{general}. See
+\sectionref{sec:categories} for further information about
+categories.
+\item \gloskey{alias}, which allows an entry to be alias to another
+entry. See \sectionref{sec:alias} for further details.
+\item \gloskey{seealso}, which performs much like \gloskey{see}, but
+allows for separate \qt{see} and \qt{see also} treatment.
+See \sectionref{sec:see} for further details.
+\end{itemize}
+The test file \texttt{example-glossaries-xr.tex} contains
+dummy entries with a mixture of \gloskey{see}, \gloskey{alias}
+and \gloskey{seealso} keys for use with minimal working examples.
+There are also \texttt{example-glossaries-*.bib} files that
+correspond to each \texttt{example-glossaries-*.tex} file
+for testing \gls{bib2gls}.
+
+The \cs{longnewglossaryentry} command now has a starred version
+(as from v1.12) that doesn't automatically insert
+\begin{verbatim}
+\leavevmode\unskip\nopostdesc
+\end{verbatim}
+at the end of the description field.
+\begin{definition}[\DescribeMacro\longnewglossaryentry]
+\cs{longnewglossaryentry}*\marg{label}\marg{options}\marg{description}
+\end{definition}
+The \gloskey{descriptionplural} key is left unset unless explicitly
+set in \meta{options}.
+
+The unstarred version no longer hard-codes the above code (which
+removes trailing space and suppresses the post-description hook) but instead
+uses:
+\begin{definition}[\DescribeMacro\glsxtrpostlongdescription]
+\cs{glsxtrpostlongdescription}
+\end{definition}
+This can be redefined to allow the post-description hook to work
+but retain the \cs{unskip} part if required.
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip}
+\end{verbatim}
+This will discarded unwanted trailing space at the end of the description
+but won't suppress the post-description hook.
+
+The unstarred version also alters the base \sty{glossaries} package's
+treatment of the \gloskey{descriptionplural} key. Since a
+plural description doesn't make much sense for multi-paragraph
+descriptions, the default behaviour with
+\sty{glossaries-extra}'s
+\cs{longnewglossaryentry} is to simply leave the plural description
+unset unless explicitly set using the \gloskey{descriptionplural}
+key. The \styfmt{glossaries.sty} version of this command sets the description's
+plural form to the same as the singular.\footnote{The
+\gloskey{descriptionplural} key is a
+throwback to the base package's original acronym mechanism before the introduction of
+the \gloskey{long} and \gloskey{short} keys, where the long form was
+stored in the \gloskey{description} field and the short form was stored in the
+\gloskey{symbol} field.}
+
+Note that this modified unstarred version doesn't append
+\cs{glsxtrpostlongdescription} to the description's plural form.
+
+The \ics{newterm} command (defined through the \pkgopt{index} package
+option) is modified so that the category defaults to \category{index}.
+The \ics{newacronym} command is modified to use the new abbreviation
+interface provided by \styfmt{glossaries-extra}.
+(See \sectionref{sec:abbreviations}.)
+
+The \cs{makeglossaries} command now has an optional argument.
+\begin{definition}[\DescribeMacro\makeglossaries]
+\cs{makeglossaries}\oarg{list}
+\end{definition}
+If \meta{list} is empty, \cs{makeglossaries} behaves as per
+its original definition in the \styfmt{glossaries} package,
+otherwise \meta{list} can be a comma-separated list of glossaries
+that need processing with an external indexing application.
+
+This command is not permitted with the \pkgopt[only]{record}
+package option. Without the optional argument, it's permitted
+with \pkgopt[alsoindex]{record}. With the optional argument,
+it's only permitted with the default \pkgopt[off]{record}.
+
+It should then be possible to use \cs{printglossary} for those
+glossaries listed in \meta{list} and \cs{printnoidxglossary}
+for the other glossaries. (See the accompanying file
+\texttt{sample-mixedsort.tex} for an example.)
+
+\begin{important}
+If you use the optional argument \meta{list}, you can't define
+entries in the document (even with the \pkgopt{docdef} option).
+\end{important}
+
+You will need at least version 2.20 of \gls{makeglossaries} or at
+least version 1.3 of the Lua alternative \gls{makeglossaries-lite.lua} (both distributed
+with \styfmt{glossaries} v4.27) to allow for this use of
+\cs{makeglossaries}\oarg{list}. Alternatively, use the
+\pkgopt{automake} option.
+
+\section{Entry Indexing}
+\label{sec:wrglossary}
+
+As from version 1.31, there is a new command like \cs{glsadd}
+where the mandatory argument is a comma-separated list
+of labels:
+\begin{definition}[\DescribeMacro\glsaddeach]
+\cs{glsaddeach}\oarg{options}\marg{list}
+\end{definition}
+This simply iterates over \meta{list} and does
+\cs{glsadd}\oarg{options}\marg{label} for each entry in the list.
+
+As from version 1.37, you can make commands like \cs{gls} or
+\cs{glslink} automatically use \cs{glsadd} with specific options
+when a given format is used (identified with
+\texttt{format=\marg{format}} in the optional argument of the
+corresponding \cs{gls}, \cs{glslink} etc).
+\begin{definition}[\DescribeMacro\GlsXtrAutoAddOnFormat]
+\cs{GlsXtrAutoAddOnFormat}\oarg{label}\marg{format list}\marg{glsadd options}
+\end{definition}
+The optional argument \meta{label} defaults to \cs{glslabel} and
+indicates the label to use in \cs{glsadd} and so needs to be
+expandable. The \meta{format list} is a comma-separated list
+of format values that will trigger the automated adding. The
+\meta{glsadd options} are the options to pass to \cs{glsadd} with
+\texttt{format=\marg{format}} prepended to the list.
+
+For example, with:
+\begin{verbatim}
+\GlsXtrAutoAddOnFormat{hyperbf}{counter=chapter}
+\end{verbatim}
+then \verb|\gls[format=hyperbf]{sample}| will be equivalent to
+\begin{verbatim}
+\glsadd[format=hyperbf,counter=chapter]{sample}\gls[format=hyperbf]{sample}
+\end{verbatim}
+Note that the explicit range markers will prevent a match
+unless you include them in \meta{format list} (in which case, be
+sure to add both the start and end formats).
+
+Here's another example:
+\begin{verbatim}
+\GlsXtrAutoAddOnFormat[dual.\glslabel]{hyperbf}{}
+\end{verbatim}
+In this case \verb|\gls[format=hyperbf]{sample}| will now be
+equivalent to:
+\begin{verbatim}
+\glsadd[format=hyperbf]{dual.sample}\gls[format=hyperbf]{sample}
+\end{verbatim}
+
+\begin{important}
+\cs{GlsXtrAutoAddOnFormat} is not applied to \cs{glsadd}
+as it could cause an infinite loop.
+\end{important}
+The \styfmt{glossaries-extra} package provides extra keys for
+commands like \cs{gls} and \cs{glstext}:
+\begin{description}
+\item[{\gloskey[glslink]{noindex}}] This is a boolean key. If true,
+this suppresses the indexing. (That is, it prevents \cs{gls} or
+whatever from adding a line to the external glossary file.)
+This is more useful than the \pkgopt{indexonlyfirst} package option
+provided by \styfmt{glossaries}, as the \gls{firstuse} might not be the most
+pertinent use. (If you want to apply \pkgopt{indexonlyfirst}
+to selected entries, rather than all of them, you can use
+the \catattr{indexonlyfirst} attribute, see
+\sectionref{sec:categories} for further details.)
+Note that the \gloskey[glslink]{noindex} key isn't available
+for \ics{glsadd} (and \ics{glsaddall}) since the whole purpose
+of that command is to index an entry.
+
+\item[{\gloskey[glslink]{wrgloss}}] (New to v1.14.)
+This is may only take the
+values \optfmt{before} or \optfmt{after}. By default, commands
+that both index and display link text (such as \cs{gls},
+\cs{glstext} and \cs{glslink}), perform the indexing before
+the link text as the indexing creates a whatsit that can cause
+problems if it occurs after the link text. However, it may
+be that in some cases (such as long phrases) you may actually
+want the indexing performed after the link text. In this
+case you can use \texttt{wrgloss=after} for specific
+instances. Note that this option doesn't
+have an effect if the indexing has been suppressed through
+other settings (such as \gloskey[glslink]{noindex}).
+
+The default value is set up using
+\begin{definition}[\DescribeMacro\glsxtrinitwrgloss]
+\cs{glsxtrinitwrgloss}
+\end{definition}
+which is defined as:
+\begin{verbatim}
+\newcommand*{\glsxtrinitwrgloss}{%
+ \glsifattribute{\glslabel}{wrgloss}{after}%
+ {%
+ \glsxtrinitwrglossbeforefalse
+ }%
+ {%
+ \glsxtrinitwrglossbeforetrue
+ }%
+}
+\end{verbatim}
+This sets the conditional
+\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore]
+\cs{ifglsxtrinitwrgloss}
+\end{definition}
+which is used to determine where to perform the indexing.
+
+This means you can set the \catattr{wrgloss}
+attribute to \optfmt{after} to automatically use this as
+the default for entries with that category attribute. (Note that
+adding \gloskey[glslink]{wrgloss} to the default options
+in \ics{GlsXtrSetDefaultGlsOpts} will override
+\cs{glsxtrinitwrgloss}.)
+
+\item[{\gloskey[glslink]{hyperoutside}}] (New to v1.21.) This is a
+boolean key. The default is \texttt{hyperoutside=true}, which puts
+the hyperlink outside \cs{glstextformat}, so that commands like
+\cs{gls} will effectively do
+\begin{alltt}
+\cs{hyperlink}\marg{target}\{\cs{glstextformat}\marg{link text}\}
+\end{alltt}
+This is the same behaviour as with the base \styfmt{glossaries}
+package. With \texttt{hyperoutside=false}, \cs{hyperlink} is placed
+inside the argument of \cs{glstextformat}:
+\begin{alltt}
+\cs{glstextformat}\{\cs{hyperlink}\marg{target}\marg{link text}\}
+\end{alltt}
+You can use the \catattr{hyperoutside} category attribute to set
+the default for a given category. This can be combined
+with the use of the \catattr{textformat} attribute to counteract
+any interference caused by \cs{hyperlink}.
+For example:
+\begin{verbatim}
+\glssetcategoryattribute{mathrelation}{hyperoutside}{false}
+\end{verbatim}
+will set \texttt{hyperoutside=false} for all entries that are
+assigned to the category \texttt{mathrelation} and
+\begin{verbatim}
+\glssetcategoryattribute{mathrelation}{textformat}{mathrel}
+\end{verbatim}
+will use \cs{mathrel} instead of \cs{glstextformat} resulting in:
+\begin{alltt}
+\cs{mathrel}\{\cs{hyperlink}\marg{target}\marg{link text}\}
+\end{alltt}
+for entries with the \gloskey{category} key set to
+\texttt{mathrelation}.
+
+\item[{\gloskey[glslink]{textformat}}] This key must have a
+control sequence name as its value. The command formed from
+this name must exist and must take one argument. (Use
+\texttt{relax} for default behaviour.) If set, this overrides
+the \catattr{textformat} attribute and \cs{glstextformat}.
+See the \sty{soul} example in \sectionref{sec:glsunset}.
+
+\item[{\gloskey[glslink]{prefix}}] Locally redefines
+\ics{glolinkprefix} to the given value. It should match the prefix
+for the desired glossary.
+
+\item[{\gloskey[glslink]{thevalue}}] Explicitly set the location to
+this value (see below).
+
+\item[{\gloskey[glslink]{theHvalue}}] Set the corresponding
+hyperlink location (see below).
+
+\end{description}
+
+There is a new hook that's used each time indexing information is
+written to the external glossary files:
+\begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook]
+\cs{glsxtrdowrglossaryhook}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. This does nothing by
+default but may be redefined. (See, for example, the
+accompanying sample file \texttt{sample-indexhook.tex},
+which uses this hook to determine which entries haven't been
+indexed.)
+
+There's also a new hook (from v1.26) that's used immediately
+before the options are set by the \cs{gls}-like and
+\cs{glstext}-like commands:
+\begin{definition}[\DescribeMacro\glslinkpresetkeys]
+\cs{glslinkpresetkeys}
+\end{definition}
+(The base package provides \ics{glslinkpostsetkeys} that's
+used immediately after the options are set.)
+
+As from version 1.30 there are also similar hooks for \cs{glsadd}:
+\begin{definition}[\DescribeMacro\glsaddpresetkeys]
+\cs{glsaddpresetkeys}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glsaddpostsetkeys]
+\cs{glsaddpostsetkeys}
+\end{definition}
+For example, to default to using the \ctr{equation} counter in maths
+mode:
+\begin{verbatim}
+\renewcommand{\glslinkpresetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpresetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+In this case, the counter can be overridden with an explicit use of
+\gloskey{counter} in the optional argument of \cs{gls} or
+\cs{glsadd}. (As from version 1.37, a simpler method is to just use
+the \pkgopt{equations} package option.)
+
+Alternatively, to enforce this (overriding the option
+argument):
+\begin{verbatim}
+\renewcommand{\glslinkpostsetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpostsetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+
+As from version 1.14, there are two new keys for \cs{glsadd}:
+\gloskey[glsadd]{thevalue} and \gloskey[glsadd]{theHvalue}.
+These keys are designed for manually adding explicit locations
+rather than obtaining the value from the associated counter.
+As from version 1.19, these two keys are also available for commands
+like \cs{gls} and \cs{glslink}. The \gloskey[glsadd]{thevalue} keys is
+intended primarily for adding locations in supplementary material
+that can't be obtained from a counter.
+
+The principle key \gloskey[glslink]{thevalue} is for the location value. The
+other key \gloskey[glslink]{theHvalue} can be used to
+extract a prefix value for the first argument of commands like
+\ics{glsnoidxdisplayloc}. Its value must be in the format
+\meta{prefix}\meta{location}. In general, there's little need for
+this key as the prefix is typically associated with a counter that can be
+used to form hypertargets.
+
+\begin{important}
+If you use \gloskey[glsadd]{thevalue}, you must make sure that you
+use an indexing application that will accept the given value.
+\end{important}
+
+For example, \app{makeindex} will only accept locations in the form
+[\meta{num}\meta{sep}]*\meta{num} where \meta{num} is an arabic
+number (0, 1, \ldots), roman numeral (i, ii, \ldots\ or I, II,
+\ldots) or a character from a, \ldots, z or A, \ldots, Z, and
+[\meta{num}\meta{sep}]* indicates zero or more instances of a number
+followed by the recognised separator character (set with
+\cs{glsSetCompositor}). This means that \app{makeindex} won't
+accept, for example,
+\begin{verbatim}
+\glsadd[thevalue={Supplementary Material}]{sample}
+\end{verbatim}
+This location value will be accepted by \gls{bib2gls}, since it will
+allow any location and will only try forming ranges if the location
+matches any of its numerical patterns.
+In the case of \app{xindy}, you'll need to add a rule that can match
+the value. If you're using \sty{hyperref}, you may need to use the
+\gloskey[glslink]{format} key to prevent a hyperlink if one can't
+naturally be formed from the prefix, counter and location value.
+
+For example, suppose the file \texttt{suppl.tex} contains:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\renewcommand{\thepage}{S.\arabic{page}}
+
+\begin{document}
+First page.
+\newpage
+\gls{sample}.
+\end{document}
+\end{verbatim}
+This has an entry on page S.2. Suppose another document wants to
+include this location in the glossary. Then this can be done by
+setting \gloskey[glsadd]{thevalue} to \texttt{S.2}. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\begin{document}
+Some \gls{sample} text.
+
+\printglossaries
+\glsadd[thevalue={S.2}]{sample}
+\end{document}
+\end{verbatim}
+This location value will be accepted by \app{makeindex} as it's in
+the form \meta{num}\meta{sep}\meta{num}.
+
+If you want hyperlinks, things are more complicated. First
+you need to set the \catattr{externallocation} attribute to the location of
+the PDF file. For example:
+\begin{verbatim}
+\glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf}
+
+\newglossaryentry{sample}{category=supplemental,
+ name={sample},description={an example}}
+\end{verbatim}
+Next you need to add \texttt{glsxtrsupphypernumber} as the format:
+\begin{verbatim}
+\glsadd[thevalue={S.2},format=glsxtrsupphypernumber]{sample}
+\end{verbatim}
+Both documents will need to use the \sty{hyperref} package.
+Remember that the counter used for the location also needs to match.
+If \cs{theH}\meta{counter} is defined in the other document
+and doesn't match in the referencing document, then you need
+to use \gloskey[glsadd]{theHvalue} to set the appropriate value.
+See the accompanying sample files \texttt{sample-suppl-hyp.tex}
+and \texttt{sample-suppl-main-hyp.tex} for an example that uses
+\sty{hyperref}.
+
+\begin{important}
+The hyperlink for the supplementary location may or \emph{may not}
+take you to the relevant place in the external PDF file
+\emph{depending on your PDF viewer}. Some may not support external
+links, and some may take you to the first page or last visited page.
+\end{important}
+
+For example, if both \texttt{sample-suppl-hyp.pdf}
+and \texttt{sample-suppl-main-hyp.pdf} are in the same directory,
+then viewing \texttt{sample-suppl-main-hyp.pdf} in Evince will
+take you to the correct location in the linked document (when you
+click on the S.2 external link), but Okular will take you to the top
+of the first page of the linked document.
+
+This method can only be used where there is one external source
+for the designated category (identified by the
+\catattr{externallocation} attribute). For multiple sources, you need to use
+\gls{bib2gls} version 1.7+, which is the better method in general as it can
+automatically fetch the relevant locations from the \texttt{.aux}
+files of the designated external documents without the need to
+explicitly use \cs{glsadd}.
+
+\section{Cross-References (\qt{see} and \qt{see also})}
+\label{sec:see}
+
+The value of the \gloskey{see} key is now saved
+as a field. This isn't the case with \styfmt{glossaries}, where
+the \gloskey{see} value is simply used to directly
+write a line to the corresponding glossary file and is then
+discarded. This is why the \gloskey{see} key can't be
+used before \ics{makeglossaries} (since the file hasn't been opened
+yet). It's also the reason why the \gloskey{see} key doesn't have
+any effect when used in entries that are defined in the
+\env{document} environment. Since the value isn't saved,
+it's not available when the \texttt{.glsdefs} file is created at the
+end of the document and so isn't available at the start of the
+\env{document} environment on the next run.
+
+This modification allows \styfmt{glossaries-extra} to provide
+\begin{definition}[\DescribeMacro\glsxtraddallcrossrefs]
+\cs{glsxtraddallcrossrefs}
+\end{definition}
+which is used at the end of the document to automatically add
+any unused cross-references unless the package option
+\pkgopt{indexcrossrefs} was set to false.
+
+As a by-product of this enhancement, the \gloskey{see} key will now
+work for entries defined in the \env{document} environment, but it's still
+best to define entries in the preamble, and the \gloskey{see} key
+still can't perform any indexing before the file has been opened by
+\cs{makeglossaries}. Note that \styfmt{glossaries} v4.24 introduced
+the \pkgopt{seenoindex} package option, which can be used to
+suppress the error when the \gloskey{see} key is used before
+\cs{makeglossaries}, so \pkgopt[ignore]{seenoindex} will allow the
+\gloskey{see} value to be stored even though it may not be possible
+to index it at that point.
+
+As from version 1.06, you can display the cross-referenced
+information for a given entry using
+\begin{definition}[\DescribeMacro\glsxtrusesee]
+\cs{glsxtrusesee}\marg{label}
+\end{definition}
+This internally uses
+\begin{definition}[\DescribeMacro\glsxtruseseeformat]
+\cs{glsxtruseseeformat}\marg{tag}\marg{xr list}
+\end{definition}
+where \meta{tag} and \meta{xr list} are obtained from the value of
+the entry's \gloskey{see} field (if non-empty).
+By default, this just does \cs{glsseeformat}\oarg{tag}\marg{xr
+list}\verb|{}|, which is how the cross-reference is displayed in the
+\gls{numberlist}. Note that \cs{glsxtrusesee} does nothing if the
+\gloskey{see} field hasn't been set for the entry given by
+\meta{label}.
+
+As with the base \sty{glossaries} package, \cs{glsseeformat}
+is defined to do \texttt{\cs{emph}\marg{tag} \cs{glsseelist}\marg{xr
+list}}. The third argument is always ignored and is present for
+\app{makeindex}, which always requires a final argument to
+encapsulate the associated location. The command
+\begin{definition}
+\ics{glsseelist}\marg{xr list}
+\end{definition}
+used to iterate over the list of cross-reference labels is also
+unchanged from the base \sty{glossaries} package, with each item in
+the list formatted according to:
+\begin{definition}
+\ics{glsseeitem}\marg{label}
+\end{definition}
+This is defined by the \sty{glossaries} package to:
+\begin{alltt}
+\cs{glshyperlink}[\cs{glsseeitemformat}\marg{label}]\marg{label}
+\end{alltt}
+So the actual formatting for each cross-referenced entry is
+performed by \ics{glsseeitemformat}, which is redefined by
+\sty{glossaries-extra}, as described in
+\sectionref{sec:modifications}. This now displays the value
+of the \gloskey{text} field for abbreviations and the value
+of the \gloskey{name} field otherwise. There's no indication
+of the entry hierarchy, which could confuse the reader. Therefore,
+as from \sty{glossaries-extra} v1.37, there are some new commands
+that include the hierarchical information. You may prefer to
+redefine \cs{glsseeitemformat} to use one of this if you have
+sub-entries. For example:
+\begin{verbatim}
+\renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}}
+\end{verbatim}
+
+The command:
+\begin{definition}[\DescribeMacro\glsxtrhiername]
+\cs{glsxtrhiername}\marg{label}
+\end{definition}
+performs a recursive action:
+\begin{enumerate}
+\item If the entry given by \meta{label} has a parent, then
+\cs{glsxtrhiername}\marg{parent label} is done followed by
+\cs{glsxtrhiernamesep} then:
+\item If the entry given by \meta{label} is an abbreviation
+(that is, it has the \gloskey{short} field set) then
+the short form is displayed (using \cs{glsaccessshort})
+otherwise the name is displayed (using \cs{glsaccessname}).
+\end{enumerate}
+The first step above is skipped if the entry doesn't have a parent.
+Each level is separated by:
+\begin{definition}[\DescribeMacro\glsxtrhiernamesep]
+\cs{glsxtrhiernamesep}
+\end{definition}
+which defaults to \qt{\glsxtrhiernamesep}. This can be redefined as
+appropriate.
+
+There are some case-changing variants:
+\begin{definition}[\DescribeMacro\Glsxtrhiername]
+\cs{Glsxtrhiername}\marg{label}
+\end{definition}
+The top-level has the first letter changed to upper case
+(either \cs{Glsaccessshort} or \cs{Glsaccessname}). There's
+no case-change for sub-entries.
+
+\begin{definition}[\DescribeMacro\GlsXtrhiername]
+\cs{GlsXtrhiername}\marg{label}
+\end{definition}
+All levels have the first letter changed to upper case
+(either \cs{Glsaccessshort} or \cs{Glsaccessname}).
+
+\begin{definition}[\DescribeMacro\GLSxtrhiername]
+\cs{GLSxtrhiername}\marg{label}
+\end{definition}
+The top-level is converted to upper case
+(either \cs{GLSaccessshort} or \cs{GLSaccessname}). There's
+no case-change for sub-entries.
+
+\begin{definition}[\DescribeMacro\GLSXTRhiername]
+\cs{GLSXTRhiername}\marg{label}
+\end{definition}
+All levels are converted to upper case
+(either \cs{GLSaccessshort} or \cs{GLSaccessname}).
+
+Suppose you want to suppress the \gls*{numberlist}
+using \pkgopt{nonumberlist}. This will automatically prevent the
+cross-references from being displayed. The
+\pkgopt{seeautonumberlist} package option will automatically
+enable the \gls*{numberlist} for entries that have the \gloskey{see}
+key set, but this will also show the rest of the \gls*{numberlist}.
+
+Another approach in this situation is to use the post description
+hook with \cs{glsxtrusesee} to append the cross-reference after
+the description. For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrpostdescgeneral}{%
+ \ifglshasfield{see}{\glscurrententrylabel}
+ {, \glsxtrusesee{\glscurrententrylabel}}%
+ {}%
+}
+\end{verbatim}
+Now the cross-references can appear even though the \gls{numberlist}
+has been suppressed.
+
+As from v1.16, there's a separate \gloskey{seealso} key. Unlike
+\gloskey{see}, this doesn't have an optional part for the textual
+tag. The syntax \texttt{seealso=\marg{xr-labels}} works in much the same way as using
+\texttt{see=[\cs{seealsoname}]\marg{xr-labels}} but the information
+is stored in a separate field. If you need a different tag, use the
+\gloskey{see} key instead (or redefine \cs{seealsoname} or
+\cs{glsxtruseseealsoformat}, described below).
+
+You can display the formatted list of
+cross-references stored in the \gloskey{seealso} key using:
+\begin{definition}[\DescribeMacro\glsxtruseseealso]
+\cs{glsxtruseseealso}\marg{label}
+\end{definition}
+This works in much the same way as \cs{glsxtrusesee}
+but it internally uses
+\begin{definition}[\DescribeMacro\glsxtruseseeformat]
+\cs{glsxtruseseealsoformat}\marg{xr list}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrpostdescgeneral}{%
+ \ifglshasfield{see}{\glscurrententrylabel}
+ {, \glsxtrusesee{\glscurrententrylabel}}%
+ {}%
+ \ifglshasfield{seealso}{\glscurrententrylabel}
+ { (\glsxtruseseealso{\glscurrententrylabel})}%
+ {}%
+}
+\end{verbatim}
+
+The actual unformatted comma-separated list \meta{xr-list}
+stored in the \gloskey{seealso} field can be accessed with:
+\begin{definition}[\DescribeMacro\glsxtrseealsolabels]
+\cs{glsxtrseealsolabels}\marg{label}
+\end{definition}
+This will just expand to the \meta{xr-labels} provided in the value
+of the \gloskey{seealso} key. There's no corresponding command to
+access the \gloskey{see} field. If you really need to access it, you
+can use commands like \cs{glsxtrfielduse}, but remember that it
+may start with \oarg{tag}, so it can't be automatically treated
+as a simple comma-separated list.
+
+As mentioned above, the base \styfmt{glossaries} package provides \ics{glsseelist},
+which requires a comma-separated list of labels as the argument.
+The argument isn't fully expanded, so it's not suitable to use, for
+example, \cs{glsxtrseealsolabels}\marg{label} as the argument.
+For convenience, \styfmt{glossaries-extra} provides
+\begin{definition}[\DescribeMacro\glsxtrseelist]
+\cs{glsxtrseelist}\marg{xr list}
+\end{definition}
+which fully expands its argument and passes it to \cs{glsseelist}.
+
+The \gloskey{seealso} key implements the automatic indexing using
+\begin{definition}[\DescribeMacro\glsxtrindexseealso]
+\cs{glsxtrindexseealso}\marg{label}\marg{xr list}
+\end{definition}
+which just does
+\begin{alltt}
+\cs{glssee}[\cs{seealsoname}]\marg{label}\marg{xr list}
+\end{alltt}
+unless the \pkgopt{xindy} option is used with \sty{glossaries}
+v4.30+, in which case a distinct \texttt{seealso} cross-reference
+class is used instead.
+
+\section{Entry Display Style Modifications}
+\label{sec:entryfmtmods}
+
+Recall from the \styfmt{glossaries} package that commands such as \cs{gls}
+display text at that point in the document (optionally with a
+hyperlink to the relevant line in the glossary). This text is
+referred to as the \qt{\gls{linktext}} regardless of whether or not it
+actually has a hyperlink. The actual text and the way it's displayed
+depends on the command used (such as \cs{gls}) and the entry format.
+
+The default entry format (\ics{glsentryfmt}) used in the
+\gls{linktext} by commands like \ics{gls}, \ics{glsxtrfull},
+\ics{glsxtrshort} and \ics{glsxtrlong} (but not commands like
+\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by \styfmt{glossaries-extra} to test for
+regular entries, which are determined as follows:
+
+\begin{itemize}
+\item If an entry is assigned to a category that has the
+\catattr{regular} attribute set (see \sectionref{sec:categories}), the entry is considered a~regular
+entry, even if it has a~value for the \gloskey{short} key.
+In this case \cs{glsentryfmt} uses \ics{glsgenentryfmt}
+(provided by \styfmt{glossaries}), which uses the \gloskey{first}
+(or \gloskey{firstplural}) value on \gls{firstuse} and the
+\gloskey{text} (or \gloskey{plural}) value on subsequent use.
+
+\item An entry that doesn't have a~value for the \gloskey{short}
+key is assumed to be a~regular entry, even if the
+\catattr{regular} attribute isn't set to \qt{true} (since it can't
+be an abbreviation without the short form).
+In this case \cs{glsentryfmt} uses \ics{glsgenentryfmt}.
+
+\item If an entry does has a~value for the \gloskey{short} key
+and hasn't been marked as a~regular entry through the
+\catattr{regular} attribute, it's not considered a regular entry.
+In this case \cs{glsentryfmt} uses \ics{glsxtrgenabbrvfmt}
+(defined by \styfmt{glossaries-extra}) which is governed
+by the abbreviation style (see \sectionref{sec:abbrstyle}).
+
+\end{itemize}
+
+This means that entries with a short
+form can be treated as regular entries rather than
+abbreviations if it's more appropriate for the desired style.
+
+As from version 1.04, \ics{glsentryfmt} now puts \ics{glsgenentry}
+in the argument of the new command
+\begin{definition}[\DescribeMacro\glsxtrregularfont]
+\cs{glsxtrregularfont}\marg{text}
+\end{definition}
+This just does its argument \meta{text} by default. This means that
+if you want regular entries in a different font but don't want
+that font to apply to abbreviations, then you can redefine
+\cs{glsxtrregularfont}. This is more precise than changing
+\ics{glstextformat} which is applied to all linking commands
+for all entries, unless overridden by the \catattr{textformat}
+attribute.
+
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrregularfont}[1]{\textsf{#1}}
+\end{verbatim}
+You can access the label through \cs{glslabel}. For example,
+you can query the category:
+\begin{verbatim}
+\renewcommand*{\glsxtrregularfont}[1]{%
+ \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
+\end{verbatim}
+or query the category attribute, for example, provide a custom
+attribute called \texttt{font}:
+\begin{verbatim}
+\glssetcategoryattribute{general}{font}{sf}
+
+\renewcommand*{\glsxtrregularfont}[1]{%
+ \glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
+\end{verbatim}
+As from version 1.21, it's simpler to just do, for example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{textformat}{textsf}
+\end{verbatim}
+without redefining \cs{glsxtrregularfont}.
+
+As from version 1.30, there is also a command for abbreviations
+that encapsulates \cs{glsxtrgenabbrvfmt}:
+\begin{definition}[\DescribeMacro\glsxtrabbreviationfont]
+\cs{glsxtrabbreviationfont}\marg{text}
+\end{definition}
+This also just does its argument by default. Font changes
+made by abbreviation styles are within \meta{text}.
+
+The \cs{glspostlinkhook} provided by the \styfmt{glossaries} package to
+insert information after the \gls{linktext} produced by commands like \cs{gls} and \cs{glstext} is
+redefined to
+\begin{definition}[\DescribeMacro\glsxtrpostlinkhook]
+\cs{glsxtrpostlinkhook}
+\end{definition}
+This command will discard a following full stop (period) if the
+\catattr{discardperiod} attribute is set to \qt{true} for the
+current entry's category. It will also do
+\begin{definition}[\DescribeMacro\glsxtrpostlink]
+\cs{glsxtrpostlink}
+\end{definition}
+if a full stop hasn't be discarded and
+\begin{definition}[\DescribeMacro\glsxtrpostlinkendsentence]
+\cs{glsxtrpostlinkendsentence}
+\end{definition}
+if a full stop has been discarded.
+
+It may be that you want to check some other setting (rather
+than a category attribute) to determine whether or not to discard
+a following full stop. In which case you can redefine:
+\begin{definition}[\DescribeMacro\glsxtrifcustomdiscardperiod]
+\cs{glsxtrifcustomdiscardperiod}\marg{true}\marg{false}
+\end{definition}
+You can access the field's label using \cs{glslabel}.
+This command should do \meta{true} if the post-link hook
+should check if a period follows and \meta{false} otherwise.
+The default definition is simply:
+\begin{verbatim}
+\newcommand*{\glsxtrifcustomdiscardperiod}[2]{#2}
+\end{verbatim}
+which means that no additional checks are performed.
+(Only the recognised category attributes will be checked.)
+
+\begin{important}
+Avoid the use of \cs{gls}-like and \cs{glstext}-like commands
+within the post-link hook as they will cause interference.
+Consider using commands like \cs{glsentrytext}, \cs{glsaccesstext}
+or \cs{glsxtrp} (\sectionref{sec:nested}) instead.
+\end{important}
+
+By default \cs{glsxtrpostlink} just does \postlinkcat\ if it exists, where
+\meta{category} is the category label for the current entry.
+(For example, for the \category{general} category,
+\cs{glsxtrpostlinkgeneral} if it has been defined.)
+
+You can define the post-link hook command using \cs{newcommand}, for
+example:
+\begin{verbatim}
+\newcommand*{\glsxtrpostlinkgeneral}{%
+ \glsxtrpostlinkAddDescOnFirstUse
+}
+\end{verbatim}
+or, as from v1.31, you can use
+\begin{definition}[\DescribeMacro\glsdefpostlink]
+\cs{glsdefpostlink}\marg{category}\marg{definition}
+\end{definition}
+This is simply a shortcut for:
+\begin{alltt}
+\cs{csdef}\{glsxtrpostlink\meta{category}\}\marg{definition}
+\end{alltt}
+Note that it doesn't check if the command has already been defined.
+
+\begin{sloppypar}
+The sentence-ending hook is slightly more complicated.
+If the command \postlinkcat\ is defined the hook will do that
+and then insert a full stop with the space factor adjusted to match
+the end of sentence. If \postlinkcat\ hasn't
+been defined, the space factor is adjusted to match the end of
+sentence. This means that if you have, for example, an entry that
+ends with a full stop, a redundant following full stop will be
+discarded and the space factor adjusted (in case the entry is in
+uppercase) unless the entry is followed by additional material, in
+which case the following full stop is no longer redundant and needs
+to be reinserted.
+\end{sloppypar}
+
+There are some convenient commands you might want to use
+when customizing the post-\gls{linktext} category hooks:
+\begin{definition}[\DescribeMacro\glsxtrpostlinkAddDescOnFirstUse]
+\cs{glsxtrpostlinkAddDescOnFirstUse}
+\end{definition}
+This will add the description in parentheses on \gls{firstuse}.
+
+For example, suppose you want to append the description in
+parentheses on \gls{firstuse} for entries in the \category{symbol}
+category:
+\begin{verbatim}
+\newcommand*{\glsxtrpostlinksymbol}{%
+ \glsxtrpostlinkAddDescOnFirstUse
+}
+\end{verbatim}
+
+\begin{definition}[\DescribeMacro\glsxtrpostlinkAddSymbolOnFirstUse]
+\cs{glsxtrpostlinkAddSymbolOnFirstUse}
+\end{definition}
+This will append the symbol (if defined) in parentheses on
+\gls{firstuse}. (Does nothing if the symbol hasn't been set.)
+
+\begin{definition}[\DescribeMacro\glsxtrpostlinkAddSymbolDescOnFirstUse]
+\cs{glsxtrpostlinkAddSymbolDescOnFirstUse}
+\end{definition}
+(New to v1.31.) On \gls{firstuse},
+this will append \cs{space}(\meta{symbol}, \meta{description}) if
+the symbol is defined otherwise it just appends
+\cs{space}(\meta{description}).
+
+If you want to provide your own custom format be aware that you
+can't use \ics{ifglsused} within the post-\gls{linktext} hook as by this point
+the \gls{firstuseflag} will have been unset. Instead you can use
+\begin{definition}[\DescribeMacro\glsxtrifwasfirstuse]
+\cs{glsxtrifwasfirstuse}\marg{true}\marg{false}
+\end{definition}
+This will do \meta{true} if the last used entry was the
+\gls{firstuse}
+for that entry, otherwise it will do \meta{false}. (Requires at
+least \styfmt{glossaries} v4.19 to work properly.) This command is
+locally set by commands like \cs{gls}, so don't rely on it outside
+of the post-\gls{linktext} hook.
+
+\begin{important}
+Note that commands like \ics{glsfirst} and \ics{glsxtrfull} fake
+\gls{firstuse} for the benefit of the post-\gls{linktext} hooks by setting
+\cs{glsxtrifwasfirstuse} to \cs{@firstoftwo}.
+(Although, depending on the styles in use, they may not exactly match
+the text produced by \ics{gls}-like commands on \gls{firstuse}.)
+However, the \abbrstyle{short-postfootnote} style alters \cs{glsxtrfull}
+so that it fakes non-\gls{firstuse} otherwise the inline full format
+would include the footnote, which is inappropriate.
+\end{important}
+
+For example, if you want to place the description in a footnote
+after the \gls{linktext} on \gls{firstuse} for the \category{general} category:
+\begin{verbatim}
+\newcommand*{\glsxtrpostlinkgeneral}{%
+ \glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}%
+}
+\end{verbatim}
+
+The \abbrstyle{short-postfootnote} abbreviation style uses the
+post-\gls{linktext} hook to
+place the footnote after trailing punctuation characters.
+
+You can set the default options used by \ics{glslink}, \ics{gls}
+etc with:
+\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts]
+\cs{GlsXtrSetDefaultGlsOpts}\marg{options}
+\end{definition}
+For example, if you mostly don't want to index entries then
+you can do:
+\begin{verbatim}
+\GlsXtrSetDefaultGlsOpts{noindex}
+\end{verbatim}
+and then use, for example, \verb|\gls[noindex=false]{sample}|
+when you actually want the location added to the \gls{numberlist}.
+These defaults may be overridden by other settings (such as
+category attributes) in addition to any settings passed in the
+option argument of commands like \cs{glslink} and \cs{gls}.
+
+Note that if you don't want \emph{any} indexing, just omit
+\cs{makeglossaries} and \cs{printglossaries} (or analogous
+commands). If you want to adjust the default for
+\gloskey[glslink]{wrgloss}, it's better to do this by redefining
+\ics{glsxtrinitwrgloss} instead.
+
+\begin{important}
+\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}.
+\end{important}
+
+If you want to change the default value of \gloskey[glsadd]{format},
+you can instead use:
+\begin{definition}[\GlsXtrSetDefaultNumberFormat]
+\cs{GlsXtrSetDefaultNumberFormat}\marg{format}
+\end{definition}
+This has the advantage of also working for \cs{glsadd}.
+For example, if you want all locations in the back matter to appear
+in italic (unless explicitly overridden):
+\begin{verbatim}
+\backmatter
+\GlsXtrSetDefaultNumberFormat{hyperit}
+\end{verbatim}
+
+Commands like \ics{gls} have star (\texttt{*}) and plus
+(\texttt{+}) modifiers as a short cut for \texttt{hyper=false}
+and \texttt{hyper=true}. The \styfmt{glossaries-extra} package
+provides a way to add a third modifier, if required, using
+\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier]
+\cs{GlsXtrSetAltModifier}\marg{char}\marg{options}
+\end{definition}
+where \meta{char} is the character used as the modifier and
+\meta{options} is the default set of options (which may be
+overridden). Note that \meta{char} must be a single character
+(not a UTF-8 character, unless you are using \XeLaTeX\ or
+\LuaLaTeX).
+
+\begin{important}
+When choosing the character \meta{char} take care of any
+changes in category code.
+\end{important}
+
+Example:
+\begin{verbatim}
+\GlsXtrSetAltModifier{!}{noindex}
+\end{verbatim}
+This means that \verb|\gls!{sample}| will be equivalent to
+\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers.
+For example, if you want to do
+\begin{verbatim}
+\gls[noindex,hyper=false]{sample}
+\end{verbatim}
+you can use \verb|\gls*[noindex]{sample}| or
+\verb|\gls![hyper=false]{sample}| but you can't combine the
+\texttt{*} and \texttt{!} modifiers.
+
+\Glspl{locationlist} displayed with \cs{printnoidxglossary}
+internally use
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+This command is provided by \styfmt{glossaries}, but is modified by
+\styfmt{glossaries-extra} to check for the start and end range
+formation identifiers \verb|(| and \verb|)| which are discarded to
+obtain the actual control sequence name that forms the location
+formatting command.
+
+If the range identifiers aren't present, this just uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc]
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{definition}
+otherwise it uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc]
+\cs{glsxtrdisplaystartloc}\marg{format}\marg{location}
+\end{definition}
+for the start of a range (where the identifier has been stripped
+from \meta{format}) or
+\begin{definition}[\DescribeMacro\glsxtrdisplayendloc]
+\cs{glsxtrdisplayendloc}\marg{format}\marg{location}
+\end{definition}
+for the end of a range (where the identifier has been stripped
+from \meta{format}).
+
+By default the start range command saves the format in
+\begin{definition}[\DescribeMacro\glsxtrlocrangefmt]
+\cs{glsxtrlocrangefmt}
+\end{definition}
+and does
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+(If the format is empty, it will be replaced with
+\texttt{glsnumberformat}.)
+
+The end command checks that the format matches the start of the
+range, does
+\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook]
+\cs{glsxtrdisplayendlochook}\marg{format}\marg{location}
+\end{definition}
+(which does nothing by default), followed by
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+and then sets \cs{glsxtrlocrangefmt} to empty.
+
+This means that the list
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{(textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{)textbf}{1}.
+\end{verbatim}
+doesn't display any differently from
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1}.
+\end{verbatim}
+but it does make it easier to define your own custom list handler
+that can accommodate the ranges.
+
+
+\section{Entry Counting Modifications}
+\label{sec:entrycountmods}
+
+If you are using \gls{bib2gls} you may find it more convenient
+to use the record count commands described in
+\sectionref{sec:bib2gls} instead.
+
+The \ics{glsenableentrycount} command is modified to allow
+for the \catattr{entrycount} attribute. This means that
+you not only need to enable entry counting with
+\cs{glsenableentrycount}, but you also need
+to set the appropriate attribute (see \sectionref{sec:categories}).
+
+For example, instead of just doing:
+\begin{verbatim}
+\glsenableentrycount
+\end{verbatim}
+you now need to do:
+\begin{verbatim}
+\glsenableentrycount
+\glssetcategoryattribute{abbreviation}{entrycount}{1}
+\end{verbatim}
+This will enable the entry counting for entries in the
+\category{abbreviation} category, but any entries assigned to
+other categories will be unchanged.
+
+Further information about entry counting, including the
+new per-unit feature, is described in \sectionref{sec:entrycount}.
+
+\section{First Use Flag}
+\label{sec:glsunset}
+
+The \styfmt{glossaries} package provides
+\begin{definition}
+\ics{ifglsused}\marg{label}\marg{true}\marg{false}
+\end{definition}
+to determine whether or not an entry has been used. This requires
+the entry to have been defined. If the entry is undefined, then the
+underlying boolean variable doesn't exist and so is neither true
+nor false. This command will produce an error with the default
+\pkgopt[error]{undefaction} mode and a warning with
+\pkgopt[warn]{undefaction} and, where appropriate, displays ?? in
+the document text to denote an undefined reference. With both modes,
+neither \meta{true} nor \meta{false} will be performed if
+\meta{label} doesn't exist.
+
+The \pkgopt{record} option automatically implements
+\pkgopt[warn]{undefaction} since no entries will be defined until
+they have been selected by \gls{bib2gls}. In this case, you
+may prefer to use:
+\begin{definition}[\DescribeMacro\GlsXtrIfUnusedOrUndefined]
+\cs{GlsXtrIfUnusedOrUndefined}\marg{label}\marg{true}\marg{false}
+\end{definition}
+(new to v1.34) which does \meta{true} if the entry given by
+\meta{label} is undefined or if the entry is marked as unused.
+Remember that neither \cs{ifglsused} nor
+\cs{GlsXtrIfUnusedOrUndefined} should be used in the post-link
+hook as the \gls{firstuseflag} will have already been unset
+before the hook is performed. (Instead, \ics{glsxtrifwasfirstuse}
+should be used, see \sectionref{sec:entryfmtmods}.)
+
+There are two new commands provided with version 1.31+:
+\begin{definition}[\DescribeMacro\glslocalreseteach]
+\cs{glslocalreseteach}\marg{list}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslocalunseteach]
+\cs{glslocalunseteach}\marg{list}
+\end{definition}
+These behave like \cs{glslocalreset} and \cs{glslocalunset}
+but the argument is a comma-separated list of labels.
+
+The internal command used by \cs{glsunset} is modified first to
+allow for the changing in entry counting, described above, but
+also to allow for buffering pending unsets when commands like
+\cs{gls} are used in a context where changing a boolean variable
+can cause things to go wrong. One example of this is using
+\cs{gls} in one of the commands provided with the \isty{soul}
+package. For example:
+\begin{verbatim}
+\ul{Some text about \gls{html}.}
+\end{verbatim}
+This causes the confusing error:
+\begin{verbatim}
+Glossary entry `{html}' has not been defined.
+\end{verbatim}
+The simplest workaround is to put \verb|\gls{html}| inside the
+argument of \cs{mbox}. For example:
+\begin{verbatim}
+\ul{Some text about \mbox{\gls{html}}.}
+\end{verbatim}
+This can work provided it's not the first use of this entry.
+It if is, then unsetting the first use flag causes a problem
+and results in the error:
+\begin{verbatim}
+! Package soul Error: Reconstruction failed.
+\end{verbatim}
+The \styfmt{glossaries-extra} package provides a way of temporarily
+switching off \cs{glsunset} so that it just makes a note of the
+entry's label but doesn't actually perform the change:
+\begin{definition}[\DescribeMacro\GlsXtrStartUnsetBuffering]
+\cs{GlsXtrStartUnsetBuffering}
+\end{definition}
+The unstarred version doesn't check for duplicates, so the internal
+list may end up with multiple occurrences of the same label. The
+starred version only adds a label to the internal list if it's not
+already in it. Note that this buffering only applies to the
+global \cs{glsunset} and does not affect the local
+\cs{glslocalunset}.
+
+Later you can restore \cs{glsunset} and unset all buffered
+labels using:
+\begin{definition}[\DescribeMacro\GlsXtrStopUnsetBuffering]
+\cs{GlsXtrStopUnsetBuffering}
+\end{definition}
+The starred form \cs{GlsXtrStopUnsetBuffering*} uses
+\cs{glslocalunset} instead. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[T1]{fontenc}
+\usepackage{soul}
+\usepackage{glossaries-extra}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+
+\begin{document}
+\GlsXtrStartUnsetBuffering
+\ul{Some text about \mbox{\gls{html}}.}
+\GlsXtrStopUnsetBuffering
+
+Next use: \gls{html}.
+\end{document}
+\end{verbatim}
+Before you stop the unset buffering, you can iterate over the
+current buffer using
+\begin{definition}[\DescribeMacro\GlsXtrForUnsetBufferedList]
+\cs{GlsXtrForUnsetBufferedList}\marg{cs}
+\end{definition}
+where \meta{cs} is a control sequence that takes a single argument
+(which is the entry label). This is best used with the starred
+version \cs{GlsXtrStartUnsetBuffering*} to avoid duplicates.
+
+\begin{important}
+Note that since the change in the first use flag now doesn't
+occur until \cs{GlsXtrStopUnsetBuffering}, multiple references
+of the same term within the buffering zone will always be
+treated as first use (if the term wasn't used before the
+buffering started).
+\end{important}
+
+There can still be a problem here as content within \cs{mbox}
+can't break across a line so you may end up with an overfull
+line or excessive white space within the paragraph.
+
+An alternative is to use \cs{protect}:
+\begin{verbatim}
+\GlsXtrStartUnsetBuffering
+\ul{Some text about \protect\gls{html}.}
+\GlsXtrStopUnsetBuffering
+\end{verbatim}
+but the formatting (underlining in this example) won't be applied.
+Another possibility is:
+\begin{verbatim}
+\usepackage[T1]{fontenc}
+\usepackage{soul}
+\usepackage{glossaries-extra}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+
+\newrobustcmd{\gul}[1]{%
+ {%
+ \def\glsxtrabbreviationfont##1{\GlsXtrExpandedFmt{\ul}{##1}}%
+ \def\glsxtrregularfont##1{\GlsXtrExpandedFmt{\ul}{##1}}%
+ #1%
+ }%
+}
+
+\begin{document}
+\ul{Some text about }\gls[textformat=gul]{html}.
+
+Next use: \gls{html}.
+\end{document}
+\end{verbatim}
+This moves \cs{gls} outside of \cs{ul} and uses
+\gloskey[glslink]{textformat} to locally change the formatting
+command used by \cs{gls} (which is normally given by
+\cs{glstextformat} or the \catattr{textformat} attribute)
+to a custom command \cs{gul}, which locally changes the regular font
+and the default abbreviation font to use \cs{ul}. It then uses
+\begin{definition}[\DescribeMacro\GlsXtrExpandedFmt]
+\cs{GlsXtrExpandedFmt}\marg{cs}\marg{text}
+\end{definition}
+which (protected) fully expands \meta{text} before applying
+\meta{cs}, which must be a control sequence that takes a single
+argument. This allows \cs{ul} to move much further inside
+and increases its chances of working. It can still break if
+\meta{text} expands to something that \cs{ul} can't deal with.
+For example, if an abbreviation style is used that contains
+complex formatting or if the field value contains problematic
+content.
+
+\section{Plurals}
+
+Some languages, such as English, have a general rule that plurals
+are formed from the singular with a suffix appended. This isn't
+an absolute rule. There are plenty of exceptions (for example,
+geese, children, churches, elves, fairies, sheep). The
+\sty{glossaries} package allows the \gloskey{plural} key to be
+optional when defining entries. In some cases a plural may not make
+any sense (for example, the term is a symbol) and in some cases
+the plural may be identical to the singular.
+
+To make life easier for languages where the majority of plurals can
+simply be formed by appending a suffix to the singular, the
+\sty{glossaries} package lets the \gloskey{plural} field default
+to the value of the \gloskey{text} field with \ics{glspluralsuffix}
+appended. This command is defined to be just the letter \qt{s}.
+This means that the majority of terms don't need to have the
+\gloskey{plural} supplied as well, and you only need to use it for the
+exceptions.
+
+For languages that don't have this general rule, the \gloskey{plural}
+field will always need to be supplied, where needed.
+
+There are other plural fields, such as \gloskey{firstplural},
+\gloskey{longplural} and \gloskey{shortplural}. Again, if you are using
+a language that doesn't have a simple suffix rule, you'll have to
+supply the plural forms if you need them (and if a plural makes
+sense in the context).
+
+If these fields are omitted, the \sty{glossaries} package follows
+these rules:
+\begin{itemize}
+\item If \gloskey{firstplural} is missing, then \cs{glspluralsuffix}
+is appended to the \gloskey{first} field, if that field has been
+supplied. If the \gloskey{first} field hasn't been supplied but the
+\gloskey{plural} field has been supplied, then the \gloskey{firstplural}
+field defaults to the \gloskey{plural} field. If the \gloskey{plural}
+field hasn't been supplied, then both the \gloskey{plural} and
+\gloskey{firstplural} fields default to the \gloskey{text} field (or
+\gloskey{name}, if no \gloskey{text} field) with \cs{glspluralsuffix}
+appended.
+
+\item If the \gloskey{longplural} field is missing, then
+\cs{glspluralsuffix} is appended to the \gloskey{long} field, if the
+\gloskey{long} field has been supplied.
+
+\item If the \gloskey{shortplural} field is missing then, \emph{with
+the base \sty{glossaries} acronym mechanism}, \ics{acrpluralsuffix}
+is appended to the \gloskey{short} field.
+
+\end{itemize}
+
+This \emph{last case is changed} with \styfmt{glossaries-extra}.
+With this extension package, the \gloskey{shortplural} field
+defaults to the \gloskey{short} field with \ics{abbrvpluralsuffix}
+appended unless overridden by category attributes. This
+suffix command is set by the abbreviation styles. This means that
+every time an abbreviation style is implemented,
+\cs{abbrvpluralsuffix} is redefined. In most cases its redefined to
+use
+\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix]
+\cs{glsxtrabbrvpluralsuffix}
+\end{definition}
+which defaults to just \cs{glspluralsuffix}. Some of the
+abbreviation styles have their own command for the plural suffix,
+such as \cs{glsxtrscsuffix},
+so if you want to completely strip all the plural suffixes used for
+abbreviations then you need to redefine \cs{glsxtrabbrvpluralsuffix}
+\emph{not} \cs{abbrvpluralsuffix}, which changes with the style. Redefining
+\cs{acrpluralsuffix} will have no affect, since it's not used by the
+new abbreviation mechanism.
+
+If you require a mixture (for example, in a multilingual document),
+there are two attributes that affect the short plural suffix
+formation. The first is \catattr{aposplural} which uses the suffix
+\begin{verbatim}
+'\abbrvpluralsuffix
+\end{verbatim}
+That is, an apostrophe followed by \cs{abbrvpluralsuffix} is
+appended. The second attribute is \catattr{noshortplural} which
+suppresses the suffix and simply sets \gloskey{shortplural} to the
+same as \gloskey{short}.
+
+\section{Nested Links}
+\label{sec:nested}
+
+Complications arise when you use \ics{gls} in the
+value of the \gloskey{name} field (or \gloskey{text}
+or \gloskey{first} fields, if set). This tends to occur with
+abbreviations that extend other abbreviations. For example,
+SHTML is an abbreviation for SSI enabled HTML, where SSI
+is an abbreviation for Server Side Includes and HTML
+is an abbreviation for Hypertext Markup Language.
+
+Things can go wrong if we try the following with the
+\styfmt{glossaries} package:
+\begin{verbatim}
+\newacronym{ssi}{SSI}{Server Side Includes}
+\newacronym{html}{HTML}{Hypertext Markup Language}
+\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
+\end{verbatim}
+
+The main problems are:
+\begin{enumerate}
+\item\label{itm:nestedfirstucprob} The first letter upper casing commands, such as \ics{Gls},
+won't work for the \texttt{shtml} entry on \gls{firstuse} if the
+long form is displayed before the short form (which is the
+default abbreviation style). This will attempt to do
+\begin{verbatim}
+\gls{\uppercase ssi} enabled \gls{html}
+\end{verbatim}
+which just doesn't work. Grouping the \verb|\gls{ssi}| doesn't
+work either as this will effectively try to do
+\begin{verbatim}
+\uppercase{\gls{ssi}} enabled \gls{html}
+\end{verbatim}
+This will upper case the label \texttt{ssi} so the entry won't be
+recognised. This problem will also occur if you use the all capitals
+version, such as \ics{GLS}.
+
+\item\label{itm:nonexpandprob} The long and abbreviated forms accessed through
+\ics{glsentrylong} and \ics{glsentryshort} are no longer expandable
+and so can't be used be used in contexts that require this,
+such as PDF bookmarks.
+
+\item\label{itm:nestedsortprob} The nested commands may end up in the \gloskey{sort} key,
+which will confuse the indexing.
+
+\item\label{itm:inconsistentfirstuseprob} The \texttt{shtml} entry produces inconsistent results
+depending on whether the \texttt{ssi} or \texttt{html} entries have
+been used. Suppose both \texttt{ssi} and \texttt{html} are used
+before \texttt{shtml}. For example:
+\begin{verbatim}
+This section discusses \gls{ssi}, \gls{html} and \gls{shtml}.
+\end{verbatim}
+This produces:
+\begin{quote}
+This section discusses server side includes (SSI), hypertext markup
+language (HTML) and SSI enabled HTML (SHTML).
+\end{quote}
+So the \gls{firstuse} of the \texttt{shtml} entry produces
+\qt{SSI enabled HTML (SHTML)}.
+
+Now let's suppose the \texttt{html} entry is used before the
+\texttt{shtml} but the \texttt{ssi} entry is used after the
+\texttt{shtml} entry, for example:
+\begin{verbatim}
+The sample files are either \gls{html} or \gls{shtml}, but let's
+first discuss \gls{ssi}.
+\end{verbatim}
+This produces:
+\begin{quote}
+The sample files are either hypertext markup language (HTML) or
+server
+side includes (SSI) enabled HTML (SHTML), but let's first discuss
+SSI.
+\end{quote}
+So the \gls{firstuse} of the \texttt{shtml} entry now produces
+\qt{server side includes (SSI) enabled HTML (SHTML)}, which looks
+a bit strange.
+
+Now let's suppose the \texttt{shtml} entry is used before (or
+without) the other two entries:
+\begin{verbatim}
+This article is an introduction to \gls{shtml}.
+\end{verbatim}
+This produces:
+\begin{quote}
+This article is an introduction to server side includes (SSI)
+enabled hypertext markup language (HTML) (SHTML).
+\end{quote}
+So the \gls{firstuse} of the \texttt{shtml} entry now produces
+\qt{server side includes (SSI) enabled hypertext markup language (HTML)
+(SHTML)}, which is even more strange.
+
+This is all aggravated by setting the style using the
+\styfmt{glossaries} package's
+\cs{setacronymstyle}. For example:
+\begin{verbatim}
+\setacronymstyle{long-short}
+\end{verbatim}
+as this references the label through the use of \cs{glslabel}
+when displaying the long and short forms, but this value
+changes with each use of \cs{gls}, so instead of displaying
+\qt{(SHTML)} at the end of the \gls{firstuse}, it now displays
+\qt{(HTML)}, since \cs{glslabel} has been changed to \texttt{html}
+by \verb|\gls{html}|.
+
+Another oddity occurs if you reset the \texttt{html} entry between
+uses of the \texttt{shtml} entry. For example:
+\begin{verbatim}
+\gls{shtml} ... \glsreset{html}\gls{shtml}
+\end{verbatim}
+The next use of \texttt{shtml} produces \qt{Shypertext markup
+language (HTML)}, which is downright weird.
+
+Even without this, the short form has nested formatting commands,
+which amount to \verb|\acronymfont{S\acronymfont{HTML}}|. This
+may not be a problem for some styles, but if you use one of the
+\qt{sm} styles (that use \ics{textsmaller}), this will produce
+an odd result.
+
+\item\label{itm:indexingprob} Each time the \texttt{shtml} entry is used, the
+\texttt{html} entry will also be indexed and marked as used,
+and on \gls{firstuse} this will happen to both the \texttt{ssi}
+and \texttt{html} entries. This kind of duplication in the location
+list isn't usually particularly helpful to the reader.
+
+\item\label{itm:nestedhyplinkprob} If \sty{hyperref} is in use, you'll get nested hyperlinks
+and there's no consistent way of dealing with this across the
+available PDF viewers. If on the \gls{firstuse} case, the user
+clicks on the \qt{HTML} part of the \qt{SSI enabled HTML (SHTML)}
+link, they may be directed to the HTML entry in the glossary or
+they may be directed to the SHTML entry in the glossary.
+
+\end{enumerate}
+
+For these reasons it's better to use the simple expandable commands like
+\ics{glsentrytext} or \ics{glsentryshort} in the definition
+of other entries (although that doesn't fix the first problem).
+Alternatively use something like:
+\begin{verbatim}
+\newacronym
+ [description={\acrshort{ssi} enabled \acrshort{html}}]
+ {shtml}{SHTML}{SSI enabled HTML}
+\end{verbatim}
+with \styfmt{glossaries} or:
+\begin{verbatim}
+\newabbreviation
+ [description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}]
+ {shtml}{SHTML}{SSI enabled HTML}
+\end{verbatim}
+with \styfmt{glossaries-extra}. This fixes all the above
+listed problems (as long as you don't use \ics{glsdesc}).
+Note that replacing \cs{gls} with \cs{acrshort} in the original
+example may fix the \gls{firstuse} issue, but it doesn't
+fix any of the other problems listed above.
+
+If it's simply that you want to use the abbreviation font, you can
+use \cs{glsabbrvfont}:
+\begin{verbatim}
+\setabbreviationstyle{long-short-sc}
+
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+\newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled
+\glsabbrvfont{html}}
+\end{verbatim}
+This will pick up the font style setting of the outer entry (shtml,
+in the above case). This isn't a problem in the above example as all
+the abbreviations use the same style.
+
+However if you're really determined to use
+\ics{gls} in a field that may be included within
+some \gls{linktext}, \styfmt{glossaries-extra} patches internals
+used by the linking commands so that if \cs{gls} (or plural or
+case changing variants) occurs in the \gls{linktext} it will
+behave as though you used
+\texttt{\ics{glstext}[hyper=false,noindex]}
+instead. Grouping is also added so that, for example, when
+\verb|\gls{shtml}| is used for the first time the long form
+\begin{verbatim}
+\gls{ssi} enabled \gls{html}
+\end{verbatim}
+is treated as
+\begin{verbatim}
+{\glstext[hyper=false,noindex]{ssi}} enabled
+{\glstext[hyper=false,noindex]{html}}
+\end{verbatim}
+This overcomes problems~\ref{itm:inconsistentfirstuseprob},
+\ref{itm:indexingprob} and \ref{itm:nestedhyplinkprob} listed
+above, but still doesn't fix problems~\ref{itm:nestedfirstucprob}
+and \ref{itm:nonexpandprob}.
+Problem~\ref{itm:nestedsortprob} usually won't be an issue as most abbreviation
+styles set the \gloskey{sort} key to the short form, so using these
+commands in the long form but not the short form will only affect
+entries with a style that sorts according to the long form (such as
+\abbrstyle{long-noshort-desc}).
+
+Additionally, any instance of the long form commands, such
+as \ics{glsxtrlong} or \ics{acrlong} will be temporarily
+redefined to just use
+\begin{alltt}
+\{\ics{glsentrylong}\marg{label}\meta{insert}\}
+\end{alltt}
+(or case-changing versions). Similarly the short form commands,
+such as \ics{glsxtrshort} or \ics{acrshort} will use
+\ics{glsentryshort} in the argument of either \cs{glsabbrvfont}
+(for \cs{glsxtrshort}) or \cs{acronymfont} (for \cs{acrshort}).
+So if the \texttt{shtml} entry had instead been defined as:
+\begin{verbatim}
+\newacronym{shtml}{SHTML}{\acrshort{ssi} enabled \acrshort{html}}
+\end{verbatim}
+then (using the \abbrstyle{long-short} style) the \gls{firstuse}
+will be like
+\begin{verbatim}
+{\acronymfont{\glsentryshort{ssi}}} enabled
+{\acronymfont{\glsentryshort{html}}} (SHTML)
+\end{verbatim}
+whereas if the entry is defined as:
+\begin{verbatim}
+\newabbreviation{shtml}{SHTML}{\glsxtrshort{ssi} enabled
+\glsxtrshort{html}}
+\end{verbatim}
+then the \gls{firstuse} will be like:
+\begin{verbatim}
+{\glsabbrvfont{\glsentryshort{ssi}}} enabled
+{\glsabbrvfont{\glsentryshort{html}}} (SHTML)
+\end{verbatim}
+Note that the first optional argument of
+\cs{acrshort} or \cs{glsxtrshort} is ignored in this context.
+(The final optional argument will be inserted, if present.)
+The abbreviation style that governs \ics{glsabbrvfont} will be
+set for \ics{glsxtrshort}. Note that \cs{acrshort} doesn't
+set the abbreviation style.
+
+Alternatively you can use:
+\begin{definition}[\DescribeMacro\glsxtrp]
+\cs{glsxtrp}\marg{field}\marg{label}
+\end{definition}
+where \meta{field} is the field label and corresponds to a
+command in the form \cs{gls}\meta{field} (e.g.\ \cs{glstext}) or
+in the form \cs{glsxtr}\meta{field} (e.g.\ \cs{glsxtrshort}).
+
+There's a shortcut command for the most common fields:
+\begin{definition}[\DescribeMacro\glsps]
+\cs{glsps}\marg{label}
+\end{definition}
+which is equivalent to \verb|\glsxtrp{short}|\marg{label}, and
+\begin{definition}[\DescribeMacro\glspt]
+\cs{glspt}\marg{label}
+\end{definition}
+which is equivalent to \verb|\glsxtrp{text}|\marg{label}.
+
+The \cs{glsxtrp} command behaves much like the
+\cs{glsfmt}\meta{field} commands described in
+\sectionref{sec:headtitle} but the post-link hook is also
+suppressed and extra grouping is added. It automatically sets
+\gloskey[glslink]{hyper} to \texttt{false} and
+\gloskey[glslink]{noindex} to \texttt{true}. If you want to change
+this, you can use
+\begin{definition}[\DescribeMacro\glsxtrsetpopts]
+\cs{glsxtrsetpopts}\marg{options}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrsetpopts{hyper=false}
+\end{verbatim}
+will just switch off the hyperlinks but not the indexing.
+Be careful using this command or you can end up back to the
+original problem of nested links.
+
+The hyper link is re-enabled within glossaries. This is
+done through the command:
+\begin{definition}[\DescribeMacro\glossxtrsetpopts]
+\cs{glossxtrsetpopts}
+\end{definition}
+which by default just does
+\begin{verbatim}
+\glsxtrsetpopts{noindex}
+\end{verbatim}
+You can redefine this if you want to adjust the setting when
+\cs{glsxtrp} is used in the glossary. For example:
+\begin{verbatim}
+\renewcommand{\glossxtrsetpopts}{\glsxtrsetpopts{noindex=false}}
+\end{verbatim}
+
+For example,
+\begin{verbatim}
+\glsxtrp{short}{ssi}
+\end{verbatim}
+is equivalent to
+\begin{verbatim}
+{\let\glspostlinkhook\relax
+ \glsxtrshort[hyper=false,noindex]{ssi}[]%
+}
+\end{verbatim}
+in the main body of the document or
+\begin{verbatim}
+{\let\glspostlinkhook\relax
+ \glsxtrshort[noindex]{ssi}[]%
+}
+\end{verbatim}
+inside the glossary. (Note the post-link hook is locally disabled.)
+
+If \verb|\glsxtrp{short}{ssi}| occurs in a sectioning mark,
+it's equivalent to
+\begin{verbatim}
+{\glsxtrheadshort{ssi}}
+\end{verbatim}
+(which recognises the \catattr{headuc} attribute.)
+
+If \sty{hyperref} has been loaded, then the bookmark will
+use \cs{glsentry}\meta{field}
+(\verb|\glsentryshort{ssi}| in the above example).
+
+There are similar commands
+\begin{definition}[\DescribeMacro\Glsxtrp]
+\cs{Glsxtrp}\marg{field}\marg{label}
+\end{definition}
+for first letter upper case and
+\begin{definition}[\DescribeMacro\GLSxtrp]
+\cs{GLSxtrp}\marg{field}\marg{label}
+\end{definition}
+for all upper case.
+
+\begin{important}
+If you use any of the case-changing commands, such as \ics{Gls}
+or \ics{Glstext}, (either all caps or first letter upper casing)
+don't use any of the linking commands, such as \ics{gls} or
+\ics{glstext}, in the definition of entries for any of the
+fields that may be used by those case-changing commands.
+\end{important}
+
+You can, with care, protect against issue~\ref{itm:nestedfirstucprob} by
+inserting an empty group at the start if the long form starts with a
+command that breaks the first letter uppercasing commands like
+\cs{Gls}, but you still won't be able to use the all caps commands,
+such as \cs{GLS}.
+
+If you \emph{really need} nested commands, the safest method is
+\begin{verbatim}
+\newabbreviation{shtml}{shtml}{{}\glsxtrp{short}{ssi} enabled
+\glsxtrp{short}{html}}
+\end{verbatim}
+but be aware that it may have some unexpected results occasionally.
+
+Example document:
+\begin{verbatim}
+\documentclass{report}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{slantsc}
+\usepackage[colorlinks]{hyperref}
+\usepackage[nopostdot=false]{glossaries-extra}
+
+\makeglossaries
+
+\setabbreviationstyle{long-short-sc}
+
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+\newabbreviation{shtml}{shtml}{{}\glsps{ssi} enabled {}\glsps{html}}
+
+\pagestyle{headings}
+
+\glssetcategoryattribute{abbreviation}{headuc}{true}
+\glssetcategoryattribute{abbreviation}{glossdesc}{title}
+
+\begin{document}
+
+\tableofcontents
+
+\chapter{\glsfmtfull{shtml}}
+
+First use: \gls{shtml}, \gls{ssi} and \gls{html}.
+
+Next use: \gls{shtml}, \gls{ssi} and \gls{html}.
+
+\newpage
+Next page.
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
+\section{Acronym Style Modifications}
+\label{sec:acronymmods}
+
+The \styfmt{glossaries-extra} package provides a new way of dealing
+with abbreviations and redefines \ics{newacronym} to
+use \cs{newabbreviation} (see \sectionref{sec:abbreviations}).
+The simplest way to update a document that uses
+\cs{newacronym} from \styfmt{glossaries} to
+\styfmt{glossaries-extra} is do just add
+\begin{verbatim}
+\setabbreviationstyle[acronym]{long-short}
+\end{verbatim}
+before you define any entries.
+For example, the following document using just \styfmt{glossaries}
+\begin{verbatim}
+\documentclass{article}
+\usepackage[acronym,nopostdot,toc]{glossaries}
+\makeglossaries
+\setacronymstyle{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\begin{document}
+\gls{html}
+\printglossaries
+\end{document}
+\end{verbatim}
+can be easily adapted to use \styfmt{glossaries-extra}:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[acronym]{glossaries-extra}
+\makeglossaries
+\setabbreviationstyle[acronym]{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\begin{document}
+\gls{html}
+\printglossaries
+\end{document}
+\end{verbatim}
+Table~\ref{tab:acrabbrvstyles} lists the nearest equivalent
+\styfmt{glossaries-extra} abbreviation styles for
+the predefined acronym styles provided by \styfmt{glossaries}, but
+note that the new styles use different formatting commands. See
+\sectionref{sec:predefabbrvstyles} for further details.
+
+\begin{table}[htbp]
+\caption[Old Acronym Styles Verses New Abbreviation Styles]{Old Acronym Styles
+\cs{setacronymstyle}\marg{old-style-name} Verses New Abbreviation
+Styles \cs{setabbreviationstyle}\oarg{category}\marg{new-style-name}}
+\label{tab:acrabbrvstyles}
+\centering
+\begin{tabular}{@{}p{\dimexpr0.3\textwidth-2\tabcolsep}p{0.7\textwidth}@{}}
+\bfseries Old Style Name &
+\bfseries New Style Name\\
+\acrstyle{long-sc-short} & \abbrstyle{long-short-sc}\\
+\acrstyle{long-sm-short} & \abbrstyle{long-short-sm}\\
+\acrstyle{long-sp-short} & \abbrstyle{long-short} \newline with
+\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\
+\acrstyle{short-long} & \abbrstyle{short-long}\\
+\acrstyle{sc-short-long} & \abbrstyle{short-sc-long}\\
+\acrstyle{sm-short-long} & \abbrstyle{short-sm-long}\\
+\acrstyle{long-short-desc} & \abbrstyle{long-short-desc}\\
+\acrstyle{long-sc-short-desc} & \abbrstyle{long-short-sc-desc}\\
+\acrstyle{long-sm-short-desc} & \abbrstyle{long-short-sm-desc}\\
+\acrstyle{long-sp-short-desc} & \abbrstyle{long-short-desc} \newline with
+\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\
+\acrstyle{short-long-desc} & \abbrstyle{short-long-desc}\\
+\acrstyle{sc-short-long-desc} & \abbrstyle{short-sc-long-desc}\\
+\acrstyle{sm-short-long-desc} & \abbrstyle{short-sm-long-desc}\\
+\acrstyle{dua} & \abbrstyle{long-noshort}\\
+\acrstyle{dua-desc} & \abbrstyle{long-noshort-desc}\\
+\acrstyle{footnote} & \abbrstyle{short-footnote}\\
+\acrstyle{footnote-sc} & \abbrstyle{short-sc-footnote}\\
+\acrstyle{footnote-sm} & \abbrstyle{short-sm-footnote}\\
+\acrstyle{footnote-desc} & \abbrstyle{short-footnote-desc}\\
+\acrstyle{footnote-sc-desc} & \abbrstyle{short-sc-footnote-desc}\\
+\acrstyle{footnote-sm-desc} & \abbrstyle{short-sm-footnote-desc}
+\end{tabular}
+\end{table}
+
+The reason for introducing the new style of abbreviation commands
+provided by \styfmt{glossaries-extra} is because the original
+acronym commands provided by \styfmt{glossaries} are too restrictive
+to work with the internal modifications made by
+\styfmt{glossaries-extra}. However, if you really want to restore
+the generic acronym function provided
+by \styfmt{glossaries} you can use
+\begin{definition}[\DescribeMacro\RestoreAcronyms]
+\cs{RestoreAcronyms}
+\end{definition}
+(before any use of \cs{newacronym}).
+
+\cs{RestoreAcronyms} should not be used in combination with the newer
+\styfmt{glossaries-extra} abbreviations. Don't combine old and
+new style entries with the same \gloskey{type}. The
+original \styfmt{glossaries} acronym mechanism doesn't work well
+with the newer \styfmt{glossaries-extra} commands.
+
+\begin{important}
+If you use \cs{RestoreAcronyms}, don't use any of the commands
+provided by \styfmt{glossaries-extra} intended for abbreviations
+(such as \ics{glsxtrshort} or \ics{glsfmtshort}) with entries
+defined via \ics{newacronym} as it will cause unexpected
+results.
+\end{important}
+
+In general, there's rarely any need for \cs{RestoreAcronyms}. If you
+have a document that uses \ics{newacronymstyle}, then it's best to
+either stick with just \styfmt{glossaries} for that document or
+define an equivalent abbreviation style with
+\ics{newabbreviationstyle}. (See \sectionref{sec:newabbrvstyle} for
+further details.)
+
+\begin{definition}[\DescribeMacro\glsacspace]
+\cs{glsacspace}\marg{label}
+\end{definition}
+The space command \cs{glsacspace} used by the
+\acrstyle{long-sp-short} acronym style provided by \styfmt{glossaries}
+is modified so that it uses
+\begin{definition}[\DescribeMacro\glsacspacemax]
+\cs{glsacspacemax}
+\end{definition}
+instead of the hard-coded 3em. This is a command not a length
+and so can be changed using \cs{renewcommand}.
+
+Any of the new abbreviation styles that use \ics{glsxtrfullsep}
+(such as \abbrstyle{long-short}) can easily be changed to use
+\cs{glsacspace} with
+\begin{verbatim}
+\renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}}
+\end{verbatim}
+
+The \gls{firstuse} acronym font command
+\begin{definition}[\firstacronymfont]
+\cs{firstacronymfont}\marg{text}
+\end{definition}
+is redefined to use the \gls{firstuse} abbreviation font command
+\ics{glsfirstabbrvfont}. This will be reset if you use
+\cs{RestoreAcronyms}.
+
+The subsequent use acronym font command
+\begin{definition}[\acronymfont]
+\cs{acronymfont}\marg{text}
+\end{definition}
+is redefined to use the subsequent use abbreviation font command
+\ics{glsabbrvfont}. This will be reset if you use
+\cs{RestoreAcronyms}.
+
+\section{\styfmt{glossary-bookindex} package}
+\label{sec:bookindex}
+
+As from v1.21, \styfmt{glossaries-extra} has a new supplementary
+package \sty{glossary-bookindex} which provides the glossary style
+\glostyle{bookindex}. This is very similar to the
+\glostyle{mcolindexgroup} style but is designed for indexes, so by
+default only the name and location list are displayed. You can
+either load this package explicitly and then set the style:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage{glossary-bookindex}
+\setglossarystyle{bookindex}
+\end{verbatim}
+or use both the \pkgopt{stylemods} and \sty{style} options:
+\begin{verbatim}
+\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra}
+\end{verbatim}
+The \glostyle{bookindex} style only supports a maximum
+hierarchical level of 2 (top-level, level~1 and level~2). It's
+primarily designed for use with \gls{bib2gls}. It may be used with
+other indexing options, but some features may not be present and
+UTF-8 characters may cause a problem with non-Unicode engines in
+letter group headings or PDF bookmarks. (\gls{bib2gls} uses numeric
+identifies by default to avoid these problems. If numbers show up in
+the group headings instead of the appropriate characters, check that
+you have used the \pkgopt{record} package option.)
+
+The number of columns is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexcols]
+\cs{glsxtrbookindexcols}
+\end{definition}
+which defaults to 2.
+
+This style uses the \env{multicols} environment. If
+the command
+\begin{definition}[\DescribeMacro\glsxtrbookindexcolspread]
+\cs{glsxtrbookindexcolspread}
+\end{definition}
+isn't empty then it's supplied as the optional argument
+following \verb|\begin{multicols}|\marg{n}. You can switch from
+\env{multicols} to \env{multicols*} by redefining
+\begin{definition}[\DescribeMacro\glsxtrbookindexmulticolsenv]
+\cs{glsxtrbookindexmulticolsenv}
+\end{definition}
+For example
+\begin{verbatim}
+\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*}
+\end{verbatim}
+
+Each top-level entry is displayed using
+\begin{definition}[\DescribeMacro\glsxtrbookindexname]
+\cs{glsxtrbookindexname}\marg{label}
+\end{definition}
+where the entry is identified by \meta{label}. This just
+does \cs{glossentryname}\marg{label} by default.
+For example, if you want the symbol to be included:
+\begin{verbatim}
+\renewcommand*{\glsxtrbookindexname}[1]{%
+ \glossentryname{#1}%
+ \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}%
+}
+\end{verbatim}
+or if you want the description (if set):
+\begin{verbatim}
+\renewcommand*{\glsxtrbookindexname}[1]{%
+ \glossentryname{#1}%
+ \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}%
+}
+\end{verbatim}
+(which picks up the post-description hook).
+
+Alternatively you can use the \cs{glsxtrpostname\meta{category}}
+hook to append information after the name according to the entry's
+category.
+
+Sub-entries are displayed using
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubname]
+\cs{glsxtrbookindexsubname}\marg{label}
+\end{definition}
+which just defaults to \cs{glsxtrbookindexname}\marg{label}.
+
+The separator used before the location list for top-level
+entries is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexprelocation]
+\cs{glsxtrbookindexprelocation}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. This checks if
+the \texttt{location} field has been set. If it has, it
+does
+\begin{verbatim}
+,\glsxtrprelocation
+\end{verbatim}
+otherwise it just does \cs{glsxtrprelocation} (which defaults
+to \cs{space}). If you're not using
+\gls{bib2gls}, the \gloskey{location} field won't be set.
+
+The separator used before the
+location list for sub-entries is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubprelocation]
+\cs{glsxtrbookindexsubprelocation}\marg{label}
+\end{definition}
+which defaults to \cs{glsxtrbookindexprelocation}\marg{label}.
+
+The actual location list is encapsulated with:
+\begin{definition}[\DescribeMacro\glsxtrbookindexlocation]
+\cs{glsxtrbookindexlocation}\marg{label}\marg{location list}
+\end{definition}
+for top-level entries and
+\begin{definition}[\DescribeMacro\glsxtrbookindexsublocation]
+\cs{glsxtrbookindexsublocation}\marg{label}\marg{location list}
+\end{definition}
+for sub-entries. These both just do \meta{location list} by default.
+
+The separator used between a top-level parent and child entry is
+given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexparentchildsep]
+\cs{glsxtrbookindexparentchildsep}
+\end{definition}
+This defaults to \cs{nopagebreak}.
+
+The separator used between a sub-level parent and child entry is
+given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexparentsubchildsep]
+\cs{glsxtrbookindexparentsubchildsep}
+\end{definition}
+This defaults to \cs{glsxtrbookindexparentchildsep}.
+
+The separator between top-level entries is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexbetween]
+\cs{glsxtrbookindexbetween}\marg{label1}\marg{label2}
+\end{definition}
+This comes after the entry given by \meta{label1}, if the entry
+has no children, or after the last descendent otherwise,
+so it always comes immediately before the entry given
+by \meta{label2} unless the entry occurs at the start of
+a group. This does nothing by default.
+
+The separator between two level~1 entries is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubbetween]
+\cs{glsxtrbookindexsubbetween}\marg{label1}\marg{label2}
+\end{definition}
+
+The separator between two level~2 entries is given by
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubbetween]
+\cs{glsxtrbookindexsubsubbetween}\marg{label1}\marg{label2}
+\end{definition}
+At the end of each letter group, the following hooks
+are done in order:
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubatendgroup]
+\cs{glsxtrbookindexsubsubatendgroup}\marg{sub-sub-label}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrbookindexsubatendgroup]
+\cs{glsxtrbookindexsubatendgroup}\marg{sub-label}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrbookindexatendgroup]
+\cs{glsxtrbookindexatendgroup}\marg{label}
+\end{definition}
+where \meta{sub-sub-label} is the label of the last
+level~2 entry, \meta{sub-label} is the label of the last
+level~1 entry and \meta{label} is the label of the last
+level~0 entry.
+
+For example, the resource option \texttt{seealso=omit}
+instructs \gls{bib2gls} to omit the \texttt{seealso} cross-reference
+from the location list. (The \texttt{see} cross-reference
+will still be added unless you also have \texttt{see=omit}.)
+The \texttt{seealso} cross-reference can instead be appended after
+the child entries using:
+\begin{verbatim}
+\renewcommand{\glsxtrbookindexatendgroup}[1]{%
+ \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}%
+}
+\renewcommand{\glsxtrbookindexbetween}[2]{%
+ \glsxtrbookindexatendgroup{#1}%
+}%
+
+\renewcommand{\glsxtrbookindexsubatendgroup}[1]{%
+ \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}%
+}
+
+\renewcommand{\glsxtrbookindexsubbetween}[2]{%
+ \glsxtrbookindexsubatendgroup{#1}%
+}
+
+\renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{%
+ \glsxtrifhasfield{seealso}{#1}%
+ {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}%
+}
+
+\renewcommand{\glsxtrbookindexsubsubbetween}[2]{%
+ \glsxtrbookindexsubsubatendgroup{#1}%
+}
+\end{verbatim}
+This uses \cs{glstreesubitem} and \cs{glstreesubsubitem}
+to indent the cross-reference according to the next level down,
+so the cross-reference for a top-level entry is aligned with
+the sub-entries, and a level~1 entry has its cross-reference
+aligned with sub-sub-entries. In the event that a level~2
+entry has a cross-reference, this is indented a bit further
+(but it won't be aligned with any deeper level as the
+\glostyle{bookindex} style only supports a maximum of two
+sub-levels).
+
+The \glostyle{bookindex} style uses group headings. (If you
+use \gls{bib2gls} remember to invoke it with the \verb|--group|
+or \verb|-g| switch.) The heading will use
+\begin{definition}[\DescribeMacro\glsxtrbookindexbookmark]
+\cs{glsxtrbookindexbookmark}\marg{group title}\marg{name}
+\end{definition}
+If \cs{pdfbookmark} has been defined, this will
+use that command to bookmark the group title. If
+\pkgopt[chapter]{section} is set (default if chapters are defined)
+then this uses level~1 otherwise it uses level~2. You can
+redefine this command if this isn't appropriate.
+If \cs{pdfbookmark} hasn't been defined, this command does nothin.
+
+The group heading is formatted according to
+\begin{definition}[\DescribeMacro\glsxtrbookindexformatheader]
+\cs{glsxtrbookindexformatheader}\marg{group title}
+\end{definition}
+which is defined as
+\begin{verbatim}
+\newcommand*{\glsxtrbookindexformatheader}[1]{%
+ \par{\centering\glstreegroupheaderfmt{#1}\par}%
+}
+\end{verbatim}
+where \cs{glstreegroupheaderfmt} is provided by the
+\sty{glossary-tree} package, which is automatically loaded.
+Note that the entry names aren't encapsulated with
+\cs{glstreenamefmt}.
+
+The \sty{glossary-bookindex} package provides some supplementary
+commands that aren't used by default, but may be used when
+adjusting the style. These commands should only be
+used within one of the \cs{print\ldots glossary} commands.
+(That is, they should only be used in glossary styles.)
+\begin{definition}[\DescribeMacro\glsxtrbookindexmarkentry]
+\cs{glsxtrbookindexmarkentry}\marg{label}
+\end{definition}
+This writes information to the \texttt{.aux} file that
+can be read on the next run to obtain the first and last entry on
+each page of the glossary.
+
+You can display the first entry
+associated with the current page using:
+\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmark]
+\cs{glsxtrbookindexfirstmark}
+\end{definition}
+and the last entry associated with the current page
+using:
+\begin{definition}[\DescribeMacro\glsxtrbookindexlastmark]
+\cs{glsxtrbookindexlastmark}
+\end{definition}
+These do nothing if there are no entries marked on the current page
+(or if the document build isn't up to date).
+
+The entry is formatted using:
+\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmarkfmt]
+\cs{glsxtrbookindexfirstmarkfmt}\marg{label}
+\end{definition}
+for the first instance and
+\begin{definition}[\DescribeMacro\glsxtrbookindexlastmarkfmt]
+\cs{glsxtrbookindexlastmarkfmt}\marg{label}
+\end{definition}
+for the last.
+
+These commands are designed for use in page headers or footers
+where the page number is stable. For example, \cs{glsxtrbookindexname}
+can be redefined to mark the current entry:
+\begin{verbatim}
+\renewcommand{\glsxtrbookindexname}[1]{%
+ \glsxtrbookindexmarkentry{#1}%
+ \glossentryname{#1}%
+}
+\end{verbatim}
+If you only want to mark the top-level entries, remember
+to redefine \cs{glsxtrbookindexsubname} as it defaults
+to \cs{glsxtrbookindexname}:
+\begin{verbatim}
+\renewcommand{\glsxtrbookindexsubname}[1]{%
+ \glossentryname{#1}%
+}
+\end{verbatim}
+
+Then if you're using \sty{fancyhdr} you can set the page style
+to show the first and last entry for the current page with:
+\begin{verbatim}
+ \pagestyle{fancy}%
+ \lhead{\thepage}%
+ \lfoot{\glsxtrbookindexfirstmark}%
+ \cfoot{}%
+ \rfoot{\glsxtrbookindexlastmark}%
+\end{verbatim}
+
+\section{\styfmt{glossary-longextra} package}
+\label{sec:longextra}
+
+As from version 1.37, the \styfmt{glossaries-extra} package comes
+with the supplementary package \sty{glossary-longextra} that
+provides additional styles, listed below, that use the
+\env{longtable} environment. If you know that your glossary won't
+span more than a page and you need to use it in a context that's
+incompatible with \env{longtable}, you can instead setup these styles
+to use \env{tabular} instead. In order to do this you must use
+\begin{definition}[\DescribeMacro\GlsLongExtraUseTabulartrue]
+\cs{GlsLongExtraUseTabulartrue}
+\end{definition}
+\emph{before the style is set}. For example:
+\begin{verbatim}
+\GlsLongExtraUseTabulartrue
+\setglossarystyle{long-name-desc}
+\end{verbatim}
+or
+\begin{verbatim}
+\GlsLongExtraUseTabulartrue
+\printunsrtglossary[style={long-name-desc}]
+\end{verbatim}
+If you use this setting, you can change the default vertical
+alignment with:
+\begin{definition}[\DescribeMacro\glslongextraTabularVAlign]
+\cs{glslongextraTabularVAlign}
+\end{definition}
+The default definition is \texttt{c}.
+
+The column titles are formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraHeaderFmt]
+\cs{glslongextraHeaderFmt}\marg{text}
+\end{definition}
+which simply does \cs{textbf}\marg{text} by default.
+
+The name column has the title given by \ics{entryname} and
+the column alignment is given by:
+\begin{definition}[\DescribeMacro\glslongextraNameAlign]
+\cs{glslongextraNameAlign}
+\end{definition}
+which expands to \texttt{l} (left) by default.
+
+The symbol column (where applicable) has the title given by
+\ics{symbolname} and the column alignment is given by:
+\begin{definition}[\DescribeMacro\glslongextraSymbolAlign]
+\cs{glslongextraSymbolAlign}
+\end{definition}
+which expands to \texttt{c} (centred) by default.
+
+The location list column (where applicable) has the title given by
+\ics{pagelistname} and the column alignment is given by:
+\begin{definition}[\DescribeMacro\glslongextraLocationAlign]
+\cs{glslongextraLocationAlign}
+\end{definition}
+which expands to
+\begin{verbatim}
+>{\raggedright}p{\glspagelistwidth}
+\end{verbatim}
+by default. (Ragged-right paragraph, \ics{glspagelistwidth} is
+defined in \sty{glossary-long}, which is automatically loaded.)
+
+The description column has the title given by \ics{descriptionname}
+and the column alignment is given by:
+\begin{definition}[\DescribeMacro\glslongextraDescAlign]
+\cs{glslongextraDescAlign}
+\end{definition}
+which expands to
+\begin{verbatim}
+>{\raggedright}p{\glsdescwidth}
+\end{verbatim}
+by default. (Ragged-right paragraph, \ics{glsdescwidth} is
+defined in \sty{glossary-long}, which is automatically loaded.)
+
+Unlike the long styles provided by the base \styfmt{glossaries}
+package, these new styles try to determine the value of
+\cs{glsdescwidth} at the start of the glossary according to the
+number of columns provided by the style. The calculations are
+performed by the following commands:
+\begin{definition}[\DescribeMacro\glslongextraSetDescWidth]
+\cs{glslongextraSetDescWidth}
+\end{definition}
+This is used by the styles that have a name and description
+column. The value of \cs{glsdescwidth} is computed as:
+\[
+ \cs{glsdescwidth} = \cs{linewidth} - 4\cs{tabcolsep} - W
+\]
+where $W$ is a guess at the width of the name column. This is first
+set to the width of the name column header:
+\begin{alltt}
+\cs{settowidth}\marg{width}\{\cs{glslongextraHeaderFmt}\cs{entryname}\}
+\end{alltt}
+If any names in that column are larger than this, then you need
+to specify the widest name using:
+\begin{definition}[\DescribeMacro\glslongextraSetWidest]
+\cs{glslongextraSetWidest}\marg{widest name}
+\end{definition}
+or
+\begin{definition}[\DescribeMacro\glslongextraUpdateWidest]
+\cs{glslongextraUpdateWidest}\marg{text}
+\end{definition}
+These work like the analogous commands \cs{glssetwidest} and
+\cs{glsupdatewidest} provided with the \glostyle{alttree} style, but
+in this case there's no hierarchy. The default widest name
+is obtained from the \glostyle{alttree} top-level name if set,
+otherwise it's empty, so you can use \gls{bib2gls}['s]
+\texttt{set-widest} option. If you have the entry counter enabled,
+you will need to include this with the name for the extra material to
+be taken into account.
+
+The name isn't shown for child entries by default, but if
+you change this and you want to use \gls{bib2gls}['s]
+\texttt{set-widest} option (for \gls{bib2gls} v1.8+) then you need to
+redefine:
+\begin{definition}[\DescribeMacro\glslongextraUpdateWidestChild]
+\cs{glslongextraUpdateWidestChild}\marg{level}\marg{text}
+\end{definition}
+This does nothing by default, but if you are including the child
+names then you need to redefine this command:
+\begin{verbatim}
+\renewcommand{\glslongextraUpdateWidestChild}[2]{%
+ \glslongextraUpdateWidest{#2}%
+}
+\end{verbatim}
+
+If you prefer to set an explicit width for the description
+column then you need to redefine \cs{glslongextraSetDescWidth}. For
+example:
+\begin{verbatim}
+\renewcommand{\glslongextraSetDescWidth}{%
+ \setlength{\glsdescwidth}{0.6\linewidth}%
+}
+\end{verbatim}
+
+The styles that have a name, symbol and description,
+\cs{glsdescwidth} is set with:
+\begin{definition}[\DescribeMacro\glslongextraSymSetDescWidth]
+\cs{glslongextraSymSetDescWidth}
+\end{definition}
+This first uses \cs{glslongextraSetDescWidth} and then subtracts
+2\cs{tabcolsep} and the width of the symbol column header from
+\cs{glsdescwidth}. This assumes that the symbol column header
+is larger than any of the symbols. If this isn't appropriate
+then you can redefine this command. For example:
+\begin{verbatim}
+\renewcommand{\glslongextraSymSetDescWidth}{%
+ \glslongextraSetDescWidth
+ \addtolength{\glsdescwidth}{-3cm}%
+}
+\end{verbatim}
+or
+\begin{verbatim}
+\renewcommand{\glslongextraSymSetDescWidth}{%
+ \setlength{\glsdescwidth}{.5\linewidth}%
+}
+\end{verbatim}
+
+For the styles that have a name, description and location column,
+\cs{glsdescwidth} is set using:
+\begin{definition}[\DescribeMacro\glslongextraLocSetDescWidth]
+\cs{glslongextraLocSetDescWidth}
+\end{definition}
+This uses \cs{glslongextraSetDescWidth} and then subtracts
+2\cs{tabcolsep} and \cs{glspagelistwidth} from \cs{glsdescwidth}.
+You can redefine this command to set both \cs{glsdescwidth} and
+\cs{glspagelistwidth} if appropriate.
+
+For the styles that have a name, description, symbol and location
+column, \cs{glsdescwidth} is set using:
+\begin{definition}[\DescribeMacro\glslongextraSymLocSetDescWidth]
+\cs{glslongextraSymLocSetDescWidth}
+\end{definition}
+This uses \cs{glslongextraSymSetDescWidth} and then subtracts
+2\cs{tabcolsep} and \cs{glspagelistwidth} from
+\cs{glsdescwidth}. Again, you can redefine this command
+to explicitly set both lengths.
+
+In all cases, the top-level name is formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraNameFmt]
+\cs{glslongextraNameFmt}\marg{label}
+\end{definition}
+This does
+\begin{alltt}
+\cs{glsentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\}
+\end{alltt}
+which includes the entry counter (if enabled), the target and the post-name link.
+
+The top-level description is formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraDescFmt]
+\cs{glslongextraDescFmt}\marg{label}
+\end{definition}
+This does \cs{glossentrydesc}\marg{label} followed by the
+post-description hook.
+
+The styles that have a symbol column format the symbol using:
+\begin{definition}[\DescribeMacro\glslongextraSymbolFmt]
+\cs{glslongextraSymbolFmt}\marg{label}
+\end{definition}
+This just does \cs{glossentrysymbol}\marg{label}.
+
+The styles that have a location list column format the list using:
+\begin{definition}[\DescribeMacro\glslongextraLocationFmt]
+\cs{glslongextraLocationFmt}\marg{label}\marg{locations}
+\end{definition}
+This just does \meta{locations} and ignores the label.
+
+The child entries have their name formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraSubNameFmt]
+\cs{glslongextraSubNameFmt}\marg{level}\marg{label}
+\end{definition}
+where \meta{level} is the hierarchical level. This defaults to:
+\begin{alltt}
+\cs{glssubentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{strut}\}
+\end{alltt}
+This includes the sub-entry counter (if enabled) and the target
+but doesn't show the name. The child description is formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraSubDescFmt]
+\cs{glslongextraSubDescFmt}\marg{level}\marg{label}
+\end{definition}
+which defaults to just \cs{glslongextraDescFmt}\marg{label}
+
+The child symbol is formatted (where appropriate) according to:
+\begin{definition}[\DescribeMacro\glslongextraSubSymbolFmt]
+\cs{glslongextraSubSymbolFmt}\marg{level}\marg{label}
+\end{definition}
+This just does \cs{glslongextraSymbolFmt}\marg{label} by default.
+
+The styles that have a location list column format the list for
+child entries using:
+\begin{definition}[\DescribeMacro\glslongextraLocationFmt]
+\cs{glslongextraSubLocationFmt}\meta{level}\marg{label}\marg{locations}
+\end{definition}
+This just does \meta{locations} and ignores the level and label.
+
+The letter group headings are formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraGroupHeading]
+\cs{glslongextraGroupHeading}\marg{n}\marg{label}
+\end{definition}
+which does nothing by default. The first argument \meta{n} is the
+number of columns in the table. The second argument \meta{label}
+is the group label (not the title, although they may happen
+to be the same).
+
+This can be redefined to show the group heading. For example:
+\begin{verbatim}
+\renewcommand*{\glslongextraGroupHeading}[2]{%
+ \glsxtrgetgrouptitle{#2}{\thisgrptitle}%
+ \glslongextraHeaderFmt{\thisgrptitle}%
+ \tabularnewline
+ \noalign{\vskip\normalbaselineskip}%
+}
+\end{verbatim}
+This ignores the first argument and just puts the group
+title in the first column formatted according to
+\cs{glslongextraHeaderFmt} (to match the column header).
+
+Remember that you can also adjust the styles through category
+attributes. The name column's title is given by
+\cs{entryname}, the description column's title is given by
+\cs{descriptionname} and (where present) the symbol column's
+title is given by \cs{symbolname}, as for the other long styles
+that have headers.
+
+\begin{description}
+\item{\glostyle{long-name-desc}} This is like the
+\glostyle{longragged-booktabs} style but doesn't show the location
+list (regardless of the \pkgopt{nonumberlist} option). The name is
+shown in the first column and the description in the second.
+
+The symbol is not displayed. The header
+row is produced with:
+\begin{definition}[\DescribeMacro\glslongextraNameDescHeader]
+\cs{glslongextraNameDescHeader}
+\end{definition}
+This essentially uses the same code as for \glostyle{longragged-booktabs}
+but makes it easier to adjust the header without having to define a
+new style. This is defined as:
+\begin{verbatim}
+\glslongextraNameDescTabularHeader\endhead
+\glslongextraNameDescTabularFooter\endfoot
+\end{verbatim}
+where:
+\begin{definition}[\DescribeMacro\glslongextraNameDescTabularHeader]
+\cs{glslongextraNameDescTabularHeader}
+\end{definition}
+sets up the header and
+\begin{definition}[\DescribeMacro\glslongextraNameDescTabularFooter]
+\cs{glslongextraNameDescTabularFooter}
+\end{definition}
+sets up the footer. If you have setup the \env{tabular} version
+of this style then the above two commands are used at the
+start and end of the \env{tabular} environment (and
+\cs{glslongextraNameDescHeader} isn't used).
+
+For example, to simply remove the header and footer (for the default
+\env{longtable} version of the style):
+\begin{verbatim}
+\renewcommand{\glslongextraNameDescHeader}{}
+\end{verbatim}
+Or to change the name alignment to centred:
+\begin{verbatim}
+\renewcommand{\glslongextraNameAlign}{c}
+\end{verbatim}
+
+\item{\glostyle{long-name-desc-loc}} This is like the
+\glostyle{long-name-desc} style but has a third column for the
+location list. The \env{longtable} header is given by:
+\begin{definition}[\DescribeMacro\glslongextraNameDescLocationHeader]
+\cs{glslongextraNameDescLocationHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularHeader]
+\cs{glslongextraNameDescLocationTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularFooter]
+\cs{glslongextraNameDescLocationTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-desc-name}} This is like the
+\glostyle{long-name-desc} style but swaps the columns. Note that
+if the entry counter is displayed it will appear at the start
+of the second column by default. The \env{longtable} header is formatted according
+to:
+\begin{definition}[\DescribeMacro\glslongextraDescNameHeader]
+\cs{glslongextraDescNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraDescNameTabularHeader]
+\cs{glslongextraDescNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraDescNameTabularFooter]
+\cs{glslongextraDescNameTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-loc-desc-name}} This has three columns
+containing the location list, description and name. The
+\env{longtable} header
+is formatted according to:
+\begin{definition}[\DescribeMacro\glslongextraLocationDescNameHeader]
+\cs{glslongextraLocationDescNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularHeader]
+\cs{glslongextraLocationDescNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularFooter]
+\cs{glslongextraLocationDescNameTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-name-desc-sym}} This is has three columns, with
+the name in the first, the description in the second and the symbol
+in the third.
+
+The \env{longtable} header row is produced with:
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymHeader]
+\cs{glslongextraNameDescSymHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularHeader]
+\cs{glslongextraNameDescSymTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularFooter]
+\cs{glslongextraNameDescSymTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-name-desc-sym-loc}} This is has four columns, with
+the name in the first, the description in the second, the symbol
+in the third and the location list in the fourth.
+
+The \env{longtable} header row is produced with:
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationHeader]
+\cs{glslongextraNameDescSymLocationHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularHeader]
+\cs{glslongextraNameDescSymLocationTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularFooter]
+\cs{glslongextraNameDescSymLocationTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-name-sym-desc}} This is like the
+\glostyle{long-name-desc-sym} but the second and third column are
+swapped. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescHeader]
+\cs{glslongextraNameSymDescHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularHeader]
+\cs{glslongextraNameSymDescTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularFooter]
+\cs{glslongextraNameSymDescTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-name-sym-desc-loc}} This is like the
+\glostyle{long-name-desc-sym-loc} but the second and third column are
+swapped. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationHeader]
+\cs{glslongextraNameSymDescLocationHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularHeader]
+\cs{glslongextraNameSymDescLocationTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularFooter]
+\cs{glslongextraNameSymDescLocationTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-sym-desc-name}} This has the symbol in the
+first column, the description in the second and the name in the
+third. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraSymDescNameHeader]
+\cs{glslongextraSymDescNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularHeader]
+\cs{glslongextraSymDescNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularFooter]
+\cs{glslongextraSymDescNameTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-loc-sym-desc-name}} This has the location list
+in the first column, symbol in the
+second column, the description in the third and the name in the
+fourth. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameHeader]
+\cs{glslongextraLocationSymDescNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularHeader]
+\cs{glslongextraLocationSymDescNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularFooter]
+\cs{glslongextraLocationSymDescNameTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-desc-sym-name}} This has the description in the
+first column, the symbol in the second and the name in the
+third. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraDescSymNameHeader]
+\cs{glslongextraDescSymNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularHeader]
+\cs{glslongextraDescSymNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularFooter]
+\cs{glslongextraDescSymNameTabularFooter}
+\end{definition}
+
+\item{\glostyle{long-loc-desc-sym-name}} This has the location list
+in the first column, the description in the
+second column, the symbol in the third and the name in the
+fourth. The \env{longtable} header row is given by:
+\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameHeader]
+\cs{glslongextraLocationDescSymNameHeader}
+\end{definition}
+which similarly defined in terms of the commands used for the
+\env{tabular} version:
+\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularHeader]
+\cs{glslongextraLocationDescSymNameTabularHeader}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularFooter]
+\cs{glslongextraLocationDescSymNameTabularFooter}
+\end{definition}
+
+\end{description}
+
+\section{\styfmt{glossary-topic} package}
+\label{sec:topic}
+
+As from version 1.40, the \styfmt{glossaries-extra} package comes
+with the supplementary package \sty{glossary-topic} that
+provides glossary styles designed for hierarchical glossaries
+where the top-level entries are topic titles. This package
+automatically loads the \sty{multicols} package. If the
+\sty{glossary-tree} package is also loaded then commands like
+\cs{glssetwidest} can be used on these styles in much the same way
+as for the \glostyle{alttree} style. If a widest value isn't set
+then these styles behave more like the \glostyle{tree} style.
+\begin{description}
+\item[\glostyle{topic}] This style is similar to the \glostyle{tree}
+style but the indentation doesn't start until the second
+sub-item level. The top-level entries have the name displayed
+in a larger font with the description following in a new paragraph.
+This style doesn't support the \pkgopt{nogroupskip} setting.
+
+\item[\glostyle{topicmcols}] This style is like the \glostyle{topic}
+style but the sub-entries are placed inside a \env{multicols}
+environment. The environment name is supplied in the value of
+the command:
+\begin{definition}[\DescribeMacro\glstopicColsEnv]
+\cs{glstopicColsEnv}
+\end{definition}
+You can change this to the starred form. For example:
+\begin{verbatim}
+\renewcommand{\glstopicColsEnv}{multicols*}
+\end{verbatim}
+The number of columns is given by the command:
+\begin{definition}[\DescribeMacro\glstopicCols]
+\cs{glstopicCols}
+\end{definition}
+The default value is 2.
+\end{description}
+Both styles use the following commands.
+\begin{definition}[\DescribeMacro\glstopicParIndent]
+\cs{glstopicParIndent}
+\end{definition}
+This command is a length that's used for the paragraph indentation
+in any multi-paragraph description for top-level entries, but not
+for the first paragraph (at the start of the description) which
+isn't indented.
+
+\begin{definition}[\DescribeMacro\glstopicSubIndent]
+\cs{glstopicSubIndent}
+\end{definition}
+This command is a length that's used to calculate the hanging
+indentation for sub-entries. The level~1 sub-entries don't indent
+the name. Level~$n$ sub-entries have the name indented by
+$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends
+on whether or not a widest name has been set for the level.
+
+\begin{definition}[\DescribeMacro\glstopicInit]
+\cs{glstopicInit}
+\end{definition}
+Hook used at the start of the glossary. Does nothing by default.
+
+Although the styles don't support letter groups by default, if you
+have many topics (top-level entries) and you feel that it would help
+the reader to divide them up into headed letter groups, you can
+redefine:
+\begin{definition}[\DescribeMacro\glstopicGroupHeading]
+\cs{glstopicGroupHeading}\marg{group label}
+\end{definition}
+This does nothing by default. If you want to redefine it, you can
+fetch the title corresponding to the group label with
+\cs{glsxtrgetgrouptitle}. For example:
+\begin{verbatim}
+\renewcommand*{\glstopicGroupHeading}[1]{%
+ \glsxtrgetgrouptitle{#1}{\thisgrptitle}%
+ \section*{\thisgrptitle}%
+}
+\end{verbatim}
+Remember that if you use \gls{bib2gls}, you will need the
+\verb|--group| (or \verb|-g|) switch to support this.
+
+\begin{definition}[\DescribeMacro\glstopicItem]
+\cs{glstopicItem}\marg{label}\marg{location list}
+\end{definition}
+Used to format the name, symbol, description and location list
+for the top-level entries. This starts with a paragraph break
+followed by:
+\begin{definition}[\DescribeMacro\glstopicPreSkip]
+\cs{glstopicPreSkip}
+\end{definition}
+which defaults to \cs{medskip}. There is then a hook:
+\begin{definition}[\DescribeMacro\glstopicMarker]
+\cs{glstopicMarker}\marg{label}
+\end{definition}
+which does nothing by default, but may be redefined. For example,
+to add a line to the table of contents.
+The name and symbol are set in the
+form of a title using:
+\begin{definition}[\DescribeMacro\glstopicTitle]
+\cs{glstopicTitle}\marg{label}
+\end{definition}
+This uses \cs{Glossentryname} which converts the first letter to
+upper case. If there's a symbol, this is added in parentheses.
+Both name and symbol (if present) are encapsulated by
+\begin{definition}[\DescribeMacro\glstopicTitleFont]
+\cs{glstopicTitleFont}\marg{text}
+\end{definition}
+This uses a bold, large font by default.
+
+If the entry has the description key set (tested with
+\cs{ifglshasdesc}) then a paragraph break is inserted followed by:
+\begin{definition}[\DescribeMacro\glstopicMidSkip]
+\cs{glstopicMidSkip}
+\end{definition}
+which defaults to \cs{smallskip}. This is followed by the
+description which is formatted according to:
+\begin{definition}[\DescribeMacro\glstopicDesc]
+\cs{glstopicDesc}\marg{label}
+\end{definition}
+This just does \cs{Glossentrydesc}\marg{label} followed
+by the post-description hook.
+
+A paragraph break followed by:
+\begin{definition}[\DescribeMacro\glstopicPostSkip]
+\cs{glstopicPostSkip}
+\end{definition}
+comes next regardless of whether or not the description was
+displayed. This defaults to \cs{smallskip}. This is then followed
+by:
+\begin{definition}[\DescribeMacro\glstopicLoc]
+\cs{glstopicLoc}\marg{label}\marg{location list}
+\end{definition}
+which may be used to display the location list, but does nothing by
+default.
+
+The sub-entries first set up the paragraph and hanging indentations
+using:
+\begin{definition}[\DescribeMacro\glstopicAssignSubIndent]
+\cs{glstopicAssignSubIndent}\marg{level}
+\end{definition}
+This uses:
+\begin{definition}[\DescribeMacro\glstopicAssignWidest]
+\cs{glstopicAssignWidest}\marg{level}
+\end{definition}
+to determine if a widest name has been set for the given level.
+
+The sub-entry has its information displayed using:
+\begin{definition}[\DescribeMacro\glstopicSubItem]
+\cs{glstopicSubItem}\marg{level}\marg{label}\marg{location}
+\end{definition}
+This encapsulates the name with:
+\begin{definition}[\DescribeMacro\glstopicSubNameFont]
+\cs{glstopicSubNameFont}\marg{text}
+\end{definition}
+By default this just uses \cs{textbf}. This is followed by:
+\begin{definition}[\DescribeMacro\glstopicSubItemSep]
+\cs{glstopicSubItemSep}
+\end{definition}
+which defaults to \cs{quad}. The name and separator are
+passed in the \meta{text} argument of:
+\begin{definition}[\DescribeMacro\glstopicSubItemBox]
+\cs{glstopicSubItemBox}\marg{level}\marg{text}
+\end{definition}
+If a widest name was set for the given level, this will
+put \meta{text} inside a box of that width otherwise it just does
+\meta{text}.
+
+This is followed by the symbol in parentheses if set. Then, if the
+description is set, the description and post-description hook are
+displayed followed by:
+\begin{definition}[\DescribeMacro\glstopicSubPreLocSep]
+\cs{glstopicSubPreLocSep}
+\end{definition}
+(This command isn't used if the description isn't set.)
+
+Finally the location list is displayed using:
+\begin{definition}[\DescribeMacro\glstopicSubLoc]
+\cs{glstopicSubLoc}\marg{label}\marg{location}
+\end{definition}
+which just does \meta{location} by default.
+
+\section{Glossary Style Modifications}
+\label{sec:glosstylemods}
+
+The \sty{glossaries-extra-stylemods} package (more conveniently
+loaded through the \styfmt{glossaries-extra}
+\pkgopt{stylemods} option) modifies some of the predefined
+styles that are provided with the \styfmt{glossaries} package.
+These modifications are described in more detail in
+\sectionref{sec:stylemods}.
+
+The \sty{glossaries} package tries to determine the group
+title from its label by first checking if
+\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist,
+then the title is assumed to be the same as the label.
+For example, when typesetting the \qt{A} letter group,
+\sty{glossaries} first checks if \cs{Agroupname} exists.
+This could potentially cause conflict with another package
+that may have some other meaning for \cs{Agroupname}, so
+\sty{glossaries-extra} first checks for the existence
+of the internal command \cs{glsxtr@grouptitle@}\meta{label}
+which shouldn't clash with another package. You can set the
+group title using
+\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle]
+\cs{glsxtrsetgrouptitle}\marg{label}\marg{title}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrsetgrouptitle{A}{A (a)}
+\end{verbatim}
+This uses a global assignment. If you need to scope the change
+you can use
+\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle]
+\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title}
+\end{definition}
+
+\subsection{Style Hooks}
+\label{sec:stylehooks}
+
+The commands \ics{glossentryname} and \ics{glossentrydesc} are
+modified to take into account the \catattr{glossname},
+\catattr{glossdesc} and \catattr{glossdescfont} attributes (see \sectionref{sec:categories}).
+This means you can make simple case-changing modifications to
+the name and description without defining a new glossary style.
+
+If you want to adapt a style to use another field instead
+of \gloskey{name}, you can use
+\begin{definition}[\DescribeMacro\glossentrynameother]
+\cs{glossentrynameother}\marg{label}\marg{field}
+\end{definition}
+This behaves just like \cs{glossentryname} (that is, it obeys
+\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name
+hook) but it uses the given \meta{field} instead of \gloskey{name}.
+The \meta{field} argument must be the internal field name
+(for example \texttt{desc} rather than \texttt{description}).
+See the key to field mappings table in the \styfmt{glossaries}
+user manual.
+
+There is a hook after \ics{glossentryname} and
+\ics{Glossentryname}:
+\begin{definition}[\DescribeMacro\glsxtrpostnamehook]
+\cs{glsxtrpostnamehook}\marg{label}
+\end{definition}
+By default this checks the \catattr{indexname} attribute.
+If the attribute exists for the category to which the label belongs,
+then the name is automatically indexed using
+\begin{definition}
+\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}}
+\end{definition}
+See \sectionref{sec:autoindex} for further details.
+
+\begin{sloppypar}
+As from version 1.04, the post-name hook \cs{glsxtrpostnamehook}
+will also use \cs{glsxtrpostname}\meta{category} if it exists.
+You can use \ics{glscurrententrylabel} to obtain the entry label
+with the definition of this command. For example, suppose you are
+using a glossary style the doesn't display the symbol, you can
+insert the symbol after the name for a particular category, say,
+the \qt{symbol} category:
+\end{sloppypar}
+\begin{verbatim}
+\newcommand*{\glsxtrpostnamesymbol}{\space
+ (\glsentrysymbol{\glscurrententrylabel})}
+\end{verbatim}
+For convenience, as from v1.31, you can use
+\begin{definition}[\DescribeMacro\glsdefpostname]
+\cs{glsdefpostname}\marg{category}\marg{definition}
+\end{definition}
+This is simply a shortcut for:
+\begin{alltt}
+\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition}
+\end{alltt}
+Note that it doesn't check if the command has already been defined.
+
+As from version 1.25, the post-name hook also does
+\begin{definition}[\DescribeMacro\glsextrapostnamehook]
+\cs{glsextrapostnamehook}\marg{label}
+\end{definition}
+(before \cs{glsxtrpostname}\meta{category})
+to allow for additional non-category related code. This does nothing
+by default.
+
+The post-description code used within the glossary is modified so
+that it also does
+\begin{definition}[\DescribeMacro\glsxtrpostdescription]
+\cs{glsxtrpostdescription}
+\end{definition}
+This occurs before the original \cs{glspostdescription}, so if the
+\pkgopt[false]{nopostdot} option is used, it will be inserted before
+the terminating full stop.
+
+This new command will do \cs{glsxtrpostdesc\meta{category}}
+if it exists, where \meta{category} is the category label associated
+with the current entry. For example \cs{glsxtrpostdescgeneral}
+for entries with the category set to \category{general}
+or \cs{glsxtrpostdescacronym} for entries with the category set to
+\category{acronym}.
+For convenience, as from v1.31, you can use
+\begin{definition}[\DescribeMacro\glsdefpostdesc]
+\cs{glsdefpostdesc}\marg{category}\marg{definition}
+\end{definition}
+This is simply a shortcut for:
+\begin{alltt}
+\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition}
+\end{alltt}
+Note that it doesn't check if the command has already been defined.
+
+Since both \cs{glossentry} and \cs{subglossentry} set
+\begin{definition}[\DescribeMacro\glscurrententrylabel]
+\cs{glscurrententrylabel}
+\end{definition}
+to the label for the current entry, you can use this within the
+definition of these post-description hooks if you need to reference
+the label.
+
+For example, suppose you want to insert the plural form in brackets
+after the description in the glossary, but only for entries in the
+\category{general} category, then you could do:
+\begin{verbatim}
+\renewcommand{\glsxtrpostdescgeneral}{\space
+ (plural: \glsentryplural{\glscurrententrylabel})}
+\end{verbatim}
+This means you don't have to define a custom glossary style, which
+you may find more complicated. (It also allows more flexibility if
+you decide to change the underlying glossary style.)
+
+\begin{important}
+This feature can't be used for glossary styles that ignore
+\cs{glspostdescription} or if you redefine
+\cs{glspostdescription} without including \cs{glsxtrpostdescription}.
+(For example, if you redefine \cs{glspostdescription} to do
+nothing instead of using the \pkgopt{nopostdot} option to suppress
+the terminating full stop.) See \sectionref{sec:stylemods} to patch
+the predefined styles provided by \styfmt{glossaries} that are missing
+\cs{glspostdescription}.
+\end{important}
+
+\subsection{Number List}
+\label{sec:glosstylenumlist}
+
+The \gls{numberlist} is now placed inside the argument of
+\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList]
+\cs{GlsXtrFormatLocationList}\marg{number list}
+\end{definition}
+This is internally used by \cs{glossaryentrynumbers}. The
+\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it
+doesn't display the \gls{numberlist}, but it still saves the
+\gls{numberlist} in case it's required.
+
+\begin{important}
+If you want to suppress the \gls{numberlist} always use the
+\pkgopt{nonumberlist} option instead of redefining
+\cs{glossaryentrynumbers} to do nothing.
+\end{important}
+
+If you want to, for example, change the font for the entire
+\gls{numberlist} then redefine \cs{GlsXtrFormatLocationList} as
+appropriate. Don't modify \cs{glossaryentrynumbers}.
+
+Sometimes users like to insert \qt{page} or \qt{pages} in front of
+the \gls{numberlist}. This is quite fiddly to do with the base
+\styfmt{glossaries} package, but \styfmt{glossaries-extra}
+provides a way of doing this. First you need to enable this
+option and specify the text to display using:
+\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag]
+\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages}
+\end{definition}
+where \meta{page} is the text to display if the \gls{numberlist} only
+contains a single location and \meta{pages} is the text to display
+otherwise. For example:
+\begin{verbatim}
+\GlsXtrEnablePreLocationTag{Page: }{Pages: }
+\end{verbatim}
+An extra run is required when using this command.
+
+\begin{important}
+Use \texttt{glsignore} not \texttt{@gobble} as the format if you
+want to suppress the page number (and only index the entry once).
+\end{important}
+
+See the accompanying sample file \texttt{sample-pages.tex}.
+
+Note that \gls{bib2gls} can be instructed to insert
+a prefix at the start of non-empty location lists, which
+can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}.
+
+\subsection{The \styfmt{glossaries-extra-stylemods} Package}
+\label{sec:stylemods}
+
+As from v1.02, \styfmt{glossaries-extra} now includes the package
+\sty{glossaries-extra-stylemods} that will redefine the predefined
+styles to include the post-description hook (for those that are
+missing it). You will need to make sure the styles have already
+been defined before loading \styfmt{glossaries-extra}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage{glossary-longragged}
+\usepackage{glossaries-extra-stylemods}
+\end{verbatim}
+Alternatively you can load
+\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by
+passing \meta{name} as a package option to
+\sty{glossaries-extra-stylemods}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage[longragged]{glossaries-extra-stylemods}
+\end{verbatim}
+Another option is to use the \pkgopt{stylemods} key when you
+load \styfmt{glossaries-extra}. You can omit a value if you only want to use
+the predefined styles that are automatically loaded by
+\styfmt{glossaries} (for example, the \glostyle{long3col} style):
+\begin{verbatim}
+\usepackage[style=long3col,stylemods]{glossaries-extra}
+\end{verbatim}
+Or the value of \pkgopt{stylemods} may be a comma-separated list
+of the style package identifiers. For example:
+\begin{verbatim}
+\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
+\end{verbatim}
+Remember to group the value if it contains any commas:
+\begin{verbatim}
+\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
+\end{verbatim}
+
+Note that the \glostyle{inline} style is dealt with slightly
+differently. The original definition provided by the
+\sty{glossary-inline} package uses \cs{glspostdescription} at the
+end of the glossary (not after each entry description) within the
+definition of \cs{glspostinline}. The style modification changes
+this so that \cs{glspostinline} just does a full stop followed by
+space factor adjustment, and the description
+\cs{glsinlinedescformat} and sub-entry description formats
+\cs{glsinlinesubdescformat} are redefined to include
+\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means
+that the modified \glostyle{inline} style isn't affected by the
+\pkgopt{nopostdot} option, but the post-description category hook
+can still be used.
+
+The \env{tabular}-like styles, such as \glostyle{long} are
+adjusted so that the \ics{ifglsnogroupskip} conditional (set with
+\pkgopt{nogroupskip}) is moved outside of the definition of
+\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete
+\cs{iftrue}} error with \cs{printunsrtglossary} and
+\cs{printnoidxglossary}. This means that if you want to change this
+conditional using \cs{setupglossaries} or using the
+\gloskey[printglossary]{nogroupskip} option in \cs{printglossary},
+\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also
+reset the glossary style.
+
+As from version 1.21, the hard-coded \cs{space} before the
+\gls{numberlist} in many of the predefined styles is replaced
+with
+\begin{definition}[\DescribeMacro\glsxtrprelocation]
+\cs{glsxtrprelocation}
+\end{definition}
+This just defaults to \cs{space} but may be redefined as required.
+For example:
+\begin{verbatim}
+\renewcommand{\glsxtrprelocation}{\dotfill}
+\end{verbatim}
+
+The \glostyle{list} styles use
+\begin{definition}[\DescribeMacro\glslistprelocation]
+\cs{glslistprelocation}
+\end{definition}
+(which defaults to \cs{glsxtrprelocation}) for top-level items and
+\begin{definition}[\DescribeMacro\glslistchildprelocation]
+\cs{glslistchildprelocation}
+\end{definition}
+(which defaults to \cs{glslistprelocation}) for child items.
+
+As from v1.31, the description (including the post-description hook)
+is governed by:
+\begin{definition}[\DescribeMacro\glslistdesc]
+\cs{glslistdesc}\marg{label}
+\end{definition}
+for the \glostyle{list} and \glostyle{altlist} styles (but not the
+\glostyle{listdotted} variations).
+
+For just the \glostyle{list} style and its letter group variations
+(not the \glostyle{altlist} or \glostyle{listdotted} variations) the
+\gls{numberlist} for child entries is followed by
+\begin{definition}[\DescribeMacro\glslistchildpostlocation]
+\cs{glslistchildpostlocation}
+\end{definition}
+which defaults to a full stop.
+
+The default value of \ics{glslistdottedwidth} is changed so that
+it's set at the start of the document (if it hasn't been changed in
+the preamble). This should take into account situations where
+\cs{hsize} isn't set until the start of the document.
+
+The separator between groups (if not \pkgopt{nogroupskip}) is now
+given by:
+\begin{definition}[\DescribeMacro\glslistgroupskip]
+\cs{glslistgroupskip}
+\end{definition}
+This defaults to \cs{indexspace} with penalties to deter page
+breaks.
+This command isn't used if \pkgopt{nogroupskip} is set.
+
+The \sty{glossary-tree} package introduced two new commands in
+\sty{glossaries} version 4.22, \ics{glstreegroupheaderfmt}
+and \ics{glstreenavigationfmt}, which are used to format
+the letter group headings and the navigation elements for the
+appropriate styles. These two new commands are defined in terms of
+\ics{glstreenamefmt} since that was the command originally used
+for the group headings and navigation. This now allows these
+different elements to be defined independently, but the most common
+redefinition is for \cs{glstreenamefmt} to remove the bold in the
+name. If the bold is still required for the group heading and navigation
+elements, then both other commands also need redefining. To simplify
+matters, if \cs{glstreenamefmt} has been defined, as from v1.31
+\sty{glossaries-extra-stylemods} defines:
+\begin{definition}[\DescribeMacro\glstreedefaultnamefmt]
+\cs{glstreedefaultnamefmt}\marg{text}
+\end{definition}
+which simply does \cs{textbf}\marg{text} and redefines
+\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
+\cs{glstreenavigationfmt} all in terms of
+\cs{glstreedefaultnamefmt}. This means that if you want to change
+all three to use a particular style you only need to redefine
+\cs{glstreedefaultnamefmt}, but if you only want to redefine
+\cs{glstreenamefmt} without affecting the other two commands, then
+you now can.
+
+The separator between groups (if not \pkgopt{nogroupskip}) is now
+given by:
+\begin{definition}[\DescribeMacro\glstreegroupskip]
+\cs{glstreegroupskip}
+\end{definition}
+This defaults to \cs{indexspace} with penalties to deter page
+breaks.
+This command isn't used if \pkgopt{nogroupskip} is set (except for
+the styles that display the group titles).
+
+The styles that display the group titles now use:
+\begin{definition}[\DescribeMacro\glstreePreHeader]
+\cs{glstreePreHeader}\marg{label}\marg{title}
+\end{definition}
+where \meta{label} is the group label and \meta{title} is the group
+title. This does nothing by default
+and is inserted before the group title. You can redefine it to add
+the group title to the PDF bookmarks. For example, if the
+glossary title uses \cs{chapter} then:
+\begin{verbatim}
+\renewcommand{\glstreePreHeader}[2]{%
+ \pdfbookmark[1]{#2}{\currentglossary.#1}%
+}
+\end{verbatim}
+will insert section-level bookmarks. The use of \cs{currentglossary}
+helps to provide unique bookmark labels in the event of multiple
+glossaries.
+
+The \glostyle{index}-like and \glostyle{tree}-like styles
+insert the pre-\gls{numberlist} space with
+\begin{definition}[\DescribeMacro\glstreeprelocation]
+\cs{glstreeprelocation}
+\end{definition}
+(which defaults to \cs{glsxtrprelocation}) for top-level items and
+\begin{definition}[\DescribeMacro\glstreechildprelocation]
+\cs{glstreechildprelocation}
+\end{definition}
+(which defaults to \cs{glstreeprelocation}) for child items.
+
+As from version 1.31, the \styfmt{glossaries-extra-stylemods}
+package also provides:
+\begin{definition}[\DescribeMacro\glstreenonamedesc]
+\cs{glstreenonamedesc}\marg{label}
+\end{definition}
+which is used by the \glostyle{treenoname} styles to display the
+pre-description separator, the description and the post-description
+hook. Similarly for the symbol:
+\begin{definition}[\DescribeMacro\glstreenonamesymbol]
+\cs{glstreenonamesymbol}\marg{label}
+\end{definition}
+The above are just used for top-level entries. Child entries don't
+have the name or symbol displayed for the \glostyle{treenoname}
+styles, so there's only a command for the child description:
+\begin{definition}[\DescribeMacro\glstreenonamechilddesc]
+\cs{glstreenonamechilddesc}\marg{label}
+\end{definition}
+
+For the \glostyle{tree} styles (but not the \glostyle{treenoname} or
+\glostyle{alttree} styles), the description is displayed using:
+\begin{definition}[\DescribeMacro\glstreedesc]
+\cs{glstreedesc}\marg{label}
+\end{definition}
+and the symbol with:
+\begin{definition}[\DescribeMacro\glstreesymbol]
+\cs{glstreesymbol}\marg{label}
+\end{definition}
+Again the above two commands are just for top-level entries. The
+child entries use:
+\begin{definition}[\DescribeMacro\glstreechilddesc]
+\cs{glstreechilddesc}\marg{label}
+\end{definition}
+for the description and
+\begin{definition}[\DescribeMacro\glstreechildsymbol]
+\cs{glstreechildsymbol}\marg{label}
+\end{definition}
+for the symbol.
+
+As from version 1.41, there are now wrapper commands for
+\cs{glstreedesc} and \cs{glstreechilddesc} that check for
+the description and symbol to determine whether or not to insert a
+space (\cs{glstreeprelocation} or \cs{glstreechildprelocation})
+before the page list. These are:
+\begin{definition}[\DescribeMacro\glstreeDescLoc]
+\cs{glstreeDescLoc}\marg{label}\marg{location}
+\end{definition}
+for top-level entries and
+\begin{definition}[\DescribeMacro\glstreeChildDescLoc]
+\cs{glstreeChildDescLoc}\marg{label}\marg{location}
+\end{definition}
+for sub-entries. This prevents a spurious space for terms that don't
+have a symbol or description but do have a location list (for
+example, aliases).
+
+As from version 1.05, the \styfmt{glossaries-extra-stylemods}
+package provides some additional commands for use with the
+\glostyle{alttree} style to make it easier to modify.
+These commands are only defined if the
+\sty{glossary-tree} package has already been loaded, which is
+typically the case unless the \pkgopt{notree} option has been used
+when loading \styfmt{glossaries}.
+
+\begin{definition}[\DescribeMacro\gglssetwidest]
+\cs{gglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+(New to version 1.21.)
+This is like \cs{glssetwidest} (provided by \sty{glossary-tree})
+but performs a global assignment.
+
+\begin{definition}[\DescribeMacro\eglssetwidest]
+\cs{eglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+This is like \cs{glssetwidest}
+but performs a protected expansion on \meta{name}. This has
+a localised effect. For a global setting, use
+\begin{definition}[\DescribeMacro\xglssetwidest]
+\cs{xglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+The following only set the value if \meta{name} is wider than the
+current value (new to version 1.23). Local update:
+\begin{definition}[\DescribeMacro\glsupdatewidest]
+\cs{glsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update:
+\begin{definition}[\DescribeMacro\gglsupdatewidest]
+\cs{gglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Locale update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\eglsupdatewidest]
+\cs{eglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\xglsupdatewidest]
+\cs{xglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+
+
+The widest entry value can later be retrieved using
+\begin{definition}[\DescribeMacro\glsgetwidestname]
+\cs{glsgetwidestname}
+\end{definition}
+for the top-level entries and
+\begin{definition}[\DescribeMacro\glsgetwidestsubname]
+\cs{glsgetwidestsubname}\marg{level}
+\end{definition}
+for sub-entries, where \meta{level} is the level number.
+
+Note that if you are using \gls{bib2gls}, you can use the
+resource option \texttt{set-widest} which will try to determine the
+widest name of all the selected entries. This isn't guaranteed
+to work as it may depend on fonts or commands that \gls{bib2gls}
+can't replicate, but it should be suitable for names that just
+consist of text, and can be more efficient than iterating over all
+the defined entries using \TeX.
+
+The command \cs{glsfindwidesttoplevelname} provided by
+\sty{glossary-tree} has a CamelCase synonym:
+\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName]
+\cs{glsFindWidestTopLevelName}\oarg{glossary list}
+\end{definition}
+Similar commands are also provided:
+\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName]
+\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list}
+\end{definition}
+This has an additional check that the entry has been used.
+Naturally this is only useful if the glossaries that use
+the \glostyle{alttree} style occur at the end of the document.
+This command should be placed just before the start of the glossary.
+(Alternatively, place it at the end of the document and save
+the value in the auxiliary file for the next run.)
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName]
+\cs{glsFindWidestUsedAnyName}\oarg{glossary list}
+\end{definition}
+This is like the previous command but if doesn't check the
+\gloskey{parent} key. This is useful if all levels should have the
+same width for the name.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyName]
+\cs{glsFindWidestAnyName}\oarg{glossary list}
+\end{definition}
+This is like the previous command but doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo]
+\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list}
+\end{definition}
+This is like \cs{glsFindWidestUsedTopLevelName} but also sets
+the first two sub-levels as well. Any entry that has a
+great-grandparent is ignored.
+
+\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo]
+\cs{glsFindWidestLevelTwo}\oarg{glossary list}
+\end{definition}
+This is like the previous command but doesn't check if the entry has
+been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol]
+\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyName} but also measures the
+symbol. The length of the widest symbol is stored in
+\meta{register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol]
+\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register}
+\end{definition}
+This is like the previous command but it doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation]
+\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary
+list}\marg{symbol register}\marg{location register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyNameSymbol} but also
+measures the \gls{numberlist}. This requires
+\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual).
+The length of the widest symbol is stored in \meta{symbol register}
+and the length of the widest \gls*{numberlist} is stored in
+\meta{location register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation]
+\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary
+list}\marg{symbol register}\marg{location register}
+\end{definition}
+This is like the previous command but it doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation]
+\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't
+measure the symbol. The length of the widest \gls{numberlist}
+is stored in \meta{register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation]
+\cs{glsFindWidestAnyNameLocation}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like the previous command but doesn't check if the entry has
+been used.
+
+The layout of the symbol, description and \gls{numberlist}
+is governed by
+\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation]
+\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list}
+\end{definition}
+for top-level entries and
+\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation]
+\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list}
+\end{definition}
+for sub-entries.
+
+There is now a user level command that performs the initialisation
+for the \glostyle{alttree} style:
+\begin{definition}[\DescribeMacro\glsxtralttreeInit]
+\cs{glsxtralttreeInit}
+\end{definition}
+
+The paragraph indent for subsequent paragraphs in multi-paragraph
+descriptions is provided by the length
+\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent]
+\cs{glsxtrAltTreeIndent}
+\end{definition}
+
+For additional commands that are available with the
+\glostyle{alttree} style, see the documented code
+(\texttt{glossaries-extra-code.pdf}). For examples, see
+the accompanying sample files \texttt{sample-alttree.tex},
+\texttt{sample-alttree-sym.tex} and
+\texttt{sample-alttree-marginpar.tex}.
+
+\chapter{Abbreviations}
+\label{sec:abbreviations}
+
+The new abbreviation system provided by \styfmt{glossaries-extra}
+is more flexible than the acronym handling provided by the
+base \styfmt{glossaries} package. The \styfmt{glossaries-extra}
+package modifies the underlying formatting used by
+\cs{gls} (and its variants) so that terms that are recognised as
+abbreviations can have their formatting dealt with by the style. You
+therefore need to select an abbreviation style that ensures that
+\cs{gls} (and its variants) displays the desired output.
+
+\begin{important}
+Don't use commands like \cs{glstext} or \cs{glsfirst} with
+abbreviations as they aren't flexible enough to handle some
+abbreviation styles and unexpected results may occur. Use commands
+like \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or
+captions instead of \cs{gls}. If you don't want the full form to
+show on first use of \cs{gls} use one of the \qt{nolong} or
+\qt{noshort} styles.
+\end{important}
+
+Abbreviations include acronyms (words formed from initial letters,
+such as \qt{laser}),
+initialisms (initial letters of a phrase, such as \qt{html}, that
+aren't pronounced as words) and contractions (where
+parts of words are omitted, often replaced by an apostrophe, such as
+\qt{don't}).
+The \qt{acronym} code provided by the \styfmt{glossaries} package is
+misnamed as it's more often than not used for initialisms instead.
+Acronyms tend not to be \emph{expanded} on \gls{firstuse} (although they may
+need to be \emph{described} for readers unfamiliar with the term). They are therefore more like a regular term,
+which may or may not require a description in the glossary.
+
+The \styfmt{glossaries-extra} package corrects this misnomer, and
+provides better abbreviation handling, with
+\begin{definition}[\DescribeMacro\newabbreviation]
+\cs{newabbreviation}\oarg{options}\marg{label}\marg{short}\marg{long}
+\end{definition}
+
+This sets the \gloskey{category} key to \texttt{abbreviation} by
+default, but that value may be overridden in \meta{options}.
+The category may have attributes that modify the way abbreviations
+are defined. For example, the \catattr{insertdots} attribute will
+automatically insert full stops (periods) into \meta{short} or the
+\catattr{noshortplural} attribute will set the default value
+of the \gloskey{shortplural} key to just \meta{short} (without
+appending the plural suffix). See \sectionref{sec:categories} for
+further details.
+
+See \sectionref{sec:nested} regarding the pitfalls of using
+commands like \ics{gls} or \ics{glsxtrshort} within
+\meta{short} or \meta{long}.
+
+\begin{important}
+Make sure that you set the category attributes before defining new
+abbreviations or they may not be correctly applied.
+\end{important}
+
+The \ics{newacronym} command provided by the \styfmt{glossaries}
+package is redefined by \styfmt{glossaries-extra} to use
+\cs{newabbreviation} with the \gloskey{category} set to
+\texttt{acronym} (see also \sectionref{sec:acronymmods}) so
+\begin{definition}[\DescribeMacro\newacronym]
+\cs{newacronym}\oarg{options}\marg{label}\marg{short}\marg{long}
+\end{definition}
+is now equivalent to
+\begin{display}\raggedright\ttfamily
+\cs{newabbreviation}[type=\cs{acronymtype},category=acronym,\meta{options}]\marg{label}\marg{short}\marg{long}
+\end{display}
+
+\begin{sloppypar}
+The \cs{newabbreviation} command is superficially similar to the
+\styfmt{glossaries} package's \cs{newacronym} but you can apply
+different styles to different categories. The default style is
+\abbrstyle{short-nolong} for entries in the \category{acronym} category and
+\abbrstyle{short-long} for entries in the \category{abbreviation}
+category. (These aren't the same as the acronym styles provided by
+the \styfmt{glossaries} package, although they may produce similar
+results.)
+\end{sloppypar}
+
+The way the abbreviations are displayed by commands like \cs{gls}
+varies according to the abbreviation style. The styles are set
+according to the entry's category so, unlike the base
+\styfmt{glossaries} package, you can have different abbreviation
+styles within the same glossary.
+
+There are two types of full forms. The display full form, which is
+used on \gls{firstuse} by commands like \ics{gls} and the inline full
+form, which is used by commands like \ics{glsxtrfull}.
+For some of the abbreviation styles, such as \abbrstyle{long-short}, the display and inline forms
+are the same. In the case of styles such as \abbrstyle{short-nolong} or
+\abbrstyle{short-footnote}, the display and inline full forms are different.
+
+These formatting commands aren't stored in the \gloskey{short},
+\gloskey{shortplural}, \gloskey{long} or \gloskey{longplural}
+fields, which means they won't be used within commands like
+\cs{glsentryshort} (but they are used within commands like
+\cs{glsxtrshort} and \cs{glsfmtshort}).
+Note that \ics{glsxtrlong} and the case-changing variants don't use
+\cs{glsfirstlongfont}.
+
+You can apply the formatting command used for the short form
+to some arbitrary text using
+\begin{definition}[\DescribeMacro\glsuseabbrvfont]
+\cs{glsuseabbrvfont}\marg{text}\marg{category}
+\end{definition}
+where \meta{category} is the category label that identifies
+the abbreviation style. Similarly for the formatting command
+use by the long form:
+\begin{definition}[\DescribeMacro\glsuselongfont]
+\cs{glsuselongfont}\marg{text}\marg{category}
+\end{definition}
+
+\section{Tagging Initials}
+\label{sec:tagging}
+
+If you would like to tag the initial letters in the long form
+such that those letters are underlined in the glossary but
+not in the main part of the document, you can use
+\begin{definition}[\DescribeMacro\GlsXtrEnableInitialTagging]
+\cs{GlsXtrEnableInitialTagging}\marg{categories}\marg{cs}
+\end{definition}
+before you define your abbreviations.
+
+This command (robustly) defines \meta{cs} (a control sequence)
+to accept a single argument, which is the letter (or letters)
+that needs to be tagged. The normal behaviour of this command
+within the document is to simply do its argument, but in the
+glossary it's activated for those categories that have
+the \catattr{tagging} attribute set to \qt{true}. For those
+cases it will use
+\begin{definition}[\DescribeMacro\glsxtrtagfont]
+\cs{glsxtrtagfont}\marg{text}
+\end{definition}
+This command defaults to \ics{underline}\marg{text}
+but may be redefined as required.
+
+The control sequence \meta{cs} can't already be defined when
+used with the unstarred version of
+\cs{GlsXtrEnableInitialTagging} for safety reasons.
+The starred version will overwrite any previous definition
+of \meta{cs}. As with redefining any commands, ensure that
+you don't redefine something important. In fact, just forget
+the existence of the starred version and let's pretend I didn't
+mention it.
+
+The first argument of \cs{GlsXtrEnableInitialTagging} is a
+comma-separated list of category names. The \catattr{tagging}
+attribute will automatically be set for those categories.
+You can later set this attribute for other categories (see
+\sectionref{sec:categories}) but this must be done before the
+glossary is displayed.
+
+The accompanying sample file \texttt{sample-mixtures.tex}
+uses initial tagging for both the \category{acronym} and
+\category{abbreviation} categories:
+\begin{verbatim}
+\GlsXtrEnableInitialTagging{acronym,abbreviation}{\itag}
+\end{verbatim}
+This defines the command \cs{itag} which can be used in the
+definitions. For example:
+\begin{verbatim}
+\newacronym
+ [description={a system for detecting the location and
+ speed of ships, aircraft, etc, through the use of radio
+ waves}% description of this term
+ ]
+ {radar}% identifying label
+ {radar}% short form (i.e. the word)
+ {\itag{ra}dio \itag{d}etection \itag{a}nd \itag{r}anging}
+
+\newabbreviation{xml}{XML}
+ {e\itag{x}tensible \itag{m}arkup \itag{l}anguage}
+\end{verbatim}
+The underlining of the tagged letters only occurs in the
+glossary and then only for entries with the \catattr{tagging}
+attribute set.
+
+\section{Abbreviation Styles}
+\label{sec:abbrstyle}
+
+The abbreviation style must be set before abbreviations are defined
+using:
+\begin{definition}[\DescribeMacro\setabbreviationstyle]
+\cs{setabbreviationstyle}\oarg{category}\marg{style-name}
+\end{definition}
+where \meta{style-name} is the name of the style and \meta{category}
+is the category label (\texttt{abbreviation} by default). New
+abbreviations will pick up the current style according to their
+given category. If there is no style set for the category, the
+fallback is the style for the \texttt{abbreviation} category.
+Some styles may automatically modify one or more of the attributes
+associated with the given category. For example, the
+\abbrstyle{long-noshort} and \abbrstyle{short-nolong} styles set the
+\catattr{regular} attribute to \texttt{true}.
+
+\begin{important}
+If you want to apply different styles to groups of abbreviations,
+assign a different category to each group and set the style for the
+given category.
+\end{important}
+
+Note that \ics{setacronymstyle} is disabled by
+\styfmt{glossaries-extra}. Use
+\begin{alltt}
+\cs{setabbreviationstyle}[acronym]\marg{style-name}
+\end{alltt}
+instead. The original acronym interface can be restored with
+\ics{RestoreAcronyms} (see \sectionref{sec:acronymmods}). However the
+original acronym interface is incompatible with all the commands
+described here.
+
+Abbreviations can be used with the standard \styfmt{glossaries}
+commands, such as \ics{gls}, but don't use the acronym commands
+like \ics{acrshort} (which use \ics{acronymfont}). The short form can be
+produced with:
+\begin{definition}[\DescribeMacro\glsxtrshort]
+\cs{glsxtrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(Use this instead of \ics{acrshort}.)
+
+The long form can be produced with
+\begin{definition}[\DescribeMacro\glsxtrlong]
+\cs{glsxtrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(Use this instead of \ics{acrlong}.)
+
+The \emph{inline} full form can be produced with
+\begin{definition}[\DescribeMacro\glsxtrfull]
+\cs{glsxtrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(This this instead of \ics{acrfull}.)
+
+\begin{important}
+In general, it's best not to use commands like \ics{glsfirst}
+for abbreviations, especially if you use the \meta{insert}
+optional argument. Use either \cs{gls} (possibly with a reset)
+or \cs{glsxtrfull}.
+\end{important}
+
+As mentioned earlier, the inline full form may not necessarily match the format used on
+\gls{firstuse} with \cs{gls}. For example, the
+\abbrstyle{short-nolong} style
+only displays the short form on \gls{firstuse}, but the full
+form will display the long form followed by the short form in
+parentheses.
+
+\begin{important}
+If you want to use an abbreviation in a chapter or section
+title, use the commands described in \sectionref{sec:headtitle}
+instead.
+\end{important}
+
+The arguments \meta{options}, \meta{label} and \meta{insert} are the
+same as for commands such as \cs{glstext}. There are also analogous
+case-changing commands:
+
+First letter upper case short form:
+\begin{definition}[\DescribeMacro\Glsxtrshort]
+\cs{Glsxtrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+First letter upper case long form:
+\begin{definition}[\DescribeMacro\Glsxtrlong]
+\cs{Glsxtrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+First letter upper case inline full form:
+\begin{definition}[\DescribeMacro\Glsxtrfull]
+\cs{Glsxtrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+All upper case short form:
+\begin{definition}[\DescribeMacro\Glsxtrshort]
+\cs{GLSxtrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+All upper case long form:
+\begin{definition}[\DescribeMacro\Glsxtrlong]
+\cs{GLSxtrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+All upper case inline full form:
+\begin{definition}[\DescribeMacro\GLSxtrfull]
+\cs{GLSxtrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+Plural forms are also available.
+
+Short form plurals:
+\begin{definition}[\DescribeMacro\glsxtrshortpl]
+\cs{glsxtrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsxtrshortpl]
+\cs{Glsxtrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\GLSxtrshortpl]
+\cs{GLSxtrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+Long form plurals:
+\begin{definition}[\DescribeMacro\glsxtrlongpl]
+\cs{glsxtrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsxtrlongpl]
+\cs{Glsxtrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\GLSxtrlongpl]
+\cs{GLSxtrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+Full form plurals:
+\begin{definition}[\DescribeMacro\glsxtrfullpl]
+\cs{glsxtrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsxtrfullpl]
+\cs{Glsxtrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\GLSxtrfullpl]
+\cs{GLSxtrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+
+\begin{important}
+Be careful about using \cs{glsentryfull}, \cs{Glsentryfull},
+\cs{glsentryfullpl} and \cs{Glsentryfullpl}. These commands will use
+the currently applied style rather than the style in use when the
+entry was defined. If you have mixed styles, you'll need to use
+\ics{glsxtrfull} instead. Similarly for \cs{glsentryshort} etc.
+\end{important}
+
+\section{Shortcut Commands}
+\label{sec:abbrshortcuts}
+
+The abbreviation shortcut commands can be enabled using
+the package option \pkgopt[abbreviation]{shortcuts}
+(or \pkgopt[abbr]{shortcuts}) or \pkgopt[ac]{shortcuts}.
+(You can use both settings at the same time.)
+The provided shortcut commands listed in
+\tableref{tab:abbrshortcuts}.
+
+\begin{table}[htbp]
+\caption{Abbreviation Shortcut Commands}
+\label{tab:abbrshortcuts}
+\centering
+\begin{tabular}{lll}
+\bfseries Shortcut &
+\bfseries Shortcut &
+\bfseries Equivalent Command\\
+\bfseries (\pkgopt[abbreviation]{shortcuts}) &
+\bfseries (\pkgopt[ac]{shortcuts})\\
+\ics{ab} & \ics{ac} & \ics{cgls}\\
+\ics{abp} & \ics{acp} & \ics{cglspl}\\
+\ics{as} & \ics{acs} & \ics{glsxtrshort}\\
+\ics{asp} & \ics{acsp} & \ics{glsxtrshortpl}\\
+\ics{al} & \ics{acl} & \ics{glsxtrlong}\\
+\ics{alp} & \ics{aclp} & \ics{glsxtrlongpl}\\
+\ics{af} & \ics{acf} & \ics{glsxtrfull}\\
+\ics{afp} & \ics{acfp} & \ics{glsxtrfullpl}\\
+\ics{Ab} & \ics{Ac} & \ics{cgls}\\
+\ics{Abp} & \ics{Acp} & \ics{cglspl}\\
+\ics{As} & \ics{Acs} & \ics{Glsxtrshort}\\
+\ics{Asp} & \ics{Acsp} & \ics{Glsxtrshortpl}\\
+\ics{Al} & \ics{Acl} & \ics{Glsxtrlong}\\
+\ics{Alp} & \ics{Aclp} & \ics{Glsxtrlongpl}\\
+\ics{Af} & \ics{Acf} & \ics{Glsxtrfull}\\
+\ics{Afp} & \ics{Acfp} & \ics{Glsxtrfullpl}\\
+\ics{AB} & \ics{AC} & \ics{cGLS}\\
+\ics{ABP} & \ics{ACP} & \ics{cGLSpl}\\
+\ics{AS} & \ics{ACS} & \ics{GLSxtrshort}\\
+\ics{ASP} & \ics{ACSP} & \ics{GLSxtrshortpl}\\
+\ics{AL} & \ics{ACL} & \ics{GLSxtrlong}\\
+\ics{ALP} & \ics{ACLP} & \ics{GLSxtrlongpl}\\
+\ics{AF} & \ics{ACF} & \ics{GLSxtrfull}\\
+\ics{AFP} & \ics{ACFP} & \ics{GLSxtrfullpl}\\
+\ics{newabbr} & \ics{newabbr} & \ics{newabbreviation}
+\end{tabular}
+\end{table}
+
+\section{Predefined Abbreviation Styles}
+\label{sec:predefabbrvstyles}
+
+There are two types of abbreviation styles: those that treat the
+abbreviation as a regular entry (so that \ics{gls} uses
+\ics{glsgenentryfmt}) and those that don't treat the abbreviation as
+a regular entry (so that \ics{gls} uses \ics{glsxtrgenabbrvfmt}).
+
+The regular entry abbreviation styles set the \catattr{regular}
+attribute to \qt{true} for the category assigned to each
+abbreviation with that style. This means that on \gls{firstuse},
+\ics{gls} uses the value of the \gloskey{first} field and on
+subsequent use \ics{gls} uses the value of the \gloskey{text} field
+(and analogously for the plural and case-changing versions). The
+\gloskey{short} and \gloskey{long} fields are set as appropriate
+and may be accessed through commands like \ics{glsxtrshort}.
+
+The other abbreviation styles don't modify the \catattr{regular}
+attribute. The \gloskey{first} and \gloskey{text} fields (and their
+plural forms) are set and can be accessed through commands like
+\cs{glsfirst}, but they aren't used by commands like \ics{gls},
+which instead use the short form (stored in the \gloskey{short} key)
+and the display full format (through commands like
+\ics{glsxtrfullformat} that are defined by the style).
+
+In both cases, the \gls{firstuse} of \ics{gls} may not match the
+text produced by \ics{glsfirst} (and likewise for the plural
+and case-changing versions).
+
+The sample file \texttt{sample-abbr-styles.tex} demonstrates all
+predefined styles described here.
+
+\begin{important}
+For the \qt{sc} styles that use \ics{textsc}, be careful about your choice
+of fonts as some only have limited support. For
+example, you may not be able to combine bold and small-caps. I
+recommend that you at least use the \sty{fontenc} package with the
+\pkgoptfmt{T1} option or something similar.
+\end{important}
+
+The parenthetical styles, such as \abbrstyle{long-short},
+use
+\begin{definition}[\DescribeMacro\glsxtrparen]
+\cs{glsxtrparen}\marg{text}
+\end{definition}
+to set the parenthetical material. This just puts parentheses around
+the text: (\meta{text}).
+
+The basic abbreviation styles, such as \abbrstyle{long-short}
+and \abbrstyle{short-long} use
+\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
+\cs{glsabbrvdefaultfont}\marg{text}
+\end{definition}
+for the short form. This just does \meta{text} by default.
+(That is, no font change is applied.) On first use,
+\begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont]
+\cs{glsfirstabbrvdefaultfont}\marg{text}
+\end{definition}
+is used instead. By default, this just does
+\cs{glsabbrvdefaultfont}. The long form is formatted according to
+\begin{definition}[\DescribeMacro\glslongdefaultfont]
+\cs{glslongdefaultfont}\marg{text}
+\end{definition}
+which again just does \meta{text} (no font change). On first use,
+\begin{definition}[\DescribeMacro\glsfirstlongdefaultfont]
+\cs{glsfirstlongdefaultfont}\marg{text}
+\end{definition}
+is used instead. This just does \cs{glslongdefaultfont}.
+The plural suffix used for the short form is given by
+\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix]
+\cs{glsxtrabbrvpluralsuffix}
+\end{definition}
+which defaults to \ics{glspluralsuffix}.
+
+The small-cap styles, such as \abbrstyle{long-short-sc}
+and \abbrstyle{short-sc-long}, use
+\begin{definition}[\DescribeMacro\glsabbrvscfont]
+\cs{glsabbrvscfont}\marg{text}
+\end{definition}
+which uses \cs{textsc}.\footnote{For compatibility with earlier
+versions, \cs{glsabbrvscfont} is defined to \cs{glsxtrscfont},
+which is defined to use \cs{textsc}. Direct use of
+\cs{glsxtrscfont} is now deprecated. Likewise for similar commands.}
+On first use
+\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
+\cs{glsfirstabbrvscfont}\marg{text}
+\end{definition}
+is used instead. This uses \cs{glsabbrvscfont} by default.
+So redefine, \cs{glsabbrvscfont} to change first and subsequent uses or
+\cs{glsfirstabbrvscfont} to change just the first use.
+
+The long form for the small-cap styles uses \cs{glslongdefaultfont}
+or \cs{glsfirstlongdefaultfont}, as with the basic style.
+The suffix is given by
+\begin{definition}[\DescribeMacro\glsxtrscsuffix]
+\cs{glsxtrscsuffix}
+\end{definition}
+This is defined as
+\begin{verbatim}
+\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}}
+\end{verbatim}
+The \ics{glstextup} command is provided by \styfmt{glossaries}
+and is used to switch off the small caps font for the suffix.
+If you override the default short plural using the
+\gloskey{shortplural} key when you define the abbreviation
+you will need to make the appropriate adjustment if necessary.
+(Remember that the default plural suffix behaviour can be modified
+through the use of the \catattr{aposplural} and
+\catattr{noshortplural} attributes. See
+\sectionref{sec:categories} for further details.)
+
+The small styles, such as \abbrstyle{long-short-sm}
+and \abbrstyle{short-sm-long}, use
+\begin{definition}[\DescribeMacro\glsabbrvsmfont]
+\cs{glsabbrvsmfont}\marg{text}
+\end{definition}
+which uses \cs{textsmaller}. (This requires the \sty{relsizes}
+package, which isn't loaded by \styfmt{glossaries-extra}, so must be
+loaded explicitly.)
+On first use
+\begin{definition}[\DescribeMacro\glsfirstabbrvsmfont]
+\cs{glsfirstabbrvsmfont}\marg{text}
+\end{definition}
+is used instead. This uses \cs{glsabbrvsmfont} by default.
+
+The long form for the smaller styles uses \cs{glslongdefaultfont}
+or \cs{glsfirstlongdefaultfont}, as with the basic style.
+The suffix is given by
+\begin{definition}[\DescribeMacro\glsxtrsmsuffix]
+\cs{glsxtrsmsuffix}
+\end{definition}
+which defaults to just \cs{glsxtrabbrvpluralsuffix}.
+
+The \qt{short-em} (emphasize short) styles, such as
+\abbrstyle{long-short-em} or \abbrstyle{short-em-long}, use
+\begin{definition}[\DescribeMacro\glsabbrvemfont]
+\cs{glsabbrvemfont}\marg{text}
+\end{definition}
+On first use
+\begin{definition}[\DescribeMacro\glsfirstabbrvemfont]
+\cs{glsfirstabbrvemfont}\marg{text}
+\end{definition}
+is used instead. This uses \cs{glsabbrvemfont} by default.
+The suffix is given by
+\begin{definition}[\DescribeMacro\glsxtremsuffix]
+\cs{glsxtremsuffix}
+\end{definition}
+which defaults to just \cs{glsxtrabbrvpluralsuffix}.
+The long form is as for the basic style unless the style
+is a \qt{long-em} style.
+
+The \qt{long-em} (emphasize long) styles, such as
+\abbrstyle{long-em-short-em} or \abbrstyle{short-em-long-em}, use
+\begin{definition}[\DescribeMacro\glsfirstlongemfont]
+\cs{glsfirstlongemfont}\marg{long-form}
+\end{definition}
+instead of \cs{glsfirstlongdefaultfont}\marg{long-form} and
+\begin{definition}[\DescribeMacro\glslongemfont]
+\cs{glslongemfont}\marg{long-form}
+\end{definition}
+instead of \cs{glslongdefaultfont}\marg{long-form}. The first form
+\cs{glsfirstlongemfont} is initialised to use \cs{glslongemfont}.
+
+The user styles have similar commands:
+\begin{definition}[\DescribeMacro\glsabbrvuserfont]
+\cs{glsabbrvuserfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvuserfont]
+\cs{glsfirstabbrvuserfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslonguserfont]
+\cs{glslonguserfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlonguserfont]
+\cs{glsfirstlonguserfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtrusersuffix]
+\cs{glsxtrusersuffix}
+\end{definition}
+for the short plural suffix.
+
+Similarly for the hyphen styles:
+\begin{definition}[\DescribeMacro\glsabbrvhyphenfont]
+\cs{glsabbrvhyphenfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvhyphenfont]
+\cs{glsfirstabbrvhyphenfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslonghyphenfont]
+\cs{glslonghyphenfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlonghyphenfont]
+\cs{glsfirstlonghyphenfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtrhyphensuffix]
+\cs{glsxtrhyphensuffix}
+\end{definition}
+for the short plural suffix.
+
+Similarly for the \qt{only} styles, such as
+\abbrstyle{long-only-short-only}:
+\begin{definition}[\DescribeMacro\glsabbrvonlyfont]
+\cs{glsabbrvonlyfont}\marg{text}
+\end{definition}
+for the short form,
+\begin{definition}[\DescribeMacro\glsfirstabbrvonlyfont]
+\cs{glsfirstabbrvonlyfont}\marg{text}
+\end{definition}
+for the first use short form,
+\begin{definition}[\DescribeMacro\glslongonlyfont]
+\cs{glslongonlyfont}\marg{text}
+\end{definition}
+for the long form,
+\begin{definition}[\DescribeMacro\glsfirstlongonlyfont]
+\cs{glsfirstlongonlyfont}\marg{text}
+\end{definition}
+for the first use long form, and
+\begin{definition}[\DescribeMacro\glsxtronlysuffix]
+\cs{glsxtronlysuffix}
+\end{definition}
+for the short plural suffix.
+
+Note that by default inserted material (provided in the final
+optional argument of commands like \cs{gls}), is placed outside the
+font command in the predefined styles. To move it inside, use:
+\begin{definition}[\DescribeMacro\glsxtrinsertinsidetrue]
+\cs{glsxtrinsertinsidetrue}
+\end{definition}
+This applies to all the predefined styles. For example:
+\begin{verbatim}
+\setabbreviationstyle{long-short}
+\renewcommand*{\glsfirstlongdefaultfont}[1]{\emph{#1}}
+\glsxtrinsertinsidetrue
+\end{verbatim}
+This will make the long form and the inserted text emphasized,
+whereas the default (without \cs{glsxtrinsertinsidetrue}) would
+place the inserted text outside of the emphasized font.
+
+Note that for some styles, such as the \abbrstyle{short-long}, the
+inserted text would be placed inside the font command for the short
+form (rather than the long form in the above example).
+
+Remember that \cs{textsc} renders \emph{lowercase} letters as small
+capitals. Uppercase letters are rendered as normal uppercase
+letters, so if you specify the short form in uppercase, you won't
+get small capitals unless you redefine \cs{glsabbrvscfont} to
+convert its argument to lowercase. For example:
+\begin{verbatim}
+\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeLowercase{#1}}}
+\end{verbatim}
+
+If you want to
+easily switch between the \qt{sc} and \qt{sm} styles, you may find
+it easier to redefine this command to convert case:
+\begin{verbatim}
+\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeTextLowercase{#1}}}
+\renewcommand*{\glsabbrvsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}}
+\end{verbatim}
+
+Some of the styles use
+\begin{definition}[\DescribeMacro\glsxtrfullsep]
+\cs{glsxtrfullsep}\marg{label}
+\end{definition}
+as a separator between the long and short forms. This is defined as
+a space by default, but may be changed as required. For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrfullsep}[1]{~}
+\end{verbatim}
+or
+\begin{verbatim}
+\renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}}
+\end{verbatim}
+
+The new naming scheme for abbreviation styles is as follows:
+\begin{itemize}
+\item
+\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[post]\meta{field2}[\texttt{-}\meta{modifier2}][\texttt{-user}]
+
+This is for the parenthetical styles. The \texttt{-}\meta{modifier} parts may
+be omitted. These styles display \meta{field1} followed by
+\meta{field2} in parentheses. If \meta{field1} or \meta{field2} starts
+with \qt{no} then that element is omitted from the display style (no
+parenthetical part) but is included in the inline style.
+
+If the \texttt{-}\meta{modifier} part is present, then the field has
+a font changing command applied to it. The special modifier
+\texttt{-only} indicates that field is only present according to
+whether or not the entry has been used.
+
+If \texttt{post} is present then \meta{field2} is
+placed after the \gls{linktext} using the post-link hook.
+
+If the \texttt{-user} part is present, then the \gloskey{user1}
+value, if provided, is inserted into the parenthetical material .
+(The field used for the inserted material may be changed.)
+
+Examples:
+ \begin{itemize}
+ \item\abbrstyle{long-noshort-sc}: \meta{field1} is the long
+form, the short form is set in smallcaps but omitted in the display
+style.
+ \item\abbrstyle{long-em-short-em}: both the long form and the
+short form are emphasized. The short form is in parentheses.
+ \item\abbrstyle{long-short-em}: the
+short form is emphasized but not the long form. The short form is in parentheses.
+ \item\abbrstyle{long-short-user}: if the \gloskey{user1} key has
+been set, this produces the style \meta{long} (\meta{short},
+\meta{user1}) otherwise it just produces \meta{long} (\meta{short}).
+
+ \item\abbrstyle{long-hyphen-postshort-hyphen}: the short
+form and the inserted material (provided by the final optional
+argument of commands like \cs{gls}) is moved to the post-link hook.
+The long form is formatted according to \cs{glslonghyphenfont}
+(or \cs{glsfirstlonghyphenfont} on first use).
+The short form is formatted according to \cs{glsabbrvhyphenfont}
+(or \cs{glsfirstabbrvhyphenfont} on first use).
+ \end{itemize}
+
+\item \meta{style}\texttt{-noreg}
+
+Some styles set the \catattr{regular} attribute. In some cases,
+there's a version of the style that doesn't set this attribute.
+For example, \abbrstyle{long-em-noshort-em} sets the
+\catattr{regular} attribute. The
+\abbrstyle{long-em-noshort-em-noreg} style is a minor variation
+that style that doesn't set the attribute.
+
+There are a few \qt{noshort} styles, such as
+\abbrstyle{long-hyphen-noshort-noreg}, that have
+\qt{-noreg} version without a regular version. This is because the
+style won't work properly with the \catattr{regular} set, but the
+naming scheme is maintained for consistency with the other
+\qt{noshort} styles.
+
+\item
+\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[\texttt{post}]\texttt{footnote}
+
+The display style uses \meta{field1} followed by a footnote with the
+other field in it. If \texttt{post} is present then the footnote is
+placed after the \gls{linktext} using the post-link hook.
+The inline style does \meta{field1} followed by the other field in
+parentheses.
+
+If \texttt{-}\meta{modifier1} is present, \meta{field1} has a
+font-changing command applied to it.
+
+Examples:
+\begin{itemize}
+\item \abbrstyle{short-footnote}: short form in the text with the
+long form in the footnote.
+\item \abbrstyle{short-sc-postfootnote}: short form in smallcaps
+with the long form in the footnote outside of the \gls{linktext}.
+\end{itemize}
+
+\begin{important}
+Take care with the footnote styles. Remember that there are some
+situations where \ics{footnote} doesn't work.
+\end{important}
+
+\item \meta{style}\texttt{-desc}
+
+Like \meta{style} but the \gloskey{description} key must be provided
+when defining abbreviations with this style.
+
+Examples:
+\begin{itemize}
+
+\item \abbrstyle{short-long-desc}: like \abbrstyle{short-long} but
+requires a description.
+\item \abbrstyle{short-em-footnote-desc}: like
+\abbrstyle{short-em-footnote} but requires a description.
+\end{itemize}
+\end{itemize}
+
+Not all combinations that fit the above syntax are provided.
+Pre-version 1.04 styles that didn't fit this naming scheme are either
+provided with a synonym (where the former name wasn't ambiguous) or
+provided with a deprecated synonym (where the former name was
+confusing).
+The deprecated style names generate a warning using:
+\begin{definition}[\DescribeMacro\GlsXtrWarnDeprecatedAbbrStyle]
+\cs{GlsXtrWarnDeprecatedAbbrStyle}\marg{old-name}\marg{new-name}
+\end{definition}
+where \meta{old-name} is the deprecated name and \meta{new-name} is
+the preferred name. You can suppress these warnings by redefining
+this command to do nothing.
+
+\subsection{Predefined Abbreviation Styles that Set the Regular
+Attribute}
+\label{sec:predefregabbrvstyles}
+
+The following abbreviation styles set the \catattr{regular}
+attribute to \qt{true} for all categories that have abbreviations
+defined with any of these styles.
+
+\begin{description}
+\item[\abbrstyledef{short-nolong}]
+This only displays the short form on \gls{firstuse}. The \gloskey{name}
+is set to the short form through the command
+\begin{definition}[\DescribeMacro\glsxtrshortnolongname]
+\cs{glsxtrshortnolongname}
+\end{definition}
+(Similarly for the other
+\texttt{short}\meta{modifier}\texttt{-nolong}\meta{modifier} styles,
+unless indicated otherwise.)
+This command is expanded as the entry is defined, so any
+redefinition must be done before \cs{newabbreviation} (or
+\cs{newacronym}) for it to take effect. Make sure to \cs{protect}
+any formatting commands (or anything else that shouldn't be expanded).
+
+The \gloskey{description} is set to the
+long form. The inline full form displays
+\meta{short} (\meta{long}). The long form on its own can be
+displayed through commands like \ics{glsxtrlong}.
+
+\item[\abbrstyledef{short}] A synonym for \abbrstyle{short-nolong}.
+
+\item[\abbrstyledef{nolong-short}] Like \abbrstyle{short-nolong}
+but the inline full form displays
+\meta{long} (\meta{short}).
+
+\item[\abbrstyledef{short-sc-nolong}]
+Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont} (which defaults to \cs{textsc}).
+
+\item[\abbrstyledef{short-sc}] A synonym for \abbrstyle{short-sc-nolong}
+
+\item[\abbrstyledef{nolong-short-sc}] Like \abbrstyle{short-sc-nolong}
+but the inline full form displays
+\meta{long} (\meta{short}). The name is still obtained from
+\cs{glsxtrshortnolongname} (similarly for the other styles in the
+form \texttt{nolong}\meta{modifier}\texttt{-short}\meta{modifier}
+unless indicated otherwise).
+
+\item[\abbrstyledef{short-sm-nolong}]
+Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}).
+
+\item[\abbrstyledef{short-sm}] A synonym for \abbrstyle{short-sm-nolong}.
+
+\item[\abbrstyledef{nolong-short-sm}] Like \abbrstyle{short-sm-nolong}
+but the inline full form displays
+\meta{long} (\meta{short}).
+
+\item[\abbrstyledef{short-em-nolong}]
+Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{short-em}] A synonym for \abbrstyle{short-em-nolong}
+
+\item[\abbrstyledef{nolong-short-em}] Like \abbrstyle{short-em-nolong}
+but the inline full form displays
+\meta{long} (\meta{short}).
+
+\item[\abbrstyledef{short-nolong-desc}]
+Like the \abbrstyle{short-nolong} style, but the \gloskey{name} is set to
+the full form obtained by expanding
+\begin{definition}[\DescribeMacro\glsxtrshortdescname]
+\cs{glsxtrshortdescname}
+\end{definition}
+(Similarly for the other
+\texttt{short}\meta{modifier}\texttt{-nolong}\meta{modifier}\texttt{-desc}
+styles, unless indicated otherwise.) This command is expanded when the entry is defined, so
+\cs{protect} fragile and formatting commands and only redefine this
+command before \cs{newabbreviation} (or \cs{newacronym}).
+
+The \gloskey{description} must be supplied by the
+user. You may prefer to use the \abbrstyle{short-nolong} style with the
+post-description hook set to display the long form and override
+the \gloskey{description} key. (See the sample file
+\texttt{sample-acronym-desc.tex}.)
+
+\item[\abbrstyledef{short-desc}] A synonym for
+\abbrstyle{short-nolong-desc}.
+
+\item[\abbrstyledef{short-sc-nolong-desc}]
+Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont} (which defaults to \cs{textsc}).
+
+\item[\abbrstyledef{short-sc-desc}] A synonym for
+\abbrstyle{short-sc-nolong-desc}.
+
+\item[\abbrstyledef{short-sm-nolong-desc}]
+Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}).
+
+\item[\abbrstyledef{short-sm-desc}] A synonym for
+\abbrstyle{short-sm-nolong-desc}.
+
+\item[\abbrstyledef{short-em-nolong-desc}]
+Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{short-em-desc}] A synonym for
+\abbrstyle{short-em-nolong-desc}.
+
+\item[\abbrstyledef{long-noshort-desc}]
+This style only displays the long form, regardless of first or
+subsequent use of commands \ics{gls}. The short form may be
+accessed through commands like \ics{glsxtrshort}. The inline full
+form displays \meta{long} (\meta{short}).
+
+The \gloskey{sort} key are set to the long form.
+The \gloskey{name} key is also set to the long form, but this is
+done by expanding
+\begin{definition}[\DescribeMacro\glsxtrlongnoshortdescname]
+\cs{glsxtrlongnoshortdescname}
+\end{definition}
+(Similarly for the other
+\texttt{long}\meta{modifier}\texttt{-noshort}\meta{modifier}\texttt{-desc}
+styles, unless indicated otherwise.) This command should only be redefined before abbreviations
+are defined, and any fragile or formatting commands within it need protecting.
+
+The \gloskey{description} must be provided by the user. The predefined
+glossary styles won't display the short form. You can use the
+post-description hook to automatically append the short form to the
+description. The inline full form will display \meta{long}
+(\meta{short}).
+
+\item[\abbrstyledef{long-desc}] A synonym for
+\abbrstyle{long-noshort-desc}.
+
+\item[\abbrstyledef{long-noshort-sc-desc}]
+Like the \abbrstyle{long-noshort-desc} style but the short form (accessed
+through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}.
+(This style was originally called \depabbrstyle{long-desc-sc}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-noshort-sm-desc}]
+Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+(This style was originally called \depabbrstyle{long-desc-sm}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-noshort-em-desc}]
+Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}. The long form isn't emphasized.
+(This style was originally called \depabbrstyle{long-desc-em}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-em-noshort-em-desc}]
+New to version 1.04, like \abbrstyle{long-noshort-desc} but redefines
+\cs{glsabbrvfont} to use \ics{glsabbrvemfont}. The long form uses
+\ics{glsfirstlongemfont} and \ics{glslongemfont}.
+
+\item[\abbrstyledef{long-noshort}]
+This style doesn't really make sense if you don't use the short
+form anywhere in the document, but is provided for completeness.
+This is like the \abbrstyle{long-noshort-desc} style, but
+the \gloskey{sort} key is set to the short form. The \gloskey{name}
+key is also set to the short form, but this is done by expanding
+\begin{definition}[\DescribeMacro\glsxtrlongnoshortname]
+\cs{glsxtrlongnoshortname}
+\end{definition}
+(Similarly for other
+\texttt{long}\meta{modifier}\texttt{-noshort}\meta{modifier} styles,
+unless indicated otherwise.)
+This command should only be redefined before abbreviations are
+defined, and fragile or formatting commands should be protected.
+
+The \gloskey{description} is set to the long form.
+
+\item[\abbrstyledef{long}] A synonym for \abbrstyle{long-noshort}
+
+\item[\abbrstyledef{long-noshort-sc}]
+Like the \abbrstyle{long-noshort} style but the short form (accessed
+through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}.
+(This style was originally called \depabbrstyle{long-sc}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-noshort-sm}]
+Like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+(This style was originally called \depabbrstyle{long-sm}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-noshort-em}]
+This style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}. The long form isn't emphasized.
+(This style was originally called \depabbrstyle{long-em}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{long-em-noshort-em}]
+New to version 1.04, this style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}, \cs{glsfirstlongfont} to use
+\cs{glsfirstlongemfont} and \cs{glslongfont} to use
+\cs{glslongemfont}. The short form isn't used by commands like
+\ics{gls}, but can be obtained using \ics{glsxtrshort}.
+The related style \abbrstyledef{long-em-noshort-em-noreg}
+doesn't set the \catattr{regular} attribute.
+
+\end{description}
+
+\subsection{Predefined Abbreviation Styles that Don't Set the Regular
+Attribute}
+\label{sec:predefnonregabbrvstyles}
+
+The following abbreviation styles will set the
+\catattr{regular} attribute to \qt{false} if it has previously
+been set. If it hasn't already been set, it's left unset.
+Other attributes may also be set, depending on the style.
+
+\begin{description}
+\item[\abbrstyledef{long-short}]
+On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}).
+The inline and display full forms are the same. The
+ \gloskey{sort} key is set to the short form. The \gloskey{name} is
+also set to the short form through
+\begin{definition}[\DescribeMacro\glsxtrlongshortname]
+\cs{glsxtrlongshortname}
+\end{definition}
+(Similarly for other
+\texttt{long}\meta{modifier}\texttt{-short}\meta{modifier} styles,
+unless indicated otherwise.)
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+The \gloskey{description} is set to the long form. The long and short
+forms are separated by \cs{glsxtrfullsep}. If you want to insert
+material within the parentheses (such as a~translation), try the
+\abbrstyle{long-short-user} style.
+
+\item[\abbrstyledef{long-short-sc}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{long-short-sm}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{long-short-em}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{long-em-short-em}]
+New to version 1.04, this style is like \abbrstyle{long-short-em} but redefines \cs{glsfirstlongfont} to
+use \ics{glsfirstlongemfont}.
+
+\item[\abbrstyledef{long-only-short-only}]
+New to version 1.17, this style only shows the long form
+on first use and only shows the short form on subsequent use.
+The inline full form \cs{glsxtrfull} shows the long form
+followed by the short form in parentheses. The \gloskey{name}
+field is obtained from
+\begin{definition}[\DescribeMacro\glsxtronlyname]
+\cs{glsxtronlyname}
+\end{definition}
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+\item[\abbrstyledef{long-only-short-only-desc}]
+New to version 1.17, this style is like
+\abbrstyle{long-only-short-only} but the user must supply the
+description. The \gloskey{name}
+field is obtained from
+\begin{definition}[\DescribeMacro\glsxtronlydescname]
+\cs{glsxtronlydescname}
+\end{definition}
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+\item[\abbrstyledef{long-em-noshort-em-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-em-noshort-em} but
+doesn't set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{long-short-user}]
+This style was introduced in version 1.04. It's like the
+\abbrstyle{long-short} style but additional information can be
+inserted into the parenthetical material. This checks the value
+of the field given by
+\begin{definition}[\DescribeMacro\glsxtruserfield]
+\cs{glsxtruserfield}
+\end{definition}
+(which defaults to \texttt{useri}) using \ics{ifglshasfield}
+(provided by \styfmt{glossaries}). If the field hasn't been set,
+the style behaves like the \abbrstyle{long-short} style and
+produces \meta{long} (\meta{short}) but if the field has been set,
+the contents of that field are inserted within the parentheses in
+the form \meta{long} (\meta{short}, \meta{field-value}).
+The format is governed by
+\begin{definition}[\DescribeMacro\glsxtruserparen]
+\cs{glsxtruserparen}\marg{text}\marg{label}
+\end{definition}
+where \meta{text} is the short form (for the
+\abbrstyle{long-short-user} style) or the long form (for the
+\abbrstyle{short-long-user} style). This command first inserts
+a space using \cs{glsxtrfullsep} and then the parenthetical content
+(using \ics{glsxtrparen}).
+The \gloskey{description} is set to
+\begin{definition}[\DescribeMacro\glsuserdescription]
+\cs{glsuserdescription}\marg{long}\marg{label}
+\end{definition}
+The default definition ignores the \meta{label} and encapsulates
+\meta{long} with \cs{glslonguserfont}.
+
+The \gloskey{name} is obtained by expanding
+\cs{glsxtrlongshortname} (see above).
+The \meta{text} argument includes the font formatting command,
+\cs{glsfirstabbrvfont}\marg{short} in the case of the
+\abbrstyle{long-short-user} style and
+\cs{glsfirstlongfont}\marg{long} in the
+case of the \abbrstyle{short-long-user} style.
+
+For example:
+\begin{verbatim}
+\setabbreviationstyle[acronym]{long-short-user}
+
+\newacronym{tug}{TUG}{\TeX\ User Group}
+
+\newacronym
+ [user1={German Speaking \TeX\ User Group}]
+ {dante}{DANTE}{Deutschsprachige Anwendervereinigung \TeX\ e.V}
+
+\end{verbatim}
+On first use, \verb|\gls{tug}| will appear as:
+\begin{quote}
+\TeX\ User Group (TUG)
+\end{quote}
+whereas \verb|\gls{dante}| will appear as:
+\begin{quote}
+Deutschsprachige Anwendervereinigung \TeX\ e.V (DANTE, German Speaking \TeX\ User Group)
+\end{quote}
+
+The short form is formatted according to
+\begin{definition}[\DescribeMacro\glsabbrvuserfont]
+\cs{glsabbrvuserfont}\marg{text}
+\end{definition}
+and the plural suffix is given by
+\begin{definition}[\DescribeMacro\glsxtrusersuffix]
+\cs{glsxtrusersuffix}
+\end{definition}
+
+These may be redefined as appropriate. For example,
+if you want a~smallcaps style, you can just set these commands
+to those used by the \abbrstyle{long-short-sc} style:
+\begin{verbatim}
+\renewcommand{\glsabbruserfont}[1]{\glsabbrvscfont{#1}}
+\renewcommand{\glsxtrusersuffix}{\glsxtrscsuffix}
+\end{verbatim}
+
+\item[\abbrstyledef{long-noshort-noreg}]
+This style is like \abbrstyle{long-noshort} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{long-noshort-desc-noreg}]
+This style is like \abbrstyle{long-noshort-desc} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{long-short-desc}]
+On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}).
+The inline and display full forms are the same. The \gloskey{name}
+is set to the full form. The \gloskey{sort} key is set to
+\meta{long} (\meta{short}). Before version 1.04, this was
+incorrectly set to the short form. If you want to revert back to
+this you can redefine
+\begin{definition}[\DescribeMacro\glsxtrlongshortdescsort]
+\cs{glsxtrlongshortdescsort}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrlongshortdescsort}{\the\glsshorttok}
+\end{verbatim}
+The \gloskey{description} must be supplied by the user.
+The long and short forms are separated by \cs{glsxtrfullsep}. The \gloskey{name}
+field is obtained from
+\begin{definition}[\DescribeMacro\glsxtrlongshortdescname]
+\cs{glsxtrlongshortdescname}
+\end{definition}
+(Similarly for other
+\texttt{long}\meta{modifier}\texttt{-short}\meta{modifier}\texttt{-desc}
+styles, unless indicated otherwise.)
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+\item[\abbrstyledef{long-short-sc-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{long-short-sm-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{long-short-em-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{long-em-short-em-desc}]
+New to version 1.04, this style is like \abbrstyle{long-short-em-desc} but redefines \cs{glsfirstlongfont} to
+use \ics{glsfirstlongemfont}.
+
+\item[\abbrstyledef{long-em-noshort-em-desc-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-em-noshort-em-desc} but
+doesn't set the \catattr{regular} attribute.
+
+
+\item[\abbrstyledef{long-short-user-desc}]
+New to version 1.04, this style is like a~cross between the
+\abbrstyle{long-short-desc} style and the
+\abbrstyle{long-short-user} style. The display and inline forms are
+as for \abbrstyle{long-short-user} and the \gloskey{name} key is
+obtained from
+\begin{definition}[\DescribeMacro\glsxtrlongshortuserdescname]
+\cs{glsxtrlongshortuserdescname}
+\end{definition}
+Again, this should only be redefined before \cs{newabbreviation} (or
+\cs{newacronym}), and fragile and formatting commands need protecting.
+
+The \gloskey{description} key must be
+supplied in the optional argument of \cs{newabbreviation}
+(or \cs{newacronym}). The \gloskey{sort} key is set to \meta{long}
+(\meta{short}) as per the \abbrstyle{long-short-desc} style.
+
+\item[\abbrstyledef{short-nolong-noreg}]
+This is like \abbrstyle{short-nolong} but doesn't set the
+\catattr{regular} attribute.
+
+\item[\abbrstyledef{nolong-short-noreg}]
+This is like \abbrstyle{nolong-short} but doesn't set the
+\catattr{regular} attribute.
+
+\item[\abbrstyledef{short-long}]
+On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}).
+The inline and display full forms are the same. The \gloskey{name}
+and \gloskey{sort} keys are set to the short form. The
+\gloskey{description} is set to the long form.
+The short and long forms are separated by \cs{glsxtrfullsep}.
+If you want to insert
+material within the parentheses (such as a~translation), try the
+\abbrstyle{short-long-user} style.
+
+The \gloskey{name} field is obtained from
+\begin{definition}[\DescribeMacro\glsxtrshortlongname]
+\cs{glsxtrshortlongname}
+\end{definition}
+(Similarly for other
+\texttt{short}\meta{modifier}\texttt{-long}\meta{modifier} styles,
+unless indicated otherwise.)
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+
+\item[\abbrstyledef{short-sc-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{short-sm-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{short-em-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{short-em-long-em}]
+New to version 1.04, this style is like \abbrstyle{short-em-long} but redefines \cs{glsfirstlongfont} to
+use \ics{glsfirstlongemfont}.
+
+\item[\abbrstyledef{short-long-user}]
+New to version 1.04. This style is like the
+\abbrstyle{long-short-user} style but with the long and short forms
+switched. The parenthetical material is governed by the same command
+\ics{glsxtruserparen}, but the first argument supplied to it is
+the long form instead of the short form. The \gloskey{name} field is
+obtained by expanding
+\begin{definition}[\DescribeMacro\glsxtrshortlongname]
+\cs{glsxtrshortlongname}
+\end{definition}
+Again, this should only be redefined before \cs{newabbreviation} (or
+\cs{newacronym}) and commands that should be expanded need to be
+protected. The \gloskey{description} is set to
+\cs{glsuserdescription}\marg{long}\marg{label}.
+
+\item[\abbrstyledef{short-nolong-desc-noreg}]
+This style is like \abbrstyle{short-nolong-desc} but it doesn't
+set the \catattr{regular} attribute.
+
+\item[\abbrstyledef{short-long-desc}]
+On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}).
+The inline and display full forms are the same. The \gloskey{name}
+is set to the full form. The
+\gloskey{description} must be supplied by the user.
+The short and long forms are separated by \cs{glsxtrfullsep}. The \gloskey{name}
+field is obtained from
+\begin{definition}[\DescribeMacro\glsxtrshortlongdescname]
+\cs{glsxtrshortlongdescname}
+\end{definition}
+(Similarly for other
+\texttt{short}\meta{modifier}\texttt{-long}\meta{modifier}\texttt{-desc}
+styles, unless indicated otherwise.)
+Any redefinition of this command must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+\item[\abbrstyledef{short-sc-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{short-sm-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{short-em-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
+\item[\abbrstyledef{short-em-long-em-desc}]
+New to version 1.04, this style is like \abbrstyle{short-em-long-desc} but redefines \cs{glsfirstlongfont} to
+use \ics{glsfirstlongemfont}.
+
+\item[\abbrstyledef{short-long-user-desc}]
+New to version 1.04, this style is like a~cross between the
+\abbrstyle{short-long-desc} style and the
+\abbrstyle{short-long-user} style. The display and inline forms are
+as for \abbrstyle{short-long-user}, but the \gloskey{name} key is
+obtained from
+\begin{definition}[\DescribeMacro\glsxtrshortlonguserdescname]
+\cs{glsxtrshortlonguserdescname}
+\end{definition}
+Again, this should only be redefined before \cs{newabbreviation} (or
+\cs{newacronym}), and fragile and formatting commands need protecting.
+
+The \gloskey{description} key must be
+supplied in the optional argument of \cs{newabbreviation}
+(or \cs{newacronym}).
+
+\item[\abbrstyledef{short-footnote}]
+On \gls{firstuse}, this style displays the short form with the long form
+as a footnote. This style automatically sets the
+\catattr{nohyperfirst} attribute to \qt{true} for the supplied
+category, so the \gls{firstuse} won't be hyperlinked (but the footnote
+marker may be, if the \sty{hyperref} package is used).
+
+The inline full form uses the \meta{short}
+(\meta{long}) style. The \gloskey{name} is set to the short form.
+The \gloskey{description} is set to the long form. The
+\gloskey{name} key is obtained by expanding
+\begin{definition}[\DescribeMacro\glsxtrfootnotename]
+\cs{glsxtrfootnotename}
+\end{definition}
+(Similarly for other
+\texttt{short\meta{modifier}-\meta{modifier}footnote} styles, unless
+indicated otherwise.) Again, this command should only be redefined
+before \cs{newabbreviation} (or \cs{newacronym}), and fragile or
+formatting commands should be protected from expansion.
+
+As from version 1.05, all the footnote styles use:
+\begin{definition}[\DescribeMacro\glsfirstlongfootnotefont]
+\cs{glsfirstlongfootnotefont}\marg{text}
+\end{definition}
+to format the long form on \gls{firstuse} or for the full form and
+\begin{definition}[\DescribeMacro\glslongfootnotefont]
+\cs{glslongfootnotefont}\marg{text}
+\end{definition}
+to format the long form elsewhere (for example, when used with
+\cs{glsxtrlong}).
+
+As from version 1.07, all the footnote styles use:
+\begin{definition}[\DescribeMacro\glsxtrabbrvfootnote]
+\cs{glsxtrabbrvfootnote}\marg{label}\marg{long}
+\end{definition}
+By default, this just does \ics{footnote}\marg{long} (the first
+argument is ignored). For example, to make the footnote text
+link to the relevant place in the glossary:
+\begin{verbatim}
+\renewcommand{\glsxtrabbrvfootnote}[2]{%
+ \footnote{\glshyperlink[#2]{#1}}%
+}
+\end{verbatim}
+or to include the short form with a hyperlink:
+\begin{verbatim}
+\renewcommand{\glsxtrabbrvfootnote}[2]{%
+ \footnote{\glshyperlink[\glsfmtshort{#1}]{#1}: #2}%
+}
+\end{verbatim}
+Note that I haven't used commands like \cs{glsxtrshort} to
+avoid interference (see \sectionref{sec:entryfmtmods}
+and \sectionref{sec:nested}).
+
+\item[\abbrstyledef{footnote}] A synonym for
+\abbrstyle{short-footnote}.
+
+\item[\abbrstyledef{short-sc-footnote}]
+Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+(This style was originally called \depabbrstyle{footnote-sc}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-sc-footnote}]
+Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+(This style was originally called \depabbrstyle{footnote-sm}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-em-footnote}]
+Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+(This style was originally called \depabbrstyle{footnote-em}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-postfootnote}]
+This is similar to the \abbrstyle{short-footnote} style but doesn't modify
+the category attribute. Instead it changes \postlinkcat\ to
+insert the footnote after the
+\gls{linktext} on \gls{firstuse}. This will also defer the footnote until after any
+following punctuation character that's recognised by
+\ics{glsxtrifnextpunc}.
+
+The inline full form uses the \meta{short}
+(\meta{long}) style. The \gloskey{name} is set to the short form.
+The \gloskey{description} is set to the long form.
+Note that this style will change \cs{glsxtrfull} (and its variants)
+so that it fakes non-\gls{firstuse}. (Otherwise the footnote would
+appear after the inline form.)
+
+\item[\abbrstyledef{postfootnote}] A synonym for
+\abbrstyle{short-postfootnote}.
+
+\item[\abbrstyledef{short-sc-postfootnote}]
+Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+(This style was originally called \depabbrstyle{postfootnote-sc}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-sm-postfootnote}]
+Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+(This style was originally called \depabbrstyle{postfootnote-sm}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-em-postfootnote}]
+Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+(This style was originally called \depabbrstyle{postfootnote-em}. Renamed in version
+1.04, but original name retained as a deprecated synonym for
+backward-compatibility.)
+
+\item[\abbrstyledef{short-postlong-user}]
+This style was introduced in version 1.12. It's like the
+\abbrstyle{short-long-user} style but defers the parenthetical
+material to after the link-text. This means that you don't have such
+a long hyperlink (which can cause problems for the DVI \LaTeX\ format)
+and it also means that the user supplied material can include a
+hyperlink to another location. The \gloskey{name} key is obtained
+from \cs{glsxtrshortlongname}.
+
+\item[\abbrstyledef{short-postlong-user-desc}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{short-postlong-user} style but the \gloskey{description}
+must be specified. The \gloskey{name} is obtained from
+\cs{glsxtrshortlonguserdescname}.
+
+\item[\abbrstyledef{long-postshort-user}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{short-postlong-user} style but the long form is shown
+first and the short form is in the parenthetical material (as for
+\abbrstyle{long-short-user}) style.
+
+\item[\abbrstyledef{long-postshort-user-desc}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{long-postshort-user} style but the \gloskey{description}
+must be specified. The \gloskey{name} is obtained from
+\cs{glsxtrlongshortuserdescname}.
+
+\item[\abbrstyledef{long-hyphen-short-hyphen}]
+This style (new to v1.17) is designed to work with the \catattr{markwords}
+category attribute. The full form is formatted using
+\begin{definition}[\DescribeMacro\glsxtrlonghyphenshort]
+\cs{glsxtrlonghyphenshort}\marg{label}\marg{long}\marg{short}\marg{insert}
+\end{definition}
+where \meta{insert} is the inserted material
+provided in the final optional argument of commands like
+\cs{insert}. If \meta{insert} start with a hyphen, then this
+locally redefines \ics{glsxtrwordsep} to a hyphen, which means that
+if the \catattr{markwords} attribute is set then the long form
+will become hyphenated. (If this attribute isn't set, there's
+no alteration to the way the long form is displayed.)
+The \gloskey{name} key is obtained from \cs{glsxtrlongshortname}.
+
+Unlike the other \meta{long} (\meta{short}) type of styles,
+such as \abbrstyle{long-short}, this style
+also repeats the insertion in the parenthetical part, so that the
+first use form is:
+\begin{quote}
+\cs{glsfirstlonghyphenfont}\marg{long}\meta{insert}
+(\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{insert})
+\end{quote}
+The space before the parenthetical material is actually given by
+\cs{glsxtrfullsep}\marg{label} which defaults to a space.
+The \meta{insert} may be moved into the formatting commands
+according to the conditional \cs{ifglsxtrinsertinside}.
+
+For example, if \texttt{ip} is defined using:
+\begin{verbatim}
+\glssetcategoryattribute{english}{markwords}{true}
+\setabbreviationstyle[english]{long-hyphen-short-hyphen}
+\newabbreviation[category=english]{ip}{IP}{Internet Protocol}
+\end{verbatim}
+then
+\begin{verbatim}
+\gls{ip}[-Adressen]
+\end{verbatim}
+will do
+\begin{quote}
+Internet-Protocol-Adressen (IP-Adressen)
+\end{quote}
+on first use, whereas
+\begin{verbatim}
+\gls{ip}[ Address]
+\end{verbatim}
+will do
+\begin{quote}
+Internet Protocol Address (IP Address)
+\end{quote}
+on first use.
+
+\begin{important}
+Note that the hyphenation isn't applied when using commands like
+\cs{glsxtrlong}. This means that
+\begin{verbatim}
+\glsxtrlong{ip}[-Adressen]
+\end{verbatim}
+will do
+\begin{quote}
+Internet Protocol-Adressen
+\end{quote}
+\end{important}
+
+If the \catattr{markwords} attribute hadn't been set, then the
+first use of
+\begin{verbatim}
+\gls{ip}[-Adressen]
+\end{verbatim}
+would do
+\begin{quote}
+Internet Protocol-Adressen (IP-Adressen)
+\end{quote}
+instead.
+
+\begin{important}
+If the inserted material \meta{insert} is likely to contain commands like
+\cs{gls}, then use \abbrstyle{long-hyphen-postshort-hyphen}
+instead to avoid nested links.
+\end{important}
+
+If you want the short version in small-caps, you can
+just redefine \cs{glsabbrvhyphenfont} and \cs{glsxtrhyphensuffix}
+to use the small-caps versions. For example:
+\begin{verbatim}
+\renewcommand{\glsabbrvhyphenfont}{\glsabbrvscfont}
+\renewcommand{\glsxtrhyphensuffix}{\glsxtrscsuffix}
+\end{verbatim}
+Similarly for other font-changing variations.
+
+\item[\abbrstyledef{long-hyphen-noshort-desc-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-hyphen-short-hyphen-desc} except that the
+parenthetical part is omitted and the long form is displayed
+on subsequent use. The short form can be accessed
+with \cs{glsxtrshort} but just uses the default abbreviation font.
+There's no regular version of this style as the regular form
+doesn't have the flexibility to deal with the hyphen switch.
+The \gloskey{name} is obtained from \cs{glsxtrlongnoshortdescname}.
+
+\item[\abbrstyledef{long-hyphen-noshort-noreg}]
+New to version 1.17, this style is like
+\abbrstyle{long-hyphen-noshort-desc-noreg} but the
+name is set to the short form and the description is set to the long
+form.
+
+\item[\abbrstyledef{long-hyphen-short-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-short-hyphen} but the user
+supplies the description. The \gloskey{name} is obtained from
+\cs{glsxtrlongshortdescname}.
+
+\item[\abbrstyledef{long-hyphen-postshort-hyphen}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-short-hyphen} but the
+inserted and parenthetical material are moved to the post-link hook.
+On first use, \cs{gls}\marg{label}\oarg{insert} will do
+\begin{display}
+\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert}\cs{glsxtrposthyphenshort}\marg{label}\meta{insert}
+\end{display}
+where
+\begin{definition}[\DescribeMacro\glsxtrposthyphenshort]
+\cs{glsxtrposthyphenshort}\marg{label}\meta{insert}
+\end{definition}
+is in the post-link hook. This uses the format:
+\begin{display}
+\meta{insert} (\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{isnert})
+\end{display}
+
+\begin{important}
+The singular short form is always used here, even with \cs{glspl}.
+(Unlike \abbrstyle{long-hyphen-long-hyphen}.)
+\end{important}
+
+The part in the link-text on first use:
+\begin{definition}[\DescribeMacro\glsxtrlonghyphen]
+\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert}
+\end{definition}
+checks if \meta{insert} starts with a hyphen. If it does, then
+\cs{glsxtrwordsep} is locally redefined to a hyphen. This command
+only uses \meta{insert} to test if it starts with a hyphen.
+The actual insertion code isn't typeset until the post-link
+hook and it's also localised, which means that you can use
+commands like \cs{gls} in \meta{insert} for this style without
+causing nested hyperlinks, but only for commands like \cs{gls}.
+
+\begin{important}
+Don't use \cs{gls} in the \meta{insert} part for commands
+like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}.
+\end{important}
+
+The inline full display format used by commands like \cs{glsxtrfull}
+behaves differently to the first use of \cs{gls} with this style.
+It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label}
+if you want to ensure the full format.
+
+\item[\abbrstyledef{long-hyphen-postshort-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{long-hyphen-postshort-hyphen} but the
+user supplies the description. The \gloskey{name} is obtained from
+\cs{glsxtrlongshortdescname}.
+
+
+\item[\abbrstyledef{short-hyphen-long-hyphen}]
+This style (new to v1.17) is like
+\abbrstyle{long-hyphen-short-hyphen}, except that the short form
+is displayed first followed by the long form in parentheses. The full form is formatted using
+\begin{definition}[\DescribeMacro\glsxtrshorthyphenlong]
+\cs{glsxtrshorthyphenlong}\marg{label}\marg{short}\marg{long}\marg{insert}
+\end{definition}
+which behaves in an analogous way to \cs{glsxtrlonghyphenshort}.
+The \gloskey{name} is obtained from \cs{glsxtrshortlongname}.
+
+\item[\abbrstyledef{short-hyphen-long-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{short-hyphen-long-hyphen} but the
+user supplies the description.
+The \gloskey{name} is obtained from \cs{glsxtrshortlongdescname}.
+
+\item[\abbrstyledef{short-hyphen-postlong-hyphen}]
+This style (new to v1.17) is like
+\abbrstyle{long-hyphen-postshort-hyphen}, but the
+short form is displayed first followed by the long form in
+parentheses.
+On first use, \cs{gls}\marg{label}\oarg{insert} will do
+\begin{display}
+\cs{glsxtrshorthyphen}\marg{short}\marg{label}\marg{insert}\cs{glsxtrposthyphenlong}\marg{label}\meta{insert}
+\end{display}
+where
+\begin{definition}[\DescribeMacro\glsxtrposthyphenlong]
+\cs{glsxtrposthyphenlong}\marg{label}\meta{insert}
+\end{definition}
+is in the post-link hook. These commands behave in an analogous
+manner to those used with \abbrstyle{long-hyphen-postshort-hyphen}.
+The \gloskey{name} is obtained from \cs{glsxtrshortlongname}.
+
+\begin{important}
+Don't use \cs{gls} in the \meta{insert} part for commands
+like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}.
+\end{important}
+
+The inline full display format used by commands like \cs{glsxtrfull}
+behaves differently to the first use of \cs{gls} with this style.
+It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label}
+if you want to ensure the full format.
+
+\item[\abbrstyledef{short-hyphen-postlong-hyphen-desc}]
+
+New to version 1.17.
+This is similar to \abbrstyle{short-hyphen-postlong-hyphen} but the
+user supplies the description. The \gloskey{name} is obtained from
+\cs{glsxtrshortlongdescname}.
+
+\end{description}
+
+\section{Defining New Abbreviation Styles}
+\label{sec:newabbrvstyle}
+
+New abbreviation styles may be defined using:
+\begin{definition}[\DescribeMacro\newabbreviationstyle]
+\cs{newabbreviationstyle}\marg{name}\marg{setup}\marg{fmts}
+\end{definition}
+\begin{sloppypar}\noindent
+where \meta{name} is the name of the new style (as used in the
+mandatory argument of \ics{setabbreviationstyle}). This is similar
+but not identical to the \styfmt{glossaries} package's
+\ics{newacronymstyle} command.
+\end{sloppypar}
+
+\begin{important}
+You can't use styles defined by
+\cs{newacronymstyle} with \styfmt{glossaries-extra} unless you have
+reverted \ics{newacronym} back to its generic definition from \styfmt{glossaries}
+(using \ics{RestoreAcronyms}). The acronym styles from the
+\styfmt{glossaries} package can't be used with abbreviations defined
+with \cs{newabbreviation}.
+\end{important}
+
+The \meta{setup} argument deals with the way the entry is defined
+and may set attributes for the given abbreviation
+category. This argument should redefine
+\begin{definition}[\DescribeMacro\CustomAbbreviationFields]
+\cs{CustomAbbreviationFields}
+\end{definition}
+to set the entry fields including the \gloskey{name} (defaults to
+the short form if omitted),
+\gloskey{sort}, \gloskey{first}, \gloskey{firstplural}. Other fields
+may also be set, such as \gloskey{text}, \gloskey{plural} and
+\gloskey{description}.
+
+\begin{important}
+\cs{CustomAbbreviationFields} is expanded by \cs{newabbreviation}
+so take care to protect commands that shouldn't be expanded.
+\end{important}
+
+For example, the \abbrstyle{long-short} style has the following in
+\meta{setup}:
+\begin{verbatim}
+ \renewcommand*{\CustomAbbreviationFields}{%
+ name={\protect\glsabbrvfont{\the\glsshorttok}},
+ sort={\the\glsshorttok},
+ first={\protect\glsfirstlongfont{\the\glslongtok}%
+ \protect\glsxtrfullsep{\the\glslabeltok}%
+ \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshorttok}}},%
+ firstplural={\protect\glsfirstlongfont{\the\glslongpltok}%
+ \protect\glsxtrfullsep{\the\glslabeltok}%
+ \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshortpltok}}},%
+ plural={\protect\glsabbrvfont{\the\glsshortpltok}},%
+ description={\the\glslongtok}}%
+\end{verbatim}
+Note that the \gloskey{first} and \gloskey{firstplural} are
+set even though they're not used by \cs{gls}.
+
+The basic styles, such as \abbrstyle{long-short}, use commands like
+\cs{glsabbrvfont} (which are redefined whenever the style formatting
+is set) within \cs{CustomAbbreviationFields}. Other styles, such as
+\abbrstyle{long-em-short-em} directly use their own custom commands,
+such as \cs{glsabbrvemfont}. With these styles, commands like
+\cs{glsabbrvfont} still need to be defined as appropriate in the
+\meta{fmts} argument even if they're not used within
+\cs{CustomAbbreviationFields}.
+
+The \meta{setup} argument may also redefine
+\begin{definition}[\DescribeMacro\GlsXtrPostNewAbbreviation]
+\cs{GlsXtrPostNewAbbreviation}
+\end{definition}
+which can be used to assign attributes. (This will automatically
+be initialised to do nothing.)
+
+For example, the \abbrstyle{short-footnote} includes the following in
+\meta{setup}:
+\begin{verbatim}
+ \renewcommand*{\GlsXtrPostNewAbbreviation}{%
+ \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}%
+ \glshasattribute{\the\glslabeltok}{regular}%
+ {%
+ \glssetattribute{\the\glslabeltok}{regular}{false}%
+ }%
+ {}%
+ }%
+\end{verbatim}
+This sets the \catattr{nohyperfirst} attribute to \qt{true}.
+It also unsets the \catattr{regular} attribute if it has
+previously been set. Note that the \catattr{nohyperfirst}
+attribute doesn't get unset by other styles, so take care
+not to switch styles for the same category.
+
+You can access the short, long, short plural and long plural
+values through the following token registers.
+
+Short value (defined by \styfmt{glossaries}):
+\begin{definition}[\DescribeMacro\glsshorttok]
+\cs{glsshorttok}
+\end{definition}
+
+Short plural value (defined by \styfmt{glossaries-extra}):
+\begin{definition}[\DescribeMacro\glsshortpltok]
+\cs{glsshortpltok}
+\end{definition}
+(This may be the default value or, if provided, the value provided by the user
+through the \gloskey{shortplural} key in the optional argument
+of \ics{newabbreviation}.)
+
+Long value (defined by \styfmt{glossaries}):
+\begin{definition}[\DescribeMacro\glslongtok]
+\cs{glslongtok}
+\end{definition}
+
+Long plural value (defined by \styfmt{glossaries-extra}):
+\begin{definition}[\DescribeMacro\glslongpltok]
+\cs{glslongpltok}
+\end{definition}
+(This may be the default value or, if provided, the value provided by the user
+through the \gloskey{longplural} key in the optional argument
+of \ics{newabbreviation}.)
+
+The short or long values may be modified by attributes (such as
+\catattr{markwords}). The above registers reflect the modification.
+If you want to access the original (unmodified) short or long form
+(as provided in the final two arguments of \cs{newabbreviation}),
+then use the commands:
+\begin{definition}[\DescribeMacro\glsxtrorgshort]
+\cs{glsxtrorgshort}
+\end{definition}
+for the short form and
+\begin{definition}[\DescribeMacro\glsxtrorglong]
+\cs{glsxtrorglong}
+\end{definition}
+for the long form. (These may be useful for the \gloskey{sort} key
+to avoid any formatting that may be added by the attribute setting.)
+
+There are two other registers available that are defined by
+\styfmt{glossaries}:
+
+\begin{definition}[\DescribeMacro\glslabeltok]
+\cs{glslabeltok}
+\end{definition}
+which contains the entry's label and
+\begin{definition}[\DescribeMacro\glskeylisttok]
+\cs{glskeylisttok}
+\end{definition}
+which contains the values provided in the optional argument
+of \ics{newabbreviation}.
+
+Remember put \cs{the} in front of the register command as in the
+examples above. The category label can be access through
+the command (not a register):
+\begin{definition}[\DescribeMacro\glscategorylabel]
+\cs{glscategorylabel}
+\end{definition}
+This may be used inside the definition of
+\cs{GlsXtrPostNewAbbreviation}.
+
+If you want to base a style on an existing style, you can use
+\begin{definition}[\DescribeMacro\GlsXtrUseAbbrStyleSetup]
+\cs{GlsXtrUseAbbrStyleSetup}\marg{name}
+\end{definition}
+where \meta{name} is the name of the existing style.
+For example, the \abbrstyle{long-noshort-sc-desc} style simply does
+\begin{verbatim}
+\GlsXtrUseAbbrStyleSetup{long-noshort-desc}
+\end{verbatim}
+within \meta{setup}.
+
+The \meta{fmts} argument deals with the way the entry is displayed
+in the document. This argument should redefine the following
+commands.
+
+The default suffix for the plural short form (if not overridden by
+the \gloskey{shortplural} key):
+\begin{definition}[\DescribeMacro\abbrvpluralsuffix]
+\cs{abbrvpluralsuffix}
+\end{definition}
+(Note that this isn't used for the plural long form, which
+just uses the regular \cs{glspluralsuffix}.)
+
+The font used for the short form on \gls{firstuse} or in the full forms:
+\begin{definition}[\DescribeMacro\glsfirstabbrvfont]
+\cs{glsfirstabbrvfont}\marg{text}
+\end{definition}
+
+The font used for the short form on subsequent use or through
+commands like \ics{glsxtrshort}:
+\begin{definition}[\DescribeMacro\glsabbrvfont]
+\cs{glsabbrvfont}\marg{text}
+\end{definition}
+
+The font used for the long form on \gls{firstuse} or in the full forms:
+\begin{definition}[\DescribeMacro\glsfirstlongfont]
+\cs{glsfirstlongfont}\marg{text}
+\end{definition}
+
+The font used for the long form in commands like \cs{glsxtrlong}
+use:
+\begin{definition}[\DescribeMacro\glslongfont]
+\cs{glslongfont}\marg{text}
+\end{definition}
+
+Display full form singular no case-change (used by \ics{gls} on
+\gls{firstuse} for abbreviations without the \catattr{regular} attribute
+set):
+\begin{definition}[\DescribeMacro\glsxtrfullformat]
+\cs{glsxtrfullformat}\marg{label}\marg{insert}
+\end{definition}
+
+Display full form singular first letter converted to upper case
+(used by \ics{Gls} on \gls{firstuse} for abbreviations without the
+\catattr{regular} attribute set):
+\begin{definition}[\DescribeMacro\Glsxtrfullformat]
+\cs{Glsxtrfullformat}\marg{label}\marg{insert}
+\end{definition}
+
+Display full form plural no case-change
+(used by \ics{glspl} on \gls{firstuse} for abbreviations without the
+\catattr{regular} attribute set):
+\begin{definition}[\DescribeMacro\glsxtrfullplformat]
+\cs{glsxtrfullplformat}\marg{label}\marg{insert}
+\end{definition}
+
+Display full form plural first letter converted to upper case
+(used by \ics{Glspl} on \gls{firstuse} for abbreviations without the
+\catattr{regular} attribute set):
+\begin{definition}[\DescribeMacro\Glsxtrfullplformat]
+\cs{Glsxtrfullplformat}\marg{label}\marg{insert}
+\end{definition}
+
+In addition \meta{fmts} may also redefine the following commands that
+govern the inline full formats. If the style doesn't redefine them,
+they will default to the same as the display full forms.
+
+Inline singular no case-change (used by
+\ics{glsentryfull}, \ics{glsxtrfull} and \ics{GLSxtrfull}):
+\begin{definition}[\DescribeMacro\glsxtrinlinefullformat]
+\cs{glsxtrinlinefullformat}\marg{label}\marg{insert}
+\end{definition}
+
+Inline singular first letter converted to upper case (used by
+\ics{Glsentryfull} and \ics{Glsxtrfull}):
+\begin{definition}[\DescribeMacro\Glsxtrinlinefullformat]
+\cs{Glsxtrinlinefullformat}\marg{label}\marg{insert}
+\end{definition}
+
+Inline plural no case-change (used by
+\ics{glsentryfullpl}, \ics{glsxtrfullpl} and \ics{GLSxtrfullpl}):
+\begin{definition}[\DescribeMacro\glsxtrinlinefullplformat]
+\cs{glsxtrinlinefullplformat}\marg{label}\marg{insert}
+\end{definition}
+
+Inline plural first letter converted to upper case (used by
+\ics{Glsentryfullpl} and \ics{Glsxtrfullpl}):
+\begin{definition}[\DescribeMacro\Glsxtrinlinefullplformat]
+\cs{Glsxtrinlinefullplformat}\marg{label}\marg{insert}
+\end{definition}
+
+(New to version 1.17.)
+You can also modify the way the subsequent use is formatted by
+redefining the following four commands, but these won't be used for
+abbreviations with the \catattr{regular} attribute set. If the style
+doesn't redefine these commands, the default values are used.
+
+Singular with no case-change:
+\begin{definition}[\DescribeMacro\glsxtrsubsequentfmt]
+\cs{glsxtrsubsequentfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Singular with first letter upper case:
+\begin{definition}[\DescribeMacro\Glsxtrsubsequentfmt]
+\cs{Glsxtrsubsequentfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Plural with no case-change:
+\begin{definition}[\DescribeMacro\glsxtrsubsequentplfmt]
+\cs{glsxtrsubsequentplfmt}\marg{label}\marg{insert}
+\end{definition}
+
+Plural with first letter upper case:
+\begin{definition}[\DescribeMacro\Glsxtrsubsequentplfmt]
+\cs{Glsxtrsubsequentplfmt}\marg{label}\marg{insert}
+\end{definition}
+
+If you want to provide support for \sty{glossaries-accsupp}
+use the following \cs{glsaccess\meta{xxx}} commands
+(\sectionref{sec:accsupp}) within the definitions of
+\cs{glsxtrfullformat} etc instead of the analogous
+\cs{glsentry}\meta{xxx} commands. (If you don't use
+\sty{glossaries-accsupp}, they will just do the corresponding
+\cs{glsentry}\meta{xxx} command.)
+
+For example, the \abbrstyle{short-long} style has the following in
+\meta{fmts}:
+\begin{verbatim}
+ \renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix}%
+ \renewcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{##1}}%
+ \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvdefaultfont{##1}}%
+ \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}%
+ \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}%
+ \renewcommand*{\glsxtrfullformat}[2]{%
+ \glsfirstabbrvfont{\glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi
+ \glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}%
+ }%
+ \renewcommand*{\glsxtrfullplformat}[2]{%
+ \glsfirstabbrvfont{\glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi
+ \glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}%
+ }%
+ \renewcommand*{\Glsxtrfullformat}[2]{%
+ \glsfirstabbrvfont{\Glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}%
+ }%
+ \renewcommand*{\Glsxtrfullplformat}[2]{%
+ \glsfirstabbrvfont{\Glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}%
+ \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}%
+ \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}%
+ }%
+\end{verbatim}
+Since the inline full commands aren't redefined, they default
+to the same as the display versions.
+
+If you want to base a style on an existing style, you can use
+\begin{definition}[\DescribeMacro\GlsXtrUseAbbrStyleFmts]
+\cs{GlsXtrUseAbbrStyleFmts}\marg{name}
+\end{definition}
+within \meta{fmts}, where \meta{name} is the name of the existing
+style. For example, the \abbrstyle{long-short-desc} style has the
+following in \meta{fmts}:
+\begin{verbatim}
+ \GlsXtrUseAbbrStyleFmts{long-short}%
+\end{verbatim}
+
+Here's an example of an abbreviation style that's based on
+\abbrstyle{long-short} that displays the short form within
+\cs{textsf}:
+\begin{verbatim}
+\newabbreviationstyle
+{custom-sf}% label
+{% setup
+ \GlsXtrUseAbbrStyleSetup{short-long}%
+}%
+{% fmts
+ \GlsXtrUseAbbrStyleFmts{short-long}%
+ \renewcommand*{\glsabbrvfont}[1]{\textsf{##1}}%
+}
+\end{verbatim}
+Note that this wouldn't work if it was instead based on one of the
+modified versions such as \abbrstyle{short-sc-long} as they
+explicitly use their own formatting commands, such as
+\cs{glsabbrvemfont}. The base styles, such as \abbrstyle{short-long},
+use the more generic \cs{glsabbrvfont} etc which makes them easier
+to adapt than the modified styles.
+
+For further details, see the \qt{Abbreviations} section in the documented code
+(\texttt{glossaries-extra-code.pdf}).
+
+\chapter{Entries in Sectioning Titles, Headers, Captions and Contents}
+\label{sec:headtitle}
+
+The \styfmt{glossaries} user manual cautions against using commands
+like \cs{gls} in chapter or section titles. The principle problems
+are:
+\begin{itemize}
+\item if you have a table of contents, the \gls{firstuseflag}
+will be unset in the contents rather than later in the document;
+\item if you have the location lists displayed in the glossary,
+unwanted locations will be added to it corresponding to the table of
+contents (if present) and every page that contains the entry in the
+page header (if the page style in use adds the chapter or section
+title to the header);
+\item if the page style in use adds the chapter or section title to
+the header and attempts to convert it to upper case, the entry label
+(in the argument of \cs{gls} etc) will be converted to upper case
+and the entry won't be recognised;
+\item if you use \sty{hyperref}, commands like \cs{gls} can't be
+expanded to a simple string and only the label will appear in the
+PDF bookmark (with a warning from \sty{hyperref});
+\item if you use \sty{hyperref}, you will end up with nested hyperlinks
+in the table of contents.
+\end{itemize}
+Similar problems can also occur with captions (except for the page
+header and bookmark issues).
+
+To get around all these problems, the \styfmt{glossaries} user manual
+recommends using the expandable non-hyperlink commands, such as
+\ics{glsentrytext} (for regular entries) or \ics{glsentryshort}
+(for abbreviations). This is the simplest solution, but doesn't
+allow for special formatting that's applied to the entry through
+commands like \cs{glstext} or \cs{glsxtrshort}. This means that if,
+for example, you are using one of the abbreviation styles that uses
+\ics{textsc} then the short form displayed with \cs{glsentryshort} won't use small
+caps. If you only have one abbreviation style in use, you can
+explicitly enclose \cs{glsentryshort}\marg{label} in the argument of
+\cs{glsabbrvfont}, like this:
+\begin{verbatim}
+\chapter{A Chapter about \glsabbrvfont{\glsentryshort{html}}}
+\end{verbatim}
+Or, if you are using \sty{hyperref}:
+\begin{verbatim}
+\chapter{A Chapter about
+\texorpdfstring{\glsabbrvfont{\glsentryshort{html}}}{\glsentryshort{html}}}
+\end{verbatim}
+
+Since this is a bit cumbersome, you might want to define a new
+command to do this for you. However, if you have mixed styles this
+won't work as commands like \cs{gls} and \cs{glsxtrshort} redefine
+\cs{glsabbrvfont} to match the entry's style before displaying it.
+In this case, the above example doesn't take into account the
+shifting definitions of \cs{glsabbrvfont} and will use whatever
+happens to be the last abbreviation style in use. More complicated
+solutions interfere with the upper casing used by the standard
+page styles that display the chapter or section title in the page
+header using \ics{MakeUppercase}.
+
+The \styfmt{glossaries-extra} package tries to resolve this by
+modifying \ics{markright} and \ics{markboth} and \cs{@starttoc}. If you don't like this
+change, you can restore their former definitions using
+\begin{definition}[\DescribeMacro\glsxtrRevertMarks]
+\cs{glsxtrRevertMarks}
+\end{definition}
+If you only want to restore \cs{@starttoc} you can use:
+\begin{definition}[\DescribeMacro\glsxtrRevertTocMarks]
+\cs{glsxtrRevertTocMarks}
+\end{definition}
+If you restore the header or table of contents commands, you'll have to use the \styfmt{glossaries} manual's
+recommendations of either simply using \cs{glsentryshort} (as above)
+or use the sectioning command's option argument to provide an
+alternative for the table of contents and page header. For example:
+\begin{verbatim}
+\chapter[A Chapter about \glsentryshort{html}]{A Chapter about \gls{html}}
+\end{verbatim}
+Alternatively, you need to find a way to insert \cs{glsxtrmarkhook} and
+\cs{@glsxtrinmark} at the start of the header or table of contents
+either scoped or afterwards cancelled with \cs{@glsxtrnotinmark} and
+\cs{glsxtrrestoremarkhook}.
+
+If you don't revert the mark commands back with
+\cs{glsxtrRevertMarks}, you can use the commands described below in
+the argument of sectioning commands. You can still use them even
+if the mark commands have been reverted, but only where they don't
+conflict with the page style.
+
+The commands listed below all use \ics{texorpdfstring} if
+\sty{hyperref} has been loaded so that the expandable non-formatted
+version is added to the PDF bookmarks. Note that since the commands
+that convert the first letter to upper case aren't expandable, the
+non-case-changing version is used for the bookmarks.
+
+These commands essentially behave as though you have used
+\cs{glsxtrshort} (or equivalent) with the options
+\gloskey[glslink]{noindex} and \gloskey[glslink]{hyper\eq false}.
+The text produced won't be converted to upper case in the page
+headings by default. If you want the text converted to upper case
+you need to set the \catattr{headuc} attribute to \qt{true}
+for the appropriate category.
+
+\begin{important}
+If you use one of the \ics{textsc} styles, be aware that the default
+fonts don't provide bold small-caps or italic small-caps. This
+means that if the chapter or section title style uses bold, this
+may override the small-caps setting, in which case the abbreviation
+will just appear as lower case bold. If the heading style uses
+italic, the abbreviation may appear in upright small-caps,
+\emph{even if you have set the \catattr{headuc} attribute} since
+the all-capitals form still uses \cs{glsabbrvfont}.
+You may want to consider using the \sty{slantsc} package in this
+case.
+\end{important}
+
+Display the short form:
+\begin{definition}[\DescribeMacro\glsfmtshort]
+\cs{glsfmtshort}\marg{label}
+\end{definition}
+
+Display the plural short form:
+\begin{definition}[\DescribeMacro\glsfmtshortpl]
+\cs{glsfmtshortpl}\marg{label}
+\end{definition}
+
+First letter upper case singular short form:
+\begin{definition}[\DescribeMacro\Glsfmtshort]
+\cs{Glsfmtshort}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+First letter upper case plural short form:
+\begin{definition}[\DescribeMacro\Glsfmtshortpl]
+\cs{Glsfmtshortpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+Display the long form:
+\begin{definition}[\DescribeMacro\glsfmtlong]
+\cs{glsfmtlong}\marg{label}
+\end{definition}
+
+Display the plural long form:
+\begin{definition}[\DescribeMacro\glsfmtlongpl]
+\cs{glsfmtlongpl}\marg{label}
+\end{definition}
+
+First letter upper case singular long form:
+\begin{definition}[\DescribeMacro\Glsfmtlong]
+\cs{Glsfmtlong}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+First letter upper case plural long form:
+\begin{definition}[\DescribeMacro\Glsfmtlongpl]
+\cs{Glsfmtlongpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+There are similar commands for the full form, but note that these
+use the \emph{inline} full form, which may be different from the
+full form used by \cs{gls}.
+
+Display the full form:
+\begin{definition}[\DescribeMacro\glsfmtfull]
+\cs{glsfmtfull}\marg{label}
+\end{definition}
+
+Display the plural full form:
+\begin{definition}[\DescribeMacro\glsfmtfullpl]
+\cs{glsfmtfullpl}\marg{label}
+\end{definition}
+
+First letter upper case singular full form:
+\begin{definition}[\DescribeMacro\Glsfmtfull]
+\cs{Glsfmtfull}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+First letter upper case plural full form:
+\begin{definition}[\DescribeMacro\Glsfmtfullpl]
+\cs{Glsfmtfullpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+There are also equivalent commands for the value of the
+\gloskey{text} field:
+\begin{definition}[\DescribeMacro\glsfmttext]
+\cs{glsfmttext}\marg{label}
+\end{definition}
+
+First letter converted to upper case:
+\begin{definition}[\DescribeMacro\Glsfmttext]
+\cs{Glsfmttext}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+The plural equivalents:
+\begin{definition}[\DescribeMacro\glsfmtplural]
+\cs{glsfmtplural}\marg{label}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\Glsfmtplural]
+\cs{Glsfmtplural}\marg{label}
+\end{definition}
+
+Likewise for the value of the
+\gloskey{name} field:
+\begin{definition}[\DescribeMacro\glsfmtname]
+\cs{glsfmtname}\marg{label}
+\end{definition}
+
+First letter converted to upper case:
+\begin{definition}[\DescribeMacro\Glsfmtname]
+\cs{Glsfmtname}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+Similarly for the value of the
+\gloskey{first} field:
+\begin{definition}[\DescribeMacro\glsfmtfirst]
+\cs{glsfmtfirst}\marg{label}
+\end{definition}
+
+First letter converted to upper case:
+\begin{definition}[\DescribeMacro\Glsfmtfirst]
+\cs{Glsfmtfirst}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+The plural equivalents:
+\begin{definition}[\DescribeMacro\glsfmtfirstpl]
+\cs{glsfmtfirstpl}\marg{label}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\Glsfmtfirstpl]
+\cs{Glsfmtfirstpl}\marg{label}
+\end{definition}
+
+\chapter{Categories}
+\label{sec:categories}
+
+Each entry defined by \ics{newglossaryentry} (or commands that
+internally use it such as \ics{newabbreviation})
+is assigned a category
+through the \gloskey{category} key. You may add any category that
+you like, but since the category is a label used in the creation
+of some control sequences, avoid problematic characters within the
+category label. (So take care if you have \sty{babel} shorthands on
+that make some characters active.)
+
+The use of categories can give you more control over the way entries
+are displayed in the text or glossary. Note that an entry's category
+is independent of the glossary type. Be careful not to confuse
+\gloskey{category} with \gloskey{type}.
+
+The default category assumed by
+\cs{newglossaryentry} is labelled \category{general}. Abbreviations
+defined with \cs{newabbreviation} have the category set to
+\category{abbreviation} by default. Abbreviations defined with
+\cs{newacronym} have the category set to \category{acronym} by
+default.
+
+Additionally, if you have enabled \ics{newterm} with the
+\pkgopt{index} package option that command
+will set the category to \category{index} by default. If you have
+enabled \ics{glsxtrnewsymbol} with the \pkgopt{symbols} package
+option, that command will set the category to \category{symbol}. If you have
+enabled \ics{glsxtrnewnumber} with the \pkgopt{numbers} package
+option, that command will set the category to \category{number}.
+
+You can obtain the category label for a given entry using
+\begin{definition}[\DescribeMacro\glscategory]
+\cs{glscategory}\marg{label}
+\end{definition}
+This is equivalent to commands like \cs{glsentryname} and so may be
+used in an expandable context. No error is generated if the entry
+doesn't exist.
+
+You can test the category for a given entry using
+\begin{definition}[\DescribeMacro\glsifcategory]
+\cs{glsifcategory}\marg{entry-label}\marg{category-label}\marg{true
+part}\marg{false part}
+\end{definition}
+This is equivalent to
+\begin{alltt}
+\ics{ifglsfieldeq}\marg{entry-label}\{category\}\marg{category-label}\marg{true
+part}\marg{false part}
+\end{alltt}
+so any restrictions that apply to \cs{ifglsfieldeq} also apply to
+\cs{glsifcategory}.
+
+Each category may have a set of attributes. For example, the
+\category{general} and \category{acronym} categories have the
+attribute \catattr{regular} set to \qt{true} to indicate that all
+entries with either of those categories are regular entries (as
+opposed to abbreviations). This attribute is accessed by
+\cs{glsentryfmt} to determine whether to use \cs{glsgenentryfmt} or
+\cs{glsxtrgenabbrvfmt}.
+
+Other attributes recognised by \styfmt{glossaries-extra} are:
+
+\begin{description}
+
+\item[\catattrdef{nohyperfirst}] When using commands like \ics{gls}
+this will automatically suppress the hyperlink on \gls{firstuse} for entries with a
+category that has this attribute set to \qt{true}.
+(This settings can be overridden by explicitly setting
+the \gloskey[glslink]{hyper} key on or off in the optional argument of
+commands like \cs{gls}.) As from version 1.07, \cs{glsfirst},
+\cs{Glsfirst}, \cs{GLSfirst} and their plural versions (which should ideally
+behave in a similar way to the \gls{firstuse} of \cs{gls} or
+\cs{glspl}) now honour
+this attribute (but not the package-wide \pkgopt[false]{hyperfirst}
+option, which matches the behaviour of \sty{glossaries}). If you
+want commands like \cs{glsfirst} to ignore the
+\catattr{nohyperfirst} attribute then just redefine
+\begin{definition}[\DescribeMacro\glsxtrchecknohyperfirst]
+\cs{glsxtrchecknohyperfirst}\marg{label}
+\end{definition}
+to do nothing.
+
+\item[\catattrdef{nohyper}] When using commands like \ics{gls}
+this will automatically suppress the hyperlink for entries with a
+category that has this attribute set to \qt{true}.
+(This settings can be overridden by explicitly setting
+the \gloskey[glslink]{hyper} key on or off in the optional argument of
+commands like \cs{gls}.)
+
+\item[\catattrdef{indexonlyfirst}] This is similar to the
+\pkgopt{indexonlyfirst} package option but only for entries
+that have a category with this attribute set to \qt{true}.
+
+\item[\catattrdef{wrgloss}] When using commands like \ics{gls},
+if this attribute is set to \qt{after}, it will automatically
+implement \gloskey[glslink]{wrgloss}\optfmt{=after}. (New to v1.14.)
+
+\item[\catattrdef{discardperiod}] If set to \qt{true}, the
+post-\gls{linktext} hook will
+discard a~full stop (period) that follows \emph{non-plural} commands like \cs{gls} or
+\cs{glstext}. (Provided for entries such as abbreviations that end
+with a full stop.) This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.) This attribute
+doesn't apply to the accessibility fields.
+
+Note that this can cause a problem if you access a field that
+doesn't end with a full stop. For example:
+\begin{verbatim}
+\newabbreviation
+ [user1={German Speaking \TeX\ User Group}]
+ {dante}{DANTE e.V.}{Deutschsprachige Anwendervereinigung \TeX\
+e.V.}
+\end{verbatim}
+Here the \gloskey{short} and \gloskey{long} fields end with a full stop, but the
+\gloskey{user1} field doesn't. The simplest solution in this
+situation is to put the sentence terminator in the final optional
+argument. For example:
+\begin{verbatim}
+\glsuseri{dante}[.]
+\end{verbatim}
+This will bring the punctuation character inside the \gls{linktext}
+and it won't be discarded.
+
+\item[\catattrdef{pluraldiscardperiod}] If this attribute is set to
+\qt{true} \emph{and} the \catattr{discardperiod} attribute is set to
+\qt{true}, this will behave as above for the plural commands like
+\cs{glspl} or \cs{glsplural}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{retainfirstuseperiod}] If this attribute is set
+to \qt{true} then the full stop won't be discarded for
+\gls{firstuse} instances, even if \catattr{discardperiod} or
+\catattr{pluraldiscardperiod} are set. This is useful for
+\meta{short} (\meta{long}) abbreviation styles where only the short
+form has a trailing full stop. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.) This attribute doesn't apply to the
+accessibility fields.
+
+\item[\catattrdef{markwords}] If this attribute is set to \qt{true}
+any entry defined using \ics{newabbreviation} will automatically
+have spaces in the long form replaced with
+\begin{definition}[\DescribeMacro\glsxtrwordsep]
+\cs{glsxtrwordsep}
+\end{definition}
+and each word is encapsulated with
+\begin{definition}[\DescribeMacro\glsxtrword]
+\cs{glsxtrword}\marg{word}
+\end{definition}
+For example:
+\begin{verbatim}
+\glssetcategoryattribute{abbreviation}{markwords}{true}
+\newabbreviation{ip}{IP}{Internet Protocol}
+\end{verbatim}
+is essentially the same as
+\begin{verbatim}
+\newabbreviation{ip}{IP}
+{\glsxtrword{Internet}\glsxtrwordsep\glsxtrword{Protocol}}
+\end{verbatim}
+The \qt{hyphen} styles, such as
+\abbrstyle{long-hyphen-short-hyphen}, take advantage of this
+markup. If the inserted material (provided in the final argument
+of commands like \ics{gls}) starts with a hyphen then
+\cs{glsxtrwordsep} is locally redefined to a hyphen. (The default
+value is a space). Note that this only applies to commands
+like \cs{gls} and not like \cs{glsxtrlong}. You can provide your own
+localised switch, if required. For example:
+\begin{verbatim}
+\newcommand{\hyplong}[2][]{%
+ {\def\glsxtrwordsep{-}\glsxtrlong[#1]{#2}}}
+\end{verbatim}
+
+This setting will also adjust the long plural. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\begin{important}
+This setting may result in the
+\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the
+\gloskey{sort} field, depending on the style in use.
+\end{important}
+
+\item[\catattrdef{markshortwords}] This is similar to
+\catattr{markwords} but applies to the short form. (Only useful for
+abbreviations that contain spaces.) This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+This setting will only adjust the short plural if the
+\gloskey{shortplural} key isn't used. This setting will
+take precedence over \catattr{insertdots}.
+
+\begin{important}
+This setting may result in the
+\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the
+\gloskey{sort} field, depending on the style in use.
+\end{important}
+
+\item[\catattrdef{insertdots}] If this attribute is set to \qt{true}
+any entry defined using \ics{newabbreviation} will automatically
+have full stops (periods) inserted after each letter. The entry will
+be defined with those dots present as though they had been present
+in the \meta{short} argument of \cs{newabbreviation} (rather than
+inserting them every time the entry is used). The short plural
+form defaults to the new dotted version of the original \meta{short}
+form with the plural suffix appended. \emph{This setting is incompatible
+with \catattr{markshortwords}.} This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\begin{important}
+If you explicitly override
+the short plural using the \gloskey{shortplural} key, you must
+explicitly insert the dots yourself (since there's no way for the
+code to determine if the plural has a suffix that shouldn't be
+followed by a dot).
+\end{important}
+
+This attribute is best used with the \catattr{discardperiod}
+attribute set to \qt{true}.
+
+\item[\catattrdef{aposplural}] If this attribute is set to \qt{true},
+\ics{newabbreviation} will insert an apostrophe (') before
+the plural suffix for the \emph{short} plural form (unless explicitly
+overridden with the \gloskey{shortplural} key). The long plural form
+is unaffected by this setting. This setting overrides
+\catattr{noshortplural}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.) Check with your supervisor, publisher or
+editor if you want to use this attribute as this
+usage is controversial.
+
+
+\item[\catattrdef{noshortplural}] If this attribute is set to
+\qt{true}, \ics{newabbreviation} won't append the plural suffix for
+the short plural form. This means the \gloskey{short} and
+\gloskey{shortplural} values will be the same unless explicitly
+overridden. \emph{This setting is incompatible with \catattr{aposplural}.} This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{accessinsertdots}] If this attribute is set to
+\qt{true} and the \sty{glossaries-accsupp} package has been loaded
+(with the \pkgopt{accsupp} option), then this behaves like
+\catattr{insertdots} but for the \gloskey{shortaccess} field instead
+of the \gloskey{short} field. This can be used to assist the
+screen reader for initialisms that should be read out letter by
+letter rather than as a word. For example:
+\begin{verbatim}
+\glssetcategoryattribute{initialism}{accessinsertdots}{true}
+
+\newabbreviation[category=initialism]{pi}{PI}{Private Investigator}
+\end{verbatim}
+This setting will be overridden by an explicit use of
+the \gloskey{shortaccess} key in the optional argument
+of \cs{newabbreviation} (or \cs{newacronym}). This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{nameshortaccess}] If this attribute is set to
+\qt{true}, the \gloskey{access} field (used for the \gloskey{name}
+field's accessibility support) is set to the \gloskey{shortaccess}
+value. This attribute has no effect if there's no accessibility
+support or if the \gloskey{shortaccess} field hasn't been assigned
+or if the \gloskey{access} field is used explicitly. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess}
+but applies to the \gloskey{textaccess} field (for use with
+regular abbreviations).
+
+\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess}
+but applies to the \gloskey{firstaccess} field (for use with
+regular abbreviations).
+
+\item[\catattrdef{accessaposplural}] This boolean attribute overrides
+\catattr{aposplural} for the \gloskey{shortpluralaccess} key.
+Has no effect if there's no accessibility support or if
+the \gloskey{shortaccess} key hasn't been set or if the
+\gloskey{shortpluralaccess} key is explicitly set. If
+the \catattr{aposplural} is set and this attribute isn't set
+and the \gloskey{shortaccess} key is set, then the
+\catattr{aposplural} setting governs the default
+\gloskey{shortpluralaccess} setting. If you want
+\catattr{aposplural} but don't want it applied to the accessibility
+support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides
+\catattr{noshortplural} for the \gloskey{shortpluralaccess} key.
+The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{headuc}] If this attribute is set to \qt{true},
+commands like \ics{glsfmtshort} will use the upper case version
+in the page headers.
+
+\item[\catattrdef{tagging}] If this attribute is set to \qt{true},
+the tagging command defined by \ics{GlsXtrEnableInitialTagging}
+will be activated to use \ics{glsxtrtagfont} in the glossary
+(see \sectionref{sec:tagging}).
+
+\item[\catattrdef{entrycount}] Unlike the above attributes,
+this attribute isn't boolean but instead must be an integer
+value and is used in combination with \ics{glsenableentrycount}
+(see \sectionref{sec:entrycountmods}). Leave blank or undefined
+for categories that shouldn't have this facility enabled. The
+value of this attribute is used by \ics{glsxtrifcounttrigger}
+to determine how commands such as \ics{cgls} should behave.
+
+With \styfmt{glossaries}, commands like \cs{cgls} use \cs{cglsformat}
+only if the previous usage count for that entry was equal to~1.
+With \styfmt{glossaries-extra} the test is now for entries that
+have the \catattr{entrycount} attribute set and
+where the previous usage count for that entry is less than or
+equal to the value of that attribute.
+
+\item[\catattrdef{linkcount}] This attribute is set to
+\texttt{true} by \ics{GlsXtrEnableLinkCounting} (see
+\sectionref{sec:linkcount}).
+
+\item[\catattrdef{linkcountmaster}] This attribute is set to
+the name of the master counter by \ics{GlsXtrEnableLinkCounting}
+if the optional argument is provided (see
+\sectionref{sec:linkcount}).
+
+\item[\catattrdef{glossdesc}] The \ics{glossentrydesc} command
+(used in the predefined glossary styles) is modified by
+\styfmt{glossaries-extra} to check for this attribute.
+The attribute may have one of the following values:
+\begin{itemize}
+\item \texttt{firstuc}: the first letter of the description will be
+converted to upper case (using \ics{Glsentrydesc}).
+
+\item \texttt{title}: the description will be used in the argument of the
+title casing command \ics{capitalisewords} (provided by
+\sty{mfirstuc}). If you want to use a different command
+you can redefine:
+\begin{definition}[\DescribeMacro\glsxtrfieldtitlecasecs]
+\cs{glsxtrfieldtitlecasecs}\marg{phrase cs}
+\end{definition}
+For example:
+\begin{verbatim}
+\newcommand*{\glsxtrfieldtitlecasecs}[1]{\xcapitalisefmtwords*{#1}}
+\end{verbatim}
+(Note that the argument to \cs{glsxtrfieldtitlecasecs}
+will be a control sequence whose replacement text is the
+entry's description, which is why \cs{xcapitalisefmtwords}
+is needed instead of \cs{capitalisefmtwords}.)
+
+\end{itemize}
+Any other values of this attribute are ignored. Remember
+that there are design limitations for both the first letter
+uppercasing and the title casing commands. See the \sty{mfirstuc}
+user manual for further details.
+
+\item[\catattrdef{glossdescfont}] (New to version 1.04)
+In addition to the above, the modified \ics{glossentrydesc}
+command also checks this attribute. If set, it should be the name of
+a control sequence (without the leading backslash) that takes one
+argument. This control sequence will be applied to the description
+text. For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{glossdescfont}{emph}
+\end{verbatim}
+
+
+\item[\catattrdef{glossname}] As \catattr{glossdesc} but applies
+to \ics{glossentryname}. Additionally, if this attribute is
+set to \qt{uc} the name is converted to all capitals.
+
+\item[\catattrdef{indexname}] If set, the \cs{glsxtrpostnamehook} hook
+used at the end of \ics{glossentryname}
+will index the entry using \ics{index}. See
+\sectionref{sec:autoindex} for further details.
+
+\item[\catattrdef{glossnamefont}] (New to version 1.04)
+In addition to the above, the modified \ics{glossentryname}
+command also checks this attribute. If set, it should be the name of
+a control sequence (without the leading backslash) that takes one
+argument. This control sequence will be applied to the name
+text. For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{glossnamefont}{emph}
+\end{verbatim}
+Note that this overrides \cs{glsnamefont} which will only
+be used if this attribute hasn't been set.
+
+Remember that glossary styles may additionally apply a font change,
+such as the list styles which put the name in the optional argument
+of \cs{item}.
+
+\item[\catattrdef{textformat}] (New to version 1.21.)
+Commands like \cs{gls} and \cs{glstext} have the link text
+encapsulated in the argument of \cs{glstextformat} by default. If
+this attribute is set, the control sequence given by the attribute
+value will be used instead. As with the above, the attribute value
+should be the name (without the leading backslash) of a command that
+takes a single argument (the link text). Remember that the
+abbreviation styles may apply an additional font change.
+
+\item[\catattrdef{hyperoutside}] (New to v1.21.) The attribute value
+may be \texttt{false}, \texttt{true} or unset. If unset,
+\texttt{true} is assumed. This indicates the default setting
+of the \gloskey[glslink]{hyperoutside} key, described in
+\sectionref{sec:wrglossary}.
+
+\item[\catattrdef{dualindex}] If set, whenever a glossary entry
+has information written to the external glossary file
+through commands like \ics{gls} and \ics{glsadd}, a~corresponding
+line will be written to the indexing file using \ics{index}. See
+\sectionref{sec:autoindex} for further details.
+
+\item[\catattrdef{targeturl}] If set, the hyperlink generated by
+commands like \cs{gls} will be set to the URL provided by this
+attributes value. For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targeturl}{master-doc.pdf}
+\end{verbatim}
+(See also the accompanying sample file
+\texttt{sample-external.tex}.) If the URL contains awkward
+characters (such as \verb|%| or \verb|~|) remember that the base
+\styfmt{glossaries} package provides commands like
+\ics{glspercentchar} and \cs{glstildechar} that expand to literal
+characters.
+
+If you want to a named anchor within the target URL (notionally
+adding \texttt{\#}\meta{name} to the URL), then you also
+need to set \catattr{targetname} to the anchor \meta{name}. You may
+use \cs{glslabel} within \meta{name} which is set by commands
+like \cs{gls} to the entry's label.
+
+All the predefined glossary styles start each entry
+listing with \cs{glstarget} which sets the anchor to
+\verb|\glolinkprefix\glslabel|, so if you want entries to link
+to glossaries in the URL given by \catattr{targeturl}, you
+can just do:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel}
+\end{verbatim}
+(If the target document changed \cs{glolinkprefix} then you will
+need to adjust the above as appropriate.)
+
+If the anchor is in the form \meta{name1}\texttt{.}\meta{name2}
+then use \catattr{targetname} for the \meta{name2} part and
+\catattr{targetcategory} for the \meta{name1} part.
+
+For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{targeturl}{master-doc.pdf}
+\glssetcategoryattribute{general}{targetcategory}{page}
+\glssetcategoryattribute{general}{targetname}{7}
+\end{verbatim}
+will cause all link text for \texttt{general} entries to
+link to \texttt{master-doc.pdf\#page.7} (page 7 of that PDF).
+
+If you want a mixture in your document of entries that link to
+an internal glossary and entries that link to an external URL
+then you can use the starred form of \ics{newignoredglossary}
+for the external list. For example:
+\begin{verbatim}
+\newignoredglossary*{external}
+
+\glssetcategoryattribute{external}{targeturl}{master-doc.pdf}
+\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel}
+
+\newglossaryentry{sample}{name={sample},description={local example}}
+
+\newglossaryentry{sample2}{name={sample2},
+ type=external,
+ category=external,
+ description={external example}}
+\end{verbatim}
+
+\item[\catattrdef{externallocation}] The value should be the
+file name of the target document when manually indexing an
+external location (see \sectionref{sec:wrglossary}). In general,
+it's better to use \gls{bib2gls} v1.7+ which can handle multiple
+external sources and doesn't require this attribute.
+
+\end{description}
+
+An attribute can be set using:
+\begin{definition}[\DescribeMacro\glssetcategoryattribute]
+\cs{glssetcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value}
+\end{definition}
+where \meta{category-label} is the category label,
+\meta{attribute-label} is the attribute label and \meta{value} is
+the new value for the attribute.
+
+There is a shortcut version to set the \catattr{regular} attribute
+to \qt{true}:
+\begin{definition}[\DescribeMacro\glssetregularcategory]
+\cs{glssetregularcategory}\marg{category-label}
+\end{definition}
+
+If you need to lookup the category label for a particular entry, you
+can use the shortcut command:
+\begin{definition}[\DescribeMacro\glssetattribute]
+\cs{glssetattribute}\marg{entry-label}\marg{attribute-label}\marg{value}
+\end{definition}
+This uses \cs{glssetcategoryattribute} with \cs{glscategory} to set
+the attribute. Note that this will affect all other entries that
+share this entry's category.
+
+You can fetch the value of an attribute for a particular category
+using:
+\begin{definition}[\DescribeMacro\glsgetcategoryattribute]
+\cs{glsgetcategoryattribute}\marg{category-label}\marg{attribute-label}
+\end{definition}
+Again there is a shortcut if you need to lookup the category label
+for a given entry:
+\begin{definition}[\DescribeMacro\glsgetattribute]
+\cs{glsgetattribute}\marg{entry-label}\marg{attribute-label}
+\end{definition}
+
+You can test if an attribute has been assigned to a given
+category using:
+\begin{definition}[\DescribeMacro\glshascategoryattribute]
+\cs{glshascategoryattribute}\marg{category-label}\marg{attribute-label}\marg{true
+code}\marg{false code}
+\end{definition}
+This uses \sty{etoolbox}'s
+\cs{ifcsvoid} and does \meta{true code} if the attribute has been
+set and isn't blank and isn't \cs{relax}. The shortcut if you need
+to lookup the category label from an entry is:
+\begin{definition}[\DescribeMacro\glshasattribute]
+\cs{glshasattribute}\marg{entry-label}\marg{attribute-label}\marg{true
+code}\marg{false code}
+\end{definition}
+
+You can test the value of an attribute for a particular category
+using:
+\begin{definition}[\DescribeMacro\glsifcategoryattribute]
+\cs{glsifcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value} \marg{true-part}\marg{false-part}
+\end{definition}
+This tests if the attribute (given by \meta{attribute-label}) for
+the category (given by \meta{category-label}) is set and equal to
+\meta{value}. If true, \meta{true-part} is done. If the attribute
+isn't set or is set but isn't equal to \meta{value}, \meta{false
+part} is done.
+
+For example:
+\begin{verbatim}
+\glsifcategoryattribute{general}{nohyper}{true}{NO HYPER}{HYPER}
+\end{verbatim}
+This does \qt{NO HYPER} if the \category{general} category has the
+\catattr{nohyper} attribute set to \texttt{true} otherwise if
+does \qt{HYPER}.
+
+With boolean-style attributes like \catattr{nohyper}, make sure you
+always test for \texttt{true} not \texttt{false} in case the attribute hasn't been set.
+
+Again there's a shortcut if you need to lookup the category label
+from a particular entry:
+\begin{definition}[\DescribeMacro\glsifattribute]
+\cs{glsifattribute}\marg{entry-label}\marg{attribute-label}\marg{value}\marg{true-part} \marg{false-part}
+\end{definition}
+
+There's also a shortcut to determine if a particular category has
+the \catattr{regular} attribute set to \qt{true}:
+\begin{definition}[\DescribeMacro\glsifregularcategory]
+\cs{glsifregularcategory}\marg{category-label}\marg{true-part}\marg{false-part}
+\end{definition}
+Alternatively, if you need to lookup the category for a particular
+entry:
+\begin{definition}[\DescribeMacro\glsifregular]
+\cs{glsifregular}\marg{entry-label}\marg{true-part}\marg{false-part}
+\end{definition}
+Note that if the \catattr{regular} attribute hasn't be set, the
+above do \meta{false-part}. There are also reverse commands that
+test if the \catattr{regular} attribute has been set to \qt{false}:
+\begin{definition}[\DescribeMacro\glsifnotregularcategory]
+\cs{glsifnotregularcategory}\marg{category-label}\marg{true-part}\marg{false-part}
+\end{definition}
+or for a particular entry:
+\begin{definition}[\DescribeMacro\glsifnotregular]
+\cs{glsifnotregular}\marg{entry-label}\marg{true-part}\marg{false-part}
+\end{definition}
+Again, if the \catattr{regular} attribute hasn't been set, the above
+do \meta{false-part}, so these reverse commands aren't logically
+opposite in the strict sense.
+
+You can iterate through all entries with a given category using:
+\begin{definition}
+\cs{glsforeachincategory}\oarg{glossary-labels}\marg{category-label} \marg{glossary-cs}\marg{label-cs}\marg{body}
+\end{definition}
+This iterates through all entries in the glossaries identified by
+the comma-separated list \meta{glossary-labels} that have the
+category given by \meta{category-label} and performs \meta{body} for
+each match. Within \meta{body}, you can use \meta{glossary-cs} and
+\meta{label-cs}
+(which much be control sequences) to access the current glossary and
+entry label. If \meta{glossary-labels} is omitted, all glossaries
+are assumed.
+
+Similarly, you can iterate through all entries that have a category
+with a given attribute using:
+\begin{definition}[\DescribeMacro\glsforeachwithattribute]
+\cs{glsforeachwithattribute}\oarg{glossary-labels}\marg{attribute-label} \marg{attribute-value}\marg{glossary-cs}\marg{label-cs}\marg{body}
+\end{definition}
+This will do \meta{body} for each entry that has a category with the
+attribute \meta{attribute-label} set to \meta{attribute-value}.
+The remaining arguments are as the previous command.
+
+You can change the category for a particular entry using the
+standard glossary field changing commands, such as
+\ics{glsfielddef}. Alternatively, you can use
+\begin{definition}[\DescribeMacro\glsxtrsetcategory]
+\cs{glsxtrsetcategory}\marg{entry-labels}\marg{category-label}
+\end{definition}
+This will change the category to \meta{category-label} for each
+entry listed in the comma-separated list \meta{entry-labels}. This
+command uses \ics{glsfieldxdef} so it will expand
+\meta{category-label} and make the change global.
+
+You can also change the category for all entries with a glossary or
+glossaries using:
+\begin{definition}[\DescribeMacro\glsxtrsetcategoryforall]
+\cs{glsxtrsetcategoryforall}\marg{glossary-labels}\marg{category-label}
+\end{definition}
+where \meta{glossary-labels} is a comma-separated list of glossary
+labels.
+
+\chapter{Counting References}
+\label{sec:countref}
+
+There are three basic ways of counting entry references:
+\begin{enumerate}
+\item Counting the total number of times \cs{glsunset} is used
+(\cs{glsreset} resets the count and is best avoided).
+This is provided by the base \styfmt{glossaries} package and is
+intended for documents where the term should be displayed
+differently if it's only been used a certain number of times.
+The information has to be written to the \texttt{.aux} file
+so that it's available on the next \LaTeX\ run.
+
+This method is extended by \styfmt{glossaries-extra} and is
+described in \sectionref{sec:entrycount}.
+
+\item Counting the total number of records. This method is
+only available with \gls{bib2gls} and is intended
+for documents where the term should be displayed differently
+if it's only been recorded (indexed) a certain number of times.
+See \sectionref{sec:recordcount} for further details.
+
+\item Counting the number of times the \cs{gls}-like or
+\cs{glstext}-like commands are used. (That is, those commands
+that internally use \cs{@gls@link}.) Unlike the other two methods,
+this just provides a running total rather than the total from the
+previous \LaTeX\ run. This method is intended to make it more
+convenient to work with hooks like \cs{glslinkcheckfirsthyperhook},
+\cs{glslinkpostsetkeys} or \cs{glslinkpresetkeys}.
+See \sectionref{sec:linkcount} for further details.
+\end{enumerate}
+
+\section{Entry Counting (First Use Flag)}
+\label{sec:entrycount}
+
+As mentioned in \sectionref{sec:entrycountmods},
+\styfmt{glossaries-extra} modifies the \ics{glsenableentrycount} command to allow
+for the \catattr{entrycount} attribute. This means that
+you not only need to enable entry counting with
+\ics{glsenableentrycount}, but you also need
+to set the appropriate attribute (see \sectionref{sec:categories}).
+
+\begin{important}
+Remember that entry counting only counts the number of times an
+entry is used by commands that change the \gls{firstuseflag}. (That
+is, all those commands that mark the entry as having been used.)
+There are many commands that don't modify this flag and they won't
+contribute to the entry use count.
+\end{important}
+
+With \styfmt{glossaries-extra}, you may use \ics{cgls} instead of
+\ics{gls} even if you haven't enabled entry counting. You will only
+get a warning if you use \cs{glsenableentrycount} without setting
+the \catattr{entrycount} attribute. (With \styfmt{glossaries},
+commands like \ics{cgls} will generate a warning if
+\cs{glsenableentrycount} hasn't been used.) The abbreviation
+shortcut \ics{ab} uses \cs{cgls} (see
+\sectionref{sec:abbrshortcuts}). The acronym shortcut
+\ics{ac} uses \cs{cgls} if it's been defined with
+\pkgopt[ac]{shortcuts} (or \pkgopt[all]{shortcuts})
+but uses \cs{gls} if it's been defined with
+\pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}).
+
+All upper case versions (not provided by \styfmt{glossaries}) are
+also available:
+\begin{definition}[\DescribeMacro\cGLS]
+\cs{cGLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\cGLSpl]
+\cs{cGLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+These are analogous to \cs{cgls} and \cs{cglspl} but they
+use
+\begin{definition}[\DescribeMacro\cGLSformat]
+\cs{cGLSformat}\marg{label}\marg{insert}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\cGLSplformat]
+\cs{cGLSplformat}\marg{label}\marg{insert}
+\end{definition}
+which convert the analogous \cs{cglsformat} and
+\cs{cglsplformat} to upper case.
+
+Just using \styfmt{glossaries}:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries}
+
+\makeglossaries
+
+\glsenableentrycount
+
+\newacronym{html}{HTML}{hypertext markup language}
+\newacronym{xml}{XML}{extensible markup language}
+
+\begin{document}
+
+Used once: \cgls{html}.
+
+Used twice: \cgls{xml} and \cgls{xml}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+
+If you switch to \styfmt{glossaries-extra} you must set the
+\catattr{entrycount} attribute:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\glsenableentrycount
+
+\glssetcategoryattribute{abbreviation}{entrycount}{1}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+\newabbreviation{xml}{XML}{extensible markup language}
+
+\begin{document}
+
+Used once: \cgls{html}.
+
+Used twice: \cgls{xml} and \cgls{xml}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+
+When activated with \cs{glsenableentrycount}, commands such as
+\ics{cgls} now use
+\begin{definition}[\DescribeMacro\glsxtrifcounttrigger]
+\cs{glsxtrifcounttrigger}\marg{label}\marg{trigger code}\marg{normal
+code}
+\end{definition}
+to determine if the entry trips the entry count trigger.
+The \meta{trigger code} uses commands like \cs{cglsformat} and
+unsets the \gls{firstuseflag}. The \meta{normal code} is the code that
+would ordinarily be performed by whatever the equivalent
+command is (for example, \cs{cgls} will use \cs{cglsformat} in
+\meta{trigger code} but the usual \cs{gls} behaviour in \meta{normal
+code}).
+
+The default definition is:
+\begin{verbatim}
+\newcommand*{\glsxtrifcounttrigger}[3]{%
+ \glshasattribute{#1}{entrycount}%
+ {%
+ \ifnum\glsentryprevcount{#1}>\glsgetattribute{#1}{entrycount}\relax
+ #3%
+ \else
+ #2%
+ \fi
+ }%
+ {#3}%
+}
+\end{verbatim}
+This means that if an entry is assigned to a category that has
+the \catattr{entrycount} attribute then the \meta{trigger code}
+will be used if the previous count value
+(the number of times the entry was used on the last run) is greater
+than the value of the attribute.
+
+For example, to trigger normal use if the previous count value
+is greater than four:
+\begin{verbatim}
+\glssetcategoryattribute{abbreviation}{entrycount}{4}
+\end{verbatim}
+
+There is a convenient command provided to enable entry counting,
+set the \catattr{entrycount} attribute and redefine \ics{gls},
+etc to use \ics{cgls} etc:
+\begin{definition}[\DescribeMacro\GlsXtrEnableEntryCounting]
+\cs{GlsXtrEnableEntryCounting}\marg{categories}\marg{value}
+\end{definition}
+The first argument \meta{categories} is a comma-separated list
+of categories. For each category, the \catattr{entrycount}
+attribute is set to \meta{value}. In addition, this does:
+\begin{verbatim}
+\renewcommand*{\gls}{\cgls}%
+\renewcommand*{\Gls}{\cGls}%
+\renewcommand*{\glspl}{\cglspl}%
+\renewcommand*{\Glspl}{\cGlspl}%
+\renewcommand*{\GLS}{\cGLS}%
+\renewcommand*{\GLSpl}{\cGLSpl}%
+\end{verbatim}
+This makes it easier to enable entry-counting on existing
+documents.
+
+If you use \cs{GlsXtrEnableEntryCounting} more than once, subsequent uses will
+just set the \catattr{entrycount} attribute for each listed
+category.
+
+The above example document can then become:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\GlsXtrEnableEntryCounting{abbreviation}{1}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+\newabbreviation{xml}{XML}{extensible markup language}
+
+\begin{document}
+
+Used once: \gls{html}.
+
+Used twice: \gls{xml} and \gls{xml}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+
+The standard entry-counting function describe above counts
+the number of times an entry has been marked as used throughout
+the document. (The reset commands will reset the total back to
+zero.) If you prefer to count per sectional-unit, you can
+use
+\begin{definition}[\DescribeMacro\GlsXtrEnableEntryUnitCounting]
+\cs{GlsXtrEnableEntryUnitCounting}\marg{categories}\marg{value}\marg{counter-name}
+\end{definition}
+where \meta{categories} is a comma-separated list of categories
+to which this feature should be applied, \meta{value} is the
+trigger value and \meta{counter-name} is the name of the counter
+used by the sectional unit.
+
+\begin{important}
+Due to the asynchronous nature of \TeX's output routine,
+discrepancies will occur in page spanning paragraphs if you
+use the \ctr{page} counter.
+\end{important}
+
+Note that you can't use both the document-wide counting and
+the per-unit counting in the same document.
+
+The counter value is used as part of a label, which means
+that \cs{the}\meta{counter-name} needs to be expandable.
+Since \sty{hyperref} also has a similar requirement and provides
+\cs{theH}\meta{counter-name} as an expandable alternative,
+\styfmt{glossaries-extra} will use \cs{theH}\meta{counter-name}
+if it exists otherwise it will use \cs{the}\meta{counter-name}.
+
+The per-unit counting function uses two attributes: \catattr{entrycount}
+(as before) and \catattr{unitcount} (the name of the counter).
+
+Both the original document-wide counting mechanism and the
+per-unit counting mechanism provide a command that can be
+used to access the current count value for this run:
+\begin{definition}[\DescribeMacro\glsentrycurrcount]
+\cs{glsentrycurrcount}\marg{label}
+\end{definition}
+and the final value from the previous run:
+\begin{definition}[\DescribeMacro\glsentryprevcount]
+\cs{glsentryprevcount}\marg{label}
+\end{definition}
+In the case of the per-unit counting, this is the final value
+\emph{for the current unit}. In both commands \meta{label}
+is the entry's label.
+
+The per-unit counting mechanism additionally provides:
+\begin{definition}[\DescribeMacro\glsentryprevtotalcount]
+\cs{glsentryprevtotalcount}\marg{label}
+\end{definition}
+which gives the sum of all the per-unit totals from the previous run
+for the entry given by \meta{label}, and
+\begin{definition}[\DescribeMacro\glsentryprevmaxcount]
+\cs{glsentryprevmaxcount}\marg{label}
+\end{definition}
+which gives the maximum per-unit total from the previous run.
+
+The above two commands are unavailable for the document-wide counting.
+
+Example of per-unit counting, where the unit is the chapter:
+\begin{verbatim}
+\documentclass{report}
+\usepackage{glossaries-extra}
+
+\GlsXtrEnableEntryUnitCounting{abbreviation}{2}{chapter}
+
+\makeglossaries
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+\newabbreviation{css}{CSS}{cascading style sheet}
+
+\newglossaryentry{sample}{name={sample},description={sample}}
+
+\begin{document}
+\chapter{Sample}
+
+Used once: \gls{html}.
+
+Used three times: \gls{css} and \gls{css} and \gls{css}.
+
+Used once: \gls{sample}.
+
+\chapter{Another Sample}
+
+Used once: \gls{css}.
+
+Used twice: \gls{html} and \gls{html}.
+
+\printglossaries
+\end{document}
+\end{verbatim}
+In this document, the \texttt{css} entry is used three times in the
+first chapter. This is more than the trigger value of 2, so
+\verb|\gls{css}| is expanded on \gls{firstuse} with the short
+form used on subsequent use, and the \texttt{css} entries in
+that chapter are added to the glossary. In the second chapter,
+the \texttt{css} entry is only used once, which trips the
+suppression trigger, so in that chapter, the long form
+is used and \verb|\gls{css}| doesn't get a line added to
+the glossary file.
+
+The \texttt{html} is used a total of three times, but the
+expansion and indexing suppression trigger is tripped
+in both chapters because the per-unit total (1 for the first
+chapter and 2 for the second chapter) is less than or equal
+to the trigger value.
+
+The \texttt{sample} entry has only been used once, but it doesn't
+trip the indexing suppression because it's in the \category{general}
+category, which hasn't been listed in
+\cs{GlsXtrEnableEntryUnitCounting}.
+
+The per-unit entry counting can be used for other purposes.
+In the following example document the trigger value is set
+to zero, which means the index suppression won't be triggered,
+but the unit entry count is used to automatically suppress the
+hyperlink for commands like \ics{gls} by modifying the
+hook
+\begin{definition}[\DescribeMacro\glslinkcheckfirsthyperhook]
+\cs{glslinkcheckfirsthyperhook}
+\end{definition}
+which is used at the end of the macro the determines whether
+or not to suppress the hyperlink.
+
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\GlsXtrEnableEntryUnitCounting{general}{0}{page}
+
+\newglossaryentry{sample}{name={sample},description={an example}}
+
+\renewcommand*{\glslinkcheckfirsthyperhook}{%
+ \ifnum\glsentrycurrcount\glslabel>0
+ \setkeys{glslink}{hyper=false}%
+ \fi
+}
+
+\begin{document}
+
+A \gls{sample} entry.
+Next use: \gls{sample}.
+
+\newpage
+
+Next page: \gls{sample}.
+Again: \gls{sample}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+This only produces a hyperlink for the first instance of
+\verb|\gls{sample}| on each page.
+
+The earlier warning about using the \ctr{page} counter still
+applies. If the first instance of \cs{gls} occurs at the top of the
+page within a paragraph that started on the previous page, then
+the count will continue from the previous page.
+
+\section{Link Counting}
+\label{sec:linkcount}
+
+As from version 1.26, an alternative method of entry counting
+is to count the number of times the \cs{gls}-like or
+\cs{glstext}-like commands are used. (The \qt{link} in this method's
+name refers to the use of the internal command \cs{@gls@link}
+not to \cs{hyperlink} although \cs{@gls@link} may use
+\cs{hyperlink} when displaying the \gls{linktext}.)
+
+To enable link counting use the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrEnableLinkCounting]
+\cs{GlsXtrEnableLinkCounting}\oarg{master counter}\marg{categories}
+\end{definition}
+where \meta{categories} is a list of category labels. The optional
+argument \meta{master counter} may be used to identify a master
+counter (which must be defined). If present, the associated
+link counter will be reset when the master counter is incremented.
+This command automatically sets the \catattr{linkcount} attribute
+for the given categories. If the optional argument is
+present, it also sets the \catattr{linkcountmaster} attribute.
+
+When enabled, commands like \cs{gls} and \cs{glstext}
+increment the associated counter using
+\begin{definition}[\DescribeMacro\glsxtrinclinkcounter]
+\cs{glsxtrinclinkcounter}\marg{counter name}
+\end{definition}
+This just does
+\texttt{\cs{stepcounter}\marg{counter name}} by default but if you
+need \cs{refstepcounter} instead, just redefine this command:
+\begin{verbatim}
+\renewcommand*{\glsxtrinclinkcounter}[1]{\refstepcounter{#1}}
+\end{verbatim}
+
+You can access the internal count register using
+\begin{definition}[\DescribeMacro\GlsXtrLinkCounterValue]
+\cs{GlsXtrLinkCounterValue}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. This will expand
+to 0 if the counter hasn't been defined.
+
+It's also possible to access the display value
+(\cs{the}\meta{counter}) using
+\begin{definition}[\DescribeMacro\GlsXtrTheLinkCounter]
+\cs{GlsXtrTheLinkCounter}\marg{counter}
+\end{definition}
+(This will expand to 0 if the counter hasn't been defined.)
+
+\begin{important}
+In order to conserve resources, the counter is only defined
+when it first needs to be incremented so terms that have
+been defined but haven't been used in the document
+won't have the associated count register allocated.
+\end{important}
+
+You can test if the counter has been defined using:
+\begin{definition}[\DescribeMacro\GlsXtrIfLinkCounterDef]
+\cs{GlsXtrIfLinkCounterDef}\marg{label}\marg{true}\marg{false}
+\end{definition}
+where \meta{label} is the entry's label.
+
+The counter name can be obtained using
+\begin{definition}[\DescribeMacro\GlsXtrLinkCounterName]
+\cs{GlsXtrLinkCounterName}\marg{label}
+\end{definition}
+This simply expands to the counter name associated with the
+entry given by \meta{label} without any check for
+existence. For example, to change the display command
+(\cs{the}\meta{counter}) using \sty{etoolbox}:
+\begin{verbatim}
+\csdef{the\GlsXtrLinkCounterName{duck}}{\Roman{\GlsXtrLinkCounterName{duck}}}
+\end{verbatim}
+This is useful if you just want to change the display for
+specific entries but isn't convenient if you want to change the
+display for all entries. Instead, it's simpler to redefine
+\cs{GlsXtrTheLinkCounter}. For example:
+\begin{verbatim}
+\renewcommand*{\GlsXtrTheLinkCounter}[1]{%
+ \GlsXtrIfLinkCounterDef{#1}%
+ {\Roman{\GlsXtrLinkCounterName{#1}}}%
+ {0}%
+}
+\end{verbatim}
+In both cases, the redefinition should be implemented
+after \cs{GlsXtrEnableLinkCounting}.
+
+Here's an example document that uses link counting to disable
+the hyperlink after the first reference. This redefines
+\ics{glslinkpresetkeys} (which is used by both \cs{gls}
+and \cs{glstext}) instead of
+\cs{glslinkcheckfirsthyperhook} (which is used by \cs{gls}
+but not by \cs{glstext}).
+
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\renewcommand*{\glslinkpresetkeys}{%
+ \ifnum\GlsXtrLinkCounterValue{\glslabel}>1
+ \setkeys{glslink}{hyper=false}%
+ \fi
+}
+
+\GlsXtrEnableLinkCounting{general}
+
+\newglossaryentry{sample1}{name={sample1},description={an example}}
+\newglossaryentry{sample2}{name={sample2},description={another example}}
+
+\newabbreviation{ex}{ex}{example}
+
+\begin{document}
+
+\section{Sample Section}
+
+\Gls{sample1}, \gls{sample2} and \gls{ex}.
+\Glstext{sample1} and \gls{ex} again.
+
+\section{Another Sample Section}
+
+\Gls{sample1}, \gls{sample2} and \gls{ex}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+The use of \ics{glslinkpresetkeys}
+means that the options can override this. For example
+\begin{verbatim}
+\gls[hyper=true]{sample1}
+\end{verbatim}
+will override the \texttt{hyper=false} setting in
+\ics{glslinkpresetkeys}. If \ics{glslinkpostsetkeys} is used
+instead, the \texttt{hyper=false} setting will override
+the setting provided in the optional argument.
+
+The \category{abbreviation} category doesn't have the
+\catattr{linkcount} attribute set (since it's not
+listed in the argument of \cs{GlsXtrEnableLinkCounting}). This means that
+\cs{GlsXtrLinkCounterValue}
+always expands to 0 for the abbreviation (\texttt{ex}), so the
+inequality test
+\begin{verbatim}
+\ifnum\GlsXtrLinkCounterValue{\glslabel}>1
+\end{verbatim}
+will always be false. This means that the abbreviation won't
+have \texttt{hyper=false} applied. If the test is changed to
+\begin{verbatim}
+\ifnum\GlsXtrLinkCounterValue{\glslabel}=1
+\else
+ \setkeys{glslink}{hyper=false}%
+\fi
+\end{verbatim}
+Then the abbreviation will always have \texttt{hyper=false}
+applied.
+
+To reset the counter every section use the optional argument to set
+the master counter:
+\begin{verbatim}
+\GlsXtrEnableLinkCounting[section]{general}
+\end{verbatim}
+
+\chapter{Auto-Indexing}
+\label{sec:autoindex}
+
+It's possible that you may also want a normal index as well as
+the glossary, and you may want entries to automatically be
+added to the index (as in this document).
+There are two attributes that govern this: \catattr{indexname}
+and \catattr{dualindex}.
+
+\begin{important}
+The auto-indexing is designed for \gls{makeindex} syntax. If you've
+used the \pkgopt{xindy} package option, the automatic escaping of
+\gls{xindy} special characters in the \gloskey{sort} field may
+result in an incorrect sort value for the \cs{index} command used by
+the auto-indexing. Note also that \app{texindy} has a fixed set of
+special characters (corresponding to \gls{makeindex}['s] defaults)
+that can't be customized. You may want to consider using \gls{bib2gls} and
+its dual entries as an alternative approach.
+\end{important}
+
+\begin{sloppypar}
+The \ics{glsxtrpostnamehook} macro, used
+at the end of \ics{glossentryname} and \ics{Glossentryname},
+checks the \catattr{indexname} attribute for the category
+associated with that entry.
+Since \cs{glossentryname} is used in the default glossary
+styles, this makes a convenient way of automatically indexing
+each entry name at its location in the glossary without
+fiddling around with the value of the \gloskey{name} key.
+\end{sloppypar}
+
+The internal macro used by the \styfmt{glossaries} package to
+write the information to the external glossary file is
+modified to check for the \catattr{dualindex} attribute.
+
+In both cases, the indexing is done through
+\begin{definition}[\DescribeMacro\glsxtrdoautoindexname]
+\cs{glsxtrdoautoindexname}\marg{label}\marg{attribute-label}
+\end{definition}
+This uses the standard \ics{index} command with the sort value
+taken from the entry's \gloskey{sort} key and the actual value
+set to \cs{glsentryname}\marg{label}. As from v1.16, there are
+user-level commands available to change the sort and actual
+value used by the automated index.
+
+The actual value is given by
+\begin{definition}[\DescribeMacro\glsxtrautoindexentry]
+\cs{glsxtrautoindexentry}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. The default definition
+is:
+\begin{verbatim}
+\newcommand*{\glsxtrautoindexentry}[1]{\string\glsentryname{#1}}
+\end{verbatim}
+Note the use of \cs{string} to prevent \cs{glsentryname} from
+being expanded as it's written to the index file.
+
+The sort value is assigned using:
+\begin{definition}[\DescribeMacro\glsxtrautoindexassignsort]
+\cs{glsxtrautoindexassignsort}\marg{cs}\marg{label}
+\end{definition}
+where \meta{label} is the entry label and \meta{cs} is the command
+which needs to be set to the sort value. The default definition is:
+\begin{verbatim}
+\newcommand*{\glsxtrautoindexassignsort}[2]{%
+ \glsletentryfield{#1}{#2}{sort}%
+}
+\end{verbatim}
+After this macro is called, \meta{cs} is then processed to escape
+any of \app{makeindex}'s special characters. Note that this
+escaping is only performed on the sort not on the actual value.
+The escaping of the sort value is performed by
+\begin{definition}[\DescribeMacro\glsxtrautoindexesc]
+\cs{glsxtrautoindexesc}
+\end{definition}
+You can redefine this to do nothing if you want to omit the
+escaping. You may want to consider providing another field to obtain
+the appropriate sort value if the one provided in the \gloskey{sort}
+field isn't suitable (because it may already have had special
+characters escaped or it may be a numeric value in the case of
+sort by use or definition).
+
+The command used to perform the actual indexing is:
+\begin{definition}[\DescribeMacro\glsxtrautoindex]
+\cs{glsxtrautoindex}\marg{text}
+\end{definition}
+This just does \cs{index}\marg{text} by default.
+
+\begin{important}
+The entry's \gloskey{parent} field isn't referenced in this
+automated indexing.
+\end{important}
+
+For example, to index the value of the \gloskey{first} key,
+instead of the \gloskey{name} key:
+\begin{verbatim}
+\renewcommand*{\glsxtrautoindexentry}[1]{\string\glsentryfirst{#1}}
+\end{verbatim}
+and if the sort value also needs to be set to the \gloskey{long}
+field, if present, otherwise the \gloskey{sort} field:
+\begin{verbatim}
+\renewcommand*{\glsxtrautoindexassignsort}[2]{%
+ \ifglshaslong{#2}%
+ {\glsletentryfield{#1}{#2}{long}}%
+ {\glsletentryfield{#1}{#2}{sort}}%
+}
+\end{verbatim}
+
+If the value of the attribute given by \meta{attribute-label}
+is \qt{true}, no encap
+will be added, otherwise the encap will be the
+attribute value. For example:
+\begin{verbatim}
+\glssetcategoryattribute{general}{indexname}{textbf}
+\end{verbatim}
+will set the encap to \texttt{textbf} which will display the
+relevant page number in bold whereas
+\begin{verbatim}
+\glssetcategoryattribute{general}{dualindex}{true}
+\end{verbatim}
+won't apply any formatting to the page number in the index.
+
+\begin{important}
+The location used in the index will always be the page number
+not the counter used in the glossary. (Unless some other loaded
+package has modified the definition of \cs{index} to use
+some thing else.)
+\end{important}
+
+By default the \gloskey[glslink]{format} key won't be used with
+the \catattr{dualindex} attribute. You can allow the
+\gloskey[glslink]{format} key to override the attribute value
+by using the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrEnableIndexFormatOverride]
+\cs{GlsXtrEnableIndexFormatOverride}
+\end{definition}
+If you use this command and \sty{hyperref} has been loaded,
+then the \env{theindex} environment will be modified to redefine
+\ics{glshypernumber} to allow formats that use that command.
+
+\begin{important}
+The \catattr{dualindex} attribute will still be used on
+subsequent use even if the \catattr{indexonlyfirst} attribute
+(or \pkgopt{indexonlyfirst} package option) is set. However,
+the \catattr{dualindex} attribute will honour the
+\gloskey[glslink]{noindex} key.
+\end{important}
+
+The \cs{glsxtrdoautoindexname} command will attempt to escape any of
+\ics{makeindex}'s special characters, but there may be special cases
+where it fails, so take care. This assumes the default \gls{makeindex} actual,
+level, quote and encap values (unless any of the commands
+\ics{actualchar}, \ics{levelchar}, \ics{quotechar} or
+\ics{encapchar} have been defined before \styfmt{glossaries-extra}
+is loaded).
+
+If this isn't the case, you can use the following preamble-only
+commands to set the correct characters.
+\begin{important}
+Be very careful of possible shifting category codes!
+\end{important}
+
+\begin{definition}[\DescribeMacro\GlsXtrSetActualChar]
+\cs{GlsXtrSetActualChar}\marg{char}
+\end{definition}
+Set the actual character to \meta{char}.
+
+\begin{definition}[\DescribeMacro\GlsXtrSetLevelChar]
+\cs{GlsXtrSetLevelChar}\marg{char}
+\end{definition}
+Set the level character to \meta{char}.
+
+\begin{definition}[\DescribeMacro\GlsXtrSetEscChar]
+\cs{GlsXtrSetEscChar}\marg{char}
+\end{definition}
+Set the escape (quote) character to \meta{char}.
+
+\begin{definition}[\DescribeMacro\GlsXtrSetEncapChar]
+\cs{GlsXtrSetEncapChar}\marg{char}
+\end{definition}
+Set the encap character to \meta{char}.
+
+\chapter{On-the-Fly Document Definitions}
+\label{sec:onthefly}
+
+\begin{important}
+The commands described here may superficially look like
+\meta{word}\cs{index}\marg{word}, but they behave rather
+differently. If you want to use \cs{index} then just use
+\cs{index}.
+\end{important}
+
+The \styfmt{glossaries} package advises against defining entries
+in the \env{document} environment. As mentioned in
+\sectionref{sec:pkgopts} above, this ability is disabled by
+default with \styfmt{glossaries-extra} but can be enabled using
+the \pkgopt{docdefs} package options.
+
+Although this can be problematic, the \styfmt{glossaries-extra}
+package provides a way of defining and using entries within
+the \env{document} environment without the tricks used with the
+\pkgopt{docdefs} option. \emph{There are limitations with this
+approach, so take care with it.} This function is disabled by
+default, but can be enabled using the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly]
+\cs{GlsXtrEnableOnTheFly}
+\end{definition}
+When used, this defines the commands described below.
+
+\begin{important}
+The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr}
+and \cs{Glsxtrpl} can't be used after the glossaries have been
+displayed (through \ics{printglossary} etc). It's best not to mix
+these commands with the standard glossary commands, such
+as \cs{gls} or there may be unexpected results.
+\end{important}
+
+\begin{definition}[\DescribeMacro\glsxtr]
+\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+If an entry with the label \meta{label} has already been defined,
+this just does \cs{gls}\oarg{gls-options}\marg{label}. If
+\meta{label} hasn't been defined, this will define the entry
+using:
+\begin{alltt}
+\cs{newglossaryentry}\marg{label}\{name=\marg{label},
+ category=\cs{glsxtrcat},
+ description=\{\cs{nopostdesc}\},
+ \meta{dfn-options}\}
+\end{alltt}
+
+\begin{important}
+The \meta{label} must contain any non-expandable commands, such as
+formatting commands or problematic characters.
+If the term requires any of these, they must be omitted from the
+\meta{label} and placed in the \gloskey{name} key must be provided
+in the optional argument \meta{dfn-options}.
+\end{important}
+
+The second optional argument \meta{dfn-options} should be empty
+if the entry has already been defined, since it's too late for
+them. If it's not empty, a~warning will be generated with
+\begin{definition}[\DescribeMacro\GlsXtrWarning]
+\cs{GlsXtrWarning}\marg{dfn-options}\marg{label}
+\end{definition}
+
+For example, this warning will be generated on the second instance
+of \cs{glsxtr} below:
+\begin{verbatim}
+\glsxtr[][plural=geese]{goose}
+% ... later
+\glsxtr[][plural=geese]{goose}
+\end{verbatim}
+
+If you are considering doing something like:
+\begin{verbatim}
+\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}}
+\renewcommand*{\GlsXtrWarning}[2]{}
+% ... later
+\goose\ some more text here
+\end{verbatim}
+then don't bother. It's simpler and less problematic to just
+define the entries in the preamble with \ics{newglossaryentry}
+and then use \cs{gls} in the document.
+
+There are plural and case-changing alternatives to \cs{glsxtr}:
+\begin{definition}[\DescribeMacro\glsxtrpl]
+\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\Glsxtr]
+\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\Glsxtrpl]
+\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}.
+
+If you use UTF-8 and don't want the inconvenient of needing
+to use an ASCII-only label, then it's better to use
+\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX).
+If you really desperately want to use UTF-8 entry labels without
+switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred
+version of \cs{GlsXtrEnableOnTheFly} that allows you to
+use UTF-8 characters in \meta{label}, but it's experimental and
+may not work in some cases.
+
+\begin{important}
+If you use the starred version of \cs{GlsXtrEnableOnTheFly}
+don't use any commands in the \meta{label}, even if they expand
+to just text.
+\end{important}
+
+\chapter{\appfmt{bib2gls}: Managing Reference Databases}
+\label{sec:bib2gls}
+
+There is a new command line application called
+\gls{bib2gls}, which works in much the same way as
+a combination of \appfmt{bibtex} and
+\appfmt{makeindex}\slash\appfmt{xindy}.
+Instead of storing all your entry definitions in a \texttt{.tex} and
+loading them using \cs{input} or \cs{loadglsentries}, the entries
+can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can
+selectively write the appropriate commands to a \texttt{.glstex}
+file which is loaded using \cs{glsxtrresourcefile} (or
+\cs{GlsXtrLoadResources}).
+
+This means that you can use a reference managing system, such as
+JabRef, to maintain the database and it reduces the \TeX\ overhead
+by only defining the entries that are actually required in the
+document. If you currently have a \texttt{.tex} file that contains
+hundreds of definitions, but you only use a dozen or so in your
+document, then the build time is needlessly slowed by the unrequired
+definitions that occur when the file is input. (You can convert an
+existing \texttt{.tex} file containing glossary definitions to a
+\texttt{.bib} file using \app{convertgls2bib}, supplied with
+\gls{bib2gls}.)
+
+There are some new commands and options added to
+\styfmt{glossaries-extra} to help assist the integration of
+\gls{bib2gls} into the document build process.
+
+This chapter just provides a general overview of \gls{bib2gls}.
+The full details and some sample documents are provided
+in the \gls{bib2gls} \href{http://mirrors.ctan.org/support/bib2gls/bib2gls.pdf}{manual}.
+
+An example of the contents of \texttt{.bib} file that stores
+glossary entries that can be extracted with \gls{bib2gls}:
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal},
+ see={[see also]{duck,goose}}
+}
+
+@entry{duck,
+ name={duck},
+ description = {a waterbird with short legs}
+}
+
+@entry{goose,
+ name="goose",
+ plural="geese",
+ description={a waterbird with a long neck}
+}
+\end{verbatim}
+
+The follow provides some abbreviations:
+\begin{verbatim}
+@string{ssi={server-side includes}}
+@string{html={hypertext markup language}}
+
+@abbreviation{shtml,
+ short="shtml",
+ long= ssi # " enabled " # html,
+ description={a combination of \gls{html} and \gls{ssi}}
+}
+
+@abbreviation{html,
+ short ="html",
+ long = html,
+ description={a markup language for creating web pages}
+}
+
+@abbreviation{ssi,
+ short="ssi",
+ long = ssi,
+ description={a simple interpreted server-side scripting language}
+}
+\end{verbatim}
+
+Here are some symbols:
+\begin{verbatim}
+preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"}
+
+@symbol{M,
+ name={$\mtx{M}$},
+ text={\mtx{M}},
+ description={a matrix}
+}
+
+@symbol{v,
+ name={$\vec{v}$},
+ text={\vec{v}},
+ description={a vector}
+}
+
+@symbol{S,
+ name={$\mathcal{S}$},
+ text={\mathcal{S}},
+ description={a set}
+}
+\end{verbatim}
+
+To ensure that \gls{bib2gls} can find out which entries have been
+used in the document, you need the \pkgopt{record} package option:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+If this option's value is omitted (as above), the normal indexing
+will be switched off, since \gls{bib2gls} can also sort the entries and
+collate the locations.
+
+If you still want to use an indexing application (for example, you
+need a custom \gls{xindy} rule), then just use
+\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries}
+and \cs{printglossary} (or \cs{printglossaries}), but you also need
+to instruct \gls{bib2gls} to omit sorting to save time and
+to prevent the \gloskey{sort} key from being set.
+
+The \texttt{.glstex} file created by \gls{bib2gls} is loaded using:
+\begin{definition}[\DescribeMacro\glsxtrresourcefile]
+\cs{glsxtrresourcefile}\oarg{options}\marg{filename}
+\end{definition}
+(Don't include the file extension in \meta{filename}.)
+There's a shortcut version (recommended over the above) that sets \meta{filename} to use \cs{jobname}:
+\begin{definition}[\DescribeMacro\GlsXtrLoadResources]
+\cs{GlsXtrLoadResources}\oarg{options}
+\end{definition}
+On the first use, this command is a shortcut for
+\begin{alltt}
+\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}\}
+\end{alltt}
+On subsequent use,\footnote{Version 1.11 only allowed one use
+of \cs{GlsXtrLoadResources} per document.}\ this command is a shortcut for
+\begin{alltt}
+\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}-\meta{n}\}
+\end{alltt}
+where \meta{n} is the current value of
+\begin{definition}
+\cs{glsxtrresourcecount}
+\end{definition}
+which is incremented at the end of \cs{GlsXtrLoadResources}.
+Any advisory notes regarding \cs{glsxtrresourcefile} also
+apply to \cs{GlsXtrLoadResources}.
+
+The \cs{glsxtrresourcefile} command writes the line
+\begin{alltt}
+\cs{glsxtr@resource}\marg{options}\marg{filename}
+\end{alltt}
+to the \texttt{.aux} file and will input
+\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed
+\meta{filename}\texttt{.tex} but that's potentially dangerous if,
+for example, \meta{filename} happens to be the same as \cs{jobname}.
+The \texttt{.glstex} extension was enforced by version 1.11.}
+
+Since the \texttt{.glstex} file won't exist on the first \LaTeX\ run, the
+\pkgopt{record} package option additionally switches on
+\pkgopt[warn]{undefaction}. Any use of commands like \cs{gls} or
+\cs{glstext} will produce ?? in the document, since the entries are
+undefined at this point. Once \gls{bib2gls} has created the
+\texttt{.glstex} file the references should be resolved.
+This may cause a shift in the locations if the actual text produced
+once the entry is defined is significantly larger than the
+placeholder ?? (as this can alter the page breaking).
+
+Note that as from v1.12, \cs{glsxtrresourcefile} temporarily
+switches the category code of \texttt{@} to 11 (letter) while it
+reads the file to allow for any internal commands stored in the
+location field.
+
+\section{Selection}
+
+The default behaviour is for \gls{bib2gls} to select all entries
+that have a record in the \texttt{.aux} file, and any dependent
+entries (including parent and cross-references). The
+\texttt{glsignore} format (for example,
+\verb|\gls[format=glsignore]{duck}|) is recognised by \gls{bib2gls}
+as a special ignored record. This means that it will match
+the selection criteria but the record won't be added to
+the location list. This means that you won't get spurious
+commas in the location list (as can happen with the other indexing
+methods), so you can do, for example,
+\begin{verbatim}
+\GlsXtrSetDefaultNumberFormat{glsignore}
+\end{verbatim}
+at the start of the front matter and
+\begin{verbatim}
+\GlsXtrSetDefaultNumberFormat{glsnumberformat}
+\end{verbatim}
+at the start of the main matter to prevent any records in the
+front matter from occurring in the location lists.
+
+\begin{important}
+Note that commands like \cs{glsaddall} and \cs{glsaddallunused} don't work with \gls{bib2gls} as the command
+has to iterate over the internal lists of defined entry labels, which will be empty on the first
+run and on subsequent runs will only contain those entries that have
+been selected by \gls{bib2gls}.
+\end{important}
+
+If you want to add all
+entries to the glossary, you need to tell \gls{bib2gls} this in the
+options list. For example:
+\begin{verbatim}
+\GlsXtrLoadResources[src={terms},selection={all}]
+\end{verbatim}
+This will add all entries, regardless of whether or not they
+have any records in the \texttt{.aux} file. Those that don't
+have any records will have an empty location list.
+See the \gls{bib2gls} user manual for more details of this option.
+
+\section{Sorting and Displaying the Glossary}
+
+There are many sorting options provided by \gls{bib2gls}.
+The default is to sort according to the system locale.
+If the document has a language setting, you can use
+\texttt{sort=doc} to instruct \gls{bib2gls} to sort according to
+that. (The language tag obtained from \sty{tracklang}'s
+interface is written to the \texttt{.aux} file.) For a multilingual
+document you need to explicitly set the locale using a well-formed
+language tag. For example:
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=terms, % data in terms.bib
+ sort=de-DE-1996 % sort according to this locale
+]
+\end{verbatim}
+The locale-sensitive sort methods usually ignore most
+punctuation so for lists of symbols you may find it more
+appropriate to use one of the letter-base sort methods
+that sort according to the Unicode value of each character.
+Alternatively you can provide a custom rule.
+See the \gls{bib2gls} manual for full details of all the available
+sort methods.
+
+Since the \texttt{.glstex} file only defines those references
+required
+within the document (selected according to the \texttt{selection}
+option) and the definitions have been written in the
+order corresponding to \gls{bib2gls}['s] sorted list, the glossaries can
+simply be displayed using \cs{printunsrtglossary} (or
+\cs{printunsrtglossaries}), described in \sectionref{sec:printunsrt}.
+
+Suppose the \texttt{.bib} examples shown above have been stored in
+the files \texttt{terms.bib}, \texttt{abbrvs.bib} and
+\texttt{symbols.bib} which may either be in the current directory or
+on \TeX's path. Then the document might look like:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources[src={terms,abbrvs,symbols}]
+
+\begin{document}
+\gls{bird}
+
+\gls{shtml}
+
+\gls{M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+The document build process (assuming the document is called
+\texttt{mydoc}) is:
+\begin{verbatim}
+pdflatex mydoc
+bib2gls mydoc
+pdflatex mydoc
+\end{verbatim}
+This creates a single glossary containing the entries:
+\texttt{bird}, \texttt{duck}, \texttt{goose},
+\texttt{html}, \texttt{M}, \texttt{shtml} and \texttt{ssi} (in that
+order). The \texttt{bird}, \texttt{shtml} and \texttt{M} entries
+were added because \gls{bib2gls} detected (from the \texttt{.aux}
+file) that they had been used in the document. The other entries
+were added because \gls{bib2gls} detected (from the \texttt{.bib}
+files) that they are referenced by the used entries. In the case of
+\texttt{duck} and \texttt{goose}, they are in the \gloskey{see}
+field for \texttt{bird}. In the case of \texttt{ssi} and
+\texttt{html}, they are referenced in the \gloskey{description}
+field of \texttt{shtml}. These cross-referenced entries won't have a
+location list when the glossary is first displayed, but depending on
+how they are referenced, they may pick up a location list on the
+next document build.
+
+The entries can be separated into different glossaries with
+different sort methods:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record,abbreviations,symbols]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources[src={terms},sort={en-GB},type=main]
+
+\GlsXtrLoadResources
+ [src={abbrvs},sort={letter-nocase},type=abbreviations]
+
+\GlsXtrLoadResources
+ [src={symbols},sort={use},type={symbols}]
+
+\begin{document}
+\gls{bird}
+
+\gls{shtml}
+
+\gls{M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+
+Or you can have multiple instance of \cs{GlsXtrLoadResources}
+with the same \texttt{type}, which will produce a glossary
+with ordered sub-blocks. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record,style=indexgroup]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources
+ [src={abbrvs},sort={letter-nocase},type=main,
+ group={Abbreviations}]
+
+\GlsXtrLoadResources
+ [src={symbols},sort={use},type=main,
+ group={Symbols}]
+
+\GlsXtrLoadResources[src={terms},sort={en-GB},type=main]
+
+\begin{document}
+\gls{bird}
+
+\gls{shtml}
+
+\gls{M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+This will result in a glossary where the first group has
+the title \qt{Abbreviations}, the second group has the
+title \qt{Symbols} and then follow the usual letter groups.
+Note that for this example to work, you must run \gls{bib2gls}
+with the \verb|--group| (or \verb|-g|) switch. For example,
+if the document is called \texttt{myDoc.tex}:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls -g myDoc
+pdflatex myDoc
+\end{verbatim}
+The value of the \gloskey{group} field must always be a label. You
+can set the corresponding title with \cs{glsxtrsetgrouptitle}
+(see \sectionref{sec:glosstylemods}). If no title is set then the
+label is used as the group title.
+
+You can provide your own custom sort rule. For example,
+if you are using \XeLaTeX\ or \LuaLaTeX:
+\begin{alltt}
+\cs{GlsXtrLoadResources}[
+ src=terms, % entries in terms.bib
+ sort=custom, % custom sort rule
+ sort-rule=\{% required with sort=custom
+ < \ae;\AE\ < a;\'a;\aa;\"a,\"A;\'A;\AA;\"A < b,B
+ < c;\'c,C;\'C < d,D < e;\'e,E;\'E < f,F < g,G
+ < h,H < i;\'i,I;\'I < j,J < l;\l,L;\L < m,M < n,N
+ < o;\"o;\o,O;\"O;\O\ < p,P < q,Q < r,R < s;\'s,S;\'S
+ < t,T < u;\'u,U;\'U < v,V < w,W < x,X < y,Y <
+ z;\.z,Z;\.Z
+ \}
+]
+\end{alltt}
+Remember that if you are using \sty{inputenc} then extended
+characters, such as \'e or \o, are active and will expand when
+written to the \texttt{.aux} file. So with PDF\LaTeX\ the
+above would have to be changed to protect against expansion.
+Some of the options, including \texttt{sort-rule},
+allow Unicode characters to be indicated in the format
+\cs{u}\meta{hex} (or \cs{u}~\meta{hex}) \textbf{in the \texttt{.aux} file}. \gls{bib2gls}
+will recognise this as the character
+given by the hexadecimal value \meta{hex}. The \cs{u} also needs
+protection from expansion, so with a non-Unicode aware
+engine, the character \ae\ needs to be written as
+\texttt{\cs{string}\cs{u}E6} and so on. This is quite cumbersome,
+but you can use the shortcut \texttt{\ics{glshex} E6} instead, so
+the above needs to be written as:
+\begin{alltt}
+\cs{GlsXtrLoadResources}[
+ src=terms, % entries in terms.bib
+ sort=custom, % custom sort rule
+ sort-rule=\{% required with sort=custom
+ < \cs{glshex} E6;\cs{glshex} C6
+ < a;\cs{glshex} E1;\cs{glshex} E5,\cs{glshex} E4,A;\cs{glshex} C1;\cs{glshex} C5;\cs{glshex} C4
+ < b,B < c;\cs{glshex} 0107,C;\cs{glshex} 0106 < d,D
+ < e;\cs{glshex} E9,E;\cs{glshex} C9 < f,F < g,G
+ < h,H < i;\cs{glshex} ED,I;\cs{glshex} CD < j,J
+ < l;\cs{glshex} 0142,L;\cs{glshex} 0141 < m,M < n,N
+ < o;\cs{glshex} F6;\cs{glshex} F8,O;\cs{glshex} D6;\cs{glshex} D8
+ < p,P < q,Q < r,R < s;\cs{glshex} 013F,S;\cs{glshex} 015A
+ < t,T < u;\cs{glshex} FA,U;\cs{glshex} DA < v,V < w,W < x,X < y,Y
+ < z;\cs{glshex} 017C,Z;\cs{glshex} 017B
+ \}]
+\end{alltt}
+
+\section{The \styfmt{glossaries-extra-bib2gls} package}
+\label{sec:bib2glssty}
+
+The package option \pkgopt[only]{record} (or simply \pkgopt{record})
+automatically loads the supplementary package
+\sty{glossaries-extra-bib2gls}, which provides some commands
+that are specific to \gls{bib2gls}. The package isn't
+loaded by \pkgopt[alsoindex]{record} as that option is intended
+for sorting with \gls{makeindex} or \gls{xindy} and it is expected
+that the sorting will be switched off (with the resource option
+\texttt{sort=none}).
+
+If \sty{glossaries-extra-bib2gls} is loaded via the
+\pkgopt{record} package option then the check for associated
+language resource files (see \sectionref{sec:lang}) will also
+search for the existence of
+\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} for each
+document dialect (where \meta{script} is the four letter
+script identifier, such as \texttt{Latn}).
+
+This package provides some shortcut commands that use
+\ics{printunsrtglossary} if the relevant package option has defined
+the associated glossary: \ics{printunsrtabbreviations},
+\ics{printunsrtacronyms}, \ics{printunsrtsymbols},
+\ics{printunsrtnumbers} and \ics{printunsrtindex}.
+
+\begin{definition}[\DescribeMacro\glsxtrprovidecommand]
+\cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition}
+\end{definition}
+This command is intended for use in \texttt{@preamble}.
+It's simply defined to \cs{providecommand} in
+\sty{glossaries-extra-bib2gls} but \gls{bib2gls}['s] interpreter
+treats it as \cs{renewcommand}. This means that you can
+override \gls{bib2gls}['s] internal definition of a command
+without overriding the command definition in the document
+(if it's already defined before the resource file is input).
+For example
+\begin{verbatim}
+@preamble{"\glsxtrprovidecommand{\int}{integral}"}
+\end{verbatim}
+This will force \gls{bib2gls} to treat \cs{int} as the word
+\qt{integral} to assist sorting but if this preamble code is written
+to the \texttt{.glstex} file (as it is by default) then it won't
+override the current definition (provided by the kernel or redefined
+by a package).
+
+The helper commands in the resource files are defined using
+\cs{providecommand}. For many of them, if you want to provide an
+alternative definition then you need to define the command before
+the resource file is loaded. There are a few that may be redefined
+afterwards but if you use \cs{renewcommand} then you will get an
+error on the first \LaTeX\ run when the \texttt{.glstex} file
+doesn't exist. In this case, you may prefer to use:
+\begin{definition}[\DescribeMacro\glsrenewcommand]
+\cs{glsrenewcommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition}
+\end{definition}
+This behaves like \cs{renewcommand} but only generates a warning
+rather than an error if the command isn't already defined so it
+won't interrupt the document build.
+
+\begin{definition}[\DescribeMacro\GlsXtrIndexCounterLink]
+\cs{GlsXtrIndexCounterLink}\marg{text}\marg{label}
+\end{definition}
+If the \ics{hyperref} command has been defined (that is,
+\sty{hyperref} has been loaded before \styfmt{glossaries-extra})
+then this command checks for the existence of the
+\texttt{indexcounter} field. If this field is set for the entry
+given by \meta{label}, this command does
+\cs{hyperref}\texttt{[wrglossary.\meta{value}]\marg{text}}, where
+\meta{value} is the value of the \texttt{indexcounter} field. If the
+field isn't set or if \cs{hyperref} hasn't been defined, this just
+does \meta{text}. This command is provided for use with the
+\pkgopt{indexcounter} package option combined with \gls{bib2gls}['s]
+\texttt{save-index-counter} resource option. See the \gls{bib2gls}
+manual for further details (at least version 1.4).
+
+If you use the \texttt{set-widest} resource option, \gls{bib2gls}
+v1.8+ will now use:
+\begin{definition}[\DescribeMacro\glsxtrSetWidest]
+\cs{glsxtrSetWidest}\marg{type}\marg{level}\marg{text}
+\end{definition}
+(if it has been defined) to set the widest name for the given
+glossary type and level. This allows for both the \glostyle{alttree}
+style and the styles provided by \sty{glossary-longextra}, which
+need to know the widest name.
+
+If \gls{bib2gls} can't determine the widest name (typically because
+the name field consists of commands that aren't recognised by the
+interpreter) then \gls{bib2gls} v1.8+ will now use:
+\begin{definition}[\DescribeMacro\glsxtrSetWidestFallback]
+\cs{glsxtrSetWidestFallback}\marg{max depth}\marg{list}
+\end{definition}
+(if defined). Currently the maximum hierarchical depth \meta{max
+depth} may only be 0 or 2. This command requires commands provided
+by the \sty{glossaries-extra-stylemods} package with the
+\glostyle{alttree} style enabled. In this case, it may be simpler
+to just use \ics{glssetwidest}.
+
+\subsection{Supplemental Locations}
+\label{sec:supplocations}
+
+\begin{definition}[\DescribeMacro\glsxtrdisplaysupploc]
+\cs{glsxtrdisplaysupploc}\marg{prefix}\marg{counter}\marg{format}\marg{src}\marg{location}
+\end{definition}
+This is used by \gls{bib2gls} version 1.7+ for supplemental
+locations, instead of using \cs{glsxtrsupphypernumber} with the
+\catattr{externallocation} attribute. This command sets up the
+location counter and prefix (used in the formation of hyperlinks)
+and then uses
+\begin{definition}[\DescribeMacro\glsxtrmultisupplocation]
+\cs{glsxtrmultisupplocation}\marg{location}\marg{src}\marg{format}
+\end{definition}
+to format the actual location (with an external hyperlink, if
+supported).
+
+\subsection{Nameref Record}
+\label{sec:recordnameref}
+
+Normally locations are recorded in the \texttt{.aux} file
+in the form:
+\begin{definition}
+\cs{glsxtr@record}\marg{label}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+The \pkgopt[nameref]{record} option, which requires at least
+\gls{bib2gls} v1.8, instead uses:
+\begin{definition}
+\cs{glsxtr@record@nameref}\marg{label}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{href}\marg{hcounter}
+\end{definition}
+where \meta{title} is obtained from \cs{@currentlabelname}
+and \meta{href} is obtained from \cs{@currentHref}. These
+commands require \sty{hyperref}. If they are undefined,
+\meta{title} and \meta{href} will be left empty and \gls{bib2gls}
+will treat it as a regular record.
+
+\begin{important}
+Be careful with this option as \meta{href} will globally change on every
+instance of \cs{refstepcounter} but \meta{title} won't necessarily
+change. It can therefore cause unexpected behaviour.
+\end{important}
+
+The final argument \meta{hcounter} is obtained from
+\cs{theH}\meta{counter} which provides the partial target name associated
+with the indexing counter. With the original
+\gls{makeindex}\slash \gls{xindy} approach, it's not possible to
+include this information in the location, so the base
+\sty{glossaries} package attempts to derive a prefix from which the
+\meta{hcounter} value can be reconstituted by appending the prefix.
+Unfortunately, not all definitions of \cs{theH}\meta{counter} are in
+the form \meta{prefix}\cs{the}\meta{counter} (most notably the
+\ctr{equation} counter with chapters) so this can fail.
+
+Since \gls{bib2gls} is customized specifically for use with
+\styfmt{glossaries-extra}, it's now possible to save
+\meta{hcounter}, so the \pkgopt[nameref]{record} option does this.
+By providing both \meta{href} and \meta{hcounter}, you can determine
+which target you would rather use. The default is to use
+\meta{hcounter}, which will take you to the place where the
+corresponding counter was incremented with \cs{refstepcounter}.
+However, you may choose to switch to using the \meta{href} target,
+which will take you to the nearest target before the indexing took
+place.
+
+With \gls{bib2gls} v1.8+, normal locations are displayed using:
+\begin{definition}
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+This is provided by the base \sty{glossaries} package and is simply
+defined to do:
+\begin{definition}
+\cs{setentrycounter}\oarg{prefix}\marg{counter}\cs{csuse}\marg{format}\marg{location}
+\end{definition}
+Earlier versions of \gls{bib2gls} only used this in the
+\gloskey{loclist} field and explicitly used \cs{setentrycounter} in
+the \gloskey{location} field followed by
+\cs{}\meta{format}\marg{location}, which follows the code that's created
+with the default \pkgopt{makeindex} setting.
+The \cs{setentrycounter} command sets up the prefix needed for
+\cs{glshypernumber} to reform the target name from the given
+location.
+
+The locations identified by \cs{glsxtr@record@nameref} are written
+by \gls{bib2gls} to the location list using:
+\begin{definition}[\DescribeMacro\glsxtrdisplaylocnameref]
+\cs{glsxtrdisplaylocnameref}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{href}\marg{hcounter}\marg{file}
+\end{definition}
+With normal internal locations, \meta{file} will always be empty.
+With supplemental locations, \meta{file} will be the external file
+reference.
+
+The default definition is:
+\begin{verbatim}
+\newcommand*{\glsxtrdisplaylocnameref}[8]{%
+ \ifstrequal{#2}{equation}%
+ {\glsxtrnamereflink{#3}{(#4)}{#2.#7}{#8}}%
+ {%
+ \ifstrempty{#5}%
+ {%
+ \glsxtrnamereflink{#3}{#4}{#2.#7}{#8}%
+ }%
+ {%
+ \ifstrequal{#2}{page}%
+ {\glsxtrnamereflink{#3}{#4}{#2.#7}{#8}}%
+ {\glsxtrnamereflink{#3}{#5}{#2.#7}{#8}}%
+ }%
+ }%
+}
+\end{verbatim}
+which uses:
+\begin{definition}[\DescribeMacro\glsxtrnamereflink]
+\cs{glsxtrnamereflink}\marg{format}\marg{title}\marg{target}\marg{file}
+\end{definition}
+This ignores the \meta{prefix}, \meta{counter} and \marg{location}
+arguments and instead creates a hyperlink with the target name obtained from \meta{target} (and \meta{file}, if not empty).
+
+Since pages and equations typically don't have titles, the default
+definition of \cs{glsxtrdisplaylocnameref} checks the counter was
+used as the location. If it's \ctr{page} or if \meta{title} is empty, then just the location is
+used as the hyperlink text. If the counter \ctr{equation}, then the
+text is the location in parentheses. Otherwise the text is obtained
+from \meta{title}.
+
+If \meta{file} is empty an internal link is created with:
+\begin{definition}[\DescribeMacro\glsxtrfmtinternalnameref]
+\cs{glsxtrfmtinternalnameref}\marg{target}\marg{format}\marg{title}
+\end{definition}
+otherwise an external link is created with:
+\begin{definition}[\DescribeMacro\glsxtrfmtexternalnameref]
+\cs{glsxtrfmtexternalnameref}\marg{target}\marg{format}\marg{title}\marg{file}
+\end{definition}
+The \meta{file} argument is set by \gls{bib2gls} for supplemental
+locations.
+
+Here's alternative definition that uses the \meta{prefix} and
+\meta{counter} to reform the target name (as
+\cs{glsnoidxdisplayloc}) but uses the \meta{title} as the hyperlink text:
+\begin{verbatim}
+\renewcommand*{\glsxtrdisplaylocnameref}[7]{%
+ \glsxtrnamereflink{#3}{#5}{#6}{#7}%
+}
+\end{verbatim}
+which uses:
+\begin{definition}[\DescribeMacro\glsxtrnameloclink]
+\cs{glsxtrnameloclink}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{file}
+\end{definition}
+This uses the same commands as \cs{glsxtrnamereflink}
+to produce the hyperlinks.
+
+In both cases, the link is encapsulated with the text-block command
+whose name is given by \meta{format}, but \cs{glshypernumber} is
+first locally redefined to \cs{@firstofone} to prevent a conflict with the
+usual location hyperlink formation. This means that if the
+\meta{format} is \texttt{hyperbf} then it will simply behave like
+\texttt{textbf}.
+
+For compactness, \gls{bib2gls} merges normal records if the
+\meta{prefix}, \meta{counter} and \meta{location} all match. (An
+order of precedence can be provided for format conflicts.) With
+nameref records, you can use the \verb|--merge-nameref-on| switch
+provided by \gls{bib2gls} v1.8+ to determine how to merge nameref
+records. This switch must be followed by one of the following
+keywords: \texttt{hcounter} (merge on \meta{hcounter}, default)
+\texttt{href} (merge on \meta{href}), \texttt{title} (merge
+on \meta{title}) and \texttt{location} (merge on \meta{location}, as
+regular records). In all cases, the \meta{counter} must also match.
+
+\subsection{Helper Commands for Resource Options}
+\label{sec:resourcecommands}
+
+\begin{definition}[\DescribeMacro\glshex]
+\cs{glshex}
+\end{definition}
+This is just defined as \verb|\string\u|, which is required
+when you need to indicate a Unicode character in the form
+\cs{u}\meta{hex} in some of
+the resource options (as illustrated above).
+
+\begin{definition}[\DescribeMacro\glscapturedgroup]
+\cs{glscapturedgroup}
+\end{definition}
+This is just defined as \verb|\string\$| and is used for
+the captured group reference in a replacement part of a regular
+expression substitution (requires at least \gls{bib2gls} version 1.5). For example:
+\begin{verbatim}
+sort-replace={{([a-zA-Z])\string\.}{\glscapturedgroup1}}
+\end{verbatim}
+This only removes a full stop that follows any of the characters
+a,\ldots,z or A,\ldots,Z.
+
+If you use the \texttt{save-child-count} resource option,
+you can test if the \texttt{childcount} field is non-zero using:
+\begin{definition}[\DescribeMacro{\GlsXtrIfHasNonZeroChildCount}]
+\cs{GlsXtrIfHasNonZeroChildCount}\marg{label}\marg{true}\marg{false}
+\end{definition}
+This internally uses \cs{GlsXtrIfFieldNonZero} and will do
+\meta{false} if the field isn't set. Within \meta{true} and
+\meta{false} you can use \cs{glscurrentfieldvalue} to access the
+value. (It will be 0 in \meta{false} if the field isn't set.)
+
+
+A convenient shortcut for use in the \texttt{entry-type-aliases}
+setting:
+\begin{definition}[\DescribeMacro\GlsXtrBibTeXEntryAliases]
+\cs{GlsXtrBibTeXEntryAliases}
+\end{definition}
+This provides aliases for Bib\TeX's standard entry types to
+\gls{bib2gls}['s] \texttt{@bibtexentry} entry type (requires at
+least \gls{bib2gls} version 1.4).
+
+You may also want to provide storage keys for Bib\TeX's standard
+fields rather than having to alias them all. This can be done with:
+\begin{definition}[\DescribeMacro\GlsXtrProvideBibTeXFields]
+\cs{GlsXtrProvideBibTeXFields}
+\end{definition}
+Note that Bib\TeX's \texttt{type} field clashes with the \sty{glossaries}
+package's \gloskey{type} key, so this command provides the key
+\texttt{bibtextype} instead. You can alias it with
+\texttt{field-aliases={type=bibtextype}} in the resource options.
+Each storage key is provided with a convenient command to access the
+value in the form \cs{glsxtrbib}\meta{field}. For example,
+\cs{glsxtrbibaddress}. The \texttt{bibtextype} field can be accessed
+with \cs{glsxtrbibtype}. Each of these commands takes the entry
+label as the sole argument.
+
+The \sty{glossaries-extra-bib2gls} package also provides definitions
+of the missing mathematical Greek commands: \ics{Alpha},
+\ics{Beta}, \ics{Epsilon}, \ics{Zeta}, \ics{Eta}, \ics{Iota},
+\ics{Kappa}, \ics{Mu}, \ics{Nu}, \ics{Omicron}, \ics{Rho},
+\ics{Tau}, \ics{Chi}, \ics{Digamma}, \ics{omicron}.
+These are all defined with \cs{providecommand}, so they won't override
+any definitions provided by any package loaded before
+\sty{glossaries-extra}. Since \gls{bib2gls}['s] interpreter
+recognises these commands, using them instead of explicitly using
+the Latin characters with the same shape helps to keep the Greek
+symbols together when sorting.
+Similarly, if \sty{upgreek} has been loaded, the missing upright
+Greek commands are also provided.
+
+The remaining commands provide common rule blocks for use in
+the \texttt{sort-rule} resource option. If you want a rule for
+a specific locale, you can provide similar commands in a file called
+\texttt{glossariesxtr-}\meta{tag}\texttt{.ldf}, where \meta{tag}
+identifies the dialect, locale, region or root language. See the
+description of \cs{IfTrackedLanguageFileExists} in the
+\sty{tracklang} documentation for further details. If this file is
+on \TeX's path and the \sty{tracklang} package (automatically loaded
+by \styfmt{glossaries}) detects that the document has requested that
+language or locale, then the file will automatically be loaded.
+For example, if you want to provide a rule block for Welsh, then
+create a file called \texttt{glossariesxtr-welsh.ldf} that contains:
+\begin{verbatim}
+\ProvidesGlossariesExtraLang{welsh}[2018/02/23 v1.0]
+
+\@ifpackageloaded{glossaries-extra-bib2gls}
+{
+ \newcommand{\glsxtrWelshRules}{%
+ \glsxtrLatinA
+ \string<b,B
+ \string<c,C
+ \string<ch,CH
+ \string<d,D
+ \string<dd,DD
+ \string<\glsxtrLatinE
+ \string<f,F
+ \string<ff,FF
+ \string<g,G
+ \string<ng,NG
+ \string<\glsxtrLatinH
+ \string<\glsxtrLatinI
+ \string<j,J
+ \string<\glsxtrLatinL
+ \string<ll,LL
+ \string<\glsxtrLatinM
+ \string<\glsxtrLatinN
+ \string<\glsxtrLatinO
+ \string<\glsxtrLatinP
+ \string<ph,PH
+ \string<r,R
+ \string<rh,RH
+ \string<\glsxtrLatinS
+ \string<\glsxtrLatinT
+ \string<th,TH
+ \string<u,U
+ \string<w,W
+ \string<y,Y
+ }
+}
+{}% glossaries-extra-bib2gls.sty not loaded
+\end{verbatim}
+(The use of \cs{string} is in case the \texttt{<} character
+has been made active.) You can provide more than one rule-block
+per local, to allow for loanwords or foreign words. For example,
+you could provide \cs{glsxtrWelshIRules}, \cs{glsxtrWelshIIRules}
+etc.
+
+If the rules are for a particular script (independent of language
+or region) then they can be provided in a file given by
+\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} instead. For
+example, the file \texttt{glossariesxtr-Cyrl.ldf} could contain:
+\begin{verbatim}
+\ProvidesGlossariesExtraLang{Cyrl}[2018/02/23 v1.0]
+\newcommand*{\glsxtrGeneralCyrillicIRules}{%
+ % Cyrillic rules
+}
+\newcommand*{\glsxtrGeneralCyrillicIIRules}{%
+ % an alternative set of Cyrillic rules
+}
+\end{verbatim}
+(Remember that the required document language scripts need to be tracked
+through the \sty{tracklang} package, in order for these files to be
+automatically loaded. This essentially means ensuring you load the
+appropriate language package before \sty{tracklang} is loaded by
+the base \sty{glossaries} package or any other package that uses it.
+See the \sty{tracklang} documentation for further details.)
+
+Alternatively, if the rules are specific to a subject rather than
+a region or language, then you can provide a supplementary
+package. For example, if you have a package called, say,
+\styfmt{mapsymbols} that provides map symbols, then the file
+\texttt{mapsymbols.sty} might contain:
+\begin{verbatim}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{mapsymbols}
+% some package or font loading stuff here to provide
+% the appropriate symbols
+\newcommand{\Stadium}{...}
+\newcommand{\Battlefield}{...}
+\newcommand{\Harbour}{...}
+% etc
+
+% Provide a rule block:
+\newcommand{\MapSymbolOrder}{%
+ \glshex 2694 % crossed-swords 0x2694
+ \string< \glshex 2693 % anchor 0x2693
+ \string< \glshex 26BD % football 0x26BD
+}
+\end{verbatim}
+and the supplementary file \texttt{mapsymbols.bib} can provide
+the appropriate definitions for \gls{bib2gls}:
+\begin{verbatim}
+@preamble{"\glsxtrprovidecommand{\Harbour}{\char"2693}
+\glsxtrprovidecommand{\Battlefield}{\char"2694}
+\glsxtrprovidecommand{\Stadium}{\char"26BD}"}
+\end{verbatim}
+Now both the preamble and rule block can be used in the resource
+set:
+\begin{verbatim}
+\usepackage{mapsymbols}% my custom package
+\usepackage[record]{glossaries-extra}
+
+\GlsXtrLoadResources[
+ src={mapsymbols,% <--- my custom mapsymbols.bib
+ entries% data in entries.bib
+ },
+ sort={custom},
+ sort-rule={\glsxtrcontrolrules % control codes
+ ;\glsxtrspacerules % space characters
+ ;\glsxtrnonprintablerules % non-printable characters
+ ;\glsxtrcombiningdiacriticrules % combining diacritics
+ ,\glsxtrhyphenrules % hyphens
+ <\glsxtrgeneralpuncrules % general punctuation
+ <\glsxtrdigitrules % 0, ..., 9
+ <\glsxtrfractionrules % fraction symbols
+ <\MapSymbolOrder % <--- custom map symbols
+ <\glsxtrMathItalicGreekIrules % math-greek symbols
+ <\glsxtrGeneralLatinIrules % Latin letters
+ }
+]
+\end{verbatim}
+
+The following commands are provided by
+\sty{glossaries-extra-bib2gls}. They should be separated by
+the rule separator characters \texttt{;}~(semi-colon) or \texttt{,}~(comma)
+or \verb|&|~(ampersand) or \texttt{<}~(less than). See Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{Rule\-Based\-Collator}
+documentation for details of the rule syntax.
+
+For example, the following will place the mathematical Greek
+symbols (\ics{alpha}, \ics{Alpha}, \ics{beta}, \ics{Beta} etc)
+in a block before Latin characters:
+\begin{verbatim}
+sort-rule={\glsxtrcontrolrules
+ ;\glsxtrspacerules
+ ;\glsxtrnonprintablerules
+ ;\glsxtrcombiningdiacriticrules
+ ,\glsxtrhyphenrules
+ <\glsxtrgeneralpuncrules
+ <\glsxtrdigitrules
+ <\glsxtrfractionrules
+ <\glsxtrMathItalicGreekIrules
+ <\glsxtrGeneralLatinIVrules
+ <\glsxtrLatinAA
+ <\glsxtrLatinOslash
+}
+\end{verbatim}
+
+\begin{definition}[\DescribeMacro\glsxtrcontrolrules]
+\cs{glsxtrcontrolrules}
+\end{definition}
+These are control characters that are usually placed at the start of
+a rule in the ignored section. They typically won't occur in
+any sort values, but if they do they should normally be ignored.
+
+\begin{definition}[\DescribeMacro\glsxtrspacerules]
+\cs{glsxtrspacerules}
+\end{definition}
+These are space characters. They typically come after the control
+characters with the two blocks separated by a \texttt{;}~(semi-colon).
+
+\begin{definition}[\DescribeMacro\glsxtrnonprintablerules]
+\cs{glsxtrnonprintablerules}
+\end{definition}
+These are non-printable characters (BOM, tabs, line feed and
+carriage return). They typically come after the spaces separated by
+a \texttt{;}~(semi-colon). These characters aren't checked for by
+\gls{bib2gls} when it determines whether or not to use the
+interpreter, so a~TAB or newline character may end up in the sort
+value if it wasn't interpreted.
+
+\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticrules]
+\cs{glsxtrcombiningdiacriticrules}
+\end{definition}
+These are combining diacritic marks which typically follow
+the space and non-printable blocks (separated by a semi-colon). This command is
+defined in terms of sub-block commands:
+\begin{verbatim}
+\newcommand*{\glsxtrcombiningdiacriticrules}{%
+ \glsxtrcombiningdiacriticIrules\string;
+ \glsxtrcombiningdiacriticIIrules\string;
+ \glsxtrcombiningdiacriticIIIrules\string;
+ \glsxtrcombiningdiacriticIVrules
+}
+\end{verbatim}
+If you prefer, you can use the sub-blocks directly in your
+required ordered.
+
+\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIrules]
+\cs{glsxtrcombiningdiacriticIrules}
+\end{definition}
+This contains the combining diacritics: acute, grave, breve,
+circumflex, caron, ring, vertical line above, diaeresis (umlaut),
+double acute, tilde, dot above, combining macron.
+
+\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIIrules]
+\cs{glsxtrcombiningdiacriticIIrules}
+\end{definition}
+This contains the combining diacritics: short solidus overlay,
+cedilla, ogonek, dot below, low line, overline, hook above,
+double vertical line above, double grave accent, candrabindu,
+inverted breve, turned comma above, comma above, reversed comma
+above, comma above right, grave accent below, acute accent below.
+
+\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIIIrules]
+\cs{glsxtrcombiningdiacriticIIIrules}
+\end{definition}
+This contains the combining diacritics: left tack below, right tack
+below, left angle above, horn, left half ring below, up tack below,
+down tack below, plus sign below, minus sign below, palatalized hook
+below, retroflex hook below, diaresis below, ring below, comma
+below, vertical line below, bridge below, inverted double arch
+below, caron below, circumflex accent below, breve below, inverted
+breve below, tilde below, macron below, double low line, tilde
+overlay, short stroke overlay, long stroke overlay, long solidus
+overlay, right half ring below, inverted bridge below, square below,
+seagull below, x above, vertical tilde, double overline, Greek
+perispomeni, Greek dialytika tonos, Greek ypogegrammeni, double
+tilde, double inverted breve, Cyrillic titlo, Cyrillic
+palatalization, Cyrillic dasia pneumata, Cyrillic psili pneumata.
+
+\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIVrules]
+\cs{glsxtrcombiningdiacriticIVrules}
+\end{definition}
+This contains the combining diacritics:
+left harpoon above, right harpoon above, long vertical line overlay,
+short vertical line overlay, anticlockwise arrow above, clockwise
+arrow above, left arrow above, right arrow above, ring overlay,
+clockwise ring overlay, anticlockwise ring overlay, three dots
+above, four dots above, enclosing circle, enclosing square,
+enclosing diamond, enclosing circle backslash, left right arrow
+above.
+
+\begin{definition}[\DescribeMacro\glsxtrhyphenrules]
+\cs{glsxtrhyphenrules}
+\end{definition}
+This contains hyphens (including the minus sign 0x2212). This rule
+block typically comes after the diacritic rules separated by a
+comma.
+
+\begin{definition}[\DescribeMacro\glsxtrgeneralpuncrules]
+\cs{glsxtrgeneralpuncrules}
+\end{definition}
+This contains punctuation characters. This rule
+block typically comes after the hyphen rules separated by a
+less than (\texttt{<}). As with the combining diacritics, this
+command is defined in terms of sub-blocks which may be used directly
+instead if a different order is required:
+\begin{verbatim}
+\newcommand*{\glsxtrgeneralpuncrules}{%
+ \glsxtrgeneralpuncIrules
+ \string<\glsxtrcurrencyrules
+ \string<\glsxtrgeneralpuncIIrules
+}
+\end{verbatim}
+
+\begin{definition}[\DescribeMacro\glsxtrgeneralpuncIrules]
+\cs{glsxtrgeneralpuncIrules}
+\end{definition}
+This is the first punctuation sub-block containing:
+underscore, macron, comma, semi-colon, colon, exclamation mark,
+inverted exclamation mark, question mark, inverted question mark,
+solidus, full stop, acute accent, grave accent, circumflex accent,
+diaersis, tilde, middle dot, cedilla, straight apostrophe, straight
+double quote, left guillemet, right guillemet, left parenthesis,
+right parenthesis, left square bracket, right square bracket, left
+curly bracket, right curly bracket, section sign, pilcrow sign,
+copyright sign, registered sign, at sign.
+
+\begin{definition}[\DescribeMacro\glsxtrcurrencyrules]
+\cs{glsxtrcurrencyrules}
+\end{definition}
+This sub-block contains some currency symbols:
+currency sign, Thai currency symbol baht, cent sign, colon sign,
+cruzeiro sign, dollar sign, dong sign, euro sign, French franc sign,
+lira sign, mill sign, naira sign, peseta sign, pound sign, rupee
+sign, new sheqel sign, won sign, yen sign.
+
+\begin{definition}[\DescribeMacro\glsxtrgeneralpuncIIrules]
+\cs{glsxtrgeneralpuncIIrules}
+\end{definition}
+This sub-block contains some other punctuation symbols:
+asterisk, backslash, ampersand, hash sign, percent sign, plus sign,
+plus-minus sign, division sign, multiplication sign, less-than sign,
+equals sign, greater-than sign, not sign, vertical bar (pipe),
+broken bar, degree sign, micron sign.
+
+\begin{definition}[\DescribeMacro\glsxtrdigitrules]
+\cs{glsxtrdigitrules}
+\end{definition}
+This rule block contains the Basic Latin digits (0, \ldots, 9)
+and the subscript and superscript digits (\textsubscript{0}
+\textsuperscript{0} etc) made equivalent to the
+corresponding Basic Latin digit. The digit block typically
+comes after the punctuation rules separated by a less than
+(\texttt{<}).
+
+\begin{definition}[\DescribeMacro\glsxtrBasicDigitrules]
+\cs{glsxtrBasicDigitrules}
+\end{definition}
+This rule block contains just the Basic Latin digits (0, \ldots, 9).
+
+\begin{definition}[\DescribeMacro\glsxtrSubScriptDigitrules]
+\cs{glsxtrSubScriptDigitrules}
+\end{definition}
+This rule block contains just the subscript digits
+(\textsubscript{0} \ldots\ \textsubscript{9}).
+
+\begin{definition}[\DescribeMacro\glsxtrSuperScriptDigitrules]
+\cs{glsxtrSuperScriptDigitrules}
+\end{definition}
+This rule block contains just the superscript digits
+(\textsuperscript{0} \ldots\ \textsuperscript{9}).
+
+\begin{definition}[\DescribeMacro\glsxtrfractionrules]
+\cs{glsxtrfractionrules}
+\end{definition}
+This rule block contains vulgar fraction characters. The digit block
+typically comes after the digit rules separated by a less than
+(\texttt{<}).
+
+There are a number of Latin rule blocks. Some of these included
+extended characters or ligatures (such as \ss\ or \oe) but they don't
+include accented characters. If you require a Latin rule block
+that includes accented characters, digraphs, trigraphs or
+other extended characters, then it's best to provide
+similar commands in a \texttt{glossariesxtr-}\meta{tag}\texttt{.ldf}
+file for the particular language or region.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIrules]
+\cs{glsxtrGeneralLatinIrules}
+\end{definition}
+This is just the basic (non-extended) Latin alphabet with the superscript
+and subscript Latin letters (\textsuperscript{a} \textsubscript{a}
+etc) treated as the equivalent basic Latin letter. (If you don't
+want the subscripts and superscripts included you can redefine
+\cs{glsxtrLatinA} etc to omit them.)
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIIrules]
+\cs{glsxtrGeneralLatinIIrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes eth
+(Ð) between `D' and `E' and eszett (\ss) treated as `ss'.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIIIrules]
+\cs{glsxtrGeneralLatinIIIrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes eth
+(Ð) between `D' and `E' and eszett (\ss) treated as `sz'.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIVrules]
+\cs{glsxtrGeneralLatinIVrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes eth
+(Ð) between `D' and `E', ae-ligature (\ae) is treated as `ae',
+oe-ligature (\oe) is treated as `oe', eszett (\ss) treated as `ss'
+and thorn (þ) is treated as `th'.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVrules]
+\cs{glsxtrGeneralLatinVrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes eth
+(Ð) between `D' and `E', eszett (\ss) treated as `ss'
+and thorn (þ) treated as `th'.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIrules]
+\cs{glsxtrGeneralLatinVIrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes eth
+(Ð) between `D' and `E', eszett (\ss) treated as `sz'
+and thorn (þ) treated as `th'.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIIrules]
+\cs{glsxtrGeneralLatinVIIrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but it includes
+ae-ligature (\ae) between `A' and `B', eth (Ð) between `D' and
+`E', insular G (Ᵹ) instead of `G', oe-ligature between `O' and `P',
+long~s (ſ) equivalent to `s', thorn (þ) between `T' and `U' and wynn (Ƿ)
+instead of W.
+
+\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIIIrules]
+\cs{glsxtrGeneralLatinVIIIrules}
+\end{definition}
+This is like \cs{glsxtrGeneralLatinIrules} but ae-ligature (\ae) is treated as `ae',
+oe-ligature (\oe) is treated as `oe', eszett (\ss) treated as `ss',
+thorn (þ) is treated as `th', \O\ is treated as `O' and
+`\L' is treated as `L'.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinA]
+\cs{glsxtrLatinA}
+\end{definition}
+A mini-rule that just covers `A' but includes the sub- and
+superscript A.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinE]
+\cs{glsxtrLatinE}
+\end{definition}
+A mini-rule that just covers `E' but includes the
+subscript E.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinH]
+\cs{glsxtrLatinH}
+\end{definition}
+A mini-rule that just covers `H' but includes the
+subscript H.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinK]
+\cs{glsxtrLatinK}
+\end{definition}
+A mini-rule that just covers `K' but includes the
+subscript K.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinI]
+\cs{glsxtrLatinI}
+\end{definition}
+A mini-rule that just covers `I' but includes the
+superscript I.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinL]
+\cs{glsxtrLatinL}
+\end{definition}
+A mini-rule that just covers `L' but includes the
+subscript L.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinM]
+\cs{glsxtrLatinM}
+\end{definition}
+A mini-rule that just covers `M' but includes the
+subscript M.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinN]
+\cs{glsxtrLatinN}
+\end{definition}
+A mini-rule that just covers `N' but includes the
+sub- and superscript N.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinO]
+\cs{glsxtrLatinO}
+\end{definition}
+A mini-rule that just covers `O' but includes the
+sub- and superscript O.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinP]
+\cs{glsxtrLatinP}
+\end{definition}
+A mini-rule that just covers `P' but includes the
+subscript P.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinS]
+\cs{glsxtrLatinS}
+\end{definition}
+A mini-rule that just covers `S' but includes the
+subscript S.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinT]
+\cs{glsxtrLatinT}
+\end{definition}
+A mini-rule that just covers `T' but includes the
+subscript T.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinX]
+\cs{glsxtrLatinX}
+\end{definition}
+A mini-rule that just covers `X' but includes the
+subscript X.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinEszettSs]
+\cs{glsxtrLatinEszettSs}
+\end{definition}
+A mini-rule that just covers eszett (\ss) and makes long~s (ſ) followed
+by short `s' equivalent to `\ss'. (This is used in the above blocks
+that treat `\ss' as `ss'.)
+
+\begin{definition}[\DescribeMacro\glsxtrLatinEszettSz]
+\cs{glsxtrLatinEszettSz}
+\end{definition}
+A mini-rule that just covers eszett (\ss) and makes long~s (ſ) followed
+by `z' equivalent to `\ss'. (This is used in the above blocks
+that treat `\ss' as `sz'.)
+
+\begin{definition}[\DescribeMacro\glsxtrLatinEth]
+\cs{glsxtrLatinEth}
+\end{definition}
+A mini-rule for eth (Ð) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinThorn]
+\cs{glsxtrLatinThorn}
+\end{definition}
+A mini-rule for thorn (þ) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinAELigature]
+\cs{glsxtrLatinAELigature}
+\end{definition}
+A mini-rule for ae-ligature (\ae) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinOELigature]
+\cs{glsxtrLatinOELigature}
+\end{definition}
+A mini-rule for oe-ligature (\oe) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinOslash]
+\cs{glsxtrLatinOslash}
+\end{definition}
+A mini-rule for `\O' so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinLslash]
+\cs{glsxtrLatinLslash}
+\end{definition}
+A mini-rule for `\L' so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinWynn]
+\cs{glsxtrLatinWynn}
+\end{definition}
+A mini-rule for wynn (Ƿ) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinInsularG]
+\cs{glsxtrLatinInsularG}
+\end{definition}
+A mini-rule for insular G (Ᵹ) so you don't need to remember the
+Unicode values.
+
+\begin{definition}[\DescribeMacro\glsxtrLatinSchwa]
+\cs{glsxtrLatinSchwa}
+\end{definition}
+A mini-rule that just covers schwa (Ə) but includes the
+subscript schwa. (Not used in any of the provided Latin rule blocks
+described above.)
+
+\begin{definition}[\DescribeMacro\glsxtrLatinAA]
+\cs{glsxtrLatinAA}
+\end{definition}
+A mini-rule for `\AA' so you don't need to remember the
+Unicode values. (Not used in any of the provided Latin rule blocks
+described above.)
+
+\begin{definition}[\DescribeMacro\glsxtrMathGreekIrules]
+\cs{glsxtrMathGreekIrules}
+\end{definition}
+A rule block for mathematical Greek (\ics{alpha}, \ics{beta} etc)
+and upright Greek (\ics{upalpha}, etc, from the \sty{upgreek}
+package) characters that includes digamma (\ics{digamma} and
+\ics{Digamma}) between epsilon and zeta. The upright and italic
+versions are gathered together into the same letter group.
+
+\begin{definition}[\DescribeMacro\glsxtrMathGreekIIrules]
+\cs{glsxtrMathGreekIIrules}
+\end{definition}
+As \cs{glsxtrMathGreekIrules} but doesn't include digamma.
+
+\begin{definition}[\DescribeMacro\glsxtrMathUpGreekIrules]
+\cs{glsxtrMathUpGreekIrules}
+\end{definition}
+A rule block for upright Greek (\ics{upalpha}, etc, from
+the \sty{upgreek} package)
+characters that includes digamma (\ics{digamma} and \ics{Digamma})
+between epsilon and zeta.
+
+\begin{definition}[\DescribeMacro\glsxtrMathUpGreekIIrules]
+\cs{glsxtrMathUpGreekIIrules}
+\end{definition}
+A rule block for upright Greek (\ics{upalpha}, etc, from
+the \sty{upgreek} package) that doesn't include digamma.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicGreekIrules]
+\cs{glsxtrMathItalicGreekIrules}
+\end{definition}
+A rule block for mathematical Greek (\ics{alpha}, \ics{Alpha}, etc)
+characters that includes digamma (\ics{diagamma} and \ics{Digamma})
+between epsilon and zeta. Note that even though the upper case
+\cs{Delta} etc are actually rendered upright by \LaTeX,
+\gls{bib2gls}['s] interpreter treats them as italic to help keep
+them close to the lower case versions.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicGreekIIrules]
+\cs{glsxtrMathItalicGreekIIrules}
+\end{definition}
+A rule block for mathematical Greek (\ics{alpha}, \ics{Alpha}, etc)
+characters that doesn't include digamma.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicUpperGreekIrules]
+\cs{glsxtrMathItalicUpperGreekIrules}
+\end{definition}
+A rule block for upper case mathematical Greek (\ics{Alpha},
+\ics{Beta}, etc) characters that includes digamma (\ics{Digamma})
+between epsilon and zeta.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicUpperGreekIIrules]
+\cs{glsxtrMathItalicUpperGreekIIrules}
+\end{definition}
+A rule block for upper case mathematical Greek (\ics{Alpha},
+\ics{Beta}, etc) characters that doesn't include digamma.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicLowerGreekIrules]
+\cs{glsxtrMathItalicLowerGreekIrules}
+\end{definition}
+A rule block for lower case mathematical Greek (\ics{alpha},
+\ics{beta}, etc) characters that includes digamma (\ics{digamma})
+between epsilon and zeta.
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicLowerGreekIIrules]
+\cs{glsxtrMathItalicLowerGreekIIrules}
+\end{definition}
+A rule block for lower case mathematical Greek (\ics{alpha},
+\ics{beta}, etc) characters that doesn't include digamma.
+
+Additionally, there are commands in the form \cs{glsxtrUpAlpha},
+\cs{glsxtrUpBeta} etc and \cs{glsxtrMathItalicAlpha},
+\cs{glsxtrMathItalicBeta} etc
+that just cover the upper and lower case forms of a special
+Greek character (\cs{Upalpha}, \cs{upalpha} etc and \cs{Alpha},
+\cs{alpha} etc) as well as the following:
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicPartial]
+\cs{glsxtrMathItalicPartial}
+\end{definition}
+The partial derivative symbol ($\partial$).
+
+\begin{definition}[\DescribeMacro\glsxtrMathItalicNabla]
+\cs{glsxtrMathItalicNabla}
+\end{definition}
+The nabla symbol ($\nabla$).
+
+
+\section{Supplementary Commands}
+
+These commands are provided by \styfmt{glossaries-extra}
+for use with \gls{bib2gls}.
+
+The information provided with \cs{GlsXtrLoadResources}
+is written to the \texttt{.aux} file using
+\begin{alltt}
+\cs{protected@write}\cs{@auxout}\{\cs{glsxtrresourceinit}\}\marg{information}
+\end{alltt}
+where \meta{information} is the information to pass to
+\gls{bib2gls}. The command in the second argument
+\begin{definition}[\DescribeMacro\glsxtrresourceinit]
+\cs{glsxtrresourceinit}
+\end{definition}
+may be used to temporarily redefine commands before the
+information is written to the file. This does nothing
+by default, but may be redefined to allow the use of
+short commands for convenience. For example, with:
+\begin{verbatim}
+\renewcommand{\glsxtrresourceinit}{\let\u\glshex}
+\end{verbatim}
+you can just use, for example, \verb|\u E6| instead of
+\verb|\string\uE6| in the custom rule. This redefinition of \cs{u}
+is scoped so its original definition is restored after the write operation.
+
+If you have multiple resource commands and you want a default set of
+options you can supply them in the definition of:
+\begin{definition}[\DescribeMacro\GlsXtrDefaultResourceOptions]
+\cs{GlsXtrDefaultResourceOptions}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand{\GlsXtrDefaultResourceOptions}{selection=all}
+\end{verbatim}
+This should be done before the resource commands.
+
+It's possible to specify label prefixes. For example, modifying
+the earlier example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record,style=indexgroup]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources
+ [src={abbrvs},sort={letter-nocase},type=main,
+ label-prefix={abr.},
+ group={Abbreviations}]
+
+\GlsXtrLoadResources
+ [src={symbols},sort={use},type=main,
+ label-prefix={sym.},
+ group={Symbols}]
+
+\GlsXtrLoadResources[src={terms},sort={en-GB},type=main
+ label-prefix={trm.}]
+
+\begin{document}
+\gls{trm.bird}
+
+\gls{abr.shtml}
+
+\gls{sym.M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+If you do something like this, you may find it more convenient
+to define custom commands that set the prefix. For example:
+\begin{verbatim}
+\newcommand*{\sym}[2][]{\gls[#1]{sym.#2}}
+\end{verbatim}
+The problem with this is that the custom command \cs{sym}
+doesn't allow for modifiers (such as \cs{gls*} or \cs{gls+}).
+Instead you can use:
+\begin{definition}[\DescribeMacro\glsxtrnewgls]
+\cs{glsxtrnewgls}\oarg{default options}\marg{prefix}\marg{cs}
+\end{definition}
+which defines the command \meta{cs} that behaves like
+\begin{alltt}
+\cs{gls}\meta{modifier}[\meta{default options},\meta{options}]\{\meta{prefix}\meta{label}\}\oarg{insert}
+\end{alltt}
+For example:
+\begin{verbatim}
+\glsxtrnewgls{sym.}{\sym}
+\end{verbatim}
+or (to default to no hyperlinks)
+\begin{verbatim}
+\glsxtrnewgls[hyper=false]{sym.}{\sym}
+\end{verbatim}
+now you can use \verb|\sym+{M}| to behave like \verb|\gls+{sym.M}|.
+
+If you also want the plural and first letter upper case
+versions you can use
+\begin{definition}[\DescribeMacro\glsxtrnewglslike]
+\cs{glsxtrnewglslike}\oarg{default
+options}\marg{prefix}\marg{\cs{gls}-like cs}\marg{\cs{glspl}-like cs}\marg{\cs{Gls}-like cs}\marg{\cs{Glspl}-like cs}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrnewglslike[hyper=false]{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
+\end{verbatim}
+For the all caps versions:
+\begin{definition}[\DescribeMacro\glsxtrnewGLSlike]
+\cs{glsxtrnewGLSlike}\oarg{default
+options}\marg{prefix}\marg{\cs{GLS}-like cs}\marg{\cs{GLSpl}-like cs}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrnewGLSlike[hyper=false]{idx.}{\IDX}{\IDXpl}
+\end{verbatim}
+
+There's an analogous command for \cs{rgls}:
+\begin{definition}[\DescribeMacro\glsxtrnewrgls]
+\cs{glsxtrnewrgls}\oarg{default options}\marg{prefix}\marg{cs}
+\end{definition}
+and for \cs{rgls}, \cs{rglspl}, \cs{rGls}
+and \cs{rGlspl}:
+\begin{definition}[\DescribeMacro\glsxtrnewrglslike]
+\cs{glsxtrnewrglslike}\oarg{default
+options}\marg{prefix}\marg{\cs{rgls}-like cs}\marg{\cs{rglspl}-like
+cs}\marg{\cs{rGls}-like cs}\marg{\cs{rGlspl}-like cs}
+\end{definition}
+and for the all caps:
+\begin{definition}[\DescribeMacro\glsxtrnewrGLSlike]
+\cs{glsxtrnewrGLSlike}\oarg{default
+options}\marg{prefix}\marg{\cs{rGLS}-like cs}\marg{\cs{rGLSpl}-like cs}
+\end{definition}
+
+If you provide your own custom command with just
+\cs{newcommand} that has syntax that starts with
+\oarg{options}\marg{label}, then you can notify \gls{bib2gls} using:
+\begin{definition}[\DescribeMacro\glsxtridentifyglslike]
+\cs{glsxtridentifyglslike}\marg{prefix}\marg{command}
+\end{definition}
+This writes information to the \texttt{.aux} file so that
+\gls{bib2gls} can search for the given command when looking
+for dependencies.
+
+Another possibility is to set up known label prefixes, with each
+one identified by:
+\begin{definition}[\DescribeMacro\glsxtraddlabelprefix]
+\cs{glsxtraddlabelprefix}\marg{prefix}
+\end{definition}
+These should be listed in order of precedence. Since no entries
+are defined on the first \LaTeX\ run, the final prefix should
+be the fallback. You can prepend a prefix to the list using:
+\begin{definition}[\DescribeMacro\glsxtrprependlabelprefix]
+\cs{glsxtrprependlabelprefix}\marg{prefix}
+\end{definition}
+which gives it the highest order of precedence.
+
+The \meta{prefix} argument may be empty. You can clear the list
+with:
+\begin{definition}[\DescribeMacro\glsxtrclearlabelprefixes]
+\cs{glsxtrclearlabelprefixes}
+\end{definition}
+
+You can test if a prefix is already in the list with:
+\begin{definition}[\DescribeMacro\glsxtrifinlabelprefixlist]
+\cs{glsxtrifinlabelprefixlist}\marg{prefix}\marg{true}\marg{false}
+\end{definition}
+In general it's best to avoid adding multiple instances of the same
+prefix, so you can check with this command before adding a prefix to
+the list. However, it can be useful to repeat a prefix at
+the end of the list so that it can be used as a fallback for entries
+that haven't yet been defined.
+
+With the list of possible prefixes set up (including an empty
+prefix if necessary), you can use:
+\begin{definition}[\DescribeMacro\dgls]
+\cs{dgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+which behaves like
+\begin{alltt}
+\cs{gls}\oarg{options}\{\meta{prefix}\meta{label}\}\oarg{insert}
+\end{alltt}
+where \meta{prefix} is the first prefix in the list such that
+\meta{prefix}\meta{label} matches a defined entry (or the last entry
+in the prefix list if none match).
+
+There are also analogous commands for the plural and case-changing
+versions:
+\begin{definition}[\DescribeMacro\dglspl]
+\cs{dglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{glspl}),
+\begin{definition}[\DescribeMacro\dGls]
+\cs{dGls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{Gls}),
+\begin{definition}[\DescribeMacro\dGlspl]
+\cs{dGlspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{Glspl}),
+\begin{definition}[\DescribeMacro\dGLS]
+\cs{dGLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{GLS}),
+\begin{definition}[\DescribeMacro\dGLSpl]
+\cs{dGLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{GLSpl}),
+\begin{definition}[\DescribeMacro\dglslink]
+\cs{dglslink}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{glslink}),
+\begin{definition}[\DescribeMacro\dglsdisp]
+\cs{dglsdisp}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+(uses \cs{glsdisp}).
+
+These commands are essentially provided for a mixture of single and
+dual entries. Suppose the file \texttt{entries.bib} contains:
+\begin{verbatim}
+@index{duck}
+@dualindexabbreviation{svm,
+ short={SVM},
+ long={support vector machine}
+}
+@dualindexsymbol{pi,
+ symbol={\ensuremath{\pi}},
+ description={ratio of a circle's circumference to its
+ diameter}
+}
+\end{verbatim}
+and suppose the document code is:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{hyperref}
+\usepackage[record,abbreviations,symbols]{glossaries-extra}
+
+\newcommand{\bibglsnewdualindexsymbolsecondary}[5]{%
+ \longnewglossaryentry*{#1}{name={#3},category={symbol},
+ type={symbols},symbol={#4},#2}{#5}%
+}
+
+\GlsXtrLoadResources[src=entries]
+
+\begin{document}
+First use: \gls{duck}, \gls{svm}, \gls{pi}.
+Next use: \gls{duck}, \gls{svm}, \gls{pi}.
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+This uses the default empty primary prefix and \texttt{dual.}\ for
+the dual prefix, so \verb|\gls{svm}| is referencing the primary
+entry, which is (essentially) an \texttt{@index} type not an
+abbreviation. It therefore doesn't follow the abbreviation style, and
+it also hyperlinks to the index not to the list of abbreviations.
+Similarly for \verb|\gls{pi}|, which references the primary
+\texttt{@index} entry rather than the symbol.
+
+What's really needed is:
+\begin{verbatim}
+\gls{duck}, \gls{dual.svm}, \gls{dual.pi}.
+\end{verbatim}
+or with
+\begin{verbatim}
+\GlsXtrLoadResources[src=entries,
+ label-prefix={idx.},
+ dual-prefix={}
+]
+\end{verbatim}
+then only the entries without a dual need a prefix:
+\begin{verbatim}
+\gls{idx.duck}, \gls{svm}, \gls{pi}.
+\end{verbatim}
+Using \cs{glsxtrnewglslike}, as earlier, this can be simplified to:
+\begin{verbatim}
+\idx{duck}, \gls{svm}, \gls{pi}.
+\end{verbatim}
+but this requires remembering which terms have duals.
+
+An alternative is to use \cs{dgls} instead:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{hyperref}
+\usepackage[record,abbreviations,symbols]{glossaries-extra}
+
+\newcommand{\bibglsnewdualindexsymbolsecondary}[5]{%
+ \longnewglossaryentry*{#1}{name={#3},category={symbol},
+ type={symbols},symbol={#4},#2}{#5}%
+}
+
+\GlsXtrLoadResources[src=entries]
+
+\glsxtraddlabelprefix{dual.}
+\glsxtraddlabelprefix{}
+
+\begin{document}
+First use: \dgls{duck}, \dgls{svm}, \dgls{pi}.
+Next use: \dgls{duck}, \dgls{svm}, \dgls{pi}.
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+On the first \LaTeX\ call (when the \texttt{.glstex} file doesn't exist),
+neither \texttt{dual.svm} nor \texttt{svm} exists, so \cs{dgls}
+uses the last prefix (which is empty in this case). This means
+that on the first \LaTeX\ run, \verb|\dgls{svm}| behaves like
+\verb|\gls{svm}|, which adds a record for the primary
+\texttt{svm} entry. The default primary-dual dependency means
+that this will cause both the primary (\texttt{svm}) and dual
+(\texttt{dual.svm}) entry to be selected. The location will be
+added to the primary entry's location list, unless overridden
+by resource options, such as \texttt{combine-dual-locations}.
+
+Once \gls{bib2gls} has been run and the \texttt{.glstex} file
+exists, then \texttt{dual.svm} exists. So \verb|\dgls{svm}| will
+again first try \texttt{dual.svm} (as \texttt{dual.} is the
+first in the list of label prefixes). That now exists, so
+\verb|\dgls{svm}| now behaves like \verb|\gls{dual.svm}|, which
+follows the abbreviation style and hyperlinks to the list
+of abbreviations.
+
+Similarly for the index-symbol combination \texttt{dual.pi} and
+\texttt{pi}. In the case of \verb|\dgls{duck}|, the label
+\texttt{dual.duck} never exists, so that's never selected.
+The empty prefix is the only one that matches, so
+\verb|\dgls{duck}| always behaves like \verb|\gls{duck}|.
+
+If you haven't used \texttt{combine-dual-locations} an extra
+\gls{bib2gls}+\LaTeX\ run may be required to correct the location
+lists.
+
+If you change the label prefixes, remember to update the
+corresponding \cs{glsxtraddlabelprefix}\marg{prefix}.
+If no prefixes have been added to the list (or if the list is
+cleared), just an empty prefix is assumed.
+
+As from version 1.8, \gls{bib2gls} provides hooks that identify
+the label prefixes in the \texttt{.glstex} file:
+\begin{alltt}
+\ics{bibglstertiaryprefixlabel}\marg{prefix}
+\ics{bibglsdualprefixlabel}\marg{prefix}
+\ics{bibglsprimaryprefixlabel}\marg{prefix}
+\end{alltt}
+These do nothing by default, but they can be defined before
+the resource file is loaded to set up the prefix list. For
+example:
+\begin{verbatim}
+\newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}}
+\newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}}
+\GlsXtrLoadResources[src=entries]
+\end{verbatim}
+Remember that this will only have an effect once the
+\texttt{.glstex} file has been created. The prefix list will be empty
+on the first run (which is treated as a single empty prefix).
+If this isn't a suitable fallback, it may be necessary to add one
+after all the resource commands:
+\begin{verbatim}
+\newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}}
+\newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}}
+\GlsXtrLoadResources[src=entries,label-prefix={idx.}]
+\glsxtraddlabelprefix{idx.}
+\end{verbatim}
+Although this rather defeats the purpose of using the hooks as you
+still have to keep track of the fallback prefix.
+
+\section{Record Counting}
+\label{sec:recordcount}
+
+As from version 1.1 of \gls{bib2gls}, you can save the total
+record count for each entry by invoking \gls{bib2gls}
+with the \texttt{-{}-record-count} or \texttt{-{}-record-count-unit}
+switches. These options will ensure that when each entry
+is written to the \texttt{.glstex} file \gls{bib2gls} will
+additionally set the following internal fields for that entry:
+\begin{itemize}
+\item \texttt{recordcount}: set to the total
+number of records found for the entry;
+\item \texttt{recordcount.\meta{counter}}: set to the total
+number of records found for the entry for the given counter.
+\end{itemize}
+If \texttt{-{}-record-count-unit} is used then additionally:
+\begin{itemize}
+\item \texttt{recordcount.\meta{counter}.\meta{location}}: set to the total
+number of records found for the entry for the given counter with the
+given location.
+\end{itemize}
+Only use the unit counting option if the locations don't contain any special
+characters. If you really need it with locations that may contain
+formatting commands, then you can try redefining:
+\begin{definition}[\DescribeMacro\glsxtrdetoklocation]
+\cs{glsxtrdetoklocation}\marg{location}
+\end{definition}
+so that it detokenizes \meta{location} but take care when
+using \cs{GlsXtrLocationRecordCount} with commands like
+\cs{thepage} as they can end up becoming detokenized
+too early.
+
+Note that the record count includes locations that \gls{bib2gls}
+discards, such as ignored records, duplicates and partial
+duplicates. It doesn't include cross-reference records. For
+example, if \verb|\gls{bird}| is used twice on page~1, once on
+page~2 and fours times on page~3, and
+\verb|\gls[counter=section]{bird}| is used once in section~3, then
+the total record count (stored in the \texttt{recordcount} field) is
+$2+1+4+1=8$, the total for the \texttt{page} counter (stored in the
+\texttt{recordcount.page} field) is $2+1+4=7$, and the total for the
+\texttt{section} counter (stored in the \texttt{recordcount.section}
+field) is 1.
+
+With the unit counting on as well, the field
+\texttt{recordcount.page.1} is set to 2, \texttt{recordcount.page.2}
+is set to 1, \texttt{recordcount.page.3} is set to 4 and
+\texttt{recordcount.section.3} is set to 1.
+
+You can access these fields using the following commands which
+will expand to the field value if set or to 0 if unset:
+\begin{definition}[\DescribeMacro\GlsXtrTotalRecordCount]
+\cs{GlsXtrTotalRecordCount}\marg{label}
+\end{definition}
+This expands to the total record count for the entry given by
+\meta{label}.
+\begin{verbatim}
+\GlsXtrTotalRecordCount{bird}
+\end{verbatim}
+expands to 8.
+
+\begin{definition}[\DescribeMacro\GlsXtrRecordCount]
+\cs{GlsXtrRecordCount}\marg{label}\marg{counter}
+\end{definition}
+This expands to the counter total for the entry given by
+\meta{label} where \meta{counter} is the counter name.
+For example:
+\begin{verbatim}
+\GlsXtrRecordCount{bird}{page}
+\end{verbatim}
+expands to 7 and
+\begin{verbatim}
+\GlsXtrRecordCount{bird}{section}
+\end{verbatim}
+expands to 1.
+
+\begin{definition}[\DescribeMacro\GlsXtrLocationRecordCount]
+\cs{GlsXtrLocationRecordCount}\marg{label}\marg{counter}\marg{location}
+\end{definition}
+This expands to the total for the given location. For example
+\begin{verbatim}
+\GlsXtrLocationRecordCount{bird}{page}{3}
+\end{verbatim}
+expands to 4. Be careful about using \cs{thepage} in the
+\meta{location} part. Remember that due to \TeX's asynchronous
+output routine, \cs{thepage} may not be correct.
+
+There are commands analogous to the entry counting commands like
+\cs{cgls} and \cs{cglsformat} that are triggered by the record count.
+These are listed below.
+
+\begin{definition}[\DescribeMacro\rgls]
+\cs{rgls}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rglspl]
+\cs{rglspl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGls]
+\cs{rGls}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGlspl]
+\cs{rGlspl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGLS]
+\cs{rGLS}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGLSpl]
+\cs{rGLSpl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+These commands check the \catattr{recordcount} attribute
+which, if set, should be a number. For example:
+\begin{verbatim}
+\glssetcategoryattribute{abbreviation}{recordcount}{1}
+\end{verbatim}
+For convenience, you can use
+\begin{definition}[\DescribeMacro\GlsXtrSetRecordCountAttribute]
+\cs{GlsXtrSetRecordCountAttribute}\marg{category list}\marg{n}
+\end{definition}
+to set the \catattr{recordcount} attribute to \meta{n}
+for all the categories listed in \meta{category list}.
+
+The \cs{rgls}-like commands use
+\begin{definition}[\DescribeMacro\glsxtrifrecordtrigger]
+\cs{glsxtrifrecordtrigger}\marg{label}\marg{trigger
+code}\marg{normal}
+\end{definition}
+to determine whether the \cs{rgls}-like command should behave like
+its \cs{gls} counterpart (\meta{normal}) or whether it should
+instead use \meta{trigger code}.
+
+This command checks if the \catattr{recordcount} attribute is set.
+If not is just does \meta{normal}, otherwise it tests
+if
+\begin{definition}[\DescribeMacro\glsxtrrecordtriggervalue]
+\cs{glsxtrrecordtriggervalue}\marg{label}
+\end{definition}
+is greater than the value given in the \catattr{recordcount}
+attribute for that entry's category. If true, this does
+\meta{normal} otherwise it does \meta{trigger code}.
+The default definition of the trigger value command is:
+\begin{verbatim}
+\newcommand*{\glsxtrrecordtriggervalue}[1]{%
+ \GlsXtrTotalRecordCount{#1}%
+}
+\end{verbatim}
+The \meta{trigger code} part writes a record with
+the \gloskey[glslink]{format} set to \texttt{glstriggerrecordformat} (which
+\gls{bib2gls} v1.1+ recognises as a special type of ignored location
+format) and does \meta{trigger format}. Then it
+unsets the \gls{firstuseflag}. Note that it doesn't
+implement the post-link hook. This ensures that the record
+count is correct on the next run.
+
+The \meta{trigger format} depends on the \cs{rgls}-like
+command used and will be one of the following:
+\begin{definition}[\DescribeMacro\rglsformat]
+\cs{rglsformat}\marg{label}\marg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rglsplformat]
+\cs{rglsplformat}\marg{label}\marg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGlsformat]
+\cs{rGlsformat}\marg{label}\marg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGlsplformat]
+\cs{rGlsplformat}\marg{label}\marg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGLSformat]
+\cs{rGLSformat}\marg{label}\marg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\rGLSplformat]
+\cs{rGLSplformat}\marg{label}\marg{insert}
+\end{definition}
+These all behave much like their \cs{cglsformat} counterparts. If
+the entry's \catattr{regular} attribute is set or if the entry
+doesn't have a long form, the first or first plural is used,
+otherwise the long or long plural form is used.
+
+You can use
+\begin{definition}[\DescribeMacro\glsxtrenablerecordcount]
+\cs{glsxtrenablerecordcount}
+\end{definition}
+to redefine \cs{gls}, \cs{glspl}, \cs{Gls}, \cs{Glspl},
+\cs{GLS}, \cs{GLSpl} to \cs{rgls}, \cs{rglspl}, \cs{rGls}, \cs{rGlspl},
+\cs{rGLS}, \cs{rGLSpl}, respectively, for convenience.
+
+If you don't want the entries that use \meta{trigger code}
+to appear in the glossary, you need to use the resource option
+\texttt{trigger-type} to assign them to another glossary.
+For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record]{glossaries-extra}
+
+\newignoredglossary{ignored}
+
+\GlsXtrLoadResources[
+ src=example-glossaries-acronym,
+ trigger-type=ignored,
+ category=abbreviation
+]
+
+\glsxtrenablerecordcount
+\GlsXtrSetRecordCountAttribute{abbreviation}{1}
+
+\begin{document}
+\gls{lid}. \gls{stc}. \gls{lid}. \gls{aeu}.
+\gls{upa}. \gls{aeu}.
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+In the above, \texttt{stc} and \texttt{upa} both only have
+one record, so they are assigned to the \texttt{ignored}
+glossary instead of the \texttt{main} one.
+
+\chapter{Miscellaneous New Commands}
+\label{sec:miscnew}
+
+The \styfmt{glossaries} package provides \ics{glsrefentry} entry to
+cross-reference entries when used with the \pkgopt{entrycounter} or
+\pkgopt{subentrycounter} options. The \styfmt{glossaries-extra}
+package provides a supplementary command
+\begin{definition}[\DescribeMacro\glsxtrpageref]
+\cs{glsxtrpageref}\marg{label}
+\end{definition}
+that works in the same way except that it uses \ics{pageref}
+instead of \ics{ref}.
+
+You can copy an entry to another glossary using
+\begin{definition}[\DescribeMacro\glsxtrcopytoglossary]
+\cs{glsxtrcopytoglossary}\marg{entry-label}\marg{glossary-type}
+\end{definition}
+This appends \meta{entry-label} to the end of the internal
+list for the glossary given by \meta{glossary-type}.
+Be careful if you use the \sty{hyperref} package as this
+may cause duplicate hypertargets. You will need to change
+\cs{glolinkprefix} to another value or disable hyperlinks
+when you display the duplicate. Alternatively, use the new
+\gloskey[printglossary]{target} key to switch off the targets:
+\begin{verbatim}
+\printunsrtglossary[target=false]
+\end{verbatim}
+
+The \styfmt{glossaries} package allows you to set preamble code
+for a given glossary type using \cs{setglossarypreamble}. This
+overrides any previous setting. With \styfmt{glossaries-extra}
+(as from v1.12) you can instead append to the preamble
+using
+\begin{definition}[\DescribeMacro\apptoglossarypreamble]
+\cs{apptoglossarypreamble}\oarg{type}\marg{code}
+\end{definition}
+or prepend using
+\begin{definition}[\DescribeMacro\pretoglossarypreamble]
+\cs{pretoglossarypreamble}\oarg{type}\marg{code}
+\end{definition}
+
+\section{Entry Fields}
+\label{sec:fields}
+
+A field may now be used to store the name of a text-block command
+that takes a single argument. The field is given by
+\begin{definition}[\DescribeMacro\GlsXtrFmtField]
+\cs{GlsXtrFmtField}
+\end{definition}
+The default value is \texttt{\GlsXtrFmtField}. Note that the
+value must be the control sequence name \emph{without the initial
+backslash}.
+
+For example:
+\begin{verbatim}
+\newcommand*{\mtx}[1]{\boldsymbol{#1}}
+\newcommand*{\mtxinv}[1]{\mtx{#1}\sp{-1}}
+
+\newglossaryentry{matrix}{%
+ name={matrix},
+ symbol={\ensuremath{\mtx{M}}},
+ plural={matrices},
+ user1={mtx},
+ description={rectangular array of values}
+}
+
+\newglossaryentry{identitymatrix}{%
+ name={identity matrix},
+ symbol={\ensuremath{\mtx{I}}},
+ plural={identity matrices},
+ description={a diagonal matrix with all diagonal elements equal to
+1 and all other elements equal to 0}
+}
+
+\newglossaryentry{matrixinv}{%
+ name={matrix inverse},
+ symbol={\ensuremath{\mtxinv{M}}},
+ user1={mtxinv},
+ description={a square \gls{matrix} such that
+ $\mtx{M}\mtxinv{M}=\glssymbol{identitymatrix}$}
+}
+\end{verbatim}
+
+There are two commands provided that allow you to apply the
+command to an argument:
+\begin{definition}[\DescribeMacro\glsxtrfmt]
+\cs{glsxtrfmt}\oarg{options}\marg{label}\marg{text}
+\end{definition}
+This effectively does
+\begin{alltt}
+\cs{glslink}[\meta{default-options},\meta{options}]\marg{label}\{\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\{\}\}
+\end{alltt}
+where \meta{cs name} is the control
+sequence name supplied in the provided field, which must be defined
+to take a single required argument. Although it effectively
+acts like \cs{glslink} it misses out the post-link hook.
+
+The default \meta{default-options} are given by
+\begin{definition}[\DescribeMacro\GlsXtrFmtDefaultOptions]
+\cs{GlsXtrFmtDefaultOptions}
+\end{definition}
+This is defined as \texttt{\GlsXtrFmtDefaultOptions} but may
+be redefined as appropriate. Note that the replacement text of
+\cs{GlsXtrFmtDefaultOptions} is prepended to the optional
+argument of \cs{glslink}.
+
+As from version 1.23, there's also a starred version of
+this command that has a final optional argument:
+\begin{definition}[\DescribeMacro{\glsxtrfmt*}]
+\cs{glsxtrfmt*}\oarg{options}\marg{label}\marg{text}\oarg{insert}
+\end{definition}
+Both the starred and unstarred versions use:
+\begin{definition}[\DescribeMacro\glsxtrfmtdisplay]
+\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\marg{insert}
+\end{definition}
+within the link text.
+In the case of the unstarred version \meta{insert} will be empty.
+It will also be empty if the final option argument is
+missing from the starred form. If the entry given by \meta{label}
+is undefined \cs{glsxtrfmt} and \cs{glsxtrfmt*} will issue
+an error (or warning if \pkgopt[warn]{undefaction}).
+There won't be a warning or error if the entry is defined by
+the given field is missing. In either case,
+(the entry is undefined or the field is missing) \meta{cs name}
+will be \texttt{@firstofone} otherwise it will be the
+field value. The default definition is:
+\begin{verbatim}
+\newcommand{\glsxtrfmtdisplay}[3]{\csuse{#1}{#2}#3}
+\end{verbatim}
+which puts \meta{text} inside the argument of the control sequence
+and \meta{insert} outside it (but it will still be inside the
+link text).
+
+\begin{important}
+Remember that nested links cause a problem so avoid using
+commands like \cs{gls} or \cs{glsxtrfmt} within \meta{text}.
+\end{important}
+
+For example:
+\begin{verbatim}
+\[
+ \glsxtrfmt{matrix}{A}
+ \glsxtrfmt{matrixinv}{A}
+ =
+ \glssymbol{identitymatrix}
+\]
+\end{verbatim}
+If the default options are set to \texttt{noindex} then
+\cs{glsxtrfmt} won't index, but will create a hyperlink (if
+\sty{hyperref} has been loaded). This can be changed so that
+it also suppresses the hyperlink:
+\begin{verbatim}
+\renewcommand{\GlsXtrFmtDefaultOptions}{hyper=false,noindex}
+\end{verbatim}
+
+Note that \cs{glsxtrfmt} won't work with PDF bookmarks. Instead
+you can use
+\begin{definition}[\DescribeMacro\glsxtrentryfmt]
+\cs{glsxtrentryfmt}\marg{label}\marg{text}
+\end{definition}
+This uses \cs{texorpdfstring} and will simply expand to \meta{text}
+within the PDF bookmarks, but in the document it will do
+\meta{cs}\marg{text} if a control sequence name has been provided
+or just \meta{text} otherwise.
+
+The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to
+add new keys. This command will cause an error if the key has
+already been defined. The \styfmt{glossaries-extra} package provides
+a supplementary command that will only define the key if it doesn't
+already exist:
+\begin{definition}[\DescribeMacro\glsxtrprovidestoragekey]
+\cs{glsxtrprovidestoragekey}\marg{key}\marg{default}\marg{cs}
+\end{definition}
+If the key has already been defined, it will still provide the command given in
+the third argument \meta{cs} (if it hasn't already been defined). Unlike
+\cs{glsaddstoragekey}, \meta{cs} may be left empty if you're happy
+to just use \cs{glsfieldfetch} to fetch the value of this new key.
+
+You can test if a key has been provided with:
+\begin{definition}[\DescribeMacro\glsxtrifkeydefined]
+\cs{glsxtrifkeydefined}\marg{key}\marg{true}\marg{false}
+\end{definition}
+This tests if \meta{key} is available for use in the
+\meta{key}=\value{value} list in the second argument of
+\cs{newglossaryentry} (or the optional argument of
+commands like \cs{newabbreviation}). The corresponding
+field may not have been set for any of the entries if no
+default was provided.
+
+There are now commands provided to set individual fields. Note that
+these only change the specified field, not any related values. For
+example, changing the value of the \gloskey{text} field won't update
+the \gloskey{plural} field. There are also some fields that
+should really only be set when entries are defined (such
+as the \gloskey{parent} field). Unexpected results may occur
+if they are subsequently changed.
+
+\begin{definition}[\DescribeMacro\GlsXtrSetField]
+\cs{GlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+Sets the field given by \meta{field} to \meta{value} for the entry
+given by \meta{label}. No expansion is performed. It's not
+necessary for the field to have been defined as a key. You
+can access the value later with \cs{glsxtrusefield}. Note that
+\cs{glsxtrifkeydefined} only tests if a key has been defined for use
+with commands like \cs{newglossaryentry}. If a field without a
+corresponding key is assigned a value, the key remains undefined.
+This command is robust.
+
+\cs{GlsXtrSetField} uses
+\begin{definition}[\DescribeMacro\glsxtrsetfieldifexists]
+\cs{glsxtrsetfieldifexists}\marg{label}\marg{field}\marg{code}
+\end{definition}
+where \meta{label} is the entry label and \meta{code} is the
+assignment code.
+
+This command just uses \ics{glsdoifexists}\marg{label}\marg{code}
+(ignoring the \meta{field} argument), so by default it causes an
+error if the entry doesn't exist. This can be changed to a warning
+with \pkgopt[warn]{undefaction}. You can redefine
+\cs{glsxtrsetfieldifexists} to simply do \meta{code} if you want to
+skip the existence check. Alternatively you can instead use
+\begin{definition}[\DescribeMacro\glsxtrdeffield]
+\cs{glsxtrdeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text}
+\end{definition}
+This simply uses \sty{etoolbox}'s \cs{csdef} without any checks.
+This command isn't robust. There is also a version that uses
+\cs{protected@csedef} instead:\footnote{Pre version 1.28 used
+\cs{csedef}.}
+\begin{definition}[\DescribeMacro\glsxtredeffield]
+\cs{glsxtredeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text}
+\end{definition}
+
+\begin{definition}[\DescribeMacro\gGlsXtrSetField]
+\cs{gGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{GlsXtrSetField} but globally.
+
+\begin{definition}[\DescribeMacro\eGlsXtrSetField]
+\cs{eGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{GlsXtrSetField} but uses protected expansion.
+
+\begin{definition}[\DescribeMacro\xGlsXtrSetField]
+\cs{xGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{gGlsXtrSetField} but uses protected expansion.
+
+\begin{definition}[\DescribeMacro\GlsXtrLetField]
+\cs{GlsXtrLetField}\marg{label}\marg{field}\marg{cs}
+\end{definition}
+Sets the field given by \meta{field} to the replacement text of \meta{cs}
+for the entry given by \meta{label} (using \cs{let}).
+
+\begin{definition}[\DescribeMacro\csGlsXtrLetField]
+\cs{csGlsXtrLetField}\marg{label}\marg{field}\marg{cs name}
+\end{definition}
+As \cs{GlsXtrLetField} but the control sequence name is supplied
+instead.
+
+\begin{definition}[\DescribeMacro\GlsXtrLetFieldToField]
+\cs{GlsXtrLetFieldToField}\marg{label-1}\marg{field-1}\marg{label-2}\marg{field-2}
+\end{definition}
+Sets the field given by \meta{field-1} for the entry given by
+\meta{label-1} to the field given by \meta{field-2} for the entry
+given by \meta{label-2}. There's no check for the existence of
+\meta{label-2}, but
+\cs{glsxtrsetfieldifexists}\marg{label-1}\marg{field-1}\marg{code}
+is still used, as for \cs{GlsXtrSetField}.
+
+The \styfmt{glossaries} package provides \ics{ifglshasfield}
+to determine if a field has been set. The \styfmt{glossaries-extra}
+package provides a simpler version:
+\begin{definition}[\DescribeMacro\glsxtrifhasfield]
+\cs{glsxtrifhasfield}\marg{field}\marg{label}\marg{true}\marg{false}
+\end{definition}
+(New to v1.19.) Note that in this case the \meta{field} must be the
+\emph{internal} field label (for example, \texttt{useri} rather than
+\texttt{user1}).
+Unlike \cs{ifglshasfield}, this version doesn't complain if the
+entry (given by \meta{label}) or the field don't exist and
+will simply do \meta{false}. If the field does exist for the given
+entry and it's not empty, the \meta{true} part is done otherwise it
+does \meta{false}. Within \meta{true} you may use
+\begin{definition}[\DescribeMacro\glscurrentfieldvalue]
+\cs{glscurrentfieldvalue}
+\end{definition}
+to access the field value. This command includes grouping
+which scopes the \meta{true} and \meta{false} parts.
+The starred version
+\begin{definition}[\DescribeMacro{\glsxtrifhasfield*}]
+\cs{glsxtrifhasfield*}\marg{field}\marg{label}\marg{true}\marg{false}
+\end{definition}
+omits the implicit grouping.
+
+\begin{important}
+Be careful of keys that use \cs{relax} as the default value
+(such as the \gloskey{symbol}). Use \cs{ifglshassymbol} instead.
+\end{important}
+
+There is also a version that simply uses \cs{ifcsundef}. It
+doesn't save the field value, but can be used if you only
+need to check if the field is defined without accessing it:
+\begin{definition}[\DescribeMacro\GlsXtrIfFieldUndef]
+\cs{GlsXtrIfFieldUndef}\marg{field}\marg{label}\marg{true}\marg{false}
+\end{definition}
+
+\begin{important}
+There's a difference between an undefined field and an unset field.
+An undefined field hasn't been assigned any value (no
+associated internal control sequence has been defined). If a defined
+field has been defined to empty, then it's considered unset.
+\cs{GlsXtrIfFieldUndef} implement \meta{false} for a defined
+but empty field whereas \cs{glsxtrifhasfield} and \cs{ifglshasfield}
+will implement \meta{false} a defined but empty field.
+Remember that any keys that may be used in \cs{newglossaryentry}
+will have a default value if not provided. In many cases, the
+default value is empty, so only use \cs{GlsXtrIfFieldUndef}
+for fields that can only be defined through commands like
+\cs{GlsXtrSetField}.
+\end{important}
+
+You can test if a field value equals a string using
+\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqStr}]
+\cs{GlsXtrIfFieldEqStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false}
+\end{definition}
+If the entry exists and has the given field set to the
+given text then this does \meta{true} otherwise it does
+\meta{false}. This uses \cs{glsxtrifhasfield}
+to test if the field exists and then compares the replacement
+text of \cs{glscurrentfieldvalue} with \meta{text} using
+\sty{etoolbox}'s \cs{ifdefstring}. Version 1.39 introduced
+a starred form of this command, which uses the starred form
+of \cs{glsxtrifhasfield}.
+
+As from version 1.31, there's a similar command:
+\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqXpStr}]
+\cs{GlsXtrIfFieldEqXpStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false}
+\end{definition}
+This is like \cs{GlsXtrIfFieldEqStr} but first (protected) fully
+expands \meta{text} (but not the field value). If you want to
+compare the (protected) full expansion of both the field value and \meta{text}
+use:
+\begin{definition}[\DescribeMacro{\GlsXtrIfXpFieldEqXpStr}]
+\cs{GlsXtrIfXpFieldEqXpStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false}
+\end{definition}
+Again, version 1.39 introduced a starred form of these commands,
+which use the starred form of \cs{glsxtrifhasfield}.
+
+As from v1.31, if a field represents a numeric (integer) value, you
+can use the following two numeric tests. If the field is set, it must
+expand to an integer. You may use \cs{glscurrentfieldvalue}
+within \meta{true} or \meta{false} to access the actual value. Both \meta{true}
+and \meta{false} are scoped. If the field is undefined or empty,
+the value is assumed to be 0, and \cs{glscurrentfieldvalue} is set
+accordingly. As from version 1.39, these numeric tests have
+starred versions. The unstarred versions add implicit grouping.
+The starred versions don't.
+
+To test if the value is non-zero:
+\begin{definition}[\DescribeMacro{\GlsXtrIfFieldNonZero}]
+\cs{GlsXtrIfFieldNonZero}\marg{field}\marg{label}\marg{true}\marg{false}
+\end{definition}
+Alternatively, you can test if the field expands to a specific
+number using:
+\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqNum}]
+\cs{GlsXtrIfFieldEqNum}\marg{field}\marg{label}\marg{n}\marg{true}\marg{false}
+\end{definition}
+This does \meta{true} if the field value equals \meta{n}
+(using \cs{ifnum} for the comparison) otherwise it does
+\meta{false}. For a more general numeric comparison you
+can use:
+\begin{definition}[\DescribeMacro{\GlsXtrIfFieldCmpNum}]
+\cs{GlsXtrIfFieldCmpNum}\marg{field}\marg{label}\marg{comparison}\marg{n}\marg{true}\marg{false}
+\end{definition}
+where \meta{comparison} is one of \texttt{=}, \texttt{<} or
+\texttt{>}.
+
+The \styfmt{glossaries} package provides \ics{glsfieldfetch} which
+can be used to fetch the value of the given field and store it in a
+control sequence. The \styfmt{glossaries-extra} package provides
+another way of accessing the field value:
+\begin{definition}[\DescribeMacro\glsxtrusefield]
+\cs{glsxtrusefield}\marg{entry-label}\marg{field-label}
+\end{definition}
+This works in the same way as commands like \cs{glsentrytext} but
+the field label is specified in the first argument. Note that the
+\meta{field-label} corresponds to the internal field tag, which
+isn't always the same as the key name. See Table~4.1 of the
+\sty{glossaries} manual. No error occurs if the entry or field
+haven't been defined. This command is not robust.
+
+There is also a version that converts the first letter to uppercase
+(analogous to \cs{Glsentrytext}):
+\begin{definition}[\DescribeMacro\Glsxtrusefield]
+\cs{Glsxtrusefield}\marg{entry-label}\marg{field-label}
+\end{definition}
+and, as from v1.37, a command that converts the entire value to upper case:
+\begin{definition}[\DescribeMacro\GLSxtrusefield]
+\cs{GLSxtrusefield}\marg{entry-label}\marg{field-label}
+\end{definition}
+
+If you want to use a field to store a list that can be used
+as an \sty{etoolbox} internal list, you can use the following
+command that adds an item to the field using \sty{etoolbox}'s
+\cs{listcsadd}:
+\begin{definition}[\DescribeMacro\glsxtrfieldlistadd]
+\cs{glsxtrfieldlistadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+where \meta{label} is the entry's label, \meta{field} is
+the entry's field and \meta{item} is the item to add. There
+are analogous commands that use \cs{listgadd}, \cs{listeadd}
+and \cs{listxadd}:
+\begin{definition}[\DescribeMacro\glsxtrfieldlistgadd]
+\cs{glsxtrfieldlistgadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrfieldlisteadd]
+\cs{glsxtrfieldlisteadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrfieldlistxadd]
+\cs{glsxtrfieldlistxadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+You can then iterate over the list using:
+\begin{definition}[\DescribeMacro\glsxtrfielddolistloop]
+\cs{glsxtrfielddolistloop}\marg{label}\marg{field}
+\end{definition}
+or
+\begin{definition}[\DescribeMacro\glsxtrfieldforlistloop]
+\cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler}
+\end{definition}
+that internally use \cs{dolistcsloop} and \cs{forlistloop},
+respectively.
+
+There are also commands that use \cs{ifinlistcs}:
+\begin{definition}[\DescribeMacro\glsxtrfieldifinlist]
+\cs{glsxtrfieldifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false}
+\end{definition}
+and \cs{xifinlistcs}
+\begin{definition}[\DescribeMacro\glsxtrfieldxifinlist]
+\cs{glsxtrfieldxifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false}
+\end{definition}
+
+See the \sty{etoolbox}'s user manual for further
+details of these commands, in particular the limitations
+of \cs{ifinlist}.
+
+If the field has a comma-separated list value instead, you
+can iterate over it using:
+\begin{definition}[\DescribeMacro\glsxtrforcsvfield]
+\cs{glsxtrforcsvfield}\marg{label}\marg{field}\marg{handler}
+\end{definition}
+where again \meta{handler} is a control sequence that takes
+a single argument. Unlike the \sty{etoolbox} loops, this
+doesn't ignore empty elements nor does it discard leading / trailing
+spaces. Internally it uses \cs{@for} (modified by \sty{xfor}
+which is automatically loaded by \sty{glossaries}). The
+\sty{xfor} package modifies the behaviour of \cs{@for} to allow
+the loop to be broken prematurely using \cs{@endfortrue}.
+The \cs{glsxtrforcsvfield} command locally defines
+a user level command:
+\begin{definition}[\DescribeMacro\glsxtrendfor]
+\cs{glsxtrendfor}
+\end{definition}
+which is just a synonym for \cs{@endfortrue}.
+
+The loop is performed within the true part of \cs{glsxtrifhasfield}
+so scoping is automatically applied.
+
+As from version 1.32, if the field given by
+\begin{definition}[\DescribeMacro\GlsXtrForeignTextField]
+\cs{GlsXtrForeignTextField}
+\end{definition}
+(which defaults to \texttt{userii}) contains a locale tag, then
+\begin{definition}[\DescribeMacro\GlsXtrForeignText]
+\cs{GlsXtrForeignText}\marg{entry label}\marg{text}
+\end{definition}
+can be used to encapsulate \meta{text} in
+\cs{foreignlanguage}\marg{dialect}\marg{text} where \meta{dialect}
+is obtained from the locale tag through \sty{tracklang}'s
+\ics{GetTrackedDialectFromLanguageTag} command. You need at least
+\sty{tracklang} v1.3.6 for this to work properly. The \meta{dialect}
+must be one that's tracked (which typically means that \sty{babel}
+or \sty{polyglossia} has been loaded with the appropriate setting
+for that language). If \cs{foreignlanguage} hasn't been defined,
+this just does \meta{text}.
+For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[main=british,brazilian,ngerman]{babel}
+\usepackage{glossaries-extra}
+
+\setabbreviationstyle{long-short-user}
+\newabbreviation
+ [user1={Associa\c{c}\~ao Brasileria de Normas T\'ecnicas},
+ user2= {pt-BR}
+ ]
+ {abnt}{ABNT}{Brazilian National Standards Organization}
+
+\newabbreviation
+ [user1={Deutsches Institut f\"ur Normung e.V.},
+ user2={de-DE-1996}]
+ {din}{DIN}{German Institute for Standardization}
+
+\renewcommand*{\glsxtruserparen}[2]{%
+ \glsxtrfullsep{#2}%
+ \glsxtrparen
+ {#1%
+ \ifglshasfield{\glsxtruserfield}{#2}%
+ {, \emph{\GlsXtrForeignText{#2}{\glscurrentfieldvalue}}}%
+ {}%
+ }%
+}
+
+\begin{document}
+\gls{abnt}, \gls{din}.
+\end{document}
+\end{verbatim}
+
+
+When using the \pkgopt{record} option, in addition to recording the
+usual location, you can also record the current value
+of another counter at the same time using the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrRecordCounter]
+\cs{GlsXtrRecordCounter}\marg{counter name}
+\end{definition}
+For example:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\GlsXtrRecordCounter{section}
+\end{verbatim}
+Each time an entry is referenced with commands like \cs{gls}
+or \cs{glstext}, the \texttt{.aux} file will not only contain
+the \cs{glsxtr@record} command but also
+\begin{alltt}
+\cs{glsxtr@counterrecord}\marg{label}\{section\}\marg{n}
+\end{alltt}
+where \meta{n} is the current expansion of \cs{thesection}
+and \meta{label} is the entry's label. On the next run, when the
+\texttt{.aux} file is run, this command will do
+\begin{alltt}
+\cs{glsxtrfieldlistgadd}\marg{label}\{record.\meta{counter}\}\marg{n}
+\end{alltt}
+In the above example, if \verb|\gls{bird}| is used in section~1.2
+this would be
+\begin{verbatim}
+\glsxtrfieldlistgadd{bird}{record.section}{1.2}
+\end{verbatim}
+Note that there's no key corresponding to this new
+\texttt{record.section} field, but its value can be
+accessed with \cs{glsxtrfielduse} or the list can be
+iterated over with \cs{glsxtrfielddolistloop} etc.
+
+\section{Display All Entries Without Sorting or Indexing}
+\label{sec:printunsrt}
+
+\begin{definition}[\DescribeMacro\printunsrtglossary]
+\cs{printunsrtglossary}\oarg{options}
+\end{definition}
+This behaves like \cs{printnoidxglossary} but never sorts the
+entries and always lists all the defined entries for the given
+glossary (and doesn't require \cs{makenoidxglossaries}).
+If you want to use one of the \env{tabular}-like
+styles with \cs{printunsrtglossary}, make sure you load
+\sty{glossaries-extra-stylemods} which modifies
+the definition of \cs{glsgroupskip} to avoid the
+\qt{Incomplete \cs{iftrue}} error that may otherwise occur.
+
+There's also a starred form
+\begin{definition}[\DescribeMacro{\printunsrtglossary*}]
+\cs{printunsrtglossary}*\oarg{options}\marg{code}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{begingroup}
+ \meta{code}\cs{printunsrtglossary}\oarg{options}\%
+\cs{endgroup}
+\end{alltt}
+Note that unlike \cs{glossarypreamble}, the supplied \meta{code} is
+done before the glossary header.
+
+This means you now have the option to simply list all entries on the
+first \LaTeX\ run without the need for a post-processor, however
+there will be no \gls{numberlist} in this case, as that has to be
+set by a post-processor such as \gls{bib2gls} (see
+\sectionref{sec:bib2gls}).
+
+\begin{important}
+No attempt is made to gather hierarchical elements.
+If child entries aren't defined immediately after their parent
+entry, they won't be together in the glossary when using
+\cs{printunsrtglossary}.
+\end{important}
+
+There's a difference in behaviour depending on whether or not the
+\gloskey{group} key is defined. If not defined (default), the
+group label will be formed from the first letter of the
+\gloskey{name} field. The corresponding group title will be obtained
+as discussed in \sectionref{sec:glosstylemods}. This can lead to an
+odd effect if you are using a style that separates letter groups
+when the ordering isn't alphabetical.
+
+If the \gloskey{group} key is defined (which it is with the
+\pkgopt{record} option) then the group label will be obtained from
+the value of that field. If the field is empty, \emph{no grouping is
+performed}, even if the style supports it. (That is, there won't be
+a header or a vertical separation.) If the \gloskey{group} field is
+non-empty, then the corresponding title is obtained as described
+earlier.
+
+If you want to use a different field, you can redefine
+\begin{definition}[\DescribeMacro\glsxtrgroupfield]
+\cs{glsxtrgroupfield}
+\end{definition}
+to the relevant internal field label, but the \gloskey{group}
+\emph{key} must still be defined (through the \pkgopt{record} option
+or with commands like \cs{glsaddstoragekey}) to ensure that
+\cs{printunsrtglossary} uses \cs{glsxtrgroupfield}. (This method is
+used by \gls{bib2gls} for secondary entries, which have the group
+label stored in the \texttt{secondarygroup} internal field.)
+
+If you have any entries with the \gloskey{see} key set, you will
+need the \sty{glossaries} package option \pkgopt[ignore]{seenoindex}
+or \pkgopt[warn]{seenoindex} to prevent an error occurring from the
+automated \cs{glssee} normally triggered by this key. The
+\pkgopt[only]{record} package option will automatically deal with
+this.
+
+For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\newglossaryentry{zebra}{name={zebra},description={stripy animal}}
+\newglossaryentry{ant}{name={ant},description={an insect}}
+
+\begin{document}
+\gls{ant} and \gls{zebra}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+In the above, zebra will be listed before ant as it was defined
+first.
+
+If you allow document definitions with the \pkgopt{docdefs} option,
+the document will require a second \LaTeX\ run if the entries are
+defined after \cs{printunsrtglossary}.
+
+The optional argument is as for \cs{printnoidxglossary} (except for
+the \gloskey[printnoidxglossary]{sort} key, which isn't available).
+
+All glossaries may be displayed in the order of their definition
+using:
+\begin{definition}[\DescribeMacro\printunsrtglossaries]
+\cs{printunsrtglossaries}
+\end{definition}
+which is analogous to \cs{printnoidxglossaries}. This just
+iterates over all defined glossaries (that aren't on the ignored
+list) and does \cs{printunsrtglossary}[type=\meta{type}].
+
+To avoid complications caused by \env{tabular}-like glossary
+styles, \cs{printunsrtglossary} iterates over all entries
+in the selected glossary and appends the appropriate code
+to an internal command. Once the construction of this
+command is complete, then it's performed to display the
+glossary. This puts the loop outside the style code.
+For convenience, there's a hook used within the loop:
+\begin{definition}[\DescribeMacro\printunsrtglossaryentryprocesshook]
+\cs{printunsrtglossaryentryprocesshook}\marg{label}
+\end{definition}
+This hook should not display any content, but may be used
+to perform calculations. For example, to calculate widths.
+Within this hook you can use:
+\begin{definition}[\DescribeMacro\printunsrtglossaryskipentry]
+\cs{printunsrtglossaryskipentry}
+\end{definition}
+to skip the current entry. This will prevent the entry from
+being added to the internal command.
+
+There's another hook immediately before the internal command
+containing the glossary code is performed:
+\begin{definition}[\DescribeMacro\printunsrtglossarypredoglossary]
+\cs{printunsrtglossarypredoglossary}
+\end{definition}
+
+The internal command uses
+\begin{definition}[\DescribeMacro\printunsrtglossaryhandler]
+\cs{printunsrtglossaryhandler}\marg{label}
+\end{definition}
+to display each item in the list, where \meta{label} is the current label.
+
+By default the handler just does
+\begin{definition}[\DescribeMacro\glsxtrunsrtdo]
+\cs{glsxtrunsrtdo}\marg{label}
+\end{definition}
+which determines whether to use \cs{glossentry} or
+\cs{subglossentry} and checks the \gloskey{location} and
+\gloskey{loclist} fields for the \gls{numberlist}. If you want to
+use a different field to be used instead of \gloskey{location}
+then redefine:
+\begin{definition}[\DescribeMacro\GlsXtrLocationField]
+\cs{GlsXtrLocationField}
+\end{definition}
+to the internal name of the desired field. For example:
+\begin{verbatim}
+\renewcommand{\GlsXtrLocationField}{primarylocation}
+\end{verbatim}
+\begin{important}
+Note that if the given location field is undefined or unset,
+the handler will fallback on the \gloskey{loclist} field.
+\end{important}
+You can instruct \gls{bib2gls} to omit setting the \gloskey{loclist}
+field with the resource option \texttt{--save-loclist=false}
+to prevent it from being used as a fallback.
+
+You can redefine the handler if required. For example,
+you may want to filter entries according to the category
+label. You can test if a label is contained in a comma-separated
+list of labels using:
+\begin{definition}[\DescribeMacro\glsxtriflabelinlist]
+\cs{glsxtriflabelinlist}\marg{label}\marg{label list}\marg{true}\marg{false}
+\end{definition}
+The \meta{label} and \meta{label list} will be fully expanded.
+
+\begin{important}
+If you redefine the handler to exclude entries, you may end
+up with an empty glossary. This could cause a problem for
+the list-based styles.
+\end{important}
+
+For example, if the preamble includes:
+\begin{verbatim}
+\usepackage[record,style=index]{glossaries-extra}
+\GlsXtrRecordCounter{section}
+\end{verbatim}
+then you can print the glossary but first redefine the handler
+to only select entries that include the current section number
+in the \texttt{record.section} field:
+\begin{verbatim}
+\renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+}
+\end{verbatim}
+
+Alternatively you can use the starred form of
+\cs{printunsrtglossary} which will localise the change:
+
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+}
+\end{verbatim}
+
+If you are using the \sty{hyperref} package and want to
+display the same glossary more than once, you can also
+add a temporary redefinition of \cs{glolinkprefix} to
+avoid duplicate hypertarget names. For example:
+
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+ \ifcsundef{theHsection}%
+ {%
+ \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}%
+ }%
+ {%
+ \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}%
+ }%
+}
+\end{verbatim}
+Note that this will cause a problem if your descriptions
+contain commands like \cs{gls} that need to link an entry that
+doesn't appear in the summary. In this case, it's a better approach
+to use:
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+ \ifcsundef{theHsection}%
+ {%
+ \setkeys{printgloss}{targetnameprefix={record.\csuse{thesection}.}}%
+ }%
+ {%
+ \setkeys{printgloss}{targetnameprefix={record.\csuse{theHsection}.}}%
+ }%
+}
+\end{verbatim}
+
+If it's a short summary at the start of a section, you might
+also want to suppress the glossary header and add some vertical
+space afterwards:
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+ \ifcsundef{theHsection}%
+ {%
+ \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}%
+ }%
+ {%
+ \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}%
+ }%
+ \renewcommand*{\glossarysection}[2][]{}%
+ \appto\glossarypostamble{\glspar\medskip\glspar}%
+}
+\end{verbatim}
+
+There's a shortcut command that essentially does this:
+\begin{definition}[\DescribeMacro\printunsrtglossaryunit]
+\cs{printunsrtglossaryunit}\oarg{options}\marg{counter name}
+\end{definition}
+The above example can simply be replaced with:
+\begin{verbatim}
+\printunsrtglossaryunit{section}
+\end{verbatim}
+
+This shortcut command is actually defined to use \cs{printunsrtglossary*} with
+\begin{definition}[\DescribeMacro\printunsrtglossaryunitsetup]
+\cs{printunsrtglossaryunitsetup}\marg{counter name}
+\end{definition}
+so if you want to just make some minor modifications you can
+do
+\begin{verbatim}
+\printunsrtglossary*{\printunsrtglossaryunitsetup{section}%
+ \renewcommand*{\glossarysection}[2][]{\subsection*{Summary}}%
+}
+\end{verbatim}
+which will start the list with a subsection header with the
+title \qt{Summary} (overriding the glossary's title).
+
+Note that this shortcut command is only available with the
+\pkgopt{record} (or \pkgopt[alsoindex]{record}) package option.
+
+This temporary change in the hypertarget prefix means you
+need to explicitly use \cs{hyperlink} to create a link to it
+as commands like \cs{gls} will try to link to the target
+created with the default definition of \cs{gloslinkprefix}.
+This isn't a problem if you want a primary glossary of all terms
+produced using just \cs{printunsrtglossary} (in the front or back
+matter) which can be the target for all glossary references
+and then just use \cs{printunsrtglossaryunit} for a quick
+summary at the start of a section etc.
+
+\section{Standalone Entry Items}
+\label{sec:glossentry}
+
+It may be that you don't want a list but would rather display
+entry details throughout the document. You can simply
+do \cs{glsentryname} followed by \cs{glsentrydesc}.
+(Remember that if you don't want a sorted list, use
+\pkgopt[none]{sort} to skip the construction of the
+\gloskey{sort} field.)
+For example, in the preamble provide a custom command:
+\begin{verbatim}
+\newcommand{\displayterm}[1]{%
+ \par\medskip\par\noindent
+ Definition: \glsentryname{#1}.\par
+ \glsentrydesc{#1}
+ \par\medskip
+}
+\end{verbatim}
+define your entries
+\begin{verbatim}
+\newglossaryentry{function}{name={function},
+ description={a relation or expression involving variables}
+}
+\end{verbatim}
+and then later in the text:
+\begin{verbatim}
+\displayterm{function}
+\end{verbatim}
+
+However, if may be that you want to use \sty{hyperref} and
+have commands like \cs{gls} link back to the place where
+the term is described. Instead of using \cs{glsentryname}
+use
+\begin{definition}[\DescribeMacro\glsxtrglossentry]
+\cs{glsxtrglossentry}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label.
+
+This is designed to behave much like the way the name is displayed
+in the glossary. It performs the following:
+\begin{itemize}
+\item Defines \cs{glscurrententrylabel} to the entry's label.
+This is usually done at the start of the glossary style commands
+\cs{glossentry} and \cs{subglossentry} and may be used by hooks,
+such as the post-name hooks. Here the definition is localised
+so that it's only available for use in \cs{glossentryname}.
+
+\item Defines \cs{currentglossary} to the entry's glossary type.
+This is usually done at the start of commands like
+\cs{printglossary} and may be used by style hooks.
+Here the definition is localised so that it's only available for use
+in \cs{glsentryitem} and \cs{glssubentryitem}. The value is obtained
+by fully expanding:
+\begin{definition}[\DescribeMacro\GlsXtrStandaloneGlossaryType]
+\cs{GlsXtrStandaloneGlossaryType}
+\end{definition}
+which defaults to the value of the \gloskey{type} field for the
+current entry.
+
+\item Increments and display the entry counters
+ if the \pkgopt{entrycounter} or \pkgopt{subentrycounter}
+ package options are set. If the entry doesn't have a parent, then
+ this does
+ \begin{itemize}
+ \item \cs{glsentryitem}\marg{label}
+ \end{itemize}
+ otherwise it does (as from v1.31)
+ \begin{itemize}
+ \item \ics{GlsXtrStandaloneSubEntryItem}\marg{label}
+which defaults to \cs{glssubentryitem}\marg{label} if the entry
+has a parent but not a grandparent.
+ \end{itemize}
+ This reflects the behaviour of the predefined hierarchical styles.
+A bug in pre-version~1.31 used \cs{glsentryitem} for all child levels,
+which doesn't match the hierarchical glossary styles. If you want to
+restore this behaviour, just do:
+\begin{verbatim}
+\renewcommand*{\GlsXtrStandaloneSubEntryItem}[1]{\glssubentryitem{#1}}
+\end{verbatim}
+
+\item Sets the hyper-target if supported (using \cs{glstarget})
+and displays the entry name using:
+\begin{definition}[\DescribeMacro\GlsXtrStandaloneEntryName]
+\cs{GlsXtrStandaloneEntryName}\marg{label}
+\end{definition}
+ which uses
+ \cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\}
+ by default.
+ Remember that \cs{glossentryname} uses \cs{glsnamefont} or picks up
+ the style from category attributes such as
+ \catattr{glossnamefont}.
+\end{itemize}
+If you have used \ics{nopostdesc} or \ics{glsxtrnopostpunc}
+in any of your description fields, you can use
+\begin{definition}[\DescribeMacro\glsxtractivatenopost]
+\cs{glsxtractivatenopost}
+\end{definition}
+to make these commands behave as they normally do within a glossary.
+This needs to be placed before
+\begin{alltt}
+\cs{glossentrydesc}\marg{label}\cs{glspostdescription}
+\end{alltt}
+and scoped. Note that \cs{glsnonextpages} and \cs{glsnextpages} have no
+effect outside of the glossary and are not intended for use in a
+standalone context.
+
+It's also possible to select a different field (rather than
+using \gloskey{name}):
+\begin{definition}[\DescribeMacro\glsxtrglossentryother]
+\cs{glsxtrglossentryother}\marg{header}\marg{label}\marg{field}
+\end{definition}
+The \meta{field} must be given using its internal field label
+which may not be the same as the key used to set the field.
+See the key to field mappings table in the \styfmt{glossaries}
+user manual. The \meta{header} argument is the code
+to pass to the third argument of \cs{glsxtrtitleorpdforheading}.
+It may be left empty in which case the default is determined as follows:
+\begin{itemize}
+\item If \cs{glsxtrhead\meta{field}} is defined, then \meta{header}
+is \cs{glsxtrhead\meta{field}}\marg{label}.
+\item Otherwise \meta{header} is simply the field value.
+\end{itemize}
+The \cs{glsxtrglossentryother} command internally uses
+\begin{definition}[\DescribeMacro\GlsXtrStandaloneEntryOther]
+\cs{GlsXtrStandaloneEntryOther}\marg{label}\marg{field}
+\end{definition}
+instead of \cs{GlsXtrStandaloneEntryName}, which uses
+\cs{glossentrynameother}\marg{label}\marg{field} instead of
+\cs{glossentryname}\marg{label}.
+
+If you have loaded the
+\sty{glossaries-accsupp} package (through the \pkgopt{accsupp}
+option) then accessibility support will be provided if
+there's a corresponding command
+\begin{alltt}
+\cs{gls\meta{field}accessdisplay}\marg{text}\marg{label}
+\end{alltt}
+(for example, \cs{glssymbolaccessdisplay}).
+
+This means that my custom command can be changed to:
+\begin{verbatim}
+\newcommand{\displayterm}[1]{%
+ \par\medskip\par\noindent
+ Definition: \glsxtrglossentry{#1}.\par
+ \glsentrydesc{#1}
+ \par\medskip
+}
+\end{verbatim}
+If I want numbered definitions, then I can use the
+package options \sty{entrycounter} or \sty{subentrycounter}
+and remove the colon:
+\begin{verbatim}
+\newcommand{\displayterm}[1]{%
+ \par\medskip\par\noindent
+ Definition \glsxtrglossentry{#1}.\par
+ \glsentrydesc{#1}
+ \par\medskip
+}
+\end{verbatim}
+The counter label uses a dot after the number by default
+but this can be changed to a colon:
+\begin{verbatim}
+\renewcommand*{\glsentrycounterlabel}{\theglossaryentry:\space}
+\end{verbatim}
+It's now possible to not only use \cs{gls} to link back to the
+definition but also use \cs{glsrefentry} to reference
+the counter and \cs{glsxtrpageref} to reference the page number.
+
+If I want the description to behave more like it does
+in a glossary in need to make the following modification:
+\begin{verbatim}
+\newcommand{\displayterm}[1]{%
+ \par\medskip\par\noindent
+ Definition \glsxtrglossentry{#1}.\par
+ \begingroup
+ \glsxtractivatenopost
+ \glossentrydesc{#1}\glspostdescription
+ \endgroup
+ \par\medskip
+}
+\end{verbatim}
+(Note the grouping to localise \cs{glsxtractivatenopost}.)
+
+You can also use \cs{glsxtrglossentry} within section headings.
+For example:
+\begin{verbatim}
+\section{\glsxtrglossentry{function}}
+\end{verbatim}
+This will use \cs{glsentryname} in PDF bookmarks (if
+\cs{texorpdfstring} is defined) and will use \cs{glsxtrheadname} in
+page headers and table of contents. (If you're using a page style or
+table of contents that doesn't use \cs{markright} or \cs{markbook}
+or \cs{@starttoc} then you need to insert \cs{glsxtrmarkhook} and
+\cs{@glsxtrinmark} at the start of the header or table of contents
+either scoped or afterwards cancelled with \cs{@glsxtrnotinmark} and
+\cs{glsxtrrestoremarkhook}.)
+
+\section{Entry Aliases}
+\label{sec:alias}
+
+An entry can be made an alias of another entry using the
+\gloskey{alias} key. The value should be the label of the other
+term. There's no check for the other's existence when the aliased
+entry is defined. This is to allow the possibility of defining the
+other entry after the aliased entry. (For example, when used with
+\gls{bib2gls}.)
+
+If an entry \meta{entry-1} is made an alias of \meta{entry-2} then:
+\begin{itemize}
+\item If the \gloskey{see} field wasn't provided when \meta{entry-1}
+was defined, the \gloskey{alias} key will automatically trigger
+\begin{alltt}
+\cs{glssee}\marg{entry-1}\marg{entry-2}
+\end{alltt}
+\item If the \sty{hyperref} package has been loaded then
+\cs{gls}\marg{entry-1} will link to \meta{entry-2}'s target. (Unless
+the \catattr{targeturl} attribute has been set for \meta{entry-1}'s
+category.)
+\item With \pkgopt[off]{record} or \pkgopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered
+when referencing \meta{entry-1} with commands like \cs{gls} or
+\cs{glstext}. This prevents \meta{entry-1} from have a
+\gls{locationlist} (aside from the cross-reference added with
+\cs{glssee}) unless it's been explicitly indexed with \cs{glsadd} or
+if the indexing has been explicitly set using
+\texttt{noindex=false}.
+
+Note that with \pkgopt[only]{record}, the \gls{locationlist}
+for aliased entries is controlled with \gls{bib2gls}['s] settings.
+\end{itemize}
+
+The index suppression trigger is performed by
+\begin{definition}[\DescribeMacro\glsxtrsetaliasnoindex]
+\cs{glsxtrsetaliasnoindex}
+\end{definition}
+This is performed after the default options provided by
+\ics{GlsXtrSetDefaultGlsOpts} have been set.
+With \pkgopt[only]{record}, \cs{glsxtrsetaliasnoindex} will
+default to do nothing.
+
+Within the definition of \cs{glsxtrsetaliasnoindex} you can use
+\begin{definition}[\DescribeMacro\glsxtrindexaliased]
+\cs{glsxtrindexaliased}
+\end{definition}
+to index \meta{entry-2}.
+
+The index suppression command can be redefined to index the main
+term instead. For example:
+\begin{verbatim}
+\renewcommand{\glsxtrsetaliasnoindex}{%
+ \glsxtrindexaliased
+ \setkeys{glslink}{noindex}%
+}
+\end{verbatim}
+
+The value of the \gloskey{alias} field can be accessed using
+\begin{definition}[\DescribeMacro\glsxtralias]
+\cs{glsxtralias}\marg{label}
+\end{definition}
+
+\chapter{Supplemental Packages}
+\label{sec:supplemental}
+
+The \styfmt{glossaries} bundle provides additional support packages
+\sty{glossaries-prefix} (for prefixing) and \sty{glossaries-accsupp}
+(for accessibility support). These packages aren't automatically
+loaded.
+
+\section{Prefixes or Determiners}
+\label{sec:prefix}
+
+If prefixing is required, you can simply load
+\sty{glossaries-prefix} after \styfmt{glossaries-extra}. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+\usepackage{glossaries-prefix}
+
+\makeglossaries
+
+\newabbreviation
+ [prefix={an\space},
+ prefixfirst={a~}]
+ {svm}{SVM}{support vector machine}
+
+\begin{document}
+
+First use: \pgls{svm}.
+Next use: \pgls{svm}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+
+\section{Accessibility Support}
+\label{sec:accsupp}
+
+The \sty{glossaries-accsupp} package needs to be loaded before
+\styfmt{glossaries-extra} or through the \pkgopt{accsupp} package
+option:
+\begin{verbatim}
+\usepackage[accsupp]{glossaries-extra}
+\end{verbatim}
+If you don't load \sty{glossaries-accsupp} or you load
+\sty{glossaries-accsupp} after \styfmt{glossaries-extra}
+the new \cs{glsaccess}\meta{xxx} commands described below will
+simply be equivalent to the corresponding \cs{glsentry}\meta{xxx}
+commands.
+
+The following \cs{glsaccess}\meta{xxx} commands add accessibility information wrapped around
+the corresponding \cs{glsentry}\meta{xxx} commands. There is
+no check for existence of the entry nor do any of these commands
+add formatting, hyperlinks or indexing information.
+
+\begin{definition}[\DescribeMacro\glsaccessname]
+\cs{glsaccessname}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{name} field for the entry
+identified by \meta{label}.
+
+If the \sty{glossaries-accsupp} package isn't loaded, this is
+simply defined as:
+\begin{verbatim}
+\newcommand*{\glsaccessname}[1]{\glsentryname{#1}}
+\end{verbatim}
+otherwise it's defined as:
+\begin{verbatim}
+\newcommand*{\glsaccessname}[1]{%
+ \glsnameaccessdisplay
+ {%
+ \glsentryname{#1}%
+ }%
+ {#1}%
+}
+\end{verbatim}
+(\ics{glsnameaccessdisplay} is defined by the
+\sty{glossaries-accsupp} package.) The first letter upper case
+version is:
+\begin{definition}[\DescribeMacro\Glsaccessname]
+\cs{Glsaccessname}\marg{label}
+\end{definition}
+Without the \sty{glossaries-accsupp} package this is just defined
+as:
+\begin{verbatim}
+\newcommand*{\Glsaccessname}[1]{\Glsentryname{#1}}
+\end{verbatim}
+With the \sty{glossaries-accsupp} package this is defined as:
+\begin{verbatim}
+\newcommand*{\Glsaccessname}[1]{%
+ \glsnameaccessdisplay
+ {%
+ \Glsentryname{#1}%
+ }%
+ {#1}%
+}
+\end{verbatim}
+
+The following commands are all defined in an analogous manner.
+\begin{definition}[\DescribeMacro\glsaccesstext]
+\cs{glsaccesstext}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{text} field.
+
+\begin{definition}[\DescribeMacro\Glsaccesstext]
+\cs{Glsaccesstext}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{text} field with the first
+letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessplural]
+\cs{glsaccessplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{plural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessplural]
+\cs{Glsaccessplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{plural} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessfirst]
+\cs{glsaccessfirst}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{first} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessfirst]
+\cs{Glsaccessfirst}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{first} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessfirstplural]
+\cs{glsaccessfirstplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{firstplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessfirstplural]
+\cs{Glsaccessfirstplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{firstplural} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccesssymbol]
+\cs{glsaccesssymbol}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{symbol} field.
+
+\begin{definition}[\DescribeMacro\Glsaccesssymbol]
+\cs{Glsaccesssymbol}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{symbol} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccesssymbolplural]
+\cs{glsaccesssymbolplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{symbolplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccesssymbolplural]
+\cs{Glsaccesssymbolplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{symbolplural} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessdesc]
+\cs{glsaccessdesc}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{description} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessdesc]
+\cs{Glsaccessdesc}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{description} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessdescplural]
+\cs{glsaccessdescplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{descriptionplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessdescplural]
+\cs{Glsaccessdescplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{descriptionplural} field
+with the first letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessshort]
+\cs{glsaccessshort}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{short} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessshort]
+\cs{Glsaccessshort}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{short} field with the first
+letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccessshortpl]
+\cs{glsaccessshortpl}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{shortplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessshortpl]
+\cs{Glsaccessshortpl}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{shortplural} field with the first
+letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccesslong]
+\cs{glsaccesslong}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{long} field.
+
+\begin{definition}[\DescribeMacro\Glsaccesslong]
+\cs{Glsaccesslong}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{long} field with the first
+letter converted to upper case.
+
+\begin{definition}[\DescribeMacro\glsaccesslongpl]
+\cs{glsaccesslongpl}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{longplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccesslongpl]
+\cs{Glsaccesslongpl}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{longplural} field with the first
+letter converted to upper case.
+
+\chapter{Sample Files}
+\label{sec:samples}
+
+The following sample files are provided with this package:
+\begin{description}
+\item[sample.tex] Simple sample file that uses one of the dummy
+files provided by the \styfmt{glossaries} package for testing.
+
+\item[sample-abbr-styles.tex] Demonstrates all predefined
+abbreviation styles.
+
+\item[sample-mixture.tex] General entries, acronyms and initialisms
+all treated differently.
+
+\item[sample-name-font] Categories and attributes are used to
+customize the way different entries appear.
+
+\item[sample-abbrv.tex] General abbreviations.
+
+\item[sample-acronym.tex] Acronyms aren't initialisms and don't
+expand on \gls{firstuse}.
+
+\item[sample-acronym-desc.tex] Acronyms that have a separate long
+form and description.
+
+\item[sample-crossref.tex] Unused entries that have been
+cross-referenced automatically are added at the end of the document.
+
+\item[sample-indexhook.tex] Use the index hook to track
+which entries have been indexed (and therefore find out
+which ones haven't been indexed).
+
+\item[sample-footnote.tex] Footnote abbreviation style that moves
+the footnote marker outside of the hyperlink generated by \cs{gls}
+and moves it after certain punctuation characters for neatness.
+
+\item[sample-undef.tex] Warn on undefined entries instead of
+generating an error.
+
+\item[sample-mixed-abbrv-styles.tex] Different abbreviation styles
+for different entries.
+
+\item[sample-initialisms.tex] Automatically insert dots into
+initialisms.
+
+\item[sample-postdot.tex] Another initialisms example.
+
+\item[sample-postlink.tex] Automatically inserting text after
+the \gls{linktext} produced by commands like \cs{gls} (outside
+of hyperlink, if present).
+
+\item[sample-header.tex] Using entries in section/chapter headings.
+
+\item[sample-autoindex.tex] Using the \catattr{dualindex} and
+\catattr{indexname} attributes to automatically add glossary
+entries to the index (in addition to the glossary \gls{locationlist}).
+
+\item[sample-autoindex-hyp.tex] As previous but uses \sty{hyperref}.
+
+\item[sample-nested.tex] Using \ics{gls} within the
+value of the \gloskey{name} key.
+
+\item[sample-entrycount.tex] Enable entry-use counting (only index
+if used more than $n$ times, see \sectionref{sec:entrycount}).
+
+\item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting
+(\sectionref{sec:entrycount}).
+
+\item[sample-onelink.tex] Using the per-unit entry counting
+(\sectionref{sec:entrycount})
+to only have one hyperlink per entry per page.
+
+\item[sample-linkcount.tex] Using link counting
+(\sectionref{sec:linkcount})
+to only have one hyperlink per entry.
+
+\item[sample-pages.tex] Insert \qt{page} or \qt{pages} before the
+location list.
+
+\item[sample-altmodifier.tex] Set the default options for
+commands like \cs{gls} and add an alternative modifier.
+
+\item[sample-mixedsort.tex] Uses the optional argument
+of \cs{makeglossaries} to allow a mixture of \cs{printglossary}
+and \cs{printnoidxglossary}.
+
+\item[sample-external.tex] Uses the \catattr{targeturl} attribute
+to allow for entries that should link to an external URL
+rather than to an internal glossary.
+
+\item[sample-fmt.tex] Provides text-block commands associated
+with entries in order to use \cs{glsxtrfmt}.
+
+\item[sample-alias.tex] Uses the \gloskey{alias} key.
+(See \sectionref{sec:alias}.)
+
+\item[sample-alttree.tex] Uses the \sty{glossaries-extra-stylemods}
+package with the \glostyle{alttree} style (see \sectionref{sec:stylemods}).
+
+\item[sample-alttree-sym.tex] Another \glostyle{alttree} example
+that measures the symbol widths.
+
+\item[sample-alttree-marginpar.tex] Another \glostyle{alttree} example
+that puts the \gls{numberlist} in the margin.
+
+\item[sample-onthefly.tex] Using on-the-fly commands. Terms with
+accents must have the \gloskey{name} key explicitly set.
+
+\item[sample-onthefly-xetex.tex] Using on-the-fly commands
+with \XeLaTeX. Terms with UTF-8 characters don't need to
+have the \gloskey{name} key explicitly set. Terms that contain
+commands must have the \gloskey{name} key explicitly set
+with the commands removed from the label.
+
+\item[sample-onthefly-utf8.tex] Tries to emulate the previous
+sample file for use with \LaTeX\ through the starred version
+of \ics{GlsXtrEnableOnTheFly}. This is a bit iffy and may not
+always work. Terms that contain commands must have the
+\gloskey{name} key explicitly set with the commands removed from
+the label.
+
+\item[sample-accsupp.tex] Integrate \sty{glossaries-accsupp}.
+
+\item[sample-prefix.tex] Integrate \sty{glossaries-prefix}.
+
+\item[sample-suppl-main.tex] Uses \gloskey[glsadd]{thevalue} to
+reference a location in the supplementary file
+\texttt{sample-suppl.tex}.
+
+\item[sample-suppl-main-hyp.tex] A more complicated version to the
+above that uses the \sty{hyperref} package to reference a location
+in the supplementary file \texttt{sample-suppl-hyp.tex}.
+
+\end{description}
+
+\chapter{Multi-Lingual Support}
+\label{sec:lang}
+
+There's only one command provided by \styfmt{glossaries-extra}
+that you're likely to want to change in your document and that's
+\ics{abbreviationsname} (\sectionref{sec:pkgopts}) if you use
+the \pkgopt{abbreviations} package option to automatically
+create the glossary labelled \texttt{abbreviations}. If this
+command doesn't already exist, it will be defined to
+\qt{Abbreviations} if \sty{babel} hasn't been loaded, otherwise
+it will be defined as \cs{acronymname} (provided by
+\styfmt{glossaries}).
+
+You can redefine it in the usual way. For example:
+\begin{verbatim}
+\renewcommand*{\abbreviationsname}{List of Abbreviations}
+\end{verbatim}
+Or using \sty{babel} or \sty{polyglossia} captions hook:
+\begin{verbatim}
+\appto\captionsenglish{%
+ \renewcommand*{\abbreviationsname}{List of Abbreviations}%
+}
+\end{verbatim}
+
+Alternatively you can use the \gloskey[printglossary]{title}
+key when you print the list of abbreviations. For example:
+\begin{verbatim}
+\printabbreviations[title={List of Abbreviations}]
+\end{verbatim}
+or
+\begin{verbatim}
+\printglossary[type=abbreviations,title={List of Abbreviations}]
+\end{verbatim}
+
+The other fixed text commands are the diagnostic messages, which
+shouldn't appear in the final draft of your document.
+
+The \styfmt{glossaries-extra} package has the facility to load
+language modules (whose filename is in the form
+\texttt{glossariesxtr-}\meta{language}\texttt{.ldf}) if they exist,
+but won't warn if they don't. If \sty{glossaries-extra-bib2gls} is
+loaded via the \pkgopt{record} package option then the check for
+language resource files will additionally search for an associated
+language script file given by
+\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} where
+\meta{script} is the four letter script identifier, such as
+\texttt{Latn}, associated with the given dialect. There's no warning if the
+associated file isn't found. The script file is loaded after the
+dialect file.
+
+If you want to write your own language module, you just need to
+create a file called
+\texttt{glossariesxtr-}\meta{lang}\texttt{.ldf}, where \meta{lang}
+identifies the language or dialect (see the \sty{tracklang}
+package). For example, \texttt{glossariesxtr-french.ldf}.
+
+The simplest code for this file is:
+\begin{verbatim}
+\ProvidesGlossariesExtraLang{french}[2015/12/09 v1.0]
+
+\newcommand*{\glossariesxtrcaptionsfrench}{%
+ \def\abbreviationsname{Abr\'eviations}%
+}
+\glossariesxtrcaptionsfrench
+
+\ifcsdef{captions\CurrentTrackedDialect}
+{%
+ \csappto{captions\CurrentTrackedDialect}%
+ {%
+ \glossariesxtrcaptionsfrench
+ }%
+}%
+{%
+ \ifcsdef{captions\CurrentTrackedLanguage}
+ {%
+ \csappto{captions\CurrentTrackedLanguage}%
+ {%
+ \glossariesxtrcaptionsfrench
+ }%
+ }%
+ {}%
+}
+\end{verbatim}
+
+You can adapt this for other languages by replacing
+all instances of the language identifier \texttt{french} and
+the translated text \verb|Abr\'eviations| as appropriate.
+You can also use the \texttt{.ldf} file to provide rule
+blocks for a particular language for use with \gls{bib2gls}['s] custom
+sort rule. See \sectionref{sec:bib2glssty} for further details.
+
+This \texttt{.ldf} file then needs to be put somewhere on \TeX's
+path so that it can be found by \styfmt{glossaries-extra}.
+You might also want to consider uploading it to CTAN so that
+it can be useful to others. (Please don't send it to me. I already
+have more packages than I am able to maintain.)
+
+If you additionally want to provide translations for the diagnostic
+messages used when a glossary is missing, you need to redefine
+the following commands:
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningHead]
+\cs{GlsXtrNoGlsWarningHead}\marg{label}\marg{file}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningHead{\meta{label}}{\meta{file}}
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyStart]
+\cs{GlsXtrNoGlsWarningEmptyStart}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningEmptyStart
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyMain]
+\cs{GlsXtrNoGlsWarningEmptyMain}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningEmptyMain
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyNotMain]
+\cs{GlsXtrNoGlsWarningEmptyNotMain}\marg{label}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningEmptyNotMain{\meta{label}}
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningCheckFile]
+\cs{GlsXtrNoGlsWarningCheckFile}\marg{file}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningCheckFile{\meta{file}}
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningMisMatch]
+\cs{GlsXtrNoGlsWarningMisMatch}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningMisMatch
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningNoOut]
+\cs{GlsXtrNoGlsWarningNoOut}\marg{file}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningNoOut{\meta{file}}
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningTail]
+\cs{GlsXtrNoGlsWarningTail}
+\end{definition}
+This produces the following text in English:
+\begin{quote}
+\GlsXtrNoGlsWarningTail
+\end{quote}
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningBuildInfo]
+\cs{GlsXtrNoGlsWarningBuildInfo}
+\end{definition}
+This is advice on how to generate the glossary files.
+See the documented code (\texttt{glossaries-extra-code.pdf})
+for further details.
+
+\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningAutoMake]
+\cs{GlsXtrNoGlsWarningAutoMake}\marg{label}
+\end{definition}
+This is the message produced when the \pkgopt{automake} option
+is used, but the document needs a rerun or the shell escape
+setting doesn't permit the execution of the external application.
+This command also generates a warning in the transcript file.
+See the documented code for further details.
+
+\printglossaries
+\PrintIndex
+
+\end{document}