summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-01-26 22:52:39 +0000
committerKarl Berry <karl@freefriends.org>2016-01-26 22:52:39 +0000
commit8d88e6714a570bf2b598132718ae2beb4641c80b (patch)
tree6d627fdd2263e73984a523aeaacd6b0aca1c358e /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent9b9abe02f86c766295512f6699dac2b40de6968c (diff)
glossaries-extra (24jan15)
git-svn-id: svn://tug.org/texlive/trunk@39487 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex3718
1 files changed, 3718 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
new file mode 100644
index 00000000000..ac2400c853e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
@@ -0,0 +1,3718 @@
+\documentclass[report,inlinetitle,widecs]{nlctdoc}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\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{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}
+
+\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
+\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+
+\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*{\abbrstyle}[1]{\textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\category}[1]{\textsf{#1}\index{categories:>#1={\protect\sffamily#1}|main}}
+
+\newcommand*{\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}%
+}
+
+\setlength\marginparwidth{70pt}
+
+\begin{document}
+\MakeShortVerb{"}
+\DeleteShortVerb{\|}
+
+ \title{glossaries-extra.sty v1.0:
+ an extension to the glossaries package}
+ \author{Nicola L.C. Talbot\\[10pt]
+Dickimaw Books\\
+\url{http://www.dickimaw-books.com/}}
+
+ \date{2016-01-24}
+ \maketitle
+
+\begin{abstract}
+The \styfmt{glossaries-extra} package is an extension to the
+\sty{glossaries} package, providing additional features.
+Some of the features provided by this package are only available
+with \sty{glossaries} version 4.19 (or above).
+This document assumes familiarity with the \sty{glossaries} package.
+
+\end{abstract}
+
+\begin{important}
+Since \styfmt{glossaries-extra} internally loads the \sty{glossaries}
+package, you also need to have \sty{glossaries} installed and
+all the packages that \sty{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}
+
+
+\tableofcontents
+
+\chapter{Introduction}
+\label{sec:intro}
+
+The \sty{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.21 of the \styfmt{glossaries} package is
+the last version to incorporate new features. 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
+\sty{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} to restore the terminating full stop
+(period).
+
+\item \pkgopt[true]{noredefwarn} (suppress warnings when
+the \env{theglossary} environment and \cs{printglossary} are redefined while
+\sty{glossaries} is loading). To restore the warnings, use
+\pkgopt[false]{noredefwarn}. Note that this won't have any effect if
+the \sty{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}
+
+Examples:
+\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,
+\sty{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 \sty{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]{glossaries-extra}
+
+\makeglossaries
+
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+
+\begin{document}
+
+\gls{laser}
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+
+
+\section{New or Modified Package Options}
+\label{sec:pkgopts}
+
+If you haven't already loaded \sty{glossaries}, you can use any of
+the package options provided by \sty{glossaries} when you load
+\styfmt{glossaries-extra} and they will automatically be passed to
+\sty{glossaries} (which \styfmt{glossaries-extra} will load). If
+\sty{glossaries} has already been loaded, then those options will be
+passed to \ics{setupglossaries}, but remember that not all of the
+\sty{glossaries} package options may be used in that command.
+
+In addition to those options recognised by \sty{glossaries},
+there are some new ones provided by \styfmt{glossaries-extra}:
+
+\begin{description}
+\item[{\pkgopt{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 (not through \ics{glossariesextrasetup}) since the \sty{glossaries-accsupp}
+package must be loaded before \styfmt{glossaries-extra} if it's
+required.
+
+\item[{\pkgopt{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 \sty{glossaries}). You can switch this to a warning
+message (and ?? appearing in the text) with
+\pkgopt[warn]{undefaction}.
+
+\item[{\pkgopt{docdef}}] This is a boolean option, which indicates
+whether or not it's permitted for the command \ics{newglossaryentry}
+to be used in the
+\env{document} environment. The \sty{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 \sty{glossaries}
+package has in certain circumstances (for example, when using
+\qt{option~1}). See the \sty{glossaries} user manual for further details.
+
+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}.
+
+\item[{\pkgopt{nomissingglstext}}] This is a boolean option.
+If true, this will suppress 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[{\pkgopt{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} key in any
+entries. To force it off, even if you use the \gloskey{see}, you
+need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
+
+\item[{\pkgopt{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}
+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 \sty{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 \sty{glossaries}
+package's \pkgopt{acronymlists} option (or associated commands)
+as the abbreviation mechanism is handled differently with
+\styfmt{glossaries-extra}.
+
+\item[{\pkgopt{symbols}}] This is passed to \sty{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.
+
+\item[{\pkgopt{numbers}}] This is passed to \sty{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}
+
+\item[{\pkgopt{shortcuts}}] Unlike the \sty{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 \sty{glossaries} package for acronyms (such as \cs{ac}).
+
+\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 \sty{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 \sty{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}):
+define all the shortcut commands.
+
+\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} option may only be used in the preamble.
+
+\section{Modifications to Existing Commands or Styles}
+\label{sec:modifications}
+
+The commands used by \sty{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 \cs{newglossaryentry} command has a new key called
+\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.
+
+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}.)
+
+\subsection{Entry Indexing}
+\label{sec:wrglossary}
+
+The \styfmt{glossaries-extra} package provides an extra key for
+commands like \cs{gls} and \cs{glstext} called
+\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 \sty{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.
+
+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.)
+
+The value of the \gloskey{see} key is now saved
+as a field. This isn't the case with \sty{glossaries}, where
+the \gloskey{see} attribute 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 document environment, but it's still
+best to define entries in the preamble, and the \gloskey{see} key
+still can't work before the file has been opened by
+\cs{makeglossaries}.
+
+\subsection{Entry Display Style Modifications}
+\label{sec:entryfmtmods}
+
+Recall from the \sty{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 \cs{gls} (but not commands like
+\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 \sty{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.
+
+The \cs{glspostlinkhook} provided by the \sty{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.
+
+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.)
+
+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.
+
+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}.
+
+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 \sty{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}.)
+\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{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).
+
+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.
+
+\subsection{Entry Counting Modifications}
+\label{sec:entrycountmods}
+
+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}.
+
+\subsection{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
+\sty{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 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 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 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
+\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 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 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 \sty{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.
+
+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 the last three problems listed
+above, but still doesn't fix the first two.
+
+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.
+
+\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}
+
+\subsection{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}).
+If you want to restore the generic acronym function provided
+by \sty{glossaries} you need to use
+\begin{definition}[\DescribeMacro\RestoreAcronyms]
+\cs{RestoreAcronyms}
+\end{definition}
+but be careful using this if you also want abbreviations as
+they will clash if you attempt to use them in the same glossary as
+generic acronyms from the \sty{glossaries} package.
+
+\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 \sty{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}.
+
+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}.
+
+\subsection{Glossary Style Modifications}
+\label{sec:glosstylemods}
+
+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 commands \ics{glossentryname} and \ics{glossentrydesc} are
+modified to take into account the \catattr{glossname} and
+\catattr{glossdesc} 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.
+
+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.
+
+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}.
+
+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.)
+\end{important}
+
+\chapter{Abbreviations}
+\label{sec:abbreviations}
+
+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 \sty{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 \sty{glossaries}
+package is redefined to use
+\cs{newabbreviation} with the \gloskey{category} set to
+\texttt{acronym}. If you want to restore the original behaviour of
+acronyms (as implemented by the \sty{glossaries} package's
+\cs{newacronym}, \ics{setacronymstyle} and \ics{newacronymstyle})
+you need to use
+\begin{definition}[\DescribeMacro\RestoreAcronyms]
+\cs{RestoreAcronyms}
+\end{definition}
+However, if you do this take care not to mix acronyms with other
+types of entries within the same glossary. (You may also need to
+redefine \ics{acronymtype}.)
+
+The \cs{newabbreviation} command is superficially similar to the
+\sty{glossaries} package's \cs{newacronym} but you can apply
+different styles to different categories. The default style is
+\abbrstyle{short} 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 \sty{glossaries} package, although they may produce similar
+results.)
+
+The short form is displayed within commands like \cs{gls} using
+\begin{definition}[\DescribeMacro\glsfirstabbrvfont]
+\cs{glsfirstabbrvfont}\marg{short-form}
+\end{definition}
+on \gls{firstuse} and
+\begin{definition}[\DescribeMacro\glsabbrvfont]
+\cs{glsabbrvfont}\marg{short-form}
+\end{definition}
+for subsequent use.
+
+\begin{important}
+These commands (\cs{glsfirstabbrvfont} and \cs{glsabbrvfont}) are
+reset by the abbreviation styles and whenever an abbreviation is
+used by commands like \cs{gls} (but not by commands like
+\ics{glsentryshort}) so don't try redefining them outside of an
+abbreviation style.
+\end{important}
+
+If you use the \abbrstyle{long-short} style,
+\cs{glsabbrvfont} is redefine to use
+\begin{definition}[\DescribeMacro\glsabbrvdefaultfont]
+\cs{glsabbrvdefaultfont}\marg{text}
+\end{definition}
+whereas the \abbrstyle{long-short-sc} style redefines
+\cs{glsabbrvfont} to use \cs{glsxtrscfont}. If you want to use a different
+font-changing command you can either redefine \cs{glsabbrvdefaultfont} and
+use one of the base styles, such as \abbrstyle{long-short}, or
+define a new style in a similar manner to the \qt{sc}, \qt{sm}
+or \qt{em} styles.
+
+All predefined abbreviation styles redefine \cs{glsfirstabbrvfont}
+to use
+\begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont]
+\cs{glsfirstabbrvdefaultfont}\marg{short-form}
+\end{definition}
+By default, this just does \cs{glsabbrvfont}\marg{short-form}
+so the \gls{firstuse} format matches the subsequence use format
+for the short form.
+
+The commands that display the full form for abbreviations use
+\cs{glsfirstabbrvfont} to display the short form and
+\begin{definition}[\DescribeMacro\glsfirstlongfont]
+\cs{glsfirstlongfont}\marg{long-form}
+\end{definition}
+to display the long form. As with \ics{glsabbrvfont}, this command
+is changed by all styles. Currently all predefined abbreviation
+styles provided by \styfmt{glossaries-extra} redefine
+\cs{glsfirstlongfont} to use
+\begin{definition}[\DescribeMacro\glsfirstlongdefaultfont]
+\cs{glsfirstlongdefaultfont}\marg{long-form}
+\end{definition}
+You can redefine this command if you want to change the font used by
+the long form on \gls{firstuse} for all your abbreviations, or you can
+define your own abbreviation style that provides a different format
+for only those abbreviations defined with that style.
+
+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} or
+\abbrstyle{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}.
+
+\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} and \abbrstyle{short} 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
+\cs{RestoreAcronyms} (see \sectionref{sec:acronymmods}).
+
+Abbreviations can be used with the standard \sty{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}.)
+
+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} 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}). This defines the commands listed in
+\tableref{tab:abbrshortcuts}.
+
+\begin{table}[htbp]
+\caption{Abbreviation Shortcut Commands}
+\label{tab:abbrshortcuts}
+\centering
+\begin{tabular}{ll}
+\bfseries Shortcut & \bfseries Equivalent Command\\
+\ics{ab} & \ics{cgls}\\
+\ics{abp} & \ics{cglspl}\\
+\ics{as} & \ics{glsxtrshort}\\
+\ics{asp} & \ics{glsxtrshortpl}\\
+\ics{al} & \ics{glsxtrlong}\\
+\ics{alp} & \ics{glsxtrlongpl}\\
+\ics{af} & \ics{glsxtrfull}\\
+\ics{afp} & \ics{glsxtrfullpl}\\
+\ics{As} & \ics{Glsxtrshort}\\
+\ics{Asp} & \ics{Glsxtrshortpl}\\
+\ics{Al} & \ics{Glsxtrlong}\\
+\ics{Alp} & \ics{Glsxtrlongpl}\\
+\ics{Af} & \ics{Glsxtrfull}\\
+\ics{Afp} & \ics{Glsxtrfullpl}\\
+\ics{AS} & \ics{GLSxtrshort}\\
+\ics{ASP} & \ics{GLSxtrshortpl}\\
+\ics{AL} & \ics{GLSxtrlong}\\
+\ics{ALP} & \ics{GLSxtrlongpl}\\
+\ics{AF} & \ics{GLSxtrfull}\\
+\ics{AFP} & \ics{GLSxtrfullpl}\\
+\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).
+
+\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 \qt{sc} styles all use
+\begin{definition}[\DescribeMacro\glsxtrscfont]
+\cs{glsxtrscfont}\marg{text}
+\end{definition}
+which is defined as
+\begin{verbatim}
+\newcommand*{\glsxtrscfont}[1]{\textsc{#1}}
+\end{verbatim}
+The default plural suffix for the short form is set to
+\begin{definition}[\DescribeMacro\glsxtrscsuffix]
+\cs{glsxtrscsuffix}
+\end{definition}
+This just defined as
+\begin{verbatim}
+\newcommand*{\glsxtrscsuffix}{\glstextup{\glspluralsuffix}}
+\end{verbatim}
+The \ics{glstextup} command is provided by \sty{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 \qt{sm} styles all use
+\begin{definition}[\DescribeMacro\glsxtrsmfont]
+\cs{glsxtrsmfont}\marg{text}
+\end{definition}
+This is defined as:
+\begin{verbatim}
+\newcommand*{\glsxtrsmfont}[1]{\textsmaller{#1}}
+\end{verbatim}
+If you want to use this, you must explicitly load the \sty{relsize}
+package which defines the \ics{textsmaller} command. 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 to upper case:
+\begin{verbatim}
+\renewcommand*{\glsxtrsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}}
+\end{verbatim}
+The default plural suffix for the short form is set to
+\begin{definition}[\DescribeMacro\glsxtrsmsuffix]
+\cs{glsxtrsmsuffix}
+\end{definition}
+This just does \ics{glspluralsuffix}.
+
+The \qt{em} styles all redefine \ics{glsabbrvfont} to use
+\ics{emph}. This is done explicitly and not through a helper
+command such as \cs{glsxtrscfont}.
+
+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}
+
+\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[\abbrstyle{short}]
+This only displays the short form on \gls{firstuse}. The \gloskey{name}
+is set to the short form. 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[\abbrstyle{short-sc}]
+Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{short-sm}]
+Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{short-em}]
+Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{short-desc}]
+Like the \abbrstyle{short} style, but the \gloskey{name} is set to
+the full form and the \gloskey{description} must be supplied by the
+user. You may prefer to use the \abbrstyle{short} 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[\abbrstyle{short-sc-desc}]
+Like \abbrstyle{short} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{short-sm-desc}]
+Like \abbrstyle{short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{short-em-desc}]
+Like \abbrstyle{short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{long-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{name} is set to the long form and 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[\abbrstyle{long-desc-sc}]
+Like the \abbrstyle{long-desc} style but the short form (accessed
+through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{long-desc-sm}]
+Like \abbrstyle{long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{long-desc-em}]
+Like \abbrstyle{long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{long}]
+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-desc} style, but the \gloskey{name}
+is set to the short form and the \gloskey{description} is set to the
+long form.
+
+\item[\abbrstyle{long-sc}]
+Like the \abbrstyle{long} style but the short form (accessed
+through commands like \ics{glsxtrshort}) use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{long-sm}]
+Like \abbrstyle{long} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{long-em}]
+Like \abbrstyle{long} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\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[\abbrstyle{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{name}
+is set to the short form. The
+\gloskey{description} is set to the long form. The long and short
+forms are separated by \cs{glsxtrfullsep}.
+
+\item[\abbrstyle{long-short-sc}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{long-short-sm}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{long-short-em}]
+Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{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{description} must be supplied by the user.
+The long and short forms are separated by \cs{glsxtrfullsep}.
+
+\item[\abbrstyle{long-short-sc-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{long-short-sm-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{long-short-em-desc}]
+Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{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}
+is set to the short form. The
+\gloskey{description} is set to the long form.
+The short and long forms are separated by \cs{glsxtrfullsep}.
+
+\item[\abbrstyle{short-sc-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{short-sm-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{short-em-long}]
+Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{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}.
+
+\item[\abbrstyle{short-sc-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{short-sm-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{short-em-long-desc}]
+Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{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.
+
+\item[\abbrstyle{footnote-sc}]
+Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{footnote-sm}]
+Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{footnote-em}]
+Like \abbrstyle{footnote} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\item[\abbrstyle{postfootnote}]
+This is similar to the \abbrstyle{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.
+
+\item[\abbrstyle{postfootnote-sc}]
+Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrscfont}.
+
+\item[\abbrstyle{postfootnote-sm}]
+Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{glsxtrsmfont}.
+
+\item[\abbrstyle{postfootnote-em}]
+Like \abbrstyle{postfootnote} but redefines \cs{glsabbrvfont} to
+use \ics{emph}.
+
+\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}
+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 \sty{glossaries} package's
+\ics{newacronymstyle} command.
+
+\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 \sty{glossaries}
+(using \ics{RestoreAcronyms}). The acronym styles from the
+\sty{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}%
+ (\protect\glsfirstabbrvfont{\the\glsshorttok})},%
+ firstplural={\protect\glsfirstlongfont{\the\glslongpltok}%
+ \protect\glsxtrfullsep{\the\glslabeltok}%
+ (\protect\glsfirstabbrvfont{\the\glsshortpltok})},%
+ plural={\protect\glsabbvfont{\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 \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{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 \sty{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 \sty{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}.)
+
+There are two other registers available that are defined by
+\sty{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{footnote-sc} and \abbrstyle{footnote-sm}
+styles both simply use
+\begin{verbatim}
+\GlsXtrUseAbbrStyleSetup{footnote}
+\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}
+
+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}
+
+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}{\glspluralsuffix}%
+ \renewcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{##1}}%
+ \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvdefaultfont{##1}}%
+ \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}%
+ \renewcommand*{\glsxtrfullformat}[2]{%
+ \glsfirstabbrvfont{\glsaccessshort{##1}}##2\glsxtrfullsep{##1}%
+ (\glsfirstlongfont{\glsaccesslong{##1}})%
+ }%
+ \renewcommand*{\glsxtrfullplformat}[2]{%
+ \glsfirstabbrvfont{\glsaccessshortpl{##1}}##2\glsxtrfullsep{##1}%
+ (\glsfirstlongfont{\glsaccesslongpl{##1}})%
+ }%
+ \renewcommand*{\Glsxtrfullformat}[2]{%
+ \glsfirstabbrvfont{\Glsaccessshort{##1}}##2\glsxtrfullsep{##1}%
+ (\glsfirstlongfont{\glsaccesslong{##1}})%
+ }%
+ \renewcommand*{\Glsxtrfullplformat}[2]{%
+ \glsfirstabbrvfont{\Glsaccessshortpl{##1}}##2\glsxtrfullsep{##1}%
+ (\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{short-sc-long} style has the
+following in \meta{fmts}:
+\begin{verbatim}
+ \GlsXtrUseAbbrStyleFmts{short-long}%
+ \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}%
+ \renewcommand*{\glsabbrvfont}[1]{\glsxtrscfont{##1}}%
+\end{verbatim}
+and the \abbrstyle{short-sm-long} style has:
+\begin{verbatim}
+ \GlsXtrUseAbbrStyleFmts{short-long-desc}%
+ \renewcommand*{\glsabbrvfont}[1]{\glsxtrsmfont{##1}}%
+ \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}%
+\end{verbatim}
+
+The simplest examples of creating a new style based on an
+existing style are the \qt{em} styles, such as the
+\abbrstyle{short-em-long} style, which is defined as:
+\begin{verbatim}
+\newabbreviationstyle
+{short-em-long}% label
+{% setup
+ \GlsXtrUseAbbrStyleSetup{short-long}%
+}%
+{% fmts
+ \GlsXtrUseAbbrStyleFmts{short-long}%
+ \renewcommand*{\glsabbrvfont}[1]{\emph{##1}}%
+}
+\end{verbatim}
+
+\chapter{Entries in Sectioning Titles, Headers and Contents}
+\label{sec:headtitle}
+
+The \sty{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}
+
+To get around all these problems, the \sty{glossaries} user manual
+recommends using the expandable non-hyperlink commands, like
+\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}. If you don't like this
+change, you can restore their former definitions using
+\begin{definition}[\DescribeMacro\glsxtrRevertMarks]
+\cs{glsxtrRevertMarks}
+\end{definition}
+In this case, you'll have to use the \sty{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}
+
+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=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.)
+
+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}
+
+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 \cs{newglossaryentry} (or commands that
+internally use \cs{newglossaryentry} such as \cs{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.
+
+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[\catattr{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}.)
+
+\item[\catattr{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[\catattr{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[\catattr{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.)
+
+\item[\catattr{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}.
+
+\item[\catattr{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.
+
+\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[\catattr{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.
+
+\item[\catattr{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{The \catattr{aposplural} attribute trumps
+the \catattr{noshortplural} attribute.}
+
+\item[\catattr{headuc}] If this attribute is set to \qt{true},
+commands like \ics{glsfmtshort} will use the upper case version
+in the page headers.
+
+\item[\catattr{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[\catattr{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 \sty{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[\catattr{glossdesc}] The \ics{glossentrydesc} command
+(used in the predefined glossary styles) is modified by
+\styfmt{glossaries-extra} to check for this attribute.
+If the attribute is set to \qt{firstuc}, the first letter
+of the description will be converted to upper case (using
+\ics{Glsentrydesc}). If the attribute is set to \qt{title},
+the title casing command \ics{capitalisewords} (provided
+by \sty{mfirstuc}) is used on the name. Any other values of
+this attribute are ignored.
+
+\item[\catattr{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[\catattr{indexname}] If set, the \cs{glsxtrpostnamehook} hook
+used at the end of \ics{glossentyname}
+will index the entry using \ics{index}. See
+\sectionref{sec:autoindex} for further details.
+
+\item[\catattr{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.
+
+\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:
+\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}
+
+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{Entry Counting}
+\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}).
+
+You may now 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 \sty{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}) unlike the acronym shortcut
+\ics{ac} which uses \cs{gls}.
+
+All upper case versions (not provided by \sty{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.
+
+[TODO: work out what to do about other commands such
+as \verb|\glsdisp| and \verb|\glstext|.]
+
+Just using \sty{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.
+
+\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}.
+
+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.
+
+The internal macro used by the \sty{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}. 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 \sty{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{Supplemental Packages}
+\label{sec:supplemental}
+
+The \sty{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} 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{desc} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessdesc]
+\cs{Glsaccessdesc}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{desc} 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{descplural} field.
+
+\begin{definition}[\DescribeMacro\Glsaccessdescplural]
+\cs{Glsaccessdescplural}\marg{label}
+\end{definition}
+This displays the value of the \gloskey{descplural} 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 \sty{glossaries} package for testing.
+
+\item[sample-mixture.tex] General entries, acronyms and initialisms
+all treated differently.
+
+\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).
+
+\item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting.
+
+\item[sample-onelink.tex] Using the per-unit entry counting
+to only have one hyperlink per entry per page.
+
+\item[sample-altmodifier.tex] Set the default options for
+commands like \cs{gls} and add an alternative modifier.
+
+\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}.
+
+\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
+\sty{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 if they exist, but won't warn if they don't.
+
+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}
+is the language name (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
+ }%
+ }%
+ {%
+ }%
+ \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.
+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}