From 5d714d9476cbb90b125ff14a9d764ad90bb7c2ed Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 24 Sep 2021 03:01:47 +0000
Subject: CTAN sync 202109240301

---
 .../latex/contrib/glossaries/glossaries-user.tex   | 10931 ++++++++++---------
 1 file changed, 5677 insertions(+), 5254 deletions(-)

(limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')

diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex
index f4dc52e08e..cefb8116a9 100644
--- a/macros/latex/contrib/glossaries/glossaries-user.tex
+++ b/macros/latex/contrib/glossaries/glossaries-user.tex
@@ -198,7 +198,7 @@
 
 \newcommand{\gallery}[2]{\href{https://www.dickimaw-books.com/gallery/#1}{#2}}
 \newcommand{\galleryurl}[1]{\gallery{#1}{\nolinkurl{https://www.dickimaw-books.com/gallery/#1}}}
-\newcommand{\gallerytopic}[1]{\galleryurl{\##1}}
+\newcommand{\gallerytopic}[1]{\gallery{\##1}{\styfmt{#1} gallery}}
 
 \newcommand*{\bibglsgallery}[2][\gallerytitle]{%
  \def\gallerytitle{#2}%
@@ -501,6 +501,17 @@ user2={sanitization\protect\iterm{sanitize}}%
   description={An alphabet consisting of \glspl{nonlatinchar}.}
 }
 
+\newglossaryentry{UTF-8}{%
+  name={UTF-8\itermdef{UTF-8}},
+  text={UTF-8},
+  sort={UTF-8},
+  description={A variable-width character encoding. This means that
+some characters are represented by more that one byte. \XeLaTeX\ and
+\LuaLaTeX\ treat the multi-byte sequence as a single token, but the
+older \LaTeX\ formats have single-byte tokens, which causes
+complications. Related blog article: \href{https://www.dickimaw-books.com/blog/binary-files-text-files-and-file-encodings/}{Binary Files, Text Files and File Encodings}.}
+}
+
 \newglossaryentry{glossaries-extra}{%
   name={\styfmt{glossaries-extra}},
   sort={glossaries-extra},
@@ -671,11 +682,11 @@ and~\hyperlink{option#2}{#2}}
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{User Manual for glossaries.sty v4.46}
+ \title{User Manual for glossaries.sty v4.47}
  \author{Nicola L.C. Talbot\\%
   \href{http://www.dickimaw-books.com/contact}{\nolinkurl{dickimaw-books.com/contact}}}
 
- \date{2020-03-19}
+ \date{2021-09-20}
  \maketitle
 
 \begin{abstract}
@@ -750,18 +761,13 @@ how to adjust the settings.
 \end{important}
 
 \noindent
-The \styfmt{glossaries} bundle comes with the following documentation:
+The \styfmt{glossaries} bundle includes the following documentation:
 \begin{description}
 \item[\url{glossariesbegin.pdf}] 
 If you are a complete beginner, start with 
 \htmldoc{The glossaries package: a guide for
 beginners}{glossariesbegin}.
 
-\item[\url{glossary2glossaries.pdf}] 
-If you are moving over from the obsolete \sty{glossary} package,
-read \htmldoc{Upgrading from the glossary package to the
-glossaries package}{glossary2glossaries}.
-
 \item[glossaries-user.pdf]
 This document is the main user guide for the \styfmt{glossaries}
 package.
@@ -769,9 +775,7 @@ package.
 \item[\url{glossaries-code.pdf}]
 Advanced users wishing to know more about the inner workings of all the
 packages provided in the \styfmt{glossaries} bundle should read
-\qt{Documented Code for glossaries v4.46}.
-
-\item[INSTALL] Installation instructions.
+\qt{Documented Code for glossaries v4.47}.
 
 \item[CHANGES] Change log.
 
@@ -785,7 +789,7 @@ Related resources:
 \item \href{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries}
 FAQ}
 
-\item \gallerytopic{glossaries}{\styfmt{glossaries} gallery}
+\item \gallerytopic{glossaries}
 
 \item
 \gallery{glossaries-styles/}{a summary of all glossary styles provided by \styfmt{glossaries} and
@@ -993,7 +997,7 @@ options are specific to \gls{glossaries-extra}. Other options are
 passed to the base \styfmt{glossaries} package.
 
 \begin{xtr}
-In this document, commands and options displayed in teal, such as
+In this user manual, commands and options displayed in teal, such as
 \xtrcs{newabbreviation} and \pkgopt*{stylemods}, are only available with 
 the \gls{glossaries-extra} package. There are also some commands and options (such
 as \cs{makeglossaries} and \pkgopt{symbols}) that are provided by the
@@ -1022,7 +1026,7 @@ hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
 you click on the word \qt{\gls{xindy}} you'll be taken to the entry
 in the glossary where there's a brief description of
 the term \qt{\gls*{xindy}}. This is the way the \styfmt{glossaries}
-mechanism works. An \gls{indexingapp} is used to generated the
+mechanism works. An \gls{indexingapp} is used to generate the
 sorted list of terms. The \glspl{indexingapp} are \gls{cli} tools,
 which means they can be run directly from a command prompt or terminal, or can
 be integrated into some text editors, or you can use a build tool
@@ -1038,9 +1042,6 @@ The remainder of this introductory section covers the following:
 \item \sectionref{sec:indexingoptions} lists the available indexing
 options.
 
-\item \sectionref{sec:samples} lists the sample documents provided 
-with this package.
-
 \item \sectionref{sec:lipsum} lists the dummy glossary files that
 may be used for testing. 
 
@@ -1053,6 +1054,9 @@ wish to write in a language other than English.
 
 \end{itemize}
 
+There are some sample documents provided with this package. They are
+described in \sectionref{sec:samples}.
+
 \section{Indexing Options}
 \label{sec:indexingoptions}
 
@@ -1173,6 +1177,7 @@ format. \cs{newglossaryentry} should not be used explicitly.\par
 
 \optionsec[\TeX]{TeX}
 
+This option isn't generally recommended for reasons given below.
 Example Document:
 \begin{verbatim}
 \documentclass{article}
@@ -1198,7 +1203,8 @@ and load it in the preamble with \ics{loadglsentries} (\emph{after}
 This option doesn't require an external \gls{indexingapp} but, with
 the default alphabetic sorting, it's very slow with severe limitations.
 If you want a sorted list, it doesn't work well for
-\glspl{exlatinalph} or \glspl{nonlatinalph}.  However, if you use
+\glspl{exlatinalph} or \glspl{nonlatinalph} and there's no guarantee
+that it will work with \gls{UTF-8}.  However, if you use
 the \pkgopt[false]{sanitizesort} package option (the default for
 Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\
 accent commands} will be ignored, so if an entry's name is set to
@@ -1232,6 +1238,7 @@ This option is not suitable for hierarchical glossaries and does
 not form ranges in the \glspl{numberlist}. If you really can't use an
 \gls{indexingapp} consider using \opt{5} instead.
 
+Summary:
  \begin{enumerate}
    \item Add 
 \begin{verbatim}
@@ -1284,8 +1291,8 @@ This option uses a~\gls{cli} application called \gls{makeindex} to sort
 the entries. This application comes with all modern \TeX\ distributions, 
 but it's hard-coded for the non-extended \gls{latinalph}. It can't
 correctly sort accent commands (such as \cs{'} or \cs{c}) and fails
-with UTF-8 characters, especially for any sort values that start
-with a UTF-8 character (as it separates the octets resulting in an
+with \gls{UTF-8} characters, especially for any sort values that start
+with a \gls{UTF-8} character (as it separates the octets resulting in an
 invalid file encoding). This process involves making \LaTeX\ write
 the glossary information to a temporary file which \gls{makeindex}
 reads.  Then \gls{makeindex} writes a~new file containing the code
@@ -1319,6 +1326,7 @@ documentation for further details. See also the
 \sectionref{sec:samplessort}.
 \end{xtr}
 
+Summary:
    \begin{enumerate}
     \item If you want to use \gls{makeindex}['s] \mkidxopt{g} option
     you must change the quote character using \ics{GlsSetQuote}. For example:
@@ -1504,6 +1512,7 @@ of use\slash definition with \opt1. See the \gls{glossaries-extra}
 documentation for further details.
 \end{xtr}
 
+Summary:
 \begin{enumerate}
      \item Add the \pkgopt{xindy} option to the \styfmt{glossaries}
 package option list:
@@ -1668,7 +1677,7 @@ or (with at least \gls{glossaries-extra} v1.37 and \gls{bib2gls} v1.8):
 The \pkgopt+{nameref}{record} option is the best method.
 
 (It's possible to use a hybrid of this method and \optsor23 with
-\pkgopt+{alsoindex}{record} but in general there is little need
+\pkgopt+{hybrid}{record} but in general there is little need
 for this and it complicates the build process.)
 
 Each resource set is loaded with \ics*{GlsXtrLoadResources}\oarg{options}.
@@ -1736,6 +1745,38 @@ Repository, which provides more extensive language support than
 numerical value it will attempt to form ranges otherwise it will
 simply list the locations.
 
+Summary:
+\begin{enumerate}
+  \item Use \gls{glossaries-extra} with the \pkgopt+{record} package
+option:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+
+  \item Use \cs*{GlsXtrLoadResources} to identify the \filetype{bib}
+file(s) and \gls{bib2gls} options:
+\begin{verbatim}
+\GlsXtrLoadResources[src={terms.bib,abbreviations.bib},sort=en]
+\end{verbatim}
+
+ \item Put
+\begin{alltt}
+\cs*{printunsrtglossary}
+\end{alltt}
+where you want your list of entries to appear. Alternatively to
+display all glossaries use the iterative command:
+\begin{alltt}
+\cs*{printunsrtglossaries}
+\end{alltt}
+
+\item Run \LaTeX\ on your document.
+
+\item Run \gls{bib2gls} with just the document base name.
+
+\item Run \LaTeX\ on your document.
+
+\end{enumerate}
+
 See \bibglsbegin\ or the \gls{bib2gls} user manual for further
 details of this method, and
 also \href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating
@@ -1766,7 +1807,11 @@ Example document:
 
 This method is best used with the package option \pkgopt[none]{sort}
 (as shown above). There's no \qt{activation} command (such as \cs{makeglossaries}
-for \optsand23).
+for \optsand23). In general it's best to use a style that doesn't
+show letter group headings. If you do want letter headings then you
+must ensure that you have defined your entries in alphabetical
+order, and use \XeLaTeX\ or \LuaLaTeX\ if you require \gls{UTF-8} letter
+groups.
 
 All entries must be defined before the glossary is displayed
 (preferably in the preamble) in the required order, and child 
@@ -2279,6 +2324,44 @@ For example:
   description={eu, nulla}}
 \end{verbatim}
 
+\item[example-glossaries-longchild.tex] (New to v4.47.) These entries all 
+have long descriptions and there are some child entries. For example:
+\begin{verbatim}
+\newglossaryentry{longsedmattis}{name={sed mattis},
+ description={erat sit amet dolor sit amet, consectetuer adipiscing elit. 
+ Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis. 
+ Curabitur dictum gravida mauris.}}
+
+\newglossaryentry{longgravida}{parent={longsedmattis},name={gravida},
+ description={malesuada libero, nonummy eget, consectetuer id, vulputate a, 
+ magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique
+senectus et netus et malesuada fames ac turpis egestas. Mauris ut
+leo.}}
+\end{verbatim}
+
+\item[example-glossaries-childmultipar.tex] (New to v4.47.) This
+consists of parent entries with single paragraph descriptions and
+child entries with multi-paragraph descriptions. Some entries have
+the \gloskey{user1} key set to the name of an image file provided by
+the \sty{mwe} package. For example:
+\begin{verbatim}
+\newglossaryentry{hiersedmattis}{name={sed mattis},user1={example-image},
+ description={Erat sit amet dolor sit amet, consectetuer adipiscing elit. 
+ Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur
+dictum gravida mauris. Ut pellentesque augue sed urna. Vestibulum
+diam eros, fringilla et, consectetuer eu, nonummy id, sapien. Nullam
+at lectus. In sagittis ultrices mauris. Curabitur malesuada erat sit
+amet massa. Fusce blandit. Aliquam erat volutpat.}}
+
+\longnewglossaryentry{hierloremi-ii}
+{name={lorem 1--2},parent={hiersedmattis}}%
+{%
+Lorem ipsum ...
+
+Nam dui ligula...
+}
+\end{verbatim}
+
 \item[example-glossaries-cite.tex] These entries use the
 \gloskey{user1} key to store a citation key (or comma-separated list
 of citation keys). The citations are defined in \texttt{xampl.bib},
@@ -2352,7 +2435,7 @@ This means that with \optsor34 you are not restricted to the A,
 \ldots, Z letter groups.  If you want to use \gls*{xindy}, remember
 to use the \pkgopt{xindy} package option. For example:
 \begin{verbatim}
-\documentclass[frenchb]{article}
+\documentclass[french]{article}
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage{babel}
@@ -2639,7 +2722,7 @@ if you have glossary entries that contain
 details on \gls{xindy}, and see the \gls{bib2gls} user manual for
 further details of that application.
 
-\subsubsection{Creating a New Language Module}
+\subsection{Creating a New Language Module}
 \label{sec:newlang}
 
 The \styfmt{glossaries} package now uses the \sty{tracklang} package
@@ -2793,10 +2876,10 @@ language file and make the appropriate changes, for example:
 
 If the translations includes \glspl{nonlatinchar}, it's necessary to
 provide code that's independent of the input encoding. Remember that
-while some users may use UTF-8, others may use Latin-1 or any other
+while some users may use \gls{UTF-8}, others may use Latin-1 or any other
 supported encoding, but while users won't appreciate you enforcing
-your preference on them, it's useful to provide a UTF-8 version for
-\XeLaTeX\ users.
+your preference on them, it's useful to provide a \gls{UTF-8} version for
+\XeLaTeX\ and \LuaLaTeX\ users.
 
 The \texttt{glossaries-irish.ldf} file provides this as follows:
 \begin{verbatim}
@@ -2842,7 +2925,7 @@ your root language label and \texttt{Irish} with the
 
 There are now two extra files: \nolinkurl{glossaries-irish-noenc.ldf}
 (no encoding information)
-and \nolinkurl{glossaries-irish-utf8.ldf} (UTF-8).
+and \nolinkurl{glossaries-irish-utf8.ldf} (\gls{UTF-8}).
 
 These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses
 \LaTeX\ accent commands:
@@ -2874,7 +2957,7 @@ These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses
 }
 \end{verbatim}
 whereas the \texttt{*-utf8.ldf} replaces the accent commands with
-the appropriate UTF-8 characters.
+the appropriate \gls{UTF-8} characters.
 
 
 \section{Generating the Associated Glossary Files}
@@ -3170,7 +3253,7 @@ For a complete list of options do \texttt{makeglossaries -{}-help}.
 \begin{important}
 When upgrading the \styfmt{glossaries} package, make sure you also
 upgrade your version of \gls{makeglossaries}. The current version is
-4.45.
+4.47.
 \end{important}
 
 \subsection{Using the makeglossaries-lite Lua Script}
@@ -3422,9 +3505,15 @@ for every time an entry has been referenced.
 If you need to gather labels for auto-completion, the
 \pkgopt{writeglslabels} package option will create a file containing
 the labels of all defined entries (regardless of whether or not the
-entry has been used in the document). The \gls{glossaries-extra}
+entry has been used in the document). As from v4.47, there is a
+similar option \pkgopt{writeglslabelnames} that writes both the
+label and name (separated by a tab).
+
+\begin{xtr}
+The \gls{glossaries-extra}
 package also provides \pkgopt+{atom}{docdef}, which will create the
 \filetype{glsdefs} file but will act like \pkgopt+{restricted}{docdef}.
+\end{xtr}
 
 \subsection{Bib2Gls}
 \label{sec:notedev.bib2gls}
@@ -3446,7 +3535,7 @@ not to run \gls{bib2gls}:
 \end{alltt}
 (It gets more complicated if both \ics*{glsxtr@resource} and
 \cs{@istfilename} are present as that indicates the hybrid
-\pkgopt+{alsoindex}{record} option.)
+\pkgopt+{hybrid}{record} option.)
 
 Remember that with \gls{bib2gls}, the entries will never be defined
 on the first \LaTeX\ call (because their definitions are contained
@@ -3817,7 +3906,8 @@ will create a file called \cs{jobname}\texttt{.}\filetype{glslabels} at the end
 of the document. This file simply contains a list of all defined
 entry labels (including those in any ignored glossaries). It's
 provided for the benefit of text editors that need to know labels
-for \Index{auto-completion}. (See also \gls{glossaries-extra}['s]
+for \Index{auto-completion}. If you also want the name, use
+\pkgopt{writeglslabelnames}. (See also \gls{glossaries-extra}['s]
 \pkgopt+{atom}{docdef} package option.)
 
 \begin{bib2gls}
@@ -3825,12 +3915,15 @@ Note that with \gls{bib2gls} the file will only contain the entries
 that \gls{bib2gls} has selected from the \filetype{bib} files.
 \end{bib2gls}
 
+\pkgoptsec{writeglslabelnames} Similar to the above but writes both
+the label and name (separated by a tab).
+
 \xtrpkgoptsec[value]{undefaction}
 
 The value may be one of:
 \begin{description}
  \item[\pkgoptfmt{error}] generate an error if a referenced entry is
-  undefined (default, and only available setting with just
+  undefined (default, and the only available setting with just
   \styfmt{glossaries});
  \item[\pkgoptfmt{warn}] only warn if a referenced entry is
   undefined (automatically activated with \opt4).
@@ -4252,7 +4345,7 @@ groups.
 
 \xtrpkgoptsec[list]{stylemods}
 
-Load the \sty{glossaries-extra-stylemods} package and patch the
+Load the \sty{glossaries-extra-stylemods} package, which patches the
 predefined styles. The \meta{list} argument is optional. If present,
 this will also load \styfmt{glossary-\meta{element}.sty} for each
 \meta{element} in the comma-separated \meta{list}.
@@ -4263,7 +4356,7 @@ this will also load \styfmt{glossary-\meta{element}.sty} for each
 \pkgoptsec[value]{seenoindex} Introduced in version 4.24, this option
 may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or
 \pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the
-cross-referenced entry using \cs{glsadd}. This means that if this
+cross-referenced entry using \ics{glssee}. This means that if this
 key is used in an entry definition before the relevant
 glossary file has been opened, the indexing can't be performed.
 Since this is easy to miss, the \styfmt{glossaries} package by
@@ -4362,17 +4455,30 @@ and \texttt{acronym} categories. (Instead of using the
 
 \xtrpkgoptsec[boolean]{indexcrossrefs}
 
-If \pkgoptfmt{true}, this will automatically index any
+If \pkgoptfmt{true}, this will automatically index (\ics{glsadd}) any
 cross-referenced entries that haven't been marked as used at the end
 of the document. Increases document build time. See
 \gls{glossaries-extra} manual for further details.
 
+\begin{bib2gls}
+Note that \gls{bib2gls} can automatically find dependent entries
+when it parses the \filetype{bib} file. Use the \xtrfont{selection} option to
+\ics*{GlsXtrLoadResources} to determine the selection of
+dependencies.
+\end{bib2gls}
+
 \xtrpkgoptsec[boolean]{autoseeindex}
 
 If \pkgoptfmt{true}, makes the \gloskey{see} and
 \xtrgloskey{seealso} keys automatically index the cross-reference
-when the entry is defined (default, and the only option with just
-the base \styfmt{glossaries} package).
+(with \ics{glssee}) when the entry is defined (default, and the only
+option with just the base \styfmt{glossaries} package).
+
+\begin{bib2gls}
+With \gls{bib2gls}, use the \xtrfont{selection} option to
+\ics*{GlsXtrLoadResources} to determine the selection of
+dependencies.
+\end{bib2gls}
 
 \xtrpkgoptsec[value]{record}
 
@@ -4388,10 +4494,11 @@ for \optsto13;
 
 \item[\pkgoptfmt{nameref}] like \pkgoptfmt{only} but provides extra
 information that allows the associated title to be used instead of
-the location number;
+the location number and provides better support for hyperlinked
+locations;
 
-\item[\pkgoptfmt{alsoindex}] a hybrid approach where \gls{bib2gls}
-is begin used to fetch entries from a \filetype{bib} file but
+\item[\pkgoptfmt{hybrid}] a hybrid approach where \gls{bib2gls}
+is used to fetch entries from a \filetype{bib} file but
 \gls{makeindex} or \gls{xindy} are used for the indexing. This
 requires a more complicated document build and isn't recommended.
 \end{description}
@@ -4415,9 +4522,10 @@ is indexed within the float before the caption.)
 
 This valueless option is primarily intended for use with
 \gls{bib2gls} and \sty{hyperref} allowing the page location
-hyperlink to the relevant point in the page (rather than the top of
-the page). Unexpected results will occur with other indexing
-methods. See \gls{glossaries-extra} manual for further details.
+hyperlink target to be set to the relevant point within the page
+(rather than the top of the page). Unexpected results will occur
+with other indexing methods. See \gls{glossaries-extra} manual for
+further details.
 
 \section{Sorting Options}
 \label{sec:pkgopts-sort}
@@ -4753,7 +4861,7 @@ with \gls*{makeindex} but may not work with \gls{xindy}.
 
 However even in unrestricted mode this option may not work with
 \gls*{xindy} as \gls*{xindy} uses language names that don't always
-correspond with \ics{babel}'s language names. (The
+correspond with \sty{babel}'s language names. (The
 \gls{makeglossaries} script applies mappings to assist you.)
 Note that you still need at least two \LaTeX\ runs to ensure the document
 is up-to-date with this setting.
@@ -5085,7 +5193,7 @@ of acronyms using:
 \end{definition}
 
 \begin{xtr}
-This option is incompatible with \gls{glossaries-extra}['s]
+This option and associated commands are incompatible with \gls{glossaries-extra}['s]
 abbreviation mechanism.
 \end{xtr}
 
@@ -5100,7 +5208,7 @@ Alternatively you can use:
 The \gls{glossaries-extra} package provides additional shortcuts.
 \end{xtr}
 
-\subsection{Deprecated Acronym Style Options}
+\section{Deprecated Acronym Style Options}
 \label{sec:pkgopts-old-acronym}
 
 The package options listed in this section are now deprecated but
@@ -5308,14 +5416,25 @@ unexpected results. If you try changing the sort option after you have
 started to define entries, you may get unexpected results.
 \end{important}
 
+\begin{xtr}
+With \gls{glossaries-extra}, use \ics*{glossariesextrasetup}
+instead.
+\end{xtr}
+
 \chapter{Setting Up}
 \label{sec:setup}
 
-In the preamble you need to indicate whether you want to use \opt1,
-\opt2 or \opt3. It's not possible to mix these options within
-a~document, although some combinations are possible with
-\gls*{glossaries-extra}. (For \optsand45 see the \gls{bib2gls} and 
-\gls{glossaries-extra} manuals.)
+In the preamble you need to indicate which method you want to use to
+generate the glossary (or glossaries). The available options with
+both \styfmt{glossaries} and \gls{glossaries-extra} are
+summarized in \sectionref{sec:indexingoptions}. This chapter
+documents \optsto13, which are provided by the base package. See the
+\gls{glossaries-extra} and \gls{bib2gls} manuals for the full
+documentation of the other options.
+
+If you don't need to display any glossaries, for example, if you are
+just using the \styfmt{glossaries} package to enable consistent
+formatting, then skip ahead to \sectionref{sec:newglosentry}.
 
 \section[Option 1]{\ifpdf\opt1\else Option 1\fi}
 \label{sec:setupopt1}
@@ -5371,8 +5490,8 @@ Note that if you have a custom \filetype{xdy} file created when using
 \end{important}
 
 The default name for the customised style file is given by
-\ics{jobname}\filetype{ist} (\opt2) or 
-\ics{jobname}\filetype{xdy} (\opt3). This name may be
+\ics{jobname}\texttt{.}\filetype{ist} (\opt2) or 
+\ics{jobname}\texttt{.}\filetype{xdy} (\opt3). This name may be
 changed using:
 \begin{definition}[\DescribeMacro{\setStyleFile}]
 \cs{setStyleFile}\marg{name}
@@ -5414,6 +5533,19 @@ See \sectionref{sec:numberlists} for further information about
 \chapter{Defining Glossary Entries}
 \label{sec:newglosentry}
 
+\begin{bib2gls}
+If you want to use \gls{bib2gls}, entries must be defined in
+\filetype{bib} files using the syntax described in the \gls{bib2gls}
+user manual.
+\end{bib2gls}
+
+Acronyms are covered in \sectionref{sec:acronyms} but they use the
+same underlying mechanism as all the other entries, so it's a good
+idea to read this chapter first. The keys provided for
+\cs{newglossaryentry} can also be used in the optional argument of
+\cs{newacronym}, although some of them, such as \gloskey{first} and
+\gloskey{plural}, interfere with the acronym styles.
+
 All glossary entries must be defined before they are used, so it is
 better to define them in the preamble to ensure this. In fact, some
 commands such as \cs{longnewglossaryentry}
@@ -5556,12 +5688,28 @@ is set to the same as the \gloskey{description} key.
 when using \ics{gls} (or one of its upper case variants). If this
 field is omitted, the value of the \gloskey{name} key is used.
 
+This key is automatically set by \cs{newacronym}. Although it is
+possible to override it by using \gloskey{text} in the optional
+argument of \cs{newacronym}, it will interfere with the acronym
+style and cause unexpected results.
+
 \item[{\gloskey{first}}] How the entry will appear in the document text
 on \firstuse\ with \ics{gls} (or one of its upper case
 variants). If this field is omitted, the value of the \gloskey{text}
 key is used. Note that if you use \ics{glspl}, \ics{Glspl},
 \ics{GLSpl}, \ics{glsdisp} before using \ics{gls}, the
-\gloskey{firstplural} value won't be used with \ics{gls}.
+\gloskey{first} value won't be used with \ics{gls}.
+
+You may prefer to use abbreviations (\sectionref{sec:acronyms})
+or the category post-link hook (\ics*{glsdefpostlink}) provided by
+\gls{glossaries-extra} if you would like to automatically append
+content on \firstuse\ in a consistent manner. See, for example,
+\gallery{index.php?label=sample-units}{Gallery: Units
+(\styfmt{glossaries-extra.sty})}.
+
+Although it is possible to use \gloskey{first} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results.
 
 \item[{\gloskey{plural}}] How the entry will appear in the document text
 when using \ics{glspl} (or one of its upper case variants).  If this
@@ -5569,6 +5717,11 @@ field is omitted, the value is obtained by appending
 \ics{glspluralsuffix} to the value of the \gloskey{text} field.  The
 default value of \ics{glspluralsuffix} is the letter \qt{s}.
 
+Although it is possible to use \gloskey{plural} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results. Use \gloskey{shortplural}
+instead, if the default value is inappropriate.
+
 \item[{\gloskey{firstplural}}] How the entry will appear in the
 document text on \firstuse\ with \ics{glspl} (or one of its
 upper case variants). If this field is omitted, the value is obtained
@@ -5579,6 +5732,11 @@ that if you use \ics{gls}, \ics{Gls}, \ics{GLS}, \cs{glsdisp} before
 using \ics{glspl}, the \gloskey{firstplural} value won't be used
 with \ics{glspl}.
 
+Although it is possible to use \gloskey{firstplural} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results. Use \gloskey{shortplural}
+and \gloskey{longplural} instead, if the default value is inappropriate.
+
 \importantpar
 Note: prior to version 1.13, the default value of 
 \gloskey{firstplural} was always taken by appending \qt{s} to the
@@ -5595,12 +5753,15 @@ symbol (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
 by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value
 is set to the same as the \gloskey{symbol} key.
 
-\item[{\gloskey{sort}}] This value indicates how this entry should
-be sorted. If omitted, the value is given
+\item[{\gloskey{sort}}] This value indicates the text to be used by
+the sort comparator when ordering all the entries.  If omitted, the value is given
 by the \gloskey{name} field unless one of the package options
-\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. In
-general, it's best to use the \gloskey{sort} key if the
-\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|).
+\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. 
+With \opt2 it's best to use the \gloskey{sort} key if the
+\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|)
+and with \optsand13, it's strongly recommended as the indexing may
+fail if you don't (see below).
+
 You can also override the \gloskey{sort} key by redefining
 \ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}).
 
@@ -5652,7 +5813,7 @@ Similarly if you use the \sty{inputenc} package:
 This is equivalent to
 \begin{alltt}
 \cs{newglossaryentry}\mgroup{elite}\mgroup{\%
-  name=i\mgroup{\mgroup{\'e}lite},
+  name=\mgroup{\mgroup{\'e}lite},
   description=\mgroup{select group of people},
   sort=elite
 }
@@ -5706,9 +5867,48 @@ this entry. Conversely, if you have used the package option
 for this entry with \gloskey{nonumberlist=false}.
 (See \sectionref{sec:numberlists}.)
 
-\item[{\gloskey{see}}] Cross-reference another entry. Using the
-\gloskey{see} key will \emph{automatically add this entry to the
-glossary}, but will not automatically add the cross-referenced entry.
+\item[{\gloskey{see}}]
+This key essentially provides a convenient shortcut that performs
+\begin{alltt}
+\cs{glssee}\oarg{tag}\marg{label}\marg{xr-label list}
+\end{alltt}
+after the entry has been defined. (See \sectionref{sec:crossref}.) 
+It was originally designed for synonyms that may not occur in the
+document text but needed to be included in the glossary in order to
+redirect the reader. Note that it doesn't index the cross-referenced
+entry (or entries) as that would interfere with their \glspl{numberlist}.
+
+\begin{important}
+Using the \gloskey{see} key will \emph{automatically add this entry
+to the glossary}, but will not automatically add the
+cross-referenced entry.
+\end{important}
+
+For example:
+\begin{verbatim}
+\newglossaryentry{courgette}{name={courgette},
+  description={variety of small marrow}}
+\newglossaryentry{zucchini}{name={zucchini},
+  description={(North American)},
+  see={courgette}}
+\end{verbatim}
+This defines two entries (courgette and zucchini) and automatically
+adds a cross-reference from zucchini to courgette. (That is, it adds
+\qt{\emph{see} courgette} to zucchini's \gls{numberlist}.) This
+doesn't automatically index courgette since this would create an
+unwanted location in courgette's \gls{numberlist}. (Page~1, if the
+definitions occur in the preamble.)
+
+Note that while it's possible to put the cross-reference in the
+description instead, for example:
+\begin{verbatim}
+\newglossaryentry{zucchini}{name={zucchini},
+  description={(North American) see \gls{courgette}}}
+\end{verbatim}
+this won't index the zucchini entry, so if zucchini isn't indexed
+elsewhere (with commands like \cs{gls} or \cs{glsadd}) then it won't
+appear in the glossary even if courgette does.
+
 The referenced entry should be supplied as the value to this key.
 If you want to override the \qt{see} tag, you can supply the new
 tag in square brackets before the label. For example
@@ -5720,12 +5920,6 @@ glossary entries using \gloskey{nonumberlist=false} (see above).
 Alternatively, you can use the \pkgopt{seeautonumberlist} package
 option.  For further details, see \sectionref{sec:crossref}.
 
-This key essentially provides a convenient shortcut that performs
-\begin{alltt}
-\cs{glssee}\oarg{tag}\marg{label}\marg{xr-label list}
-\end{alltt}
-after the entry has been defined.
-
 \begin{important}
 For \optsand23, \ics{makeglossaries} must be used before any occurrence of
 \ics{newglossaryentry} that contains the \gloskey{see} key. This key
@@ -5740,7 +5934,14 @@ If you use the \gloskey{see} key, you may want to consider using the
 \gls{glossaries-extra} package which additionally
 provides a \texttt{seealso} and \texttt{alias} key. If you want to
 avoid the automatic indexing triggered by the \gloskey{see} key,
-consider using \opt4.
+consider using \opt4. See also the FAQ item 
+\href{https://www.dickimaw-books.com/faq.php?action=view&category=glossaries&itemlabel=whyseekeyautoindex}{Why does the see key automatically index the entry?}
+
+\begin{bib2gls}
+The analogous \gls{bib2gls} \gloskey{see} field (and \xtrgloskey{seealso}) have a
+slightly different meaning. The \resourceopt{selection} resource option 
+determines the behaviour.
+\end{bib2gls}
 
 \item[{\xtrgloskey{seealso}}]
 This key is only available with \gls{glossaries-extra} and is
@@ -5756,8 +5957,12 @@ another form of cross-referencing.  An entry can be aliased to
 another entry with \texttt{alias=\marg{label}}. This behaves like
 \texttt{see=\marg{label}} but also alters the behaviour of commands
 like \cs{gls} so that they index the entry given by \meta{label}
-instead of the original entry. More variations with the key are
-available with \gls{bib2gls}.
+instead of the original entry. (See, for example,
+\gallery{index.php?label=aliases}{Gallery: Aliases}.)
+
+\begin{bib2gls}
+More variations with the key are available with \gls{bib2gls}.
+\end{bib2gls}
 
 \item[\xtrgloskey{category}]
 This key is only available with \gls{glossaries-extra} and is used
@@ -5809,8 +6014,8 @@ package:
 \cs{newglossaryentry}\mgroup{elite}\mgroup{name=\mgroup{\mgroup{\'e}lite},
 description=\mgroup{select group or class}}
 \end{alltt}
-(This doesn't apply for \XeLaTeX\ documents using the \sty{fontspec}
-package. For further details, see the \qt{UTF-8} section in the
+(This doesn't apply for \XeLaTeX\ or \LuaLaTeX\ documents. 
+For further details, see the \qt{UTF-8} section in the
 \sty{mfirstuc} user manual.)
 
 Note that in both of the above examples, you will also need to
@@ -6648,7 +6853,7 @@ maintained for newer commands. This restriction is also reimposed
 for \cs{newglossaryentry} by the new \opt1. (The
 \gls{glossaries-extra} package automatically reimposes this restriction for
 \optsand23 but provides a package option to allow document
-definitions.)
+definitions if necessary.)
 
 \subsection{Technical Issues}
 \label{sec:techissues}
@@ -6661,7 +6866,11 @@ entry before it has been defined.
  \item Entry information is required when displaying the glossary.
 If this occurs at the start of the document, but the entries aren't
 defined until later, then the entry details are
-being looked up before the entry has been defined.
+being looked up before the entry has been defined. This means that
+it's not possible to display the content of the glossary unless the
+entry definitions are saved on the previous \LaTeX\ run and can be
+picked up at the start of the \env{document} environment on the next run
+(in a similar way that \cs{label} and \cs{ref} work).
 
  \item If you use a package, such as \sty{babel}, that makes
 certain characters active at the start of the \env{document}
@@ -6683,19 +6892,21 @@ To overcome the first two problems, as from version 4.0 the
 \styfmt{glossaries} package modifies the definition of
 \cs{newglossaryentry} at the beginning of the \env{document}
 environment so that the definitions are written to an external file
-(\cs{jobname}\filetype{glsdefs}) which is then read in at the start
-of the document on the next run. The entry will then only be defined
-in the \env{document} environment if it doesn't already exist. This
-means that the entry can now be looked up in the glossary, even if
-the glossary occurs at the beginning of the document.
+(\cs{jobname}\texttt{.}\filetype{glsdefs}) which is then read in at the start
+of the document on the next run. This means that the entry can now
+be looked up in the glossary, even if the glossary occurs at the
+beginning of the document.
 
 There are drawbacks to this mechanism: if you modify an entry
 definition, you need a second run to see the effect of your
-modification; this method requires an extra \cs{newwrite}, which may
+modification in \cs{printglossary} (if it occurs at the start of the
+document); this method requires an extra \cs{newwrite}, which may
 exceed \TeX's maximum allocation; unexpected expansion issues could
-occur; the \gloskey{see} key isn't stored, which means it can't be
-added to the \filetype{glsdefs} file when it's created at the end of the 
-document (and therefore won't be present on subsequent runs).
+occur.
+
+Version 4.47 has introduced changes that have removed some of
+the issues involved, and there are now warning messages if there is an
+attempt to multiple define the same entry label.
 
 The \gls{glossaries-extra} package provides a setting (but only for
 \optsand23) that allows \cs{newglossaryentry} to occur in the
@@ -6730,5129 +6941,4759 @@ you forget the label, you can look it up in the definition file
 rather than searching through your document text to find the
 definition.
 
-\chapter{Number lists}
-\label{sec:numberlists}
+\chapter{Referencing Entries in the Document}
+\label{sec:usingentries}
 
-Each entry in the glossary has an associated \gls{numberlist}.
-By default, these numbers refer to the pages on which that entry has
-been indexed (using any of the commands described in
-\sectionref{sec:glslink} and \sectionref{sec:glsadd}). The number
-list can be suppressed using the \pkgopt{nonumberlist} package
-option, or an alternative counter can be set as the default using
-the \pkgopt{counter} package option. The number list is also
-referred to as the location list\index{location list|see{number list}}.
+Once you have defined a glossary entry using a command like
+\ics{newglossaryentry} (\sectionref{sec:newglosentry}) or
+\ics{newacronym} (\sectionref{sec:acronyms}), you can refer to that
+entry in the document with one of the provided commands that are
+describe in this manual. (There are some additional commands
+provided by \gls{glossaries-extra}.) The text produced at that point
+in the document is determined by the command and can also be
+governed by whether or not the entry has been
+\glsdisp{firstuseflag}{marked as used}.
 
-\Glspl{numberlist} are more common with indexes rather than
-glossaries (although you can use the \styfmt{glossaries} package for
-indexes as well). However, the \styfmt{glossaries} package makes use
-of \gls{makeindex} or \gls{xindy} to hierarchically sort and collate the
-entries since they are readily available with most modern \TeX\
-distributions. Since these are both designed as \glspl{indexingapp}
-they both require that terms either have a valid location or a
-cross-reference. Even if you use \pkgopt{nonumberlist}, the
-locations must still be provided and acceptable to the
-\gls{indexingapp} or they will cause an error during the indexing
-stage, which will interrupt the document build. However, if you're
-not interested in the locations, each entry only needs to be indexed
-once, so consider using \pkgopt{indexonlyfirst}, which can improve the
-document build time by only indexing the \gls{firstuse} of each term.
+Some of these commands are more complicated than others. Many of
+them are robust and can't be used in fully expandable contexts, such
+as in PDF bookmarks.
 
-The \ics{glsaddall} command (see \sectionref{sec:glsadd}), which is used to
-automatically index all entries, iterates over all defined entries
-and does \cs{glsadd}\marg{label} for each entry (where \meta{label}
-is that entry's label). This means that \cs{glsaddall} automatically
-adds the same location to every entry's \gls{numberlist}, which
-looks weird if the \gls*{numberlist} hasn't been suppressed.
+The commands are broadly divided into:
+\begin{enumerate}
+\item Those that display text in the document (where the formatting
+can be adjusted by a style or hook) and also index the
+entry (so that it's added to the document) are described in
+\sectionref{sec:glslink}. This set of commands can
+be further sub-divided into those that mark the entry as having been
+used (the \cs{gls}-like commands, \sectionref{sec:gls-like}) and those that don't
+(the \cs{glstext}-like commands, \sectionref{sec:glstext-like}).
+
+\item Those that display text in the document without indexing or applying any
+additional formatting (\sectionref{sec:glsnolink}).
+\end{enumerate}
+There are additional commands specific to entries defined with
+\cs{newacronym} that are described in \sectionref{sec:longshortfull}.
 
-With \opt4, the indexing is performed by \gls{bib2gls}, which was
-specifically designed for the \gls{glossaries-extra} package. So it
-will allow any location format, and its \texttt{selection=all}
-option will select all entries without adding an unwanted location to the
-\gls{numberlist}. If \gls{bib2gls} can deduce a numerical value for
-a location, it will attempt to form a range over consecutive
-locations, otherwise it won't try to form a range and the
-location will just form an individual item in the list.
-\opt1 also allows any location but it doesn't form ranges.
+\section{Links to Glossary Entries}
+\label{sec:glslink}
 
-\section{Encap Values}
-\label{sec:encap}
+The text which appears at the point in the document when using any
+of the commands described in \sectionref{sec:gls-like} or
+\sectionref{sec:glstext-like} is referred to as the \gls{linktext}
+(even if there are no hyperlinks). These commands also add a line to
+an external file that is used to generate the relevant entry in the
+glossary. This information includes an associated location that is
+added to the \gls{numberlist} for that entry. By default, the
+location refers to the page number. For further information on
+number lists, see \sectionref{sec:numberlists}.  These external
+files need to be post-processed by \gls{makeindex} or \gls{xindy}
+unless you have chosen \optsor14. If you don't use
+\ics{makeglossaries} these external files won't be created.
+(\optsand14 write the information to the \filetype{aux} file.)
 
-Each location in the \gls{numberlist} is encapsulated with a
-command formed from the \termdef{encap} value.  By
-default this is the \ics{glsnumberformat} command, which corresponds
-to the encap \texttt{glsnumberformat}, but this may be
-overridden using the \gloskey[glslink]{format} key in the optional
-argument to commands like \cs{gls}. (See \sectionref{sec:glslink}.)
-For example, you may want the location to appear in bold to indicate
-the principle use of a term or symbol. If the encap starts with an
-open parenthesis~\verb|(| this signifies the start of a range and if
-the encap starts with close parenthesis~\verb|)| this signifies the
-end of a range. These must always occur in matching pairs.
+Note that repeated use of these commands for the same entry can
+cause the \gls{numberlist} to become quite long, which may not be
+particular helpful to the reader. In this case, you can use the
+non-indexing commands described in \sectionref{sec:glsnolink} or
+you can use the supplemental \gls{glossaries-extra} package, which
+provides a means to suppress the automated indexing of the commands listed
+in this chapter.
 
-The \styfmt{glossaries} package provides the command \ics{glsignore}
-which ignores its argument. This is the format used by
-\cs{glsaddallunused} to suppress the location, which works fine as
-long as no other locations are added to the \gls{numberlist}. For
-example, if you use \verb|\gls{sample}| on page~2 then reset the
-\gls{firstuseflag} and then use \cs{glsaddallunused} on page~10, the
-\gls{numberlist} for \texttt{sample} will be \verb|2, \glsignore{10}| 
-which will result in \qt{2,~} which has a spurious comma.
+\begin{important}
+I strongly recommend that you don't use the commands
+defined in this chapter in the arguments of sectioning or caption
+commands or any other command that has a moving argument.
 
-This isn't a problem with \gls{bib2gls} because you'd use
-\texttt{selection=all} instead of \cs{glsaddallunused}, but even if
-you explicitly had, for example, 
-\cs{gls}\texttt{[format=glsignore]}\marg{label}
-for some reason, \gls{bib2gls} will recognise \texttt{glsignore} as
-a special encap indicating an ignored location, so it will select
-the entry but not add that location to the \gls{numberlist}. It's a
-problem for all the other options (except \opt5, which doesn't
-perform any indexing).
+Aside from problems with expansion issues, PDF bookmarks and
+possible nested hyperlinks in the table of contents (or list of
+whatever) any use of the commands described in \sectionref{sec:gls-like}
+will have their \firstuseflag\ unset when they appear in the table
+of contents (or list of whatever).
+\end{important}
 
-Complications can arise if you use different encap values for the
-same location. For example, suppose on page~10 you have both the
-default \texttt{glsnumberformat} and \texttt{textbf} encaps.  While it may
-seem apparent that \texttt{textbf} should override \texttt{glsnumberformat}
-in this situation, the \gls{indexingapp} may not know it.
-This is therefore something you need to be careful about if you use the
-\gloskey[glslink]{format} key or if you use a command that
-implicitly sets it.
+The above warning is particularly important if you are using the
+\styfmt{glossaries} package in conjunction with the \sty{hyperref}
+package. Instead, use one of the \emph{expandable} commands listed in
+\sectionref{sec:glsnolink} (such as \ics{glsentrytext} \emph{but
+not} the non-expandable
+case changing versions like \ics{Glsentrytext}). Alternatively, provide an
+alternative via the optional argument to the sectioning\slash caption
+command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples:
+\begin{verbatim}
+\chapter{An overview of \glsentrytext{perl}}
+\chapter[An overview of Perl]{An overview of \gls{perl}}
+\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
+\end{verbatim}
+\begin{xtr}
+If you want to retain the formatting that's available through
+commands like \cs{acrshort} (for example, if you are using one of
+the small caps styles), then you might want to consider the
+\gls{glossaries-extra} package which provides commands
+for this purpose.
+\end{xtr}
 
-In the case of \gls{xindy}, it only accepts one encap (according to
-the order of precedence given in the \gls{xindy} module) and discards the
-others for identical locations (for the same entry). This can cause
-a problem if a discarded location forms the start or end of a range. 
+If you want the \gls{linktext} to produce a hyperlink to the
+corresponding entry details in the glossary, you should load the
+\sty{hyperref} package \emph{before} the \styfmt{glossaries}
+package. That's what I've done in this document, so if you see a
+hyperlinked term, such as \gls{linktext}, you can click on the word
+or phrase and it will take you to a brief description in this
+document's glossary.
 
-In the case of \gls{makeindex}, it accepts different encaps for the
-same location, but warns about it.  This leads to a \gls{numberlist}
-with the same location repeated in different formats.  If you use
-the \gls{makeglossaries} Perl script with \opt2 it will detect
-\gls{makeindex}'s warning and attempt to fix the problem, ensuring
-that the \texttt{glsnumberformat} encap always has the least precedence
-unless it includes a range identifier. Other conflicting encaps will
-have the last one override earlier ones for the same location with
-range identifiers taking priority.
+\begin{important}
+If you use the \sty{hyperref} package, I strongly recommend you use
+\app{pdflatex} rather than \app{latex} to compile your document, if
+possible. The DVI format of \LaTeX\ has limitations with the
+hyperlinks that can cause a problem when used with the
+\styfmt{glossaries} package. Firstly, the DVI format can't break a
+hyperlink across a line whereas PDF\LaTeX\ can. This means that long
+glossary entries (for example, the full form of an acronym) won't be
+able to break across a line with the DVI format. Secondly, the DVI
+format doesn't correctly size hyperlinks in subscripts or
+superscripts. This means that if you define a term that may be used
+as a subscript or superscript, if you use the DVI format, it won't
+come out the correct size.
 
-No discard occurs with \opt1 so again you get the same location
-repeated in different formats. With \opt4, \gls{bib2gls} will discard
-according to order of precedence, giving priority to start and end
-range encaps.  (See the \gls{bib2gls} manual for further details.)
+These are limitations of the DVI format not of the \sty{glossaries}
+package.
+\end{important}
 
-\section{Locations}
-\label{sec:locationsyntax}
+It may be that you only want terms in certain glossaries to have
+hyperlinks, but not for other glossaries. In this case, you can use the
+package option \pkgopt{nohypertypes} to identify the glossary lists
+that shouldn't have hyperlinked \gls{linktext}. See 
+\sectionref{sec:pkgopts-general} for further details.
 
-Neither \opt1 nor \opt4 care about the location syntax as long as
-it's valid \LaTeX\ code (and doesn't contain fragile commands). In
-both cases, the indexing is performed by writing a line to the
-\filetype{aux} file. The write operation is deferred to avoid the
-problems associated with \TeX's asynchronous output routine.
-(See, for example,
-\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding
-if you're on an odd or an even page} for more details on this issue.)
-Unfortunately \optsand23 are far more problematic and need some
-complex code to deal with awkward locations.
-
-If you know that your locations will always expand to a format
-acceptable to your chosen \gls{indexingapp} then use the package
-option \pkgopt[false]{esclocations} to bypass this operation. This setting
-only affects \optsand23 as the problem doesn't arise with the other
-indexing options.
-
-Both \gls{makeindex} and \gls{xindy} are fussy about the syntax of
-the locations. In the case of \gls{makeindex}, only the numbering
-system obtained with \cs{arabic}, \cs{roman}, \cs{Roman}, \cs{alph}
-and \cs{Alph} or composites formed from them with the same separator
-(set with \cs{glsSetCompositor}\marg{char}) are accepted.
-(\gls{makeindex} won't accept an empty location.) In the case of
-\gls{xindy}, you can define your own location classes, but if the
-location contains a robust command then the leading backslash must
-be escaped. The \sty{glossaries} package tries to do this, but it's
-caught between two conflicting requirements:
-\begin{enumerate}
-\item The location must be fully expanded before \verb|\| can be
-converted to \verb|\\| (there's no point converting \verb|\thepage|
-to \verb|\\thepage|);
-\item The page number can't be expanded until the deferred write
-operation (so \verb|\c@page| mustn't expand in the previous step
-but \verb|\the\c@page| mustn't be converted to \verb|\\the\\c@page| 
-and \verb|\number\c@page| mustn't be converted to
-\verb|\\number\\c@page| etc).
-\end{enumerate}
-There's a certain amount of trickery needed to deal with this
-conflict and the code requires the location to be in a form that
-doesn't embed the counter's internal register in commands like
-\cs{value}.  For example, suppose you have a robust command called
-\cs{tallynum} that takes a number as the argument and an expandable
-command called \cs{tally} that converts a counter name into the
-associated register or number to pass to \cs{tallynum}. Let's
-suppose that this command is used to represent the page number:
-\begin{verbatim}
-\renewcommand{\thepage}{\tally{page}}
-\end{verbatim}
-Now let's suppose that a term is indexed at the beginning of page~2
-at the end of a paragraph that started on page~1. With \gls{xindy},
-the location \verb|\tally{page}| needs to be written to the file
-as \verb|\\tallynum{2}|. If it's written as \verb|\tallynum{2}| then
-\gls{xindy} will interpret \verb|\t| as the character \qt{t}
-(which means the location would appear as \qt{tallynum2}). So
-\sty{glossaries} tries to expand \cs{thepage} without expanding
-\cs{c@page} and then escapes all the backslashes, except for the
-page counter's internal command. The following definitions of
-\cs{tally} will work:
-\begin{itemize}
-\item In the following, \cs{arabic} works as its internal command \cs{c@arabic} is
-temporarily redefined to check for \cs{c@page}:
+The way the \gls{linktext} is displayed depends on 
+\begin{definition}[\DescribeMacro{\glstextformat}]
+\cs{glstextformat}\marg{text}
+\end{definition}
+For example, to make all \gls{linktext} appear in a sans-serif
+font, do:
 \begin{verbatim}
-\newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
+\renewcommand*{\glstextformat}[1]{\textsf{#1}}
 \end{verbatim}
+Further customisation can be done via \ics{defglsentryfmt} or by
+redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for
+further details.
 
-\item The form \verb|\expandafter\the\csname c@|\meta{counter}\verb|\endcsname|
-also works (provided \cs{the} is allowed to be temporarily redefined, 
-see below):
-\begin{verbatim}
-\newcommand{\tally}[1]{%
- \tallynum{\expandafter\the\csname c@#1\endcsname}}
-\end{verbatim}
+Each entry has an associated conditional referred to as the
+\firstuseflag. Some of the commands described in this chapter
+automatically unset this flag and can also use it
+to determine what text should be displayed. These types of commands
+are the \glslike\ commands and are described in
+\sectionref{sec:gls-like}. The commands that don't reference or change
+the \firstuseflag\ are \glstextlike\ commands and are described
+in \sectionref{sec:glstext-like}.  See \sectionref{sec:glsunset} for 
+commands that unset (mark the entry as having been used) or reset
+(mark the entry as not used) the \firstuseflag\ without referencing
+the entries.
 
-\item \verb|\expandafter\the\value|\marg{counter} now also works
-(with the same condition as above):
-\begin{verbatim}
-\newcommand{\tally}[1]{\tallynum{\expandafter\the\value{#1}}}
-\end{verbatim}
+The \glslike\ and \glstextlike\ commands all take a first
+optional argument that is a comma-separated list of
+\meta{key}=\meta{value} options, described below. They also have a
+star-variant, which inserts \texttt{hyper=false} at the start of the
+list of options and a plus-variant, which inserts
+\texttt{hyper=true} at the start of the list of options. For example
+\verb|\gls*{sample}| is the same as \verb|\gls[hyper=false]{sample}|
+and \verb|\gls+{sample}| is the same as
+\verb|\gls[hyper=true]{sample}|, whereas just \verb|\gls{sample}|
+will use the default hyperlink setting which depends on a number of
+factors (such as whether the entry is in a glossary that has been
+identified in the \pkgopt{nohypertypes} list).  You can override the
+\gloskey[glslink]{hyper} key in the variant's optional argument, for
+example, \verb|\gls*[hyper=true]{sample}| but this creates
+redundancy and is best avoided. The \gls{glossaries-extra} package
+provides the option to add a third custom variant.
 
-\item Another variation that will work:
-\begin{verbatim}
-\newcommand{\tally}[1]{%
-  \expandafter\tallynum\expandafter{\the\csname c@#1\endcsname}}
-\end{verbatim}
+\begin{important}
+Avoid nesting these commands. For example don't do
+\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}}
+as this is likely to cause problems. By implication, this
+means that you should avoid using any of these commands within
+the \gloskey{text}, \gloskey{first}, \gloskey{short} or
+\gloskey{long} keys (or their plural equivalent) or any
+other key that you plan to access through these commands.
+(For example, the \gloskey{symbol} key if you intend to use
+\cs{glssymbol}.)
+\end{important}
 
-\item and also:
+The keys listed below are available for the optional first argument.
+The \gls{glossaries-extra} package provides additional keys.
+(See the \gls*{glossaries-extra} manual for further details.)
+\begin{description}
+\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can
+be used to enable\slash disable the hyperlink to the relevant entry
+in the glossary. If this key is omitted, the value is determined by current
+settings, as indicated above. For example, when used with a \glslike\ command, if this is the first
+use and the \pkgopt[false]{hyperfirst} package option has been used,
+then the default value is \texttt{hyper=false}. The hyperlink can be
+forced on using \texttt{hyper=true} unless the hyperlinks have been
+suppressed using \ics{glsdisablehyper}. You must load the
+\sty{hyperref} package before the \sty{glossaries} package to
+ensure the hyperlinks work.
+
+\item[{\gloskey[glslink]{format}}] This specifies how to format the
+associated location number for this entry in the glossary. This 
+value is equivalent to the \gls{makeindex} encap value, and (as
+with \ics{index}) the value needs to be the name of a command
+\emph{without} the initial backslash. As with \ics{index}, the
+characters \verb"(" and \verb")" can also be used to specify the
+beginning and ending of a number range and they must be in matching
+pairs. (For example, \verb|\gls[format={(}]{sample}| on one page
+to start the range and later \verb|\gls[format={)}]{sample}| to close 
+the range.)  Again as with \ics{index}, the command should be the
+name of a command which takes an argument (which will be the
+associated location).  Be careful not to use a declaration (such as
+\texttt{bfseries}) instead of a text block command (such as
+\texttt{textbf}) as the effect is not guaranteed to be localised. If
+you want to apply more than one style to a given entry (e.g.\
+\textbf{bold} and \emph{italic}) you will need to create a command
+that applies both formats, e.g.\ 
 \begin{verbatim}
-\newcommand{\tally}[1]{\tallynum{\the\csname c@#1\endcsname}}
+\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}
 \end{verbatim}
-\end{itemize}
-The following \emph{don't work}:
-\begin{itemize}
-\item This definition leads to the premature expansion of \cs{c@page}
-to \qt{1} when, in this case, it should be \qt{2}:
+and use that command.
+
+In this document, the standard formats refer to the standard text
+block commands such as \ics{textbf} or \ics{emph} or any of the
+commands listed in \tableref{tab:hyperxx}. You can combine a range
+and format using \verb|(|\meta{format}  to start the range and
+\verb|)|\meta{format} to end the range.  The \meta{format} part must
+match. For example, \verb|format={(emph}| and \verb|format={)emph}|.
+
+\begin{important}
+If you use \gls{xindy} instead of \gls{makeindex}, you
+must specify any non-standard formats that you want to use
+with the \gloskey[glslink]{format} key using
+\ics{GlsAddXdyAttribute}\marg{name}. So if you use
+\gls*{xindy} with the above example, you would need to add:
 \begin{verbatim}
-\newcommand{\tally}[1]{\tallynum{\the\value{#1}}}
+\GlsAddXdyAttribute{textbfem}
 \end{verbatim}
-\item This definition leads to \verb|\\c@page| in the glossary file:
+See \sectionref{sec:xindy} for further details.
+\end{important}
+
+If you are using hyperlinks and you want to change the font of the
+hyperlinked location, don't use \ics{hyperpage} (provided by the
+\sty{hyperref} package) as the locations may not refer to a page
+number.  Instead, the \styfmt{glossaries} package provides number
+formats listed in \tableref{tab:hyperxx}. These commands are
+designed to work with the particular location formats created by
+\gls{makeindex} and \gls{xindy} and shouldn't be used in other
+contexts.
+
+\begin{table}[htbp]
+\caption{Predefined Hyperlinked Location Formats}
+\label{tab:hyperxx}
+\centering
+\vskip\baselineskip
+\begin{tabular}{ll}
+\locfmt{hyperrm} & serif hyperlink\\
+\locfmt{hypersf} & sans-serif hyperlink\\
+\locfmt{hypertt} & monospaced hyperlink\\
+\locfmt{hyperbf} & bold hyperlink\\
+\locfmt{hypermd} & medium weight hyperlink\\
+\locfmt{hyperit} & italic hyperlink\\
+\locfmt{hypersl} & slanted hyperlink\\
+\locfmt{hyperup} & upright hyperlink\\
+\locfmt{hypersc} & small caps hyperlink\\
+\locfmt{hyperemph} & emphasized hyperlink
+\end{tabular}
+\par
+\end{table}
+
+Note that if the \ics{hyperlink} command hasn't been defined, the
+\texttt{hyper}\meta{xx} formats are equivalent to the analogous
+\texttt{text}\meta{xx} font commands (and \texttt{hyperemph} is
+equivalent to \texttt{emph}). If you want to make a new format, you
+will need to define a command which takes one argument and use that.
+For example, if you want the location number to be in a bold
+sans-serif font, you can define a command called, say,
+\ics{hyperbsf}:
 \begin{verbatim}
-\newcommand{\tally}[1]{\tallynum{\csname c@#1\endcsname}}
+\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
 \end{verbatim}
-\end{itemize}
-If you have a numbering system where 
-\verb|\|\meta{cs name}\verb|{page}| expands to
-\verb|\|\meta{internal cs name}\cs{c@page} (for example, if
-\verb|\tally{page}| expands to \verb|\tallynum\c@page|) then you
-need to use:
-\begin{definition}[\DescribeMacro\glsaddprotectedpagefmt]
-\cs{glsaddprotectedpagefmt}\marg{internal cs name}
-\end{definition}
-Note that the backslash must be omitted from \meta{internal cs name}
-and the corresponding command must be able to process a count
-register as the (sole) argument.
+and then use \texttt{hyperbsf} as the value for the \gloskey[glslink]{format}
+key.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi
+\qt{Displaying the glossary} in the documented code,
+\texttt{glossaries-code.pdf}.} 
 
-For example, suppose you have a style \texttt{samplenum} that is
-implemented as follows:
-\begin{verbatim}
- \newcommand*{\samplenum}[1]{%
-   \expandafter\@samplenum\csname c@#1\endcsname}
- \newcommand*{\@samplenum}[1]{\two@digits{#1}}
+\begin{important}
+When defining a custom location format command that uses one of the
+\csmeta{hyper}{xx}{} commands, make sure that the argument of
+\csmeta{hyper}{xx}{} is just the location. Any formatting must be
+outside of \csmeta{hyper}{xx}{} (as in the above \cs{hyperbfsf}
+example).
+\end{important}
 
-\end{verbatim}
-(That is, it displays the value of the counter as a two-digit
-number.) Then to ensure the location is correct for entries in 
-page-spanning paragraphs, you need to do:
+Remember that if you use \gls{xindy}, you
+will need to add this to the list of location \ixindyattrs attributes:
 \begin{verbatim}
-\glsaddprotectedpagefmt{@samplenum}
+\GlsAddXdyAttribute{hyperbsf}
 \end{verbatim}
-(If you are using a different counter for the location, such as
-\texttt{section} or \texttt{equation}, you don't need to worry about
-this provided the inner command is expandable.)
 
-If the inner macro (as given by \verb|\|\meta{internal cs name}) contains
-non-expandable commands then you may need to redefine
-\cs{gls}\meta{internal cs name}\texttt{page} after using
-\begin{alltt}
-\cs{glsaddprotectedpagefmt}\marg{internal cs name}
-\end{alltt}
-This command doesn't take any arguments
-as \emph{the location is assumed to be given by \cs{c@page}} because
-that's the only occasion this command should be used. For example, 
-suppose now my page counter format uses small caps Roman numerals:
-\begin{verbatim}
- \newcommand*{\samplenum}[1]{%
-  \expandafter\@samplenum\csname c@#1\endcsname}
- \newcommand*{\@samplenum}[1]{\textsc{\romannumeral#1}}
-\end{verbatim}
-Again, the inner macro needs to be identified using:
-\begin{verbatim}
-\glsaddprotectedpagefmt{@samplenum}
-\end{verbatim}
-However, since \cs{textsc} isn't fully expandable, the location
-is written to the file as \verb|\textsc  {i}| (for page~1), 
-\verb|\textsc  {ii}| (for page~2), etc. This format may cause a problem for
-the \gls{indexingapp} (particularly for \gls{makeindex}).
-To compensate for this, the \cs{gls}\meta{internal cs
-name}\texttt{page} command may be redefined so that it expands to a
-format that's acceptable to the \gls*{indexingapp}. For example:
-\begin{verbatim}
-\renewcommand*{\gls@samplenumpage}{\romannumeral\c@page}
-\end{verbatim}
-While this modification means that the \gls{numberlist} in the glossary
-won't exactly match the format of the page numbers (displaying
-lower case Roman numbers instead of small cap Roman numerals)
-this method will at least work correctly for both \gls{makeindex}
-and \gls{xindy}. If you are using \gls{xindy}, the following
-definition:
-\begin{verbatim}
- \renewcommand*{\gls@samplenumpage}{%
-   \glsbackslash\string\textsc{\romannumeral\c@page}}
-\end{verbatim}
-combined with
-\begin{verbatim}
-\GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace"
- "roman-numbers-lowercase" :sep "\glsclosebrace"}
-\end{verbatim}
-will now have lowercase Roman numerals in the location list
-(see \sectionref{sec:xindyloc} for further details on that command).
-Take care of the backslashes. The location (which ends up in 
-the \xindyattr{:locref} attribute) needs \verb|\\| but the location class
-(identified with \cs{GlsAddXdyLocation}) just has a single
-backslash.  Note that this example will cause problems if your
-locations should be hyperlinks.
+\item[{\gloskey[glslink]{counter}}] This specifies which counter
+to use for this location. This overrides the default counter
+used by this entry. (See also \sectionref{sec:numberlists}.)
 
-Another possibility that may work with both \gls{makeindex} and
-\gls{xindy} is to redefine \cs{gls}\meta{internal cs
-name}\texttt{page} (\cs{gls@samplenumpage} in this example)
-to just expand to the decimal page number (\verb|\number\c@page|) and redefine
-\ics{glsnumberformat} to change the displayed format:
-\begin{verbatim}
-\renewcommand*{\gls@samplenumpage}{\number\c@page}
-\renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}}
-\end{verbatim}
+\item[{\gloskey[glslink]{local}}] This is a boolean key that only
+makes a difference when used with \glslike\ commands that change the
+entry's \gls{firstuseflag}. If \texttt{local=true}, the change to
+the \gls*{firstuseflag} will be localised to the current scope. The
+default is \texttt{local=false}.
+
+\item[{\xtrgloskey[glslink]{noindex}}] This is a boolean key that
+suppresses the indexing. Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{hyperoutside}}] This is a boolean key that
+determines whether to put the hyperlink outside of \ics{glstextformat}. 
+Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{wrgloss}}] This key determines
+whether to index before (\texttt{wrgloss\dequals before}) or after
+(\texttt{wrgloss\dequals after}) the \gls{linktext}.
+Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{textformat}}] This key identifies the
+name of the control sequence to encapsulate the \gls{linktext}
+instead of the default \ics{glstextformat}.
+Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{prefix}}] This key locally redefines
+\ics{glolinkprefix} to the given value.
+Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{thevalue}}] This key explicitly sets the
+location.
+Only available with \gls{glossaries-extra}.
+
+\item[{\xtrgloskey[glslink]{theHvalue}}] This key explicitly sets the
+hyperlink location.
+Only available with \gls{glossaries-extra}.
+
+\end{description}
 
 \begin{important}
-If you redefine \cs{gls}\meta{internal cs name}\texttt{page},
-you must make sure that \cs{c@page} is expanded when it's written to
-the file. (So don't, for example, hide \cs{c@page} inside a robust
-command.)
+The \gls{linktext} isn't scoped by default with just the base
+\styfmt{glossaries} package. Any unscoped
+declarations in the \gls{linktext} may affect subsequent text.
 \end{important}
 
-The mechanism that allows this to work temporarily redefines
-\ics{the} and \ics{number} while it processes the location. If this
-causes a problem you can disallow it using
-\begin{definition}[\DescribeMacro\glswrallowprimitivemodsfalse]
-\cs{glswrallowprimitivemodsfalse}
-\end{definition}
-but you will need to find some other way to ensure the location expands
-correctly.
+\subsection{The \cs{gls}-Like Commands (First Use Flag Queried)}
+\label{sec:gls-like}
 
-\section{Range Formations}
-\label{sec:ranges}
+This section describes the commands that unset (mark as used) the \firstuseflag\ on
+completion, and in most cases they use the current state of the flag
+to determine the text to be displayed. As described above, these
+commands all have a star-variant (\texttt{hyper=false}) and 
+a plus-variant (\texttt{hyper=true}) and have an
+optional first argument that is a \meta{key}=\meta{value} list.
+These commands use \ics{glsentryfmt} or the equivalent definition provided by
+\ics{defglsentryfmt} to determine the automatically generated text
+and its format (see \sectionref{sec:glsdisplay}).
 
-Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a
-sequence of~3 or more consecutive pages into~a range. With 
-\gls*{xindy} (\opt3) you can vary the minimum sequence length using
-\ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either
-an integer or the keyword \texttt{none} which indicates that there
-should be no range formation (see \sectionref{sec:xindyloc} for
-further details).
+Apart from \ics{glsdisp}, the commands described in this section
+also have a \emph{final} optional argument \meta{insert} which may
+be used to insert material into the automatically generated text.
 
 \begin{important}
-Note that \cs{GlsSetXdyMinRangeLength} must be used before
-\ics{makeglossaries} and has no effect if \ics{noist} is used.
+Since the commands have a final optional argument, take care if
+you actually want to display an open square bracket after the command
+when the final optional argument is absent. Insert an empty set of
+braces \verb|{}| immediately before the opening square bracket to
+prevent it from being interpreted as the final argument. For
+example:
+\begin{verbatim}
+\gls{sample} {}[Editor's comment]
+\end{verbatim}
+
+Don't use any of the \glslike\ or \glstextlike\ commands in the 
+\meta{insert} argument.
 \end{important}
 
-With both \gls{makeindex} and \gls{xindy} (\optsand23), you can replace
-the separator and the closing number in the range using:
-\begin{definition}[\DescribeMacro{\glsSetSuffixF}]
-\cs{glsSetSuffixF}\marg{suffix}
+Take care using these commands within commands or environments that
+are processed multiple times as this can confuse the first use flag
+query and state change. This includes frames with overlays in
+\cls{beamer} and the \envfmt{tabularx} environment provided by \sty{tabularx}. 
+The \styfmt{glossaries} package automatically deals with this issue
+in \sty{amsmath}'s \envfmt{align} environment. You can apply a patch
+to \sty{tabularx} by placing the following command (new to v4.28) in 
+the preamble:
+\begin{definition}[\DescribeMacro\glspatchtabularx]
+\cs{glspatchtabularx}
 \end{definition}
-\begin{definition}[\DescribeMacro{\glsSetSuffixFF}]
-\cs{glsSetSuffixFF}\marg{suffix}
+This does nothing if \sty{tabularx} hasn't been loaded. There's no
+patch available for \cls{beamer}. See \sectionref{sec:glsunset} for
+more details.
+
+\begin{definition}[\DescribeMacro{\gls}]
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-where the former command specifies the suffix to use for a 2 page
-list and the latter specifies the suffix to use for longer lists.
-For example:
+This command typically determines the \gls{linktext} from the values
+of the \gloskey{text} or \gloskey{first} keys supplied when the
+entry was defined using \ics{newglossaryentry}. However, if the
+entry was defined using \ics{newacronym} and \ics{setacronymstyle} was 
+used, then the \gls*{linktext} will usually be determined from the \gloskey{long} or
+\gloskey{short} keys.
+
+There are two upper case variants:
+\begin{definition}[\DescribeMacro{\Gls}]
+\cs{Gls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\GLS}]
+\cs{GLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+which make the first letter of the link text or all the link text
+upper case, respectively. For the former, the uppercasing of the
+first letter is performed by \ics{makefirstuc}.
+
+\begin{important}
+The first letter uppercasing command \cs{makefirstuc} has
+limitations which must be taken into account if you use \cs{Gls} or
+any of the other commands that convert the first letter to
+uppercase. 
+\end{important}
+The upper casing is performed as follows:
+\begin{itemize}
+\item If the first thing in the \gls{linktext} is a command follow
+by a group, the upper casing is performed on the first object of the
+group. For example, if an entry has been defined as
 \begin{verbatim}
-\glsSetSuffixF{f.}
-\glsSetSuffixFF{ff.}
+\newglossaryentry{sample}{
+ name={\emph{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
 \end{verbatim}
-Note that if you use \gls{xindy} (\opt3), you will also need to
-set the minimum range length to 1 if you want to change these
-suffixes:
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext}
+to\footnote{I've used \cs{MakeUppercase} in all the examples for clarity, but it
+will actually use \cs{mfirstucMakeUppercase}.}
 \begin{verbatim}
-\GlsSetXdyMinRangeLength{1}
+\emph{\MakeUppercase sample} phrase
 \end{verbatim}
-Note that if you use the \sty{hyperref} package, you will need
-to use \ics{nohyperpage} in the suffix to ensure that the hyperlinks
-work correctly. For example:
+which will appear as \emph{\MakeUppercase sample} phrase.
+
+\item If the first thing in the \gls{linktext} isn't a command or is
+a command but isn't followed by a group, then the upper casing will
+be performed on that first thing. For example, if an entry has been
+defined as:
 \begin{verbatim}
-\glsSetSuffixF{\nohyperpage{f.}}
-\glsSetSuffixFF{\nohyperpage{ff.}}
+\newglossaryentry{sample}{
+  name={\oe-ligature},
+  sort={oe-ligature},
+  description={an example}
+}
+\end{verbatim}
+Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} to
+\begin{verbatim}
+\MakeUppercase \oe-ligature
 \end{verbatim}
+which will appear as \MakeUppercase \oe-ligature.
 
-\begin{important}
-Note that \cs{glsSetSuffixF} and \cs{glsSetSuffixFF} must be used 
-before \ics{makeglossaries} and have no effect if \ics{noist} is 
-used.
-\end{important}
+\item If you have \sty{mfirstuc} v2.01 or above, an extra case is
+added. If the first thing is \cs{protect} it will be discarded and
+the above rules will then be tried.
 
-It's also possible to concatenate a sequence of consecutive
-locations into a range or have suffixes with \opt4, but with
-\gls{bib2gls} these implicit ranges can't be merged with explicit
-ranges (created with the \verb|(| and \verb|)| encaps). See
-the \gls{bib2gls} manual for further details.
+\end{itemize}
+(Note the use of the \gloskey{sort} key in the above examples.)
 
-\opt1 doesn't form ranges. However, with this option you
-can iterate over an entry's \gls{numberlist} using:
-\begin{definition}[\DescribeMacro\glsnumberlistloop]
-\cs{glsnumberlistloop}\marg{label}\marg{handler cs}\marg{xr handler
-cs}
-\end{definition}
-where \meta{label} is the entry's label and \meta{handler cs} is a
-handler control sequence of the form:
-\begin{definition}
-\meta{handler cs}\marg{prefix}\marg{counter}\marg{format}\marg{location}
-\end{definition}
-where \meta{prefix} is the \sty{hyperref} prefix, \meta{counter} is
-the name of the counter used for the location, \meta{format} is the
-format used to display the location (e.g.\ \texttt{textbf})
-and \meta{location} is the location. The third argument is the
-control sequence to use for any cross-references in the list. This
-handler should have the syntax:
-\begin{definition}
-\meta{xr handler cs}\oarg{tag}\marg{xr list}
-\end{definition}
-where \meta{tag} is the cross-referenced text (e.g.\ \qt{see}) and
-\meta{xr list} is a~comma-separated list of labels. (This actually
-has a third argument but it's always empty when used with \opt1.)
+There are hundreds of \LaTeX\ packages that altogether define
+thousands of commands with various syntax and it's impossible for
+\sty{mfirstuc} to take them all into account. The above rules are quite
+simplistic and are designed for \gls{linktext} that starts with
+a~text-block command (such as \cs{emph}) or a command that produces 
+a character (such as \cs{oe}). This means that if your \gls{linktext}
+starts with something that doesn't adhere to \sty{mfirstuc}'s assumptions
+then things are likely to go wrong.
 
-For example, if on page~12
-I~have used
+For example, starting with a math-shift symbol:
 \begin{verbatim}
-\gls[format=textbf]{apple}
+\newglossaryentry{sample}{
+  name={$a$},
+  sort={a},
+  description={an example}
+}
 \end{verbatim}
-and on page~18 I~have used
+This falls into case~2 above, so the \gls{linktext} will be set to
 \begin{verbatim}
-\gls[format=emph]{apple}
+\MakeUppercase $a$
 \end{verbatim}
-then
+This attempts to uppercase the math-shift \verb|$|, which will go
+wrong. In this case it's not appropriate to perform any
+case-changing, but it may be that you want to use \cs{Gls}
+programmatically without checking if the text contains any maths.
+In this case, the simplest solution is to insert an empty brace at
+the start:
 \begin{verbatim}
-\glsnumberlistloop{apple}{\myhandler}
+\newglossaryentry{sample}{
+  name={{}$a$},
+  sort={a},
+  description={an example}
+}
 \end{verbatim}
-will be equivalent to:
+Now the \gls{linktext} will be set to
 \begin{verbatim}
-\myhandler{}{page}{textbf}{12}%
-\myhandler{}{page}{emph}{18}%
+\MakeUppercase{}$a$
 \end{verbatim}
-There is a predefined handler that's used to display the
-\gls{numberlist} in the glossary:
-\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
-\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
-\end{definition}
-The predefined handler used for the cross-references in the glossary is:
-\begin{definition}
-\cs{glsseeformat}\oarg{tag}\marg{xr list}\marg{location}
-\end{definition}
-which is described in \sectionref{sec:customxr}.
+and the \cs{uppercase} becomes harmless.
 
-\begin{important}
-\cs{glsnumberlistloop} is not available for \optsand23.
-\end{important}
+Another issue occurs when the \gls{linktext} starts with a command
+followed by an argument (case~1) but the argument is a label,
+identifier or something else that shouldn't have a case-change.
+A common example is when the \gls{linktext} starts with one of the
+commands described in this chapter. (But you haven't done that, have
+you? What with the warning not to do it at the beginning of the chapter.)
+Or when the \gls{linktext} starts with one of the non-linking
+commands described in \sectionref{sec:glsnolink}. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+   name={\glsentrytext{sample} two},
+   sort={sample two},
+   description={another example}
+ }
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\glsentrytext{\MakeUppercase sample} two
+\end{verbatim}
+This will generate an error because there's no entry with the label
+\qt{\texttt{\cs{MakeUppercase} sample}}. The best solution here is to 
+write the term out in the \gloskey{text} field and use the command
+in the \gloskey{name} field. If you don't use \cs{glsname} anywhere
+in your document, you can use \cs{gls} in the \gloskey{name} field:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\newglossaryentry{sample2}{
+   name={\gls{sample} two},
+   sort={sample two},
+   text={sample two},
+   description={another example}
+ }
+\end{verbatim}
 
-\section{Style Hook}
-\label{sec:isthook}
+If the \gls{linktext} starts with a command that has an optional
+argument or with multiple arguments where the actual text isn't in
+the first argument, then \cs{makefirstuc} will also fail. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+ name={\textcolor{blue}{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+Now the \gls{linktext} will be set to:
+\begin{verbatim}
+\textcolor{\MakeUppercase blue}{sample} phrase
+\end{verbatim}
+This won't work because \verb|\MakeUppercase blue| isn't a recognised
+colour name. In this case you will have to define a helper command where
+the first argument is the text. For example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\blue}[1]{\textcolor{blue}{#1}}
+ name={\blue{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+In fact, since the whole design ethos of \LaTeX\ is the separation
+of content and style, it's better to use a semantic command. For
+example:
+\begin{verbatim}
+\newglossaryentry{sample}{
+\newcommand*{\keyword}[1]{\textcolor{blue}{#1}}
+ name={\keyword{sample} phrase},
+ sort={sample phrase},
+ description={an example}}
+\end{verbatim}
+For further details see the \sty{mfirstuc} user manual.
 
-As from version 4.24, there's a hook that's used near the end of
-\ics{writeist} before the file is closed. You can set the code 
-to be performed then using:
-\begin{definition}[\DescribeMacro\GlsSetWriteIstHook]
-\cs{GlsSetWriteIstHook}\marg{code}
+There are plural forms that are analogous to \cs{gls}:
+\begin{definition}[\DescribeMacro{\glspl}]
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-If you want the \meta{code} to write any information to the 
-file, you need to use
-\begin{definition}[\DescribeMacro\glswrite]
-\cs{write}\cs{glswrite}\marg{style information}
+\begin{definition}[\DescribeMacro{\Glspl}]
+\cs{Glspl}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-Make sure you use the correct format within \meta{style
-information}. For example, if you are using \app{makeindex}:
+\begin{definition}[\DescribeMacro{\GLSpl}]
+\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+These typically determine the link text from the \gloskey{plural} or
+\gloskey{firstplural} keys supplied when the entry was 
+defined using \ics{newglossaryentry} or, if the entry is an
+abbreviation and \cs{setacronymstyle} was used, from the \gloskey{longplural} or
+\gloskey{shortplural} keys.
+
+\begin{important}
+Be careful when you use glossary entries in math mode especially if you 
+are using \sty{hyperref} as it can affect the spacing of subscripts and
+superscripts. For example, suppose you have defined the following
+entry:
 \begin{verbatim}
-\GlsSetWriteIstHook{%
- \write\glswrite{page_precedence "arnAR"}%
- \write\glswrite{line_max 80}%
-}
+\newglossaryentry{Falpha}{name={F_\alpha},
+description=sample}
 \end{verbatim}
-This changes the page type precedence\index{page type precedence|main} and the maximum line length
-used by \app{makeindex}.
+and later you use it in math mode:
+\begin{verbatim}
+$\gls{Falpha}^2$
+\end{verbatim}
+This will result in $F_\alpha{}^2$ instead of $F_\alpha^2$. In this
+situation it's best to bring the superscript into the hyperlink using
+the final \meta{insert} optional argument:
+\begin{verbatim}
+$\gls{Falpha}[^2]$
+\end{verbatim}
+\end{important}
 
-Remember that if you switch to \app{xindy}, this will no longer be
-valid code.
+\begin{definition}[\DescribeMacro{\glsdisp}]
+\cs{glsdisp}\oarg{options}\marg{label}\marg{link text}
+\end{definition}
+This behaves in the same way as the above commands, except
+that the \meta{link text} is explicitly set. There's no final
+optional argument as any inserted material can be added to the
+\meta{link text} argument.
 
-\chapter{Links to Glossary Entries}
-\label{sec:glslink}
+\begin{important}
+Don't use any of the \glslike\ or \glstextlike\ commands in the 
+\meta{link text} argument of \cs{glsdisp}.
+\end{important}
 
-Once you have defined a glossary entry using \ics{newglossaryentry}
-(\sectionref{sec:newglosentry}) or \ics{newacronym} (see
-\sectionref{sec:acronyms}), you can refer to that entry in the
-document using one of the commands listed in
-\sectionref{sec:gls-like} or \sectionref{sec:glstext-like}. The text
-which appears at that point in the document when using one of these
-commands is referred to as the \gls{linktext} (even if there are no
-hyperlinks). These commands also add a line to an external file that
-is used to generate the relevant entry in the glossary. This
-information includes an associated location that is added to the
-\gls{numberlist} for that entry. By default, the location refers to
-the page number. For further information on number lists, see
-\sectionref{sec:numberlists}.  These external files need to be
-post-processed by \gls{makeindex} or \gls{xindy} unless you have
-chosen \optsor14. If you don't use \ics{makeglossaries} these external
-files won't be created. (\optsand14 write the information to the
-\filetype{aux} file.)
+\subsection{The \cs{glstext}-Like Commands (First Use Flag Not Queried)}
+\label{sec:glstext-like}
 
-Note that repeated use of these commands for the same entry can
-cause the \gls{numberlist} to become quite long, which may not be
-particular helpful to the reader. In this case, you can use the
-non-indexing commands described in \sectionref{sec:glsnolink} or
-you can use the supplemental \gls{glossaries-extra} package, which
-provides a means to suppress the automated indexing of the commands listed
-in this chapter.
+This section describes the commands that don't change or reference
+the \firstuseflag. As described above, these commands all have a
+star-variant (\texttt{hyper=false}) and a plus-variant
+(\texttt{hyper=true}) and have an optional first argument
+that is a \meta{key}=\meta{value} list. These commands also don't
+use \ics{glsentryfmt} or the equivalent definition provided by
+\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). 
+Additional commands for abbreviations are described in
+\sectionref{sec:acronyms}.
 
-\begin{important}
-I strongly recommend that you don't use the commands
-defined in this chapter in the arguments of sectioning or caption
-commands or any other command that has a moving argument.
+Apart from \ics{glslink}, the commands described in this section
+also have a \emph{final} optional argument \meta{insert} which may
+be used to insert material into the automatically generated text.
+See the caveat above in \sectionref{sec:gls-like}.
 
-Aside from problems with expansion issues, PDF bookmarks and
-possible nested hyperlinks in the table of contents (or list of
-whatever) any use of the commands described in \sectionref{sec:gls-like}
-will have their \firstuseflag\ unset when they appear in the table
-of contents (or list of whatever).
+\begin{definition}[\DescribeMacro{\glslink}]
+\cs{glslink}\oarg{options}\marg{label}\marg{link text}
+\end{definition}
+This command explicitly sets the \gls{linktext} as given in the
+final argument.
+
+\begin{important}
+Don't use any of the \glslike\ or \glstextlike\ commands in the 
+argument of \cs{glslink}. By extension, this means that you can't
+use them in the value of fields that are used to form
+\gls{linktext}.
 \end{important}
 
-The above warning is particularly important if you are using the
-\styfmt{glossaries} package in conjunction with the \sty{hyperref}
-package. Instead, use one of the \emph{expandable} commands listed in
-\sectionref{sec:glsnolink} (such as \ics{glsentrytext} \emph{but
-not} the non-expandable
-case changing versions like \ics{Glsentrytext}). Alternatively, provide an
-alternative via the optional argument to the sectioning\slash caption
-command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples:
+\begin{definition}[\DescribeMacro{\glstext}]
+\cs{glstext}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{text} key as the
+\gls{linktext}.
+
+There are also analogous commands:
+\begin{definition}[\DescribeMacro{\Glstext}]
+\cs{Glstext}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLStext}]
+\cs{GLStext}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+These convert the first character or all the characters to
+uppercase, respectively. See the note on \cs{Gls} above for details
+on the limitations of converting the first letter to upper case.
+
+There's no equivalent command for title-casing, but you
+can use the more generic command \ics{glsentrytitlecase}
+in combination with \cs{glslink}. For example:
 \begin{verbatim}
-\chapter{An overview of \glsentrytext{perl}}
-\chapter[An overview of Perl]{An overview of \gls{perl}}
-\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
+\glslink{sample}{\glsentrytitlecase{sample}{text}}
 \end{verbatim}
-If you want to retain the formatting that's available through
-commands like \cs{acrshort} (for example, if you are using one of
-the small caps styles), then you might want to consider the
-\gls{glossaries-extra} package which provides commands
-for this purpose.
+(See \sectionref{sec:glsnolink}.)
 
-If you want the \gls{linktext} to produce a hyperlink to the
-corresponding entry details in the glossary, you should load the
-\sty{hyperref} package \emph{before} the \styfmt{glossaries}
-package. That's what I've done in this document, so if you see a
-hyperlinked term, such as \gls{linktext}, you can click on the word
-or phrase and it will take you to a brief description in this
-document's glossary.
+\begin{definition}[\DescribeMacro{\glsfirst}]
+\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{first} key as the
+\gls{linktext}.
 
-\begin{important}
-If you use the \sty{hyperref} package, I strongly recommend you use
-\app{pdflatex} rather than \app{latex} to compile your document, if
-possible. The DVI format of \LaTeX\ has limitations with the
-hyperlinks that can cause a problem when used with the
-\styfmt{glossaries} package. Firstly, the DVI format can't break a
-hyperlink across a line whereas PDF\LaTeX\ can. This means that long
-glossary entries (for example, the full form of an acronym) won't be
-able to break across a line with the DVI format. Secondly, the DVI
-format doesn't correctly size hyperlinks in subscripts or
-superscripts. This means that if you define a term that may be used
-as a subscript or superscript, if you use the DVI format, it won't
-come out the correct size.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsfirst}]
+\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSfirst}]
+\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-These are limitations of the DVI format not of the \sty{glossaries}
-package.
+\begin{important}
+The value of the \gloskey{first} key (and \gloskey{firstplural} key)
+doesn't necessarily match the text produced by \ics{gls} (or \ics{glspl}) on
+\firstuse\ as the \gls{linktext} used by \ics{gls} may be modified
+through commands like \ics{defglsentry}. (Similarly, the value of the
+\gloskey{text} and \gloskey{plural} keys don't necessarily match
+the \gls*{linktext} used by \cs{gls} or \cs{glspl} on subsequent
+use.)
 \end{important}
 
-It may be that you only want terms in certain glossaries to have
-hyperlinks, but not for other glossaries. In this case, you can use the
-package option \pkgopt{nohypertypes} to identify the glossary lists
-that shouldn't have hyperlinked \gls{linktext}. See 
-\sectionref{sec:pkgopts-general} for further details.
+\begin{definition}[\DescribeMacro{\glsplural}]
+\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{plural} key as the
+\gls{linktext}.
 
-The way the \gls{linktext} is displayed depends on 
-\begin{definition}[\DescribeMacro{\glstextformat}]
-\cs{glstextformat}\marg{text}
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsplural}]
+\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSplural}]
+\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert}
 \end{definition}
-For example, to make all \gls{linktext} appear in a sans-serif
-font, do:
-\begin{verbatim}
-\renewcommand*{\glstextformat}[1]{\textsf{#1}}
-\end{verbatim}
-Further customisation can be done via \ics{defglsentryfmt} or by
-redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for
-further details.
 
-Each entry has an associated conditional referred to as the
-\firstuseflag. Some of the commands described in this chapter
-automatically unset this flag and can also use it
-to determine what text should be displayed. These types of commands
-are the \glslike\ commands and are described in
-\sectionref{sec:gls-like}. The commands that don't reference or change
-the \firstuseflag\ are \glstextlike\ commands and are described
-in \sectionref{sec:glstext-like}.  See \sectionref{sec:glsunset} for 
-commands that unset (mark the entry as having been used) or reset
-(mark the entry as not used) the \firstuseflag\ without referencing
-the entries.
+\begin{definition}[\DescribeMacro{\glsfirstplural}]
+\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{firstplural} key as the
+\gls{linktext}.
 
-The \glslike\ and \glstextlike\ commands all take a first
-optional argument that is a comma-separated list of
-\meta{key}=\meta{value} options, described below. They also have a
-star-variant, which inserts \texttt{hyper=false} at the start of the
-list of options and a plus-variant, which inserts
-\texttt{hyper=true} at the start of the list of options. For example
-\verb|\gls*{sample}| is the same as \verb|\gls[hyper=false]{sample}|
-and \verb|\gls+{sample}| is the same as
-\verb|\gls[hyper=true]{sample}|, whereas just \verb|\gls{sample}|
-will use the default hyperlink setting which depends on a number of
-factors (such as whether the entry is in a glossary that has been
-identified in the \pkgopt{nohypertypes} list).  You can override the
-\gloskey[glslink]{hyper} key in the variant's optional argument, for
-example, \verb|\gls*[hyper=true]{sample}| but this creates
-redundancy and is best avoided. The \gls{glossaries-extra} package
-provides the option to add a third custom variant.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsfirstplural}]
+\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSfirstplural}]
+\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+
+\begin{definition}[\DescribeMacro{\glsname}]
+\cs{glsname}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{name} key as the
+\gls{linktext}. Note that this may be different from the values of
+the \gloskey{text} or \gloskey{first} keys. In general it's better
+to use \cs{glstext} or \cs{glsfirst} instead of \cs{glsname}.
+
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsname}]
+\cs{Glsname}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSname}]
+\cs{GLSname}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
 \begin{important}
-Avoid nesting these commands. For example don't do
-\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}}
-as this is likely to cause problems. By implication, this
-means that you should avoid using any of these commands within
-the \gloskey{text}, \gloskey{first}, \gloskey{short} or
-\gloskey{long} keys (or their plural equivalent) or any
-other key that you plan to access through these commands.
-(For example, the \gloskey{symbol} key if you intend to use
-\cs{glssymbol}.)
+In general it's best to avoid \cs{Glsname} with acronyms. Instead,
+consider using \cs{Acrlong}, \cs{Acrshort} or \cs{Acrfull}.
 \end{important}
 
-The keys listed below are available for the optional argument.
-The \gls{glossaries-extra} package provides additional keys.
-(See the \gls*{glossaries-extra} manual for further details.)
-\begin{description}
-\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can
-be used to enable\slash disable the hyperlink to the relevant entry
-in the glossary. If this key is omitted, the value is determined by current
-settings, as indicated above. For example, when used with a \glslike\ command, if this is the first
-use and the \pkgopt[false]{hyperfirst} package option has been used,
-then the default value is \texttt{hyper=false}. The hyperlink can be
-forced on using \texttt{hyper=true} unless the hyperlinks have been
-suppressed using \ics{glsdisablehyper}. You must load the
-\sty{hyperref} package before the \sty{glossaries} package to
-ensure the hyperlinks work.
+\begin{definition}[\DescribeMacro{\glssymbol}]
+\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{symbol} key as the
+\gls{linktext}.
 
-\item[{\gloskey[glslink]{format}}] This specifies how to format the
-associated location number for this entry in the glossary. This 
-value is equivalent to the \gls{makeindex} encap value, and (as
-with \ics{index}) the value needs to be the name of a command
-\emph{without} the initial backslash. As with \ics{index}, the
-characters \verb"(" and \verb")" can also be used to specify the
-beginning and ending of a number range and they must be in matching
-pairs. (For example, \verb|\gls[format={(}]{sample}| on one page
-to start the range and later \verb|\gls[format={)}]{sample}| to close 
-the range.)  Again as with \ics{index}, the command should be the
-name of a command which takes an argument (which will be the
-associated location).  Be careful not to use a declaration (such as
-\texttt{bfseries}) instead of a text block command (such as
-\texttt{textbf}) as the effect is not guaranteed to be localised. If
-you want to apply more than one style to a given entry (e.g.\
-\textbf{bold} and \emph{italic}) you will need to create a command
-that applies both formats, e.g.\ 
-\begin{verbatim}
-\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}
-\end{verbatim}
-and use that command.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glssymbol}]
+\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSsymbol}]
+\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-In this document, the standard formats refer to the standard text
-block commands such as \ics{textbf} or \ics{emph} or any of the
-commands listed in \tableref{tab:hyperxx}. You can combine a range
-and format using \verb|(|\meta{format}  to start the range and
-\verb|)|\meta{format} to end the range.  The \meta{format} part must
-match. For example, \verb|format={(emph}| and \verb|format={)emph}|.
+\begin{definition}[\DescribeMacro{\glsdesc}]
+\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the \gloskey{description} key as the
+\gls{linktext}.
 
-\begin{important}
-If you use \gls{xindy} instead of \gls{makeindex}, you
-must specify any non-standard formats that you want to use
-with the \gloskey[glslink]{format} key using
-\ics{GlsAddXdyAttribute}\marg{name}. So if you use
-\gls*{xindy} with the above example, you would need to add:
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsdesc}]
+\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSdesc}]
+\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+
+If you want the title case version you can use
 \begin{verbatim}
-\GlsAddXdyAttribute{textbfem}
+\glslink{sample}{\glsentrytitlecase{sample}{desc}}
 \end{verbatim}
-See \sectionref{sec:xindy} for further details.
-\end{important}
-
-If you are using hyperlinks and you want to change the font of the
-hyperlinked location, don't use \ics{hyperpage} (provided by the
-\sty{hyperref} package) as the locations may not refer to a page
-number.  Instead, the \styfmt{glossaries} package provides number
-formats listed in \tableref{tab:hyperxx}. These commands are
-designed to work with the particular location formats created by
-\gls{makeindex} and \gls{xindy} and shouldn't be used in other
-contexts.
 
-\begin{table}[htbp]
-\caption{Predefined Hyperlinked Location Formats}
-\label{tab:hyperxx}
-\centering
-\vskip\baselineskip
-\begin{tabular}{ll}
-\locfmt{hyperrm} & serif hyperlink\\
-\locfmt{hypersf} & sans-serif hyperlink\\
-\locfmt{hypertt} & monospaced hyperlink\\
-\locfmt{hyperbf} & bold hyperlink\\
-\locfmt{hypermd} & medium weight hyperlink\\
-\locfmt{hyperit} & italic hyperlink\\
-\locfmt{hypersl} & slanted hyperlink\\
-\locfmt{hyperup} & upright hyperlink\\
-\locfmt{hypersc} & small caps hyperlink\\
-\locfmt{hyperemph} & emphasized hyperlink
-\end{tabular}
-\par
-\end{table}
+\begin{definition}[\DescribeMacro{\glsuseri}]
+\cs{glsuseri}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user1} key as the \gls{linktext}.
 
-Note that if the \ics{hyperlink} command hasn't been defined, the
-\texttt{hyper}\meta{xx} formats are equivalent to the analogous
-\texttt{text}\meta{xx} font commands (and \texttt{hyperemph} is
-equivalent to \texttt{emph}). If you want to make a new format, you
-will need to define a command which takes one argument and use that.
-For example, if you want the location number to be in a bold
-sans-serif font, you can define a command called, say,
-\ics{hyperbsf}:
-\begin{verbatim}
-\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
-\end{verbatim}
-and then use \texttt{hyperbsf} as the value for the \gloskey[glslink]{format}
-key.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi
-\qt{Displaying the glossary} in the documented code,
-\texttt{glossaries-code.pdf}.} 
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuseri}]
+\cs{Glsuseri}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseri}]
+\cs{GLSuseri}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\begin{important}
-When defining a custom location format command that uses one of the
-\csmeta{hyper}{xx}{} commands, make sure that the argument of
-\csmeta{hyper}{xx}{} is just the location. Any formatting must be
-outside of \csmeta{hyper}{xx}{} (as in the above \cs{hyperbfsf}
-example).
-\end{important}
+\begin{definition}[\DescribeMacro{\glsuserii}]
+\cs{glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user2} key as the \gls{linktext}.
 
-Remember that if you use \gls{xindy}, you
-will need to add this to the list of location \ixindyattrs attributes:
-\begin{verbatim}
-\GlsAddXdyAttribute{hyperbsf}
-\end{verbatim}
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuserii}]
+\cs{Glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuserii}]
+\cs{GLSuserii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\item[{\gloskey[glslink]{counter}}] This specifies which counter
-to use for this location. This overrides the default counter
-used by this entry. (See also \sectionref{sec:numberlists}.)
+\begin{definition}[\DescribeMacro{\glsuseriii}]
+\cs{glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user3} key as the \gls{linktext}.
 
-\item[{\gloskey[glslink]{local}}] This is a boolean key that only
-makes a difference when used with \glslike\ commands that change the
-entry's \gls{firstuseflag}. If \texttt{local=true}, the change to
-the \gls*{firstuseflag} will be localised to the current scope. The
-default is \texttt{local=false}.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuseriii}]
+\cs{Glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseriii}]
+\cs{GLSuseriii}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\item[{\xtrgloskey[glslink]{noindex}}] This is a boolean key that
-suppresses the indexing. Only available with \gls{glossaries-extra}.
+\begin{definition}[\DescribeMacro{\glsuseriv}]
+\cs{glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user4} key as the \gls{linktext}.
 
-\item[{\xtrgloskey[glslink]{hyperoutside}}] This is a boolean key that
-determines whether to put the hyperlink outside of \ics{glstextformat}. 
-Only available with \gls{glossaries-extra}.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuseriv}]
+\cs{Glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuseriv}]
+\cs{GLSuseriv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\item[{\xtrgloskey[glslink]{wrgloss}}] This key determines
-whether to index before (\texttt{wrgloss\dequals before}) or after
-(\texttt{wrgloss\dequals after}) the \gls{linktext}.
-Only available with \gls{glossaries-extra}.
+\begin{definition}[\DescribeMacro{\glsuserv}]
+\cs{glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user5} key as the \gls{linktext}.
 
-\item[{\xtrgloskey[glslink]{textformat}}] This key identifies the
-name of the control sequence to encapsulate the \gls{linktext}
-instead of the default \ics{glstextformat}.
-Only available with \gls{glossaries-extra}.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuserv}]
+\cs{Glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuserv}]
+\cs{GLSuserv}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\item[{\xtrgloskey[glslink]{prefix}}] This key locally redefines
-\ics{glolinkprefix} to the given value.
-Only available with \gls{glossaries-extra}.
+\begin{definition}[\DescribeMacro{\glsuservi}]
+\cs{glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+This command always uses the value of the 
+\gloskey{user6} key as the \gls{linktext}.
 
-\item[{\xtrgloskey[glslink]{thevalue}}] This key explicitly sets the
-location.
-Only available with \gls{glossaries-extra}.
+There are also analogous uppercasing commands:
+\begin{definition}[\DescribeMacro{\Glsuservi}]
+\cs{Glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\GLSuservi}]
+\cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert}
+\end{definition}
 
-\item[{\xtrgloskey[glslink]{theHvalue}}] This key explicitly sets the
-hyperlink location.
-Only available with \gls{glossaries-extra}.
+\subsection{Changing the format of the link text}
+\label{sec:glsdisplay}
 
-\end{description}
+\begin{xtr}
+The \gls{glossaries-extra} package provides ways of altering the
+format according to the category. See the \gls{glossaries-extra}
+manual for further details.
+\end{xtr}
+
+The default format of the \gls{linktext} for the \glslike\ commands 
+is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now
+deprecated. Backwards compatibility should be preserved but
+you may need to use the \pkgopt{compatible-3.07} option}:
+\begin{definition}[\DescribeMacro{\glsentryfmt}]
+\cs{glsentryfmt}
+\end{definition}
+This may be redefined but if you only want the change the display style 
+for a given glossary, then you need to use
+\begin{definition}[\DescribeMacro{\defglsentryfmt}]
+\cs{defglsentryfmt}\oarg{type}\marg{definition}
+\end{definition}
+instead of redefining \cs{glsentryfmt}. The optional first argument 
+\meta{type} is the glossary type. This defaults to
+\ics{glsdefaulttype} if omitted. The second argument is the
+entry format definition.
 
 \begin{important}
-The \gls{linktext} isn't scoped by default with just the base
-\styfmt{glossaries} package. Any unscoped
-declarations in the \gls{linktext} may affect subsequent text.
+Note that \cs{glsentryfmt} is the default display format for
+entries. Once the display format has been changed for an individual
+glossary using \ics{defglsentryfmt}, redefining \cs{glsentryfmt}
+won't have an effect on that glossary, you must instead use
+\cs{defglsentryfmt} again. Note that glossaries that have
+been identified as lists of acronyms (via the package option
+\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, 
+see \sectionref{sec:pkgopts-acronym}) use 
+\cs{defglsentryfmt} to set their display style.
 \end{important}
 
-\section{The \cs{gls}-Like Commands (First Use Flag Queried)}
-\label{sec:gls-like}
-
-This section describes the commands that unset (mark as used) the \firstuseflag\ on
-completion, and in most cases they use the current state of the flag
-to determine the text to be displayed. As described above, these
-commands all have a star-variant (\texttt{hyper=false}) and 
-a plus-variant (\texttt{hyper=true}) and have an
-optional first argument that is a \meta{key}=\meta{value} list.
-These commands use \ics{glsentryfmt} or the equivalent definition provided by
-\ics{defglsentryfmt} to determine the automatically generated text
-and its format (see \sectionref{sec:glsdisplay}).
+Within the \meta{definition} argument of \cs{defglsentryfmt}, or if you
+want to redefine \cs{glsentryfmt}, you may use the following
+commands:
 
-Apart from \ics{glsdisp}, the commands described in this section
-also have a \emph{final} optional argument \meta{insert} which may
-be used to insert material into the automatically generated text.
+\begin{definition}[\DescribeMacro{\glslabel}]
+\cs{glslabel}
+\end{definition}
+This is the label of the entry being referenced. As from version
+4.08, you can also access the glossary entry type using:
+\begin{definition}[\DescribeMacro{\glstype}]
+\cs{glstype}
+\end{definition}
+This is defined using \ics{edef} so the replacement text is the
+actual glossary type rather than \verb|\glsentrytype{\glslabel}|.
 
-\begin{important}
-Since the commands have a final optional argument, take care if
-you actually want to display an open square bracket after the command
-when the final optional argument is absent. Insert an empty set of
-braces \verb|{}| immediately before the opening square bracket to
-prevent it from being interpreted as the final argument. For
-example:
-\begin{verbatim}
-\gls{sample} {}[Editor's comment]
-\end{verbatim}
+\begin{definition}[\DescribeMacro{\glscustomtext}]
+\cs{glscustomtext}
+\end{definition}
+This is the custom text supplied in \cs{glsdisp}. It's always empty
+for \ics{gls}, \ics{glspl} and their upper case variants. (You can 
+use \sty{etoolbox}'s \cs{ifdefempty} to determine if
+\cs{glscustomtext} is empty.) 
 
-Don't use any of the \glslike\ or \glstextlike\ commands in the 
-\meta{insert} argument.
-\end{important}
+\begin{definition}[\DescribeMacro{\glsinsert}]
+\cs{glsinsert}
+\end{definition}
+The custom text supplied in the final optional argument to \cs{gls},
+\cs{glspl} and their upper case variants.
 
-Take care using these commands within commands or environments that
-are processed multiple times as this can confuse the first use flag
-query and state change. This includes frames with overlays in
-\cls{beamer} and the \envfmt{tabularx} environment provided by \sty{tabularx}. 
-The \styfmt{glossaries} package automatically deals with this issue
-in \sty{amsmath}'s \envfmt{align} environment. You can apply a patch
-to \sty{tabularx} by placing the following command (new to v4.28) in 
-the preamble:
-\begin{definition}[\DescribeMacro\glspatchtabularx]
-\cs{glspatchtabularx}
+\begin{definition}[\DescribeMacro{\glsifplural}]
+\cs{glsifplural}\marg{true text}\marg{false text}
 \end{definition}
-This does nothing if \sty{tabularx} hasn't been loaded. There's no
-patch available for \cls{beamer}. See \sectionref{sec:glsunset} for
-more details.
+If \cs{glspl}, \cs{Glspl} or \cs{GLSpl} was used, this command does 
+\meta{true text} otherwise it does \meta{false text}.
 
-\begin{definition}[\DescribeMacro{\gls}]
-\cs{gls}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glscapscase}]
+\cs{glscapscase}\marg{no case}\marg{first uc}\marg{all caps}
 \end{definition}
-This command typically determines the \gls{linktext} from the values
-of the \gloskey{text} or \gloskey{first} keys supplied when the
-entry was defined using \ics{newglossaryentry}. However, if the
-entry was defined using \ics{newacronym} and \ics{setacronymstyle} was 
-used, then the \gls*{linktext} will usually be determined from the \gloskey{long} or
-\gloskey{short} keys.
+If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no
+case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first
+uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}.
 
-There are two upper case variants:
-\begin{definition}[\DescribeMacro{\Gls}]
-\cs{Gls}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro\glsifhyperon]
+\cs{glsifhyperon}\marg{hyper true}\marg{hyper false}
+\end{definition}
+This will do \meta{hyper true} if the hyperlinks are on for the
+current reference, otherwise it will do \meta{hyper false}. The
+hyperlink may be off even if it wasn't explicitly switched off with
+the \gloskey[glslink]{hyper} key or the use of a starred command.
+It may be off because the \sty{hyperref} package hasn't been loaded
+or because \ics{glsdisablehyper} has been used or because the entry
+is in a glossary type that's had the hyperlinks switched off (using
+\pkgopt{nohypertypes}) or because it's the \firstuse\ and the
+hyperlinks have been suppressed on first use.
+
+\begin{important}
+The \cs{glsifhyperon} command should be used instead of 
+\ics{glsifhyper}, which is now deprecated (and no longer documented). 
+\end{important}
+
+If you want to know if the command used to reference
+this entry was used with the star or plus variant, you can use:
+\begin{definition}[\DescribeMacro\glslinkvar]
+\cs{glslinkvar}\marg{unmodified}\marg{star}\marg{plus}
+\end{definition} 
+This will do \meta{unmodified} if the unmodified version was used,
+or will do \meta{star} if the starred version was used, or
+will do \meta{plus} if the plus version was used.
+Note that this doesn't take into account if the 
+\gloskey[glslink]{hyper} key was used to override the default
+setting, so this command shouldn't be used to guess whether or not
+the hyperlink is on for this reference.
+
+Note that you can also use commands such as \ics{ifglsused} within
+the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}).
+
+The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural},
+\ics{glscapscase}, \ics{glsinsert} and \ics{glscustomtext} are
+typically updated at the start of the \glslike\ and \glstextlike\
+commands so they can usually be accessed in the hook user commands,
+such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}.
+
+\begin{important}
+This means that using commands like \ics{gls} within the fields
+that are accessed using the \glslike\ or \glstextlike\ commands
+(such as the \gloskey{first}, \gloskey{text}, \gloskey{long}
+or \gloskey{short} keys) will cause a problem. The entry formatting
+performed by \cs{glsentryfmt} and related commands isn't scoped
+(otherwise if would cause problems for \cs{glspostlinkhook} which
+may need to look ahead as well as look behind).
+This means that any nested commands will, at the very least, change 
+the label stored in \cs{glslabel}.
+\end{important}
+
+If you only want to make minor modifications to \cs{glsentryfmt},
+you can use
+\begin{definition}[\DescribeMacro{\glsgenentryfmt}]
+\cs{glsgenentryfmt}
+\end{definition}
+This uses the above commands to display just the \gloskey{first}, 
+\gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys 
+(or the custom text) with the insert text appended.
+
+Alternatively, if you want to change the entry format for abbreviations
+(defined via \ics{newacronym}) you can use:
+\begin{definition}[\DescribeMacro{\glsgenacfmt}]
+\cs{glsgenacfmt}
+\end{definition}
+This uses the values from the \gloskey{long}, \gloskey{short},
+\gloskey{longplural} and \gloskey{shortplural} keys, rather than
+using the \gloskey{text}, \gloskey{plural}, \gloskey{first} 
+and \gloskey{firstplural} keys. The first use singular text is obtained via:
+\begin{definition}[\DescribeMacro{\genacrfullformat}]
+\cs{genacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+instead of from the \gloskey{first} key, and the first use plural
+text is obtained via:
+\begin{definition}[\DescribeMacro{\genplacrfullformat}]
+\cs{genplacrfullformat}\marg{label}\marg{insert}
+\end{definition}
+instead of from the \gloskey{firstplural} key.
+In both cases, \meta{label} is the entry's label and \meta{insert}
+is the insert text provided in the final optional argument of
+commands like \ics{gls}. The default behaviour is to do the long
+form (or plural long form) followed by \meta{insert} and a~space and the short form (or plural
+short form) in parentheses, where the short form is in the argument
+of \ics{firstacronymfont}. There are also first letter upper case
+versions:
+\begin{definition}[\DescribeMacro{\Genacrfullformat}]
+\cs{Genacrfullformat}\marg{label}\marg{insert}
 \end{definition}
 and
-\begin{definition}[\DescribeMacro{\GLS}]
-\cs{GLS}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Genplacrfullformat}]
+\cs{Genplacrfullformat}\marg{label}\marg{insert}
 \end{definition}
-which make the first letter of the link text or all the link text
-upper case, respectively. For the former, the uppercasing of the
-first letter is performed by \ics{makefirstuc}.
+By default these perform a protected expansion on their no-case-change
+equivalents and then use \ics{makefirstuc} to convert the first
+character to upper case. If there are issues caused by this
+expansion, you will need to redefine those commands to explicitly
+use commands like \ics{Glsentrylong} (which is what the predefined
+acronym styles, such as \acrstyle{long-short}, do). Otherwise, you
+only need to redefine \ics{genacrfullformat} and
+\ics{genplacrfullformat} to change the behaviour of
+\ics{glsgenacfmt}. See \sectionref{sec:acronyms} for further details
+on changing the style of acronyms.
 
 \begin{important}
-The first letter uppercasing command \cs{makefirstuc} has
-limitations which must be taken into account if you use \cs{Gls} or
-any of the other commands that convert the first letter to
-uppercase. 
+Note that \cs{glsentryfmt} (or the formatting given by \cs{defglsentryfmt}) 
+is not used by the \glstextlike\ commands.
 \end{important}
-The upper casing is performed as follows:
-\begin{itemize}
-\item If the first thing in the \gls{linktext} is a command follow
-by a group, the upper casing is performed on the first object of the
-group. For example, if an entry has been defined as
+
+As from version 4.16, both the \glslike\ and \glstextlike\ commands
+use
+\begin{definition}[\DescribeMacro\glslinkpostsetkeys]
+\cs{glslinkpostsetkeys}
+\end{definition}
+after the \meta{options} are set. This macro does nothing by default
+but can be redefined. (For example, to switch off the hyperlink
+under certain conditions.) This version also introduces
+\begin{definition}[\DescribeMacro\glspostlinkhook]
+\cs{glspostlinkhook}
+\end{definition}
+which is done after the link text has been displayed and also
+\emph{after} the \firstuseflag\ has been unset (see
+example~\ref{ex:dotabbr}).
+
+\begin{example}{Custom Entry Display in Text}{ex:customfmt}
+Suppose you want a glossary of measurements and
+units, you can use the \gloskey{symbol} key to store the unit:
 \begin{verbatim}
-\newglossaryentry{sample}{
- name={\emph{sample} phrase},
- sort={sample phrase},
- description={an example}}
+\newglossaryentry{distance}{name=distance,
+description={The length between two points},
+symbol={km}}
 \end{verbatim}
-Then \cs{Gls}\verb|{sample}| will set the \gls{linktext}
-to\footnote{I've used \cs{MakeUppercase} in all the examples for clarity, but it
-will actually use \cs{mfirstucMakeUppercase}.}
+and now suppose you want \verb|\gls{distance}| to produce
+\qt{distance (km)} on \firstuse, then you can redefine
+\ics{glsentryfmt} as follows:
 \begin{verbatim}
-\emph{\MakeUppercase sample} phrase
+\renewcommand*{\glsentryfmt}{%
+  \glsgenentryfmt
+  \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}%
+}
 \end{verbatim}
-which will appear as \emph{\MakeUppercase sample} phrase.
 
-\item If the first thing in the \gls{linktext} isn't a command or is
-a command but isn't followed by a group, then the upper casing will
-be performed on that first thing. For example, if an entry has been
-defined as:
+(Note that I've used \ics{glsentrysymbol} rather than \ics{glssymbol}
+to avoid nested hyperlinks.)
+
+Note also that all of the \gls{linktext} will be formatted according
+to \ics{glstextformat} (described earlier). So if you do, say:
 \begin{verbatim}
-\newglossaryentry{sample}{
-  name={\oe-ligature},
-  sort={oe-ligature},
-  description={an example}
+\renewcommand{\glstextformat}[1]{\textbf{#1}}
+\renewcommand*{\glsentryfmt}{%
+  \glsgenentryfmt
+  \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}%
 }
 \end{verbatim}
-Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} to
-\begin{verbatim}
-\MakeUppercase \oe-ligature
-\end{verbatim}
-which will appear as \MakeUppercase \oe-ligature.
-
-\item If you have \sty{mfirstuc} v2.01 or above, an extra case is
-added. If the first thing is \cs{protect} it will be discarded and
-the above rules will then be tried.
-
-\end{itemize}
-(Note the use of the \gloskey{sort} key in the above examples.)
+then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}.
 
-There are hundreds of \LaTeX\ packages that altogether define
-thousands of commands with various syntax and it's impossible for
-\sty{mfirstuc} to take them all into account. The above rules are quite
-simplistic and are designed for \gls{linktext} that starts with
-a~text-block command (such as \cs{emph}) or a command that produces 
-a character (such as \cs{oe}). This means that if your \gls{linktext}
-starts with something that doesn't adhere to \sty{mfirstuc}'s assumptions
-then things are likely to go wrong.
+For a complete document, see the sample file \samplefile{-entryfmt}.
+\end{example}
 
-For example, starting with a math-shift symbol:
+\begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt}
+Suppose you have created a new glossary called
+\texttt{notation} and you want to change the way the entry is
+displayed on \firstuse\ so that it includes the symbol, you can do:
 \begin{verbatim}
-\newglossaryentry{sample}{
-  name={$a$},
-  sort={a},
-  description={an example}
-}
+\defglsentryfmt[notation]{\glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space
+   (denoted \glsentrysymbol{\glslabel})}}
 \end{verbatim}
-This falls into case~2 above, so the \gls{linktext} will be set to
+Now suppose you have defined an entry as follows:
 \begin{verbatim}
-\MakeUppercase $a$
+\newglossaryentry{set}{type=notation,
+  name=set,
+  description={A collection of objects},
+  symbol={$S$}
+}
 \end{verbatim}
-This attempts to uppercase the math-shift \verb|$|, which will go
-wrong. In this case it's not appropriate to perform any
-case-changing, but it may be that you want to use \cs{Gls}
-programmatically without checking if the text contains any maths.
-In this case, the simplest solution is to insert an empty brace at
-the start:
+The \glslink{firstuse}{first time} you reference this entry it will be displayed as:
+\qt{set (denoted $S$)} (assuming \ics{gls} was used).
+
+Alternatively, if you expect all the symbols to be set in math mode,
+you can do:
 \begin{verbatim}
-\newglossaryentry{sample}{
-  name={{}$a$},
-  sort={a},
-  description={an example}
-}
+\defglsentryfmt[notation]{\glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space
+   (denoted $\glsentrysymbol{\glslabel}$)}}
 \end{verbatim}
-Now the \gls{linktext} will be set to
+and define entries like this:
 \begin{verbatim}
-\MakeUppercase{}$a$
+\newglossaryentry{set}{type=notation,
+  name=set,
+  description={A collection of objects},
+  symbol={S}
+}
 \end{verbatim}
-and the \cs{uppercase} becomes harmless.
+\end{example}
 
-Another issue occurs when the \gls{linktext} starts with a command
-followed by an argument (case~1) but the argument is a label,
-identifier or something else that shouldn't have a case-change.
-A common example is when the \gls{linktext} starts with one of the
-commands described in this chapter. (But you haven't done that, have
-you? What with the warning not to do it at the beginning of the chapter.)
-Or when the \gls{linktext} starts with one of the non-linking
-commands described in \sectionref{sec:glsnolink}. For example:
-\begin{verbatim}
-\newglossaryentry{sample}{name={sample},description={an example}}
-\newglossaryentry{sample2}{
-   name={\glsentrytext{sample} two},
-   sort={sample two},
-   description={another example}
- }
-\end{verbatim}
-Now the \gls{linktext} will be set to:
-\begin{verbatim}
-\glsentrytext{\MakeUppercase sample} two
-\end{verbatim}
-This will generate an error because there's no entry with the label
-\qt{\texttt{\cs{MakeUppercase} sample}}. The best solution here is to 
-write the term out in the \gloskey{text} field and use the command
-in the \gloskey{name} field. If you don't use \cs{glsname} anywhere
-in your document, you can use \cs{gls} in the \gloskey{name} field:
-\begin{verbatim}
-\newglossaryentry{sample}{name={sample},description={an example}}
-\newglossaryentry{sample2}{
-   name={\gls{sample} two},
-   sort={sample two},
-   text={sample two},
-   description={another example}
- }
-\end{verbatim}
+Remember that if you use the \gloskey{symbol} key, you need to use a
+glossary style that displays the symbol, as many of the styles
+ignore it.
 
-If the \gls{linktext} starts with a command that has an optional
-argument or with multiple arguments where the actual text isn't in
-the first argument, then \cs{makefirstuc} will also fail. For
-example:
+\subsection{Enabling and disabling hyperlinks to glossary entries}
+\label{sec:disablehyperlinks}
+
+If you load the \sty{hyperref} or \sty{html} packages prior to
+loading the \styfmt{glossaries} package, the \glslike\ and
+\glstextlike\ commands will automatically have hyperlinks
+to the relevant glossary entry, unless the \gloskey[glslink]{hyper}
+option has been switched off (either explicitly or through 
+implicit means, such as via the \pkgopt{nohypertypes} package option).
+
+You can disable or enable links using:
+\begin{definition}[\DescribeMacro{\glsdisablehyper}]
+\cs{glsdisablehyper}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro{\glsenablehyper}]
+\cs{glsenablehyper}
+\end{definition}
+respectively. The effect can be localised by placing the commands
+within a group. Note that you should only use \cs{glsenablehyper}
+if the commands \ics{hyperlink} and \ics{hypertarget} have been
+defined (for example, by the \sty{hyperref} package).
+
+You can disable just the \gls{firstuse} links using the package
+option \pkgopt[false]{hyperfirst}. Note that this option only
+affects the \glslike\ commands that recognise the \firstuseflag.
+
+\begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc}
+Suppose I want the \gls*{firstuse} to have a hyperlink to the
+description in a footnote instead of hyperlinking to the relevant
+place in the glossary. First I need to disable the hyperlinks on
+first use via the package option \pkgopt[false]{hyperfirst}:
 \begin{verbatim}
-\newglossaryentry{sample}{
- name={\textcolor{blue}{sample} phrase},
- sort={sample phrase},
- description={an example}}
+\usepackage[hyperfirst=false]{glossaries}
 \end{verbatim}
-Now the \gls{linktext} will be set to:
+Now I need to redefine \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}):
 \begin{verbatim}
-\textcolor{\MakeUppercase blue}{sample} phrase
+\renewcommand*{\glsentryfmt}{%
+  \glsgenentryfmt
+  \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}%
+}
 \end{verbatim}
-This won't work because \verb|\MakeUppercase blue| isn't a recognised
-colour name. In this case you will have to define a helper command where
-the first argument is the text. For example:
+
+Now the first use won't have hyperlinked text, but will be followed
+by a footnote.
+See the sample file \samplefile{-FnDesc} for a complete document.
+\end{example}
+
+Note that the \pkgopt{hyperfirst} option applies to all defined glossaries.  It
+may be that you only want to disable the hyperlinks on
+\gls{firstuse} for glossaries that have a different form on
+\gls*{firstuse}. This can be achieved by noting that since the
+entries that require hyperlinking for all instances have identical
+first and subsequent text, they can be unset via \ics{glsunsetall}
+(see \sectionref{sec:glsunset}) so that the \pkgopt{hyperfirst}
+option doesn't get applied.
+
+\begin{example}{Suppressing Hyperlinks on First Use Just For
+Acronyms}{ex:hyperfirst}
+Suppose I want to suppress the hyperlink on \gls{firstuse} for
+acronyms but not for entries in the main glossary.  I~can load
+the \styfmt{glossaries} package using:
 \begin{verbatim}
-\newglossaryentry{sample}{
-\newcommand*{\blue}[1]{\textcolor{blue}{#1}}
- name={\blue{sample} phrase},
- sort={sample phrase},
- description={an example}}
+\usepackage[hyperfirst=false,acronym]{glossaries}
 \end{verbatim}
-In fact, since the whole design ethos of \LaTeX\ is the separation
-of content and style, it's better to use a semantic command. For
-example:
+Once all glossary entries have been defined I~then do:
 \begin{verbatim}
-\newglossaryentry{sample}{
-\newcommand*{\keyword}[1]{\textcolor{blue}{#1}}
- name={\keyword{sample} phrase},
- sort={sample phrase},
- description={an example}}
+\glsunsetall[main]
 \end{verbatim}
-For further details see the \sty{mfirstuc} user manual.
 
-There are plural forms that are analogous to \cs{gls}:
-\begin{definition}[\DescribeMacro{\glspl}]
-\cs{glspl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glspl}]
-\cs{Glspl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\GLSpl}]
-\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-These typically determine the link text from the \gloskey{plural} or
-\gloskey{firstplural} keys supplied when the entry was 
-defined using \ics{newglossaryentry} or, if the entry is an
-abbreviation and \cs{setacronymstyle} was used, from the \gloskey{longplural} or
-\gloskey{shortplural} keys.
+\end{example}
 
-\begin{important}
-Be careful when you use glossary entries in math mode especially if you 
-are using \sty{hyperref} as it can affect the spacing of subscripts and
-superscripts. For example, suppose you have defined the following
-entry:
+For more complex requirements, you might find it easier to switch
+off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks
+(where required) within the definition of \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}) via \ics{glshyperlink} (see
+\sectionref{sec:glsnolink}).
+
+\begin{example}{Only Hyperlink in Text Mode Not Math
+Mode}{ex:nomathhyper}
+This is a bit of a contrived example, but suppose, for some reason,
+I only want the \glslike\ commands to have
+hyperlinks when used in text mode, but not in math mode. I~can do
+this by adding the glossary to the list of nohypertypes and redefining 
+\ics{glsentryfmt}:
 \begin{verbatim}
-\newglossaryentry{Falpha}{name={F_\alpha},
-description=sample}
+\GlsDeclareNoHyperList{main}
+
+\renewcommand*{\glsentryfmt}{%
+  \ifmmode
+    \glsgenentryfmt
+  \else
+    \glsifhyperon
+    {\glsgenentryfmt}% hyperlink already on
+    {\glshyperlink[\glsgenentryfmt]{\glslabel}}%
+  \fi
+}
 \end{verbatim}
-and later you use it in math mode:
+Note that this doesn't affect the \glstextlike\ commands, which will
+have the hyperlinks off unless they're forced on using the plus
+variant.
+
+See the sample file \samplefile{-nomathhyper} for a complete
+document.
+\end{example}
+
+\begin{example}{One Hyper Link Per Entry Per Chapter}{ex:chap-hyperfirst}
+Here's a more complicated example that will only have the hyperlink
+on the first time an entry is used per chapter. This doesn't involve
+resetting the \firstuseflag. Instead it adds a~new key using
+\ics{glsaddstoragekey} (see \sectionref{sec:glsaddstoragekey}) that
+keeps track of the chapter number that the entry was last used in:
 \begin{verbatim}
-$\gls{Falpha}^2$
+\glsaddstoragekey{chapter}{0}{\glschapnum}
 \end{verbatim}
-This will result in $F_\alpha{}^2$ instead of $F_\alpha^2$. In this
-situation it's best to bring the superscript into the hyperlink using
-the final \meta{insert} optional argument:
+This creates a new user command called \cs{glschapnum} that's
+analogous to \cs{glsentrytext}. The default value for this key is~0.
+I~then define my glossary entries as usual.
+
+Next I redefine the hook \ics{glslinkpostsetkeys}
+(see \sectionref{sec:glsdisplay}) so that it determines the current
+chapter number (which is stored in \cs{currentchap} using
+\cs{edef}). This value is then compared with the value of the
+entry's \texttt{chapter} key that I defined earlier. If they're the
+same, this entry has already been used in this chapter so the
+hyperlink is switched off using \sty{xkeyval}'s \cs{setkeys}
+command. If the chapter number isn't the same, then this entry
+hasn't been used in the current chapter. The \texttt{chapter} field
+is updated using \ics{glsfieldxdef} (\sectionref{sec:fetchset})
+provided the user hasn't switched off the hyperlink.
+(This test is performed using \cs{glsifhyperon}.
 \begin{verbatim}
-$\gls{Falpha}[^2]$
+\renewcommand*{\glslinkpostsetkeys}{%
+ \edef\currentchap{\arabic{chapter}}%
+ \ifnum\currentchap=\glschapnum{\glslabel}\relax
+  \setkeys{glslink}{hyper=false}%
+ \else
+  \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}%
+ \fi
+}
 \end{verbatim}
-\end{important}
+Note that this will be confused if you use \cs{gls} etc when the
+chapter counter is~0. (That is, before the first \cs{chapter}.)
 
-\begin{definition}[\DescribeMacro{\glsdisp}]
-\cs{glsdisp}\oarg{options}\marg{label}\marg{link text}
-\end{definition}
-This behaves in the same way as the above commands, except
-that the \meta{link text} is explicitly set. There's no final
-optional argument as any inserted material can be added to the
-\meta{link text} argument.
+See the sample file \samplefile{-chap-hyperfirst} for a complete
+document.
+\end{example}
+
+\section{Using Glossary Terms Without Links}
+\label{sec:glsnolink}
+
+The commands described in this section display entry details without
+adding any information to the glossary. They don't use
+\ics{glstextformat}, they don't have any optional arguments, they
+don't affect the \firstuseflag\ and, apart from \ics{glshyperlink},
+they don't produce hyperlinks.
 
 \begin{important}
-Don't use any of the \glslike\ or \glstextlike\ commands in the 
-\meta{link text} argument of \cs{glsdisp}.
+Commands that aren't expandable will be ignored by PDF bookmarks, so
+you will need to provide an alternative via \sty{hyperref}'s
+\cs{texorpdfstring} if you want to use them in sectioning commands.
+(This isn't specific to the \styfmt{glossaries} package.) See the
+\sty{hyperref} documentation for further details. All the commands
+that convert the first letter to upper case aren't expandable.
+The other commands depend on whether their corresponding keys were
+assigned non-expandable values.
 \end{important}
 
-\section{The \cs{glstext}-Like Commands (First Use Flag Not Queried)}
-\label{sec:glstext-like}
-
-This section describes the commands that don't change or reference
-the \firstuseflag. As described above, these commands all have a
-star-variant (\texttt{hyper=false}) and a plus-variant
-(\texttt{hyper=true}) and have an optional first argument
-that is a \meta{key}=\meta{value} list. These commands also don't
-use \ics{glsentryfmt} or the equivalent definition provided by
-\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). 
-Additional commands for abbreviations are described in
-\sectionref{sec:acronyms}.
-
-Apart from \ics{glslink}, the commands described in this section
-also have a \emph{final} optional argument \meta{insert} which may
-be used to insert material into the automatically generated text.
-See the caveat above in \sectionref{sec:gls-like}.
-
-\begin{definition}[\DescribeMacro{\glslink}]
-\cs{glslink}\oarg{options}\marg{label}\marg{link text}
-\end{definition}
-This command explicitly sets the \gls{linktext} as given in the
-final argument.
-
-\begin{important}
-Don't use any of the \glslike\ or \glstextlike\ commands in the 
-argument of \cs{glslink}. By extension, this means that you can't
-use them in the value of fields that are used to form
-\gls{linktext}.
-\end{important}
-
-\begin{definition}[\DescribeMacro{\glstext}]
-\cs{glstext}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This command always uses the value of the \gloskey{text} key as the
-\gls{linktext}.
-
-There are also analogous commands:
-\begin{definition}[\DescribeMacro{\Glstext}]
-\cs{Glstext}\oarg{options}\marg{text}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\GLStext}]
-\cs{GLStext}\oarg{options}\marg{text}\oarg{insert}
+If you want to title case a field, you can use:
+\begin{definition}[\DescribeMacro\glsentrytitlecase]
+\cs{glsentrytitlecase}\marg{label}\marg{field}
 \end{definition}
-These convert the first character or all the characters to
-uppercase, respectively. See the note on \cs{Gls} above for details
-on the limitations of converting the first letter to upper case.
-
-There's no equivalent command for title-casing, but you
-can use the more generic command \ics{glsentrytitlecase}
-in combination with \cs{glslink}. For example:
+where \meta{label} is the label identifying the glossary entry,
+\meta{field} is the field label (see \tableref{tab:fieldmap}).
+For example:
 \begin{verbatim}
-\glslink{sample}{\glsentrytitlecase{sample}{text}}
+\glsentrytitlecase{sample}{desc}
 \end{verbatim}
-(See \sectionref{sec:glsnolink}.)
+(If you want title-casing in your glossary style, you might want to
+investigate the \gls{glossaries-extra} package.) This command will
+trigger an error if the entry is undefined.
 
-\begin{definition}[\DescribeMacro{\glsfirst}]
-\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This command always uses the value of the \gloskey{first} key as the
-\gls{linktext}.
+Note that this command has the same limitations as \cs{makefirstuc} which is
+used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case
+the first letter (see the notes about \cs{Gls} in \sectionref{sec:gls-like}).
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsfirst}]
-\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryname}]
+\cs{glsentryname}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSfirst}]
-\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryname}]
+\cs{Glsentryname}\marg{label}
 \end{definition}
+These commands display the name of the glossary entry given by
+\meta{label}, as specified by the \gloskey{name} key.
+\cs{Glsentryname} makes the first letter upper case.
+Neither of these commands check for the existence of \meta{label}.
+The first form \cs{glsentryname} is expandable (unless the name
+contains unexpandable commands). Note that this may be different from the values of
+the \gloskey{text} or \gloskey{first} keys. In general it's better
+to use \cs{glsentrytext} or \cs{glsentryfirst} instead of
+\cs{glsentryname}.
 
 \begin{important}
-The value of the \gloskey{first} key (and \gloskey{firstplural} key)
-doesn't necessarily match the text produced by \ics{gls} (or \ics{glspl}) on
-\firstuse\ as the \gls{linktext} used by \ics{gls} may be modified
-through commands like \ics{defglsentry}. (Similarly, the value of the
-\gloskey{text} and \gloskey{plural} keys don't necessarily match
-the \gls*{linktext} used by \cs{gls} or \cs{glspl} on subsequent
-use.)
+In general it's best to avoid \cs{Glsentryname} with abbreviations. Instead,
+consider using \cs{Glsentrylong}, \cs{Glsentryshort} or \cs{Glsentryfull}.
 \end{important}
 
-\begin{definition}[\DescribeMacro{\glsplural}]
-\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glossentryname}]
+\cs{glossentryname}\marg{label}
 \end{definition}
-This command always uses the value of the \gloskey{plural} key as the
-\gls{linktext}.
+This is like \cs{glsnamefont}\{\cs{glsentryname\marg{label}}\}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles, so if
+you want to change the way the name is formatted in the glossary,
+you can redefine \cs{glsnamefont} to use the required fonts. For
+example:
+\begin{verbatim}
+\renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}}
+\end{verbatim}
+\begin{definition}[\DescribeMacro{\Glossentryname}]
+\cs{Glossentryname}\marg{label}
+\end{definition}
+This is like \cs{glossentryname} but makes the first letter of the
+name upper case.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsplural}]
-\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentrytext}]
+\cs{glsentrytext}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSplural}]
-\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentrytext}]
+\cs{Glsentrytext}\marg{label}
 \end{definition}
+These commands display the subsequent use text for the glossary
+entry given by \meta{label}, as specified by the \gloskey{text} key.
+\cs{Glsentrytext} makes the first letter upper case.
+The first form is expandable (unless the text contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glsfirstplural}]
-\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryplural}]
+\cs{glsentryplural}\marg{label}
 \end{definition}
-This command always uses the value of the \gloskey{firstplural} key as the
-\gls{linktext}.
+\begin{definition}[\DescribeMacro{\Glsentryplural}]
+\cs{Glsentryplural}\marg{label}
+\end{definition}
+These commands display the subsequent use plural text for the
+glossary entry given by \meta{label}, as specified by the
+\gloskey{plural} key. \cs{Glsentryplural} makes the first letter
+upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsfirstplural}]
-\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryfirst}]
+\cs{glsentryfirst}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSfirstplural}]
-\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryfirst}]
+\cs{Glsentryfirst}\marg{label}
 \end{definition}
+These commands display the \firstusetext\ for the glossary entry
+given by \meta{label}, as specified by the \gloskey{first} key.
+\cs{Glsentryfirst} makes the first letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glsname}]
-\cs{glsname}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryfirstplural}]
+\cs{glsentryfirstplural}\marg{label}
 \end{definition}
-This command always uses the value of the \gloskey{name} key as the
-\gls{linktext}. Note that this may be different from the values of
-the \gloskey{text} or \gloskey{first} keys. In general it's better
-to use \cs{glstext} or \cs{glsfirst} instead of \cs{glsname}.
+\begin{definition}[\DescribeMacro{\Glsentryfirstplural}]
+\cs{Glsentryfirstplural}\marg{label}
+\end{definition}
+These commands display the plural form of the \firstusetext\ for the
+glossary entry given by \meta{label}, as specified by the
+\gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first
+letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsname}]
-\cs{Glsname}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentrydesc}]
+\cs{glsentrydesc}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSname}]
-\cs{GLSname}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentrydesc}]
+\cs{Glsentrydesc}\marg{label}
 \end{definition}
+These commands display the description for the glossary entry given
+by \meta{label}. 
 
-\begin{important}
-In general it's best to avoid \cs{Glsname} with acronyms. Instead,
-consider using \cs{Acrlong}, \cs{Acrshort} or \cs{Acrfull}.
-\end{important}
+\cs{Glsentrydesc} makes the first letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glssymbol}]
-\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glossentrydesc}]
+\cs{glossentrydesc}\marg{label}
 \end{definition}
-This command always uses the value of the \gloskey{symbol} key as the
-\gls{linktext}.
+This is like \cs{glsentrydesc}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles to
+display the description.
+\begin{definition}[\DescribeMacro{\Glossentrydesc}]
+\cs{Glossentrydesc}\marg{label}
+\end{definition}
+This is like \cs{glossentrydesc} but converts the first letter to
+upper case. This command is not expandable.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glssymbol}]
-\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentrydescplural}]
+\cs{glsentrydescplural}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSsymbol}]
-\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentrydescplural}]
+\cs{Glsentrydescplural}\marg{label}
 \end{definition}
+These commands display the plural description for the glossary entry
+given by \meta{label}. \cs{Glsentrydescplural} makes the first
+letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glsdesc}]
-\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This command always uses the value of the \gloskey{description} key as the
-\gls{linktext}.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsdesc}]
-\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentrysymbol}]
+\cs{glsentrysymbol}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSdesc}]
-\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentrysymbol}]
+\cs{Glsentrysymbol}\marg{label}
 \end{definition}
+These commands display the symbol for the glossary entry given by
+\meta{label}.
 
-If you want the title case version you can use
-\begin{verbatim}
-\glslink{sample}{\glsentrytitlecase{sample}{desc}}
-\end{verbatim}
+\cs{Glsentrysymbol} makes the first letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glsuseri}]
-\cs{glsuseri}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This command always uses the value of the 
-\gloskey{user1} key as the \gls{linktext}.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuseri}]
-\cs{Glsuseri}\oarg{options}\marg{text}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\GLSuseri}]
-\cs{GLSuseri}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro\glsletentryfield]
+\cs{glsletentryfield}\marg{cs}\marg{label}\marg{field}
 \end{definition}
+This command doesn't display anything. It merely fetches the
+value associated with the given field (where the available field names 
+are listed in \tableref{tab:fieldmap}) and stores the result
+in the control sequence \meta{cs}. For example, to store
+the description for the entry whose label is \qt{apple} in the
+control sequence \verb|\tmp|:
+\begin{verbatim}
+\glsletentryfield{\tmp}{apple}{desc}
+\end{verbatim}
 
-\begin{definition}[\DescribeMacro{\glsuserii}]
-\cs{glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glossentrysymbol}]
+\cs{glossentrysymbol}\marg{label}
 \end{definition}
-This command always uses the value of the 
-\gloskey{user2} key as the \gls{linktext}.
+This is like \cs{glsentrysymbol}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in some of the predefined glossary styles to
+display the symbol.
+\begin{definition}[\DescribeMacro{\Glossentrysymbol}]
+\cs{Glossentrysymbol}\marg{label}
+\end{definition}
+This is like \cs{glossentrysymbol} but converts the first letter to
+upper case. This command is not expandable.
 
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuserii}]
-\cs{Glsuserii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentrysymbolplural}]
+\cs{glsentrysymbolplural}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSuserii}]
-\cs{GLSuserii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentrysymbolplural}]
+\cs{Glsentrysymbolplural}\marg{label}
 \end{definition}
+These commands display the plural symbol for the glossary entry
+given by \meta{label}. \cs{Glsentrysymbolplural} makes the first
+letter upper case.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
 
-\begin{definition}[\DescribeMacro{\glsuseriii}]
-\cs{glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuseri}]
+\cs{glsentryuseri}\marg{label}
 \end{definition}
-This command always uses the value of the 
-\gloskey{user3} key as the \gls{linktext}.
-
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuseriii}]
-\cs{Glsuseriii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuseri}]
+\cs{Glsentryuseri}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSuseriii}]
-\cs{GLSuseriii}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuserii}]
+\cs{glsentryuserii}\marg{label}
 \end{definition}
-
-\begin{definition}[\DescribeMacro{\glsuseriv}]
-\cs{glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuserii}]
+\cs{Glsentryuserii}\marg{label}
 \end{definition}
-This command always uses the value of the 
-\gloskey{user4} key as the \gls{linktext}.
-
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuseriv}]
-\cs{Glsuseriv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuseriii}]
+\cs{glsentryuseriii}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSuseriv}]
-\cs{GLSuseriv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuseriii}]
+\cs{Glsentryuseriii}\marg{label}
 \end{definition}
-
-\begin{definition}[\DescribeMacro{\glsuserv}]
-\cs{glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuseriv}]
+\cs{glsentryuseriv}\marg{label}
 \end{definition}
-This command always uses the value of the 
-\gloskey{user5} key as the \gls{linktext}.
-
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuserv}]
-\cs{Glsuserv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuseriv}]
+\cs{Glsentryuseriv}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSuserv}]
-\cs{GLSuserv}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuserv}]
+\cs{glsentryuserv}\marg{label}
 \end{definition}
-
-\begin{definition}[\DescribeMacro{\glsuservi}]
-\cs{glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuserv}]
+\cs{Glsentryuserv}\marg{label}
 \end{definition}
-This command always uses the value of the 
-\gloskey{user6} key as the \gls{linktext}.
-
-There are also analogous uppercasing commands:
-\begin{definition}[\DescribeMacro{\Glsuservi}]
-\cs{Glsuservi}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsentryuservi}]
+\cs{glsentryuservi}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\GLSuservi}]
-\cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert}
+\begin{definition}[\DescribeMacro{\Glsentryuservi}]
+\cs{Glsentryuservi}\marg{label}
 \end{definition}
+These commands display the value of the user keys for the glossary
+entry given by \meta{label}.
+The lower case forms are expandable (unless the value of the key
+contains unexpandable commands). The commands beginning with an
+upper case letter convert the first letter of the required value to
+upper case and are not expandable. None of these commands check for
+the existence of \meta{label}.
 
-\section{Changing the format of the link text}
-\label{sec:glsdisplay}
-
-\begin{xtr}
-The \gls{glossaries-extra} package provides ways of altering the
-format according to the category. See the \gls{glossaries-extra}
-manual for further details.
-\end{xtr}
-
-The default format of the \gls{linktext} for the \glslike\ commands 
-is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now
-deprecated. Backwards compatibility should be preserved but
-you may need to use the \pkgopt{compatible-3.07} option}:
-\begin{definition}[\DescribeMacro{\glsentryfmt}]
-\cs{glsentryfmt}
-\end{definition}
-This may be redefined but if you only want the change the display style 
-for a given glossary, then you need to use
-\begin{definition}[\DescribeMacro{\defglsentryfmt}]
-\cs{defglsentryfmt}\oarg{type}\marg{definition}
+\begin{definition}[\DescribeMacro{\glshyperlink}]
+\cs{glshyperlink}\oarg{link text}\marg{label}
 \end{definition}
-instead of redefining \cs{glsentryfmt}. The optional first argument 
-\meta{type} is the glossary type. This defaults to
-\ics{glsdefaulttype} if omitted. The second argument is the
-entry format definition.
+This command provides a hyperlink to the glossary entry given by
+\meta{label} \strong{but does not add any information to the
+glossary file}. The link text is given by
+\ics{glsentrytext}\marg{label} by default\footnote{versions before
+3.0 used \ics{glsentryname} as the default, but this could cause
+problems when \gloskey{name} had been \glsd{sanitize}.}, but can be
+overridden using the optional argument. Note that the hyperlink will
+be suppressed if you have used \ics{glsdisablehyper} or if you
+haven't loaded the \sty{hyperref} package.
 
 \begin{important}
-Note that \cs{glsentryfmt} is the default display format for
-entries. Once the display format has been changed for an individual
-glossary using \ics{defglsentryfmt}, redefining \cs{glsentryfmt}
-won't have an effect on that glossary, you must instead use
-\cs{defglsentryfmt} again. Note that glossaries that have
-been identified as lists of acronyms (via the package option
-\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, 
-see \sectionref{sec:pkgopts-acronym}) use 
-\cs{defglsentryfmt} to set their display style.
+If you use \cs{glshyperlink}, you need to ensure that the relevant
+entry has been added to the glossary using any of the commands
+described in \sectionref{sec:glslink} or \sectionref{sec:glsadd}
+otherwise you will end up with an undefined link.
 \end{important}
 
-Within the \meta{definition} argument of \cs{defglsentryfmt}, or if you
-want to redefine \cs{glsentryfmt}, you may use the following
-commands:
-
-\begin{definition}[\DescribeMacro{\glslabel}]
-\cs{glslabel}
-\end{definition}
-This is the label of the entry being referenced. As from version
-4.08, you can also access the glossary entry type using:
-\begin{definition}[\DescribeMacro{\glstype}]
-\cs{glstype}
-\end{definition}
-This is defined using \ics{edef} so the replacement text is the
-actual glossary type rather than \verb|\glsentrytype{\glslabel}|.
-
-\begin{definition}[\DescribeMacro{\glscustomtext}]
-\cs{glscustomtext}
-\end{definition}
-This is the custom text supplied in \cs{glsdisp}. It's always empty
-for \ics{gls}, \ics{glspl} and their upper case variants. (You can 
-use \sty{etoolbox}'s \cs{ifdefempty} to determine if
-\cs{glscustomtext} is empty.) 
-
-\begin{definition}[\DescribeMacro{\glsinsert}]
-\cs{glsinsert}
+The next two commands are only available with \opt1 or with the
+\pkgopt{savenumberlist} package option:
+\begin{definition}[\DescribeMacro{\glsentrynumberlist}]
+\cs{glsentrynumberlist}\marg{label}
 \end{definition}
-The custom text supplied in the final optional argument to \cs{gls},
-\cs{glspl} and their upper case variants.
-
-\begin{definition}[\DescribeMacro{\glsifplural}]
-\cs{glsifplural}\marg{true text}\marg{false text}
+\begin{definition}[\DescribeMacro{\glsdisplaynumberlist}]
+\cs{glsdisplaynumberlist}\marg{label}
 \end{definition}
-If \cs{glspl}, \cs{Glspl} or \cs{GLSpl} was used, this command does 
-\meta{true text} otherwise it does \meta{false text}.
+Both display the \gls{numberlist} for the entry given by
+\meta{label}. When used with \opt1 a~rerun is required to ensure
+this list is up-to-date, when used with \optsor23
+a run of \gls{makeglossaries} (or \gls{makeindex}\slash\gls{xindy})
+followed by one or two runs of \LaTeX\ is required.
 
-\begin{definition}[\DescribeMacro{\glscapscase}]
-\cs{glscapscase}\marg{no case}\marg{first uc}\marg{all caps}
+The first command, \cs{glsentrynumberlist}, simply displays
+the number list as is. The second command,
+\cs{glsdisplaynumberlist}, formats the list using:
+\begin{definition}[\DescribeMacro{\glsnumlistsep}]
+\cs{glsnumlistsep}
 \end{definition}
-If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no
-case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first
-uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}.
-
-\begin{definition}[\DescribeMacro\glsifhyperon]
-\cs{glsifhyperon}\marg{hyper true}\marg{hyper false}
+as the separator between all but the last two elements and
+\begin{definition}[\DescribeMacro{\glsnumlistlastsep}]
+\cs{glsnumlistlastsep}
 \end{definition}
-This will do \meta{hyper true} if the hyperlinks are on for the
-current reference, otherwise it will do \meta{hyper false}. The
-hyperlink may be off even if it wasn't explicitly switched off with
-the \gloskey[glslink]{hyper} key or the use of a starred command.
-It may be off because the \sty{hyperref} package hasn't been loaded
-or because \ics{glsdisablehyper} has been used or because the entry
-is in a glossary type that's had the hyperlinks switched off (using
-\pkgopt{nohypertypes}) or because it's the \firstuse\ and the
-hyperlinks have been suppressed on first use.
+between the final two elements. The defaults are
+\verb*|, | and \verb*| \& |, respectively.
 
 \begin{important}
-The \cs{glsifhyperon} command should be used instead of 
-\ics{glsifhyper}, which is now deprecated (and no longer documented). 
+\cs{glsdisplaynumberlist} is fairly experimental. It works with
+\optsand14, but for \optsor23 it only works when the default counter
+format is used (that is, when the \gloskey[glslink]{format} key is
+set to \texttt{glsnumberformat}).  This command will only work with
+\sty{hyperref} if you choose \optsor14.  If you try using this command
+with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be
+used instead.
 \end{important}
 
-If you want to know if the command used to reference
-this entry was used with the star or plus variant, you can use:
-\begin{definition}[\DescribeMacro\glslinkvar]
-\cs{glslinkvar}\marg{unmodified}\marg{star}\marg{plus}
-\end{definition} 
-This will do \meta{unmodified} if the unmodified version was used,
-or will do \meta{star} if the starred version was used, or
-will do \meta{plus} if the plus version was used.
-Note that this doesn't take into account if the 
-\gloskey[glslink]{hyper} key was used to override the default
-setting, so this command shouldn't be used to guess whether or not
-the hyperlink is on for this reference.
+For further information see \ifpdf section~\ref*{sec:code:glsnolink}
+\fi \qt{Displaying entry details without adding information to the
+glossary} in the documented code (\texttt{glossaries-code.pdf}).
 
-Note that you can also use commands such as \ics{ifglsused} within
-the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}).
+\chapter{Acronyms and Other Abbreviations}
+\label{sec:acronyms}
 
-The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural},
-\ics{glscapscase}, \ics{glsinsert} and \ics{glscustomtext} are
-typically updated at the start of the \glslike\ and \glstextlike\
-commands so they can usually be accessed in the hook user commands,
-such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}.
+\begin{xtr}
+The \gls{glossaries-extra} package provides superior
+abbreviation handling. You may want to consider using that
+package instead of the commands described here.
+\end{xtr}
 
 \begin{important}
-This means that using commands like \ics{gls} within the fields
-that are accessed using the \glslike\ or \glstextlike\ commands
-(such as the \gloskey{first}, \gloskey{text}, \gloskey{long}
-or \gloskey{short} keys) will cause a problem. The entry formatting
-performed by \cs{glsentryfmt} and related commands isn't scoped
-(otherwise if would cause problems for \cs{glspostlinkhook} which
-may need to look ahead as well as look behind).
-This means that any nested commands will, at the very least, change 
-the label stored in \cs{glslabel}.
+Note that although this chapter uses the term \qt{acronym}, you can also
+use the commands described here for initialisms or contractions
+(as in the case of some of the examples given below).
+If the glossary title is no longer applicable (for example, it
+should be \qt{Abbreviations} rather than \qt{Acronyms}) then
+you can change the title either by redefining \ics{acronymname} (see
+\sectionref{sec:languages}) or by using the \gloskey[printglossary]{title}
+key in the optional argument of \ics{printglossary} (or
+\ics{printacronyms}). Alternatively consider using the
+\gls{glossaries-extra} package's \pkgopt*{abbreviations}
+option instead.
 \end{important}
 
-If you only want to make minor modifications to \cs{glsentryfmt},
-you can use
-\begin{definition}[\DescribeMacro{\glsgenentryfmt}]
-\cs{glsgenentryfmt}
-\end{definition}
-This uses the above commands to display just the \gloskey{first}, 
-\gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys 
-(or the custom text) with the insert text appended.
+Acronyms use the same underlying mechanism as terms defined with
+\cs{newglossaryentry} so you can reference them with \ics{gls} and
+\ics{glspl}. The way the acronym is displayed on \gls{firstuse} is
+governed by the acronym style, which should be set before you define
+your acronyms. For example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\setacronymstyle{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\newacronym{xml}{XML}{extensible markup language}
+\begin{document}
+First use: \gls{html} and \gls{xml}.
+Next use: \gls{html} and \gls{xml}.
+\end{document}
+\end{verbatim}
+If you don't specify a style, you will have a less-flexible, but
+backward-compatible, \qt{long (short)} style with just the base
+\styfmt{glossaries} package or the \abbrstyle{short-nolong} style
+(which only displays the short form on \gls{firstuse})
+with \gls{glossaries-extra}.
 
-Alternatively, if you want to change the entry format for abbreviations
-(defined via \ics{newacronym}) you can use:
-\begin{definition}[\DescribeMacro{\glsgenacfmt}]
-\cs{glsgenacfmt}
-\end{definition}
-This uses the values from the \gloskey{long}, \gloskey{short},
-\gloskey{longplural} and \gloskey{shortplural} keys, rather than
-using the \gloskey{text}, \gloskey{plural}, \gloskey{first} 
-and \gloskey{firstplural} keys. The first use singular text is obtained via:
-\begin{definition}[\DescribeMacro{\genacrfullformat}]
-\cs{genacrfullformat}\marg{label}\marg{insert}
-\end{definition}
-instead of from the \gloskey{first} key, and the first use plural
-text is obtained via:
-\begin{definition}[\DescribeMacro{\genplacrfullformat}]
-\cs{genplacrfullformat}\marg{label}\marg{insert}
-\end{definition}
-instead of from the \gloskey{firstplural} key.
-In both cases, \meta{label} is the entry's label and \meta{insert}
-is the insert text provided in the final optional argument of
-commands like \ics{gls}. The default behaviour is to do the long
-form (or plural long form) followed by \meta{insert} and a~space and the short form (or plural
-short form) in parentheses, where the short form is in the argument
-of \ics{firstacronymfont}. There are also first letter upper case
-versions:
-\begin{definition}[\DescribeMacro{\Genacrfullformat}]
-\cs{Genacrfullformat}\marg{label}\marg{insert}
-\end{definition}
-and
-\begin{definition}[\DescribeMacro{\Genplacrfullformat}]
-\cs{Genplacrfullformat}\marg{label}\marg{insert}
+Acronyms are defined using:
+\begin{definition}[\DescribeMacro{\newacronym}]
+\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
 \end{definition}
-By default these perform a protected expansion on their no-case-change
-equivalents and then use \ics{makefirstuc} to convert the first
-character to upper case. If there are issues caused by this
-expansion, you will need to redefine those commands to explicitly
-use commands like \ics{Glsentrylong} (which is what the predefined
-acronym styles, such as \acrstyle{long-short}, do). Otherwise, you
-only need to redefine \ics{genacrfullformat} and
-\ics{genplacrfullformat} to change the behaviour of
-\ics{glsgenacfmt}. See \sectionref{sec:acronyms} for further details
-on changing the style of acronyms.
+
+This creates an entry with the given
+label in the glossary given by \ics{acronymtype}. You can specify a
+different glossary using the \gloskey{type} key within the optional
+argument. The \cs{newacronym} command also uses the \gloskey{long},
+\gloskey{longplural}, \gloskey{short} and \gloskey{shortplural} keys
+in \cs{newglossaryentry} to store the long and abbreviated forms and
+their plurals. 
+
+\begin{xtr}
+If you use \cs{newacronym} with \gls{glossaries-extra}, you need to
+first set the style with:
+\begin{alltt}
+\ics*{setabbreviationstyle}[acronym]\marg{style-name}
+\end{alltt}
+\end{xtr}
+
+Note that the same restrictions on the entry \meta{label}
+in \ics{newglossaryentry} also apply to \cs{newacronym}
+(see \sectionref{sec:newglosentry}).
+Since \ics{newacronym} works like \ics{newglossaryentry}, you can use
+\ics{glsreset} to reset the \gls{firstuseflag}.
 
 \begin{important}
-Note that \cs{glsentryfmt} (or the formatting given by \cs{defglsentryfmt}) 
-is not used by the \glstextlike\ commands.
+If you haven't identified the specified glossary type as a list of
+acronyms (via the package option
+\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, 
+see \sectionref{sec:pkgopts-acronym}) \cs{newacronym} will add it to
+the list and \emph{reset the display style} for that glossary via
+\ics{defglsentryfmt}. If you have a mixture of acronyms and regular
+entries within the same glossary, care is needed if you want to
+change the display style: you must first identify that glossary as a
+list of acronyms and then use \ics{defglsentryfmt} (not redefine
+\ics{glsentryfmt}) before defining your entries. Alternatively, use
+\gls{glossaries-extra} to have better support for a mixed glossary.
 \end{important}
 
-As from version 4.16, both the \glslike\ and \glstextlike\ commands
-use
-\begin{definition}[\DescribeMacro\glslinkpostsetkeys]
-\cs{glslinkpostsetkeys}
-\end{definition}
-after the \meta{options} are set. This macro does nothing by default
-but can be redefined. (For example, to switch off the hyperlink
-under certain conditions.) This version also introduces
-\begin{definition}[\DescribeMacro\glspostlinkhook]
-\cs{glspostlinkhook}
-\end{definition}
-which is done after the link text has been displayed and also
-\emph{after} the \firstuseflag\ has been unset (see
-example~\ref{ex:dotabbr}).
-
-\begin{example}{Custom Entry Display in Text}{ex:customfmt}
-Suppose you want a glossary of measurements and
-units, you can use the \gloskey{symbol} key to store the unit:
-\begin{verbatim}
-\newglossaryentry{distance}{name=distance,
-description={The length between two points},
-symbol={km}}
-\end{verbatim}
-and now suppose you want \verb|\gls{distance}| to produce
-\qt{distance (km)} on \firstuse, then you can redefine
-\ics{glsentryfmt} as follows:
+The optional argument \marg{key-val list} allows you to specify
+additional information. Any key that can be used in the second
+argument of \ics{newglossaryentry} can also be used here in \meta{key-val
+list}.
+For example, \gloskey{description} (when used with one of the styles that
+require a description, described in
+\sectionref{sec:setacronymstyle}) or you can
+override plural forms of \meta{abbrv} or \meta{long} using the
+\gloskey{shortplural} or \gloskey{longplural} keys.
+For example:
 \begin{verbatim}
-\renewcommand*{\glsentryfmt}{%
-  \glsgenentryfmt
-  \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}%
-}
+\newacronym[longplural={diagonal matrices}]%
+  {dm}{DM}{diagonal matrix}
 \end{verbatim}
+If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will
+display: diagonal matrices (DMs). If you want to use
+the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend
+you use \ics{setacronymstyle} to set the display style rather than
+using one of the pre-version 4.02 acronym styles (described in
+\sectionref{sec:pkgopts-old-acronym}).
+
+As with \gloskey{plural}, if \gloskey{longplural} is missing, it's
+obtained by appending \ics{glspluralsuffix} to the singular form. The
+short plural \gloskey{shortplural} is obtained (if not explicitly
+set) by appending \ics{glsacrpluralsuffix} to the short form. These
+commands may be changed by the associated language files, but they
+can't be added to the usual caption hooks as there's no guarantee
+when they'll be expanded (as \hyperref[pluralsuffix]{discussed
+earlier}). 
 
-(Note that I've used \ics{glsentrysymbol} rather than \ics{glssymbol}
-to avoid nested hyperlinks.)
+\begin{xtr}
+A different approach is used by
+\styfmt{glossaries-extra}, which has \icatattrs category attributes
+to determine whether or not to append a suffix when forming the
+default value of \gloskey{shortplural}.
+\end{xtr}
 
-Note also that all of the \gls{linktext} will be formatted according
-to \ics{glstextformat} (described earlier). So if you do, say:
+\begin{important}
+Since \cs{newacronym} sets \verb|type=\acronymtype|,
+if you want to load a file containing acronym definitions using
+\ics{loadglsentries}\oarg{type}\marg{filename}, the optional argument
+\meta{type} will not have an effect unless you explicitly set the
+type as \verb|type=\glsdefaulttype| in the optional argument to
+\ics{newacronym}. See \sectionref{sec:loadglsentries}.
+\end{important}
+
+\begin{example}{Defining an Abbreviation}{ex:newacronym}
+The following defines the abbreviation IDN:
 \begin{verbatim}
-\renewcommand{\glstextformat}[1]{\textbf{#1}}
-\renewcommand*{\glsentryfmt}{%
-  \glsgenentryfmt
-  \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}%
-}
+\setacronymstyle{long-short}
+\newacronym{idn}{IDN}{identification number}
 \end{verbatim}
-then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}.
-
-For a complete document, see the sample file \samplefile{-entryfmt}.
+\verb|\gls{idn}| will produce \qt{identification number (IDN)} on
+\firstuse\ and \qt{IDN} on subsequent uses. If you want to use one
+of the \gls{smallcaps} acronym styles, described in
+\sectionref{sec:setacronymstyle}, you need to use lower case
+characters for the shortened form:
+\begin{verbatim}
+\setacronymstyle{long-sc-short}
+\newacronym{idn}{idn}{identification number}
+\end{verbatim}
+Now \verb|\gls{idn}| will produce \qt{identification number
+(\textsc{idn})} on \firstuse\ and \qt{\textsc{idn}} on subsequent
+uses.
 \end{example}
 
-\begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt}
-Suppose you have created a new glossary called
-\texttt{notation} and you want to change the way the entry is
-displayed on \firstuse\ so that it includes the symbol, you can do:
+\begin{important}
+Avoid nested definitions.
+\end{important}
+
+Recall from the warning in 
+\sectionref{sec:newglosentry} that you should avoid using
+the \glslike\ and \glstextlike\ commands within the value of
+keys like \gloskey{text} and \gloskey{first} due to complications
+arising from nested links. The same applies to abbreviations
+defined using \cs{newacronym}.
+
+For example, suppose you have defined:
 \begin{verbatim}
-\defglsentryfmt[notation]{\glsgenentryfmt
- \ifglsused{\glslabel}{}{\space
-   (denoted \glsentrysymbol{\glslabel})}}
+\newacronym{ssi}{SSI}{server side includes}
+\newacronym{html}{HTML}{hypertext markup language}
 \end{verbatim}
-Now suppose you have defined an entry as follows:
+you may be tempted to do:
 \begin{verbatim}
-\newglossaryentry{set}{type=notation,
-  name=set,
-  description={A collection of objects},
-  symbol={$S$}
-}
+\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
 \end{verbatim}
-The \glslink{firstuse}{first time} you reference this entry it will be displayed as:
-\qt{set (denoted $S$)} (assuming \ics{gls} was used).
+\strong{Don't!} This will break the case-changing commands, such
+as \ics{Gls}, it will cause inconsistencies on \firstuse, and,
+if hyperlinks are enabled, will cause nested hyperlinks. It will
+also confuse the commands used by the entry formatting (such as
+\ics{glslabel}).
 
-Alternatively, if you expect all the symbols to be set in math mode,
-you can do:
+Instead, consider doing:
 \begin{verbatim}
-\defglsentryfmt[notation]{\glsgenentryfmt
- \ifglsused{\glslabel}{}{\space
-   (denoted $\glsentrysymbol{\glslabel}$)}}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}{SSI enabled HTML}
 \end{verbatim}
-and define entries like this:
+or
 \begin{verbatim}
-\newglossaryentry{set}{type=notation,
-  name=set,
-  description={A collection of objects},
-  symbol={S}
-}
-\end{verbatim}
-\end{example}
+\newacronym
+ [description={\gls{ssi} enabled \gls{html}}]
+ {shtml}{SHTML}
+ {server side includes enabled hypertext markup language}
+\end{verbatim}
+Similarly for the \glstextlike\ commands.
 
-Remember that if you use the \gloskey{symbol} key, you need to use a
-glossary style that displays the symbol, as many of the styles
-ignore it.
+\begin{xtr}
+Other approaches are available with \gls{glossaries-extra}.
+See the section \qt{Nested Links} in the \styfmt{glossaries-extra}
+user manual.
+\end{xtr}
 
-\section{Enabling and disabling hyperlinks to glossary entries}
-\label{sec:disablehyperlinks}
+\section{Displaying the Long, Short and Full Forms (Independent of
+First Use)}
+\label{sec:longshortfull}
 
-If you load the \sty{hyperref} or \sty{html} packages prior to
-loading the \styfmt{glossaries} package, the \glslike\ and
-\glstextlike\ commands will automatically have hyperlinks
-to the relevant glossary entry, unless the \gloskey[glslink]{hyper}
-option has been switched off (either explicitly or through 
-implicit means, such as via the \pkgopt{nohypertypes} package option).
+It may be that you want the long, short or full form
+regardless of whether or not the acronym has already been used in
+the document. You can do so with the commands described in this
+section.
 
-You can disable or enable links using:
-\begin{definition}[\DescribeMacro{\glsdisablehyper}]
-\cs{glsdisablehyper}
-\end{definition}
-and
-\begin{definition}[\DescribeMacro{\glsenablehyper}]
-\cs{glsenablehyper}
-\end{definition}
-respectively. The effect can be localised by placing the commands
-within a group. Note that you should only use \cs{glsenablehyper}
-if the commands \ics{hyperlink} and \ics{hypertarget} have been
-defined (for example, by the \sty{hyperref} package).
+The \cs{acr\ldots} commands described below are part of the set of
+\glstextlike\ commands. That is, they index and can form
+hyperlinks, but they don't modify the \firstuseflag.
+However, their display is governed by \ics{defentryfmt} with
+\ics{glscustomtext} set as appropriate. All caveats that apply to
+the \glstextlike\ commands also apply to the following commands.
+(Including the above warning about nested links.)
 
-You can disable just the \gls{firstuse} links using the package
-option \pkgopt[false]{hyperfirst}. Note that this option only
-affects the \glslike\ commands that recognise the \firstuseflag.
+\begin{xtr}
+If you are using \gls{glossaries-extra}, don't use the commands
+described in this section. The \gls{glossaries-extra} package
+provides analogous \cs{glsxtr\ldots} or \cs{glsfmt\ldots}
+commands.  For example, \cs{glsxtrshort} instead of \cs{acrshort}
+or, if needed in a heading, \cs{glsfmtshort}. (Similarly for the
+case-changing variants.)
+\end{xtr}
 
-\begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc}
-Suppose I want the \gls*{firstuse} to have a hyperlink to the
-description in a footnote instead of hyperlinking to the relevant
-place in the glossary. First I need to disable the hyperlinks on
-first use via the package option \pkgopt[false]{hyperfirst}:
-\begin{verbatim}
-\usepackage[hyperfirst=false]{glossaries}
-\end{verbatim}
-Now I need to redefine \ics{glsentryfmt} (see
-\sectionref{sec:glsdisplay}):
-\begin{verbatim}
-\renewcommand*{\glsentryfmt}{%
-  \glsgenentryfmt
-  \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}%
-}
-\end{verbatim}
+The optional arguments are the same as those for the \glstextlike\
+commands, and there are similar star and plus variants that switch
+off or on the hyperlinks. As with the \glstextlike\ commands, the
+\gls{linktext} is placed in the argument of \ics{glstextformat}.
 
-Now the first use won't have hyperlinked text, but will be followed
-by a footnote.
-See the sample file \samplefile{-FnDesc} for a complete document.
-\end{example}
+\begin{definition}[\DescribeMacro{\acrshort}]
+\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This sets the \gls{linktext} to the short form (within the argument
+of \ics{acronymfont}) for the entry given by \meta{label}. The short
+form is as supplied by the \gloskey{short} key, which
+\ics{newacronym} implicitly sets.
 
-Note that the \pkgopt{hyperfirst} option applies to all defined glossaries.  It
-may be that you only want to disable the hyperlinks on
-\gls{firstuse} for glossaries that have a different form on
-\gls*{firstuse}. This can be achieved by noting that since the
-entries that require hyperlinking for all instances have identical
-first and subsequent text, they can be unset via \ics{glsunsetall}
-(see \sectionref{sec:glsunset}) so that the \pkgopt{hyperfirst}
-option doesn't get applied.
+There are also analogous upper case variants:
+\begin{definition}[\DescribeMacro{\Acrshort}]
+\cs{Acrshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRshort}]
+\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+There are also plural versions:
+\begin{definition}[\DescribeMacro\acrshortpl]
+\cs{acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrshortpl]
+\cs{Acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRshortpl]
+\cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+The short plural form is as supplied
+by the \gloskey{shortplural} key, which \ics{newacronym} implicitly sets.
 
-\begin{example}{Suppressing Hyperlinks on First Use Just For
-Acronyms}{ex:hyperfirst}
-Suppose I want to suppress the hyperlink on \gls{firstuse} for
-acronyms but not for entries in the main glossary.  I~can load
-the \styfmt{glossaries} package using:
-\begin{verbatim}
-\usepackage[hyperfirst=false,acronym]{glossaries}
-\end{verbatim}
-Once all glossary entries have been defined I~then do:
-\begin{verbatim}
-\glsunsetall[main]
-\end{verbatim}
+\begin{definition}[\DescribeMacro{\acrlong}]
+\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This sets the \gls{linktext} to the long form for the entry given by 
+\meta{label}. The long form is as supplied
+by the \gloskey{long} key, which \ics{newacronym} implicitly sets.
 
-\end{example}
+There are also analogous upper case variants:
+\begin{definition}[\DescribeMacro{\Acrlong}]
+\cs{Acrlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRlong}]
+\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+Again there are also plural versions:
+\begin{definition}[\DescribeMacro{\acrlongpl}]
+\cs{acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Acrlongpl}]
+\cs{Acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRlongpl}]
+\cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+The long plural form is as supplied by the \gloskey{longplural} key,
+which \ics{newacronym} implicitly sets.
 
-For more complex requirements, you might find it easier to switch
-off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks
-(where required) within the definition of \ics{glsentryfmt} (see
-\sectionref{sec:glsdisplay}) via \ics{glshyperlink} (see
-\sectionref{sec:glsnolink}).
+The commands below display the full form of the acronym, but note
+that this isn't necessarily the same as the form used on \firstuse.
+These full-form commands are shortcuts that use the above commands,
+rather than creating the \gls{linktext} from the complete full form.
+These full-form commands have star and plus variants and optional
+arguments that are passed to the above commands.
 
-\begin{example}{Only Hyperlink in Text Mode Not Math
-Mode}{ex:nomathhyper}
-This is a bit of a contrived example, but suppose, for some reason,
-I only want the \glslike\ commands to have
-hyperlinks when used in text mode, but not in math mode. I~can do
-this by adding the glossary to the list of nohypertypes and redefining 
-\ics{glsentryfmt}:
-\begin{verbatim}
-\GlsDeclareNoHyperList{main}
+\begin{definition}[\DescribeMacro{\acrfull}]
+\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is a shortcut for
+\begin{definition}[\DescribeMacro{\acrfullfmt}]
+\cs{acrfullfmt}\marg{options}\marg{label}\marg{insert}
+\end{definition}
+which by default does
+\begin{alltt}
+\cs{acrfullformat}
+ \mgroup{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}}
+ \mgroup{\cs{acrshort}\oarg{options}\marg{label}}
+\end{alltt}
+where
+\begin{definition}[\DescribeMacro\acrfullformat]
+\cs{acrfullformat}\marg{long}\marg{short}
+\end{definition}
+by default does \meta{long} (\meta{short}). This command is now
+deprecated for new acronym styles but is used by default for
+backward compatibility if \cs{setacronymstyle}
+(\sectionref{sec:setacronymstyle}) hasn't been used.  (For further
+details of these format commands see \ifpdf
+section~\ref*{sec:code:acronym} in \fi the documented code,
+\texttt{glossaries-code.pdf}.)
 
-\renewcommand*{\glsentryfmt}{%
-  \ifmmode
-    \glsgenentryfmt
-  \else
-    \glsifhyperon
-    {\glsgenentryfmt}% hyperlink already on
-    {\glshyperlink[\glsgenentryfmt]{\glslabel}}%
-  \fi
-}
-\end{verbatim}
-Note that this doesn't affect the \glstextlike\ commands, which will
-have the hyperlinks off unless they're forced on using the plus
-variant.
+There are also analogous upper case variants:
+\begin{definition}[\DescribeMacro{\Acrfull}]
+\cs{Acrfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRfull}]
+\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+and plural versions:
+\begin{definition}[\DescribeMacro\acrfullpl]
+\cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrfullpl]
+\cs{Acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRfullpl]
+\cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
 
-See the sample file \samplefile{-nomathhyper} for a complete
-document.
-\end{example}
+If you find the above commands too cumbersome to write, you can use
+the \pkgopt{shortcuts} package option to activate the shorter
+command names listed in \tableref{tab:shortcuts}.
 
-\begin{example}{One Hyper Link Per Entry Per Chapter}{ex:chap-hyperfirst}
-Here's a more complicated example that will only have the hyperlink
-on the first time an entry is used per chapter. This doesn't involve
-resetting the \firstuseflag. Instead it adds a~new key using
-\ics{glsaddstoragekey} (see \sectionref{sec:glsaddstoragekey}) that
-keeps track of the chapter number that the entry was last used in:
-\begin{verbatim}
-\glsaddstoragekey{chapter}{0}{\glschapnum}
-\end{verbatim}
-This creates a new user command called \cs{glschapnum} that's
-analogous to \cs{glsentrytext}. The default value for this key is~0.
-I~then define my glossary entries as usual.
+\begin{table}[htbp]
+\caption{Synonyms provided by the package option \pkgoptfmt{shortcuts}}
+\label{tab:shortcuts}
+\vskip\baselineskip
+\centering
+\begin{tabular}{ll}
+\bfseries Shortcut Command & \bfseries Equivalent Command\\
+\ics{acs} & \ics{acrshort}\\
+\ics{Acs} & \ics{Acrshort}\\
+\ics{acsp} & \ics{acrshortpl}\\
+\ics{Acsp} & \ics{Acrshortpl}\\
+\ics{acl} & \ics{acrlong}\\
+\ics{Acl} & \ics{Acrlong}\\
+\ics{aclp} & \ics{acrlongpl}\\
+\ics{Aclp} & \ics{Acrlongpl}\\
+\ics{acf} & \ics{acrfull}\\
+\ics{Acf} & \ics{Acrfull}\\
+\ics{acfp} & \ics{acrfullpl}\\
+\ics{Acfp} & \ics{Acrfullpl}\\
+\ics{ac} & \ics{gls}\\
+\ics{Ac} & \ics{Gls}\\
+\ics{acp} & \ics{glspl}\\
+\ics{Acp} & \ics{Glspl}
+\end{tabular}
+\end{table}
 
-Next I redefine the hook \ics{glslinkpostsetkeys}
-(see \sectionref{sec:glsdisplay}) so that it determines the current
-chapter number (which is stored in \cs{currentchap} using
-\cs{edef}). This value is then compared with the value of the
-entry's \texttt{chapter} key that I defined earlier. If they're the
-same, this entry has already been used in this chapter so the
-hyperlink is switched off using \sty{xkeyval}'s \cs{setkeys}
-command. If the chapter number isn't the same, then this entry
-hasn't been used in the current chapter. The \texttt{chapter} field
-is updated using \ics{glsfieldxdef} (\sectionref{sec:fetchset})
-provided the user hasn't switched off the hyperlink.
-(This test is performed using \cs{glsifhyperon}.
-\begin{verbatim}
-\renewcommand*{\glslinkpostsetkeys}{%
- \edef\currentchap{\arabic{chapter}}%
- \ifnum\currentchap=\glschapnum{\glslabel}\relax
-  \setkeys{glslink}{hyper=false}%
- \else
-  \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}%
- \fi
-}
-\end{verbatim}
-Note that this will be confused if you use \cs{gls} etc when the
-chapter counter is~0. (That is, before the first \cs{chapter}.)
+It is also possible to access the long and short forms without
+adding information to the glossary using commands analogous to
+\ics{glsentrytext} (described in \sectionref{sec:glsnolink}).
 
-See the sample file \samplefile{-chap-hyperfirst} for a complete
-document.
-\end{example}
+\begin{important}
+The commands that convert the first letter to upper case come with
+the same caveats as those for analogous commands like
+\ics{Glsentrytext} (non-expandable, can't be used in PDF bookmarks,
+care needs to be taken if the first letter is an accented character
+etc). See \sectionref{sec:glsnolink}.
+\end{important}
 
-\chapter{Adding an Entry to the Glossary Without Generating Text}
-\label{sec:glsadd}
+The long form can be accessed using:
+\begin{definition}[\DescribeMacro{\glsentrylong}]
+\cs{glsentrylong}\marg{label}
+\end{definition}
+or, with the first letter converted to upper case:
+\begin{definition}[\DescribeMacro{\Glsentrylong}]
+\cs{Glsentrylong}\marg{label}
+\end{definition}
+Plural forms:
+\begin{definition}[\DescribeMacro{\glsentrylongpl}]
+\cs{glsentrylongpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentrylongpl}]
+\cs{Glsentrylongpl}\marg{label}
+\end{definition}
 
-It is possible to add a line to the glossary file without
-generating any text at that point in the document using:
-\begin{definition}[\DescribeMacro{\glsadd}]
-\cs{glsadd}\oarg{options}\marg{label}
+Similarly, to access the short form:
+\begin{definition}[\DescribeMacro{\glsentryshort}]
+\cs{glsentryshort}\marg{label}
+\end{definition}
+or, with the first letter converted to upper case:
+\begin{definition}[\DescribeMacro{\Glsentryshort}]
+\cs{Glsentryshort}\marg{label}
+\end{definition}
+Plural forms:
+\begin{definition}[\DescribeMacro{\glsentryshortpl}]
+\cs{glsentryshortpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryshortpl}]
+\cs{Glsentryshortpl}\marg{label}
 \end{definition}
-This is similar to the \glstextlike\ commands, only it doesn't produce
-any text (so therefore, there is no \gloskey[glslink]{hyper} key
-available in \meta{options} but all the other options that can
-be used with \glstextlike\ commands can be passed to \cs{glsadd}).
-For example, to add a page range to the glossary number list for the
-entry whose label is given by \texttt{set}:
-\begin{verbatim}
-\glsadd[format=(]{set}
-Lots of text about sets spanning many pages.
-\glsadd[format=)]{set}
-\end{verbatim}
 
-To add all entries that have been defined, use:
-\begin{definition}[\DescribeMacro{\glsaddall}]
-\cs{glsaddall}\oarg{options}
+And the full form can be obtained using:
+\begin{definition}[\DescribeMacro{\glsentryfull}]
+\cs{glsentryfull}\marg{label}
 \end{definition}
-The optional argument is the same as for \cs{glsadd}, except
-there is also a key \gloskey[glsaddall]{types} which can be
-used to specify which glossaries to use. This should be a
-comma-separated list. For example, if you only want to add
-all the entries belonging to the list of acronyms (specified by
-the glossary type \ics{acronymtype}) and a list of
-notation (specified by the glossary type \texttt{notation}) then you can
-do:
-\begin{verbatim}
-\glsaddall[types={\acronymtype,notation}]
-\end{verbatim}
-If you are using \gls{bib2gls} with \gls{glossaries-extra}, you
-can't use \cs{glsaddall}. Instead use the \optfmt{selection=all}
-resource option to select all entries in the given \filetype{bib} files.
+\begin{definition}[\DescribeMacro{\Glsentryfull}]
+\cs{Glsentryfull}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsentryfullpl}]
+\cs{glsentryfullpl}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Glsentryfullpl}]
+\cs{Glsentryfullpl}\marg{label}
+\end{definition}
+These again use \ics{acrfullformat} by default, but
+the new styles described in the section below use different
+formatting commands.
 
-\begin{important}
-Note that \cs{glsadd} and \cs{glsaddall} add the current location to
-the \gls{numberlist}. In the case of \cs{glsaddall}, all entries in the
-glossary will have the same location in the number list. If you want
-to use \cs{glsaddall}, it's best to suppress the number list with
-the \pkgopt{nonumberlist} package option. (See
-sections~\ref{sec:pkgopts-printglos} and~\ref{sec:numberlists}.)
-\end{important}
+\section{Changing the Acronym Style}
+\label{sec:setacronymstyle}
 
-There is now a variation of \cs{glsaddall} that skips any entries
-that have already been used:
-\begin{definition}[\DescribeMacro\glsaddallunused]
-\cs{glsaddallunused}\oarg{list}
+\begin{xtr}
+If you are using \gls{glossaries-extra}, don't use the commands
+described in this section. Use \ics*{setabbreviationstyle} to set
+the style. This uses a different (but more consistent) naming
+scheme. For example, \abbrstyle{long-noshort} instead of
+\acrstyle{dua}. See the \qt{Acronym Style Modifications} section and 
+the \qt{Abbreviations} chapter in the \gls{glossaries-extra} manual 
+for further details.
+\end{xtr}
+
+The acronym style is set using:
+\begin{definition}[\DescribeMacro{\setacronymstyle}]
+\cs{setacronymstyle}\marg{style name}
 \end{definition}
-This command uses \cs{glsadd}\texttt{[format=glsignore]} which will
-ignore this location in the number list. The optional argument
-\meta{list} is a comma-separated list of glossary types. If omitted,
-it defaults to the list of all defined glossaries.
+where \meta{style name} is the name of the required style.
 
 \begin{important}
-If you want to use \cs{glsaddallunused}, it's best to place the
-command at the end of the document to ensure that all the commands
-you intend to use have already been used. Otherwise you could end up
-with a spurious comma or dash in the location list.
+You must use \cs{setacronymstyle} \emph{before} you define the
+acronyms with \cs{newacronym}.
 \end{important}
 
-With \gls{glossaries-extra} and \gls{bib2gls}, \texttt{glsignore}
-indicates an \qt{ignored location} which influences selection but
-isn't added to the location list. In this case, if you use
-\optfmt{selection=all} then only those entries that have been
-explicitly indexed in the document will have location lists. The
-other entries that were selected as a result of
-\optfmt{selection=all} won't have location lists.
-
-Base \sty{glossaries} package only:
-\begin{verbatim}
-\documentclass{article}
-\usepackage{glossaries}
-\makeglossaries
-\newglossaryentry{cat}{name={cat},description={feline}}
-\newglossaryentry{dog}{name={dog},description={canine}}
-\begin{document}
-\gls{cat}.
-\printglossaries
-\glsaddallunused % <- make sure dog is also listed
-\end{document}
-\end{verbatim}
-Corresponding \gls{glossaries-extra} and \gls{bib2gls} document code:
-\begin{verbatim}
-\documentclass{article}
-\usepackage[record]{glossaries-extra}
-\GlsXtrLoadResources[src={entries},selection=all]
-\begin{document}
-\gls{cat}.
-\printunsrtglossaries
-\end{document}
-\end{verbatim}
-With the file \texttt{entries.bib}:
-\begin{verbatim}
-@entry{cat,name={cat},description={feline}}
-@entry{dog,name={dog},description={canine}}
-\end{verbatim}
-
-\begin{example}{Dual Entries}{ex:dual}
-The example file \samplefile{-dual} makes use of \cs{glsadd} to
-allow for an entry that should appear both in the main glossary and
-in the list of acronyms. This example sets up the list of acronyms
-using the \pkgopt{acronym} package option:
+For example:
 \begin{verbatim}
 \usepackage[acronym]{glossaries}
-\end{verbatim}
-A new command is then defined to make it easier to define dual
-entries:
-\begin{verbatim}
-\newcommand*{\newdualentry}[5][]{%
-  \newglossaryentry{main-#2}{name={#4},%
-  text={#3\glsadd{#2}},%
-  description={#5},%
-  #1
-  }%
-  \newacronym{#2}{#3\glsadd{main-#2}}{#4}%
-}
-\end{verbatim}
-This has the following syntax:
-\begin{alltt}
-\ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description}
-\end{alltt}
-You can then define a new dual entry:
-\begin{verbatim}
-\newdualentry{svm}% label
-  {SVM}% abbreviation
-  {support vector machine}% long form
-  {Statistical pattern recognition technique}% description
-\end{verbatim}
-Now you can reference the acronym with \verb|\gls{svm}| or you can
-reference the entry in the main glossary with \verb|\gls{main-svm}|.
 
-Note that with \gls{bib2gls}, there are special dual entry types
-that implement this behaviour. That is, if an entry is referenced
-then its corresponding dual entry will automatically be selected as
-well. So there is less need for \cs{glsadd} with \gls{bib2gls}.
-(Although it can still be useful, as shown in \opt6.)
-\end{example}
+\makeglossaries
 
-\chapter{Cross-Referencing Entries}
-\label{sec:crossref}
+\setacronymstyle{long-sc-short}
+
+\newacronym{html}{html}{hypertext markup language}
+\newacronym{xml}{xml}{extensible markup language}
+\end{verbatim}
+Unpredictable results can occur if you try to use multiple styles.
 
 \begin{important}
-You must use \ics{makeglossaries} (\optsor23) or
-\ics{makenoidxglossaries} (\opt1) \emph{before} defining any
-terms that cross-reference entries. If any of the terms that you have
-cross-referenced don't appear in the glossary, check that you have
-put \cs{makeglossaries}\slash\cs{makenoidxglossaries} before all 
-entry definitions. The \gls{glossaries-extra} package provides
-better cross-reference handling.
+If you need multiple abbreviation styles, then 
+use the \gls{glossaries-extra} package, which has better
+abbreviation management. See, for example,
+\gallery{index.php?label=sample-name-font}{Gallery: Mixing Styles}.
 \end{important}
 
-There are several ways of cross-referencing entries in the 
-glossary: 
+Unlike the backward-compatible default behaviour of \cs{newacronym}, the
+styles set via \cs{setacronymstyle} don't use the \gloskey{first}
+or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to
+set a~custom format that uses the \gloskey{long} and \gloskey{short}
+keys (or their plural equivalents). This means that these styles
+cope better with plurals that aren't formed by simply appending the
+singular form with the letter \qt{s}. In fact, most of the predefined
+styles use \ics{glsgenacfmt} and modify the definitions of commands
+like \ics{genacrfullformat}.
 
-\begin{enumerate}
-\item You can use commands such as \ics{gls} in the
-entries description. For example:
-\begin{verbatim}
-\newglossaryentry{apple}{name=apple,
-description={firm, round fruit. See also \gls{pear}}}
-\end{verbatim}
-Note that with this method, if you don't use the cross-referenced term 
-in the main part of the document, you will need two runs of
-\gls{makeglossaries}:
-\begin{prompt}
-pdflatex filename
-makeglossaries filename
-pdflatex filename
-makeglossaries filename
-pdflatex filename
-\end{prompt}
-
-\item As described in \sectionref{sec:newglosentry}, you can use the
-\gloskey{see} key when you define the entry. For example:
-\begin{verbatim}
-\newglossaryentry{MaclaurinSeries}{name={Maclaurin 
-series},
-description={Series expansion},
-see={TaylorsTheorem}}
-\end{verbatim}
-Note that in this case, the entry with the \gloskey{see} key will
-automatically be added to the glossary, but the cross-referenced
-entry won't. You therefore need to ensure that you use the
-cross-referenced term with the commands described in
-\sectionref{sec:glslink} or \sectionref{sec:glsadd}.
-
-The \qt{see} tag is produce using \ics{seename}, but can be
-overridden in specific instances using square brackets
-at the start of the \gloskey{see} value. For example:
-\begin{verbatim}
-\newglossaryentry{MaclaurinSeries}{name={Maclaurin 
-series},
-description={Series expansion},
-see=[see also]{TaylorsTheorem}}
-\end{verbatim}
-Take care if you want to use the optional argument of commands such
-as \ics{newacronym} or \ics{newterm} as the value will need to be
-grouped. For example:
-\begin{verbatim}
-\newterm{seal}
-\newterm[see={[see also]seal}]{sea lion}
-\end{verbatim}
-Similarly if the value contains a list. For example:
-\begin{verbatim}
-\glossaryentry{lemon}{
-  name={lemon},
-  description={Yellow citrus fruit}
-}
-\glossaryentry{lime}
-{
-  name={lime},
-  description={Green citrus fruit}
-}
-\glossaryentry{citrus}
-{
-  name={citrus},
-  description={Plant in the Rutaceae family},
-  see={lemon,lime}
-}
-\end{verbatim}
-
-\item After you have defined the entry, use
-\begin{definition}[\DescribeMacro{\glssee}]
-\cs{glssee}\oarg{tag}\marg{label}\marg{xr label list}
+Note that when you use \cs{setacronymstyle} the \gloskey{name} key
+is set to
+\begin{definition}[\DescribeMacro{\acronymentry}]
+\cs{acronymentry}\marg{label}
 \end{definition}
-where \meta{xr label list} is a comma-separated list of entry 
-labels to be cross-referenced, \meta{label} is the label of the
-entry doing the cross-referencing and \meta{tag} is the \qt{see} tag.
-(The default value of \meta{tag} is \ics{seename}.)
-For example:
-\begin{verbatim}
-\glssee[see also]{series}{FourierSeries,TaylorsTheorem}
-\end{verbatim}
-Note that this automatically adds the entry given by \meta{label} to
-the glossary but doesn't add the cross-referenced entries (specified
-by \meta{xr label list}) to the glossary.
-\end{enumerate}
-
-In both cases~2 and 3 above, the cross-referenced information
-appears in the \gls{numberlist}, whereas in case~1, the
-cross-referenced information appears in the description. (See the
-\samplefile{-crossref} example file that comes with this package.)
-This means that in cases~2 and~3, the cross-referencing information
-won't appear if you have suppressed the \gls*{numberlist}. In this
-case, you will need to activate the \gls*{numberlist} for the given
-entries using \gloskey{nonumberlist=false}. Alternatively, if you
-just use the \gloskey{see} key instead of \ics{glssee}, you can
-automatically activate the \gls*{numberlist} using the
-\pkgopt{seeautonumberlist} package option.
-
-\section{Customising Cross-reference Text}
-\label{sec:customxr}
-
-When you use either the \gloskey{see} key or the command
-\cs{glssee}, the cross-referencing information will be typeset in the 
-glossary according to:
-\begin{definition}[\DescribeMacro{\glsseeformat}]
-\cs{glsseeformat}\oarg{tag}\marg{label-list}\marg{location}
+and the \gloskey{sort} key is set to
+\begin{definition}[\DescribeMacro{\acronymsort}]
+\cs{acronymsort}\marg{short}\marg{long}
 \end{definition}
-The default definition of \cs{glsseeformat} is:
-\begin{display}
-\cs{emph}\marg{tag} \cs{glsseelist}\marg{label-list}
-\end{display}
-Note that the location is always ignored.\footnote{\gls{makeindex}
-will always assign a location number, even if it's not needed, so it
-needs to be discarded.} For example, if you want the tag to appear
-in bold, you can do:\footnote{If you redefine \cs{glsseeformat},
-keep the default value of the optional argument as \ics{seename} as
-both \gloskey{see} and \cs{glssee} explicitly write
-\texttt[\cs{seename}\texttt] in the output file if no optional
-argument is given.}
-\begin{verbatim}
-\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} 
- \glsseelist{#2}}
-\end{verbatim}
+These commands are redefined by the acronym styles. However, you can
+redefine them again after the style has been set but before you use
+\cs{newacronym}. Protected expansion is performed on \cs{acronymsort}
+when the entry is defined.
 
+\subsection{Predefined Acronym Styles}
+\label{sec:predefinedacrstyles}
 
-The list of labels is dealt with by \cs{glsseelist}, which iterates
-through the list and typesets each entry in the label. The entries
-are separated by
-\begin{definition}[\DescribeMacro{\glsseesep}]
-\cs{glsseesep}
-\end{definition}
-or (for the last pair)
-\begin{definition}[\DescribeMacro{\glsseelastsep}]
-\cs{glsseelastsep}
+The \styfmt{glossaries} package provides a~number of predefined
+styles. These styles apply
+\begin{definition}[\DescribeMacro{\firstacronymfont}]
+\cs{firstacronymfont}\marg{text}
 \end{definition}
-These default to ``",\space"'' and
-\qt{\cs{space}\ics{andname}\cs{space}} respectively. The list entry text
-is displayed using:
-\begin{definition}[\DescribeMacro{\glsseeitemformat}]
-\cs{glsseeitemformat}\marg{label}
+to the short form on first use and
+\begin{definition}[\DescribeMacro{\acronymfont}]
+\cs{acronymfont}\marg{text}
 \end{definition}
-This defaults to \ics{glsentrytext}\marg{label}.\footnote{In
-versions before 3.0, \cs{glsentryname} was used, but this could cause
-problems when the \gloskey{name} key was \glsd{sanitize}.} For example, to
-make the cross-referenced list use small caps:
-\begin{verbatim}
-\renewcommand{\glsseeitemformat}[1]{%
-  \textsc{\glsentrytext{#1}}}
-\end{verbatim}
+on subsequent use. The styles modify the definition of
+\cs{acronymfont} as required, but \ics{firstacronymfont} is only set
+once by the package when it's loaded. By default
+\ics{firstacronymfont}\marg{text} is the same as
+\ics{acronymfont}\marg{text}.
+If you want the short form displayed differently on first use, you
+can redefine \ics{firstacronymfont} independently of the acronym
+style.
 
-\begin{important}
-You can use \ics{glsseeformat} and \ics{glsseelist} in the main body
-of the text, but they won't automatically add the cross-referenced
-entries to the glossary. If you want them added with that location,
-you can do:
-\begin{verbatim}
-Some information (see also 
-\glsseelist{FourierSeries,TaylorsTheorem}%
-\glsadd{FourierSeries}\glsadd{TaylorsTheorem}).
-\end{verbatim}
+The predefined styles that contain \texttt{sc} in their name (for
+example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to use
+\ics{textsc}, which means that the short form needs to be specified
+in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces
+\textsc{abc} but \verb|\textsc{ABC}| produces \textsc{ABC}.\fi
+
+\hypertarget{boldsc}{}%
+\begin{important}%
+Some fonts don't support bold \gls{smallcaps}, so you may need to redefine 
+\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to
+medium weight if you are using a glossary style that displays entry
+names in bold and you have chosen an acronym style that uses
+\ics{textsc}.
 \end{important}
 
-\chapter{Using Glossary Terms Without Links}
-\label{sec:glsnolink}
+The predefined styles that contain \texttt{sm} in their name
+(for example \acrstyle{long-sm-short}) redefine \cs{acronymfont} to
+use \ics{textsmaller}.  
 
-The commands described in this section display entry details without
-adding any information to the glossary. They don't use
-\ics{glstextformat}, they don't have any optional arguments, they
-don't affect the \firstuseflag\ and, apart from \ics{glshyperlink},
-they don't produce hyperlinks.
+\hypertarget{smaller}{}%
+\begin{important}
+Note that the \styfmt{glossaries} package doesn't define or load any package that
+defines \ics{textsmaller}. If you use one of the acronym styles that
+set \ics{acronymfont} to \cs{textsmaller} you must
+explicitly load the \sty{relsize} package or otherwise define
+\cs{textsmaller}.
+\end{important}
+
+The remaining predefined styles redefine \cs{acronymfont}\marg{text}
+to simply do its argument \meta{text}. 
 
 \begin{important}
-Commands that aren't expandable will be ignored by PDF bookmarks, so
-you will need to provide an alternative via \sty{hyperref}'s
-\cs{texorpdfstring} if you want to use them in sectioning commands.
-(This isn't specific to the \styfmt{glossaries} package.) See the
-\sty{hyperref} documentation for further details. All the commands
-that convert the first letter to upper case aren't expandable.
-The other commands depend on whether their corresponding keys were
-assigned non-expandable values.
+In most cases, the predefined styles adjust \ics{acrfull} and
+\ics{glsentryfull} (and their plural and upper case variants) to
+reflect the style. The only exceptions to this are the 
+\acrstyle{dua} and \acrstyle{footnote} styles (and their variants).
 \end{important}
 
-If you want to title case a field, you can use:
-\begin{definition}[\DescribeMacro\glsentrytitlecase]
-\cs{glsentrytitlecase}\marg{label}\marg{field}
+The following styles are supplied by the \styfmt{glossaries}
+package:
+\begin{itemize}
+\item \acrstyle{long-short}, \acrstyle{long-sc-short},
+\acrstyle{long-sm-short}, \acrstyle{long-sp-short}:
+
+With these three styles, acronyms are displayed in the form
+\begin{definition}
+\meta{long} (\ics{firstacronymfont}\marg{short})
 \end{definition}
-where \meta{label} is the label identifying the glossary entry,
-\meta{field} is the field label (see \tableref{tab:fieldmap}).
-For example:
+on first use and
+\begin{definition}
+\ics{acronymfont}\marg{short}
+\end{definition}
+on subsequent use.
+They also set \cs{acronymsort}\marg{short}\marg{long} to just
+\meta{short}.  This means that the acronyms are sorted according to
+their short form.  In addition, \cs{acronymentry}\marg{label} is set
+to just the short form (enclosed in \cs{acronymfont}) and the
+\gloskey{description} key is set to the long form.
+
+The \acrstyle{long-sp-short} style was introduced in version~4.16
+and uses
+\begin{definition}[\DescribeMacro\glsacspace]
+\cs{glsacspace}\marg{label}
+\end{definition}
+for the space between the long and short forms. This defaults to
+a~non-breakable space (\verb|~|) if 
+(\cs{acronymfont}\marg{short}) is less than 3em, otherwise it uses
+a~normal space. This may be redefined as required. For example, to
+always use a~non-breakable space:
 \begin{verbatim}
-\glsentrytitlecase{sample}{desc}
+\renewcommand*{\glsacspace}[1]{~}
 \end{verbatim}
-(If you want title-casing in your glossary style, you might want to
-investigate the \gls{glossaries-extra} package.) This command will
-trigger an error if the entry is undefined.
 
-Note that this command has the same limitations as \cs{makefirstuc} which is
-used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case
-the first letter (see the notes about \cs{Gls} in \sectionref{sec:gls-like}).
+\item \acrstyle{short-long}, \acrstyle{sc-short-long},
+\acrstyle{sm-short-long}:
 
-\begin{definition}[\DescribeMacro{\glsentryname}]
-\cs{glsentryname}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryname}]
-\cs{Glsentryname}\marg{label}
+These three styles are analogous to the above three styles, except
+the display order is swapped to
+\begin{definition}
+\ics{firstacronymfont}\marg{short} (\meta{long})
 \end{definition}
-These commands display the name of the glossary entry given by
-\meta{label}, as specified by the \gloskey{name} key.
-\cs{Glsentryname} makes the first letter upper case.
-Neither of these commands check for the existence of \meta{label}.
-The first form \cs{glsentryname} is expandable (unless the name
-contains unexpandable commands). Note that this may be different from the values of
-the \gloskey{text} or \gloskey{first} keys. In general it's better
-to use \cs{glsentrytext} or \cs{glsentryfirst} instead of
-\cs{glsentryname}.
+on first use.
 
-\begin{important}
-In general it's best to avoid \cs{Glsentryname} with abbreviations. Instead,
-consider using \cs{Glsentrylong}, \cs{Glsentryshort} or \cs{Glsentryfull}.
-\end{important}
+Note, however, that \ics{acronymsort} and \ics{acronymentry} are the
+same as for the \meta{long} (\meta{short}) styles above, so the
+acronyms are still sorted according to the short form.
 
-\begin{definition}[\DescribeMacro{\glossentryname}]
-\cs{glossentryname}\marg{label}
-\end{definition}
-This is like \cs{glsnamefont}\{\cs{glsentryname\marg{label}}\}
-but also checks for the existence of \meta{label}. This command is
-not expandable. It's used in the predefined glossary styles, so if
-you want to change the way the name is formatted in the glossary,
-you can redefine \cs{glsnamefont} to use the required fonts. For
-example:
-\begin{verbatim}
-\renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}}
-\end{verbatim}
-\begin{definition}[\DescribeMacro{\Glossentryname}]
-\cs{Glossentryname}\marg{label}
-\end{definition}
-This is like \cs{glossentryname} but makes the first letter of the
-name upper case.
+\item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc},
+\acrstyle{long-sm-short-desc}, \acrstyle{long-sp-short-desc}:
 
-\begin{definition}[\DescribeMacro{\glsentrytext}]
-\cs{glsentrytext}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrytext}]
-\cs{Glsentrytext}\marg{label}
-\end{definition}
-These commands display the subsequent use text for the glossary
-entry given by \meta{label}, as specified by the \gloskey{text} key.
-\cs{Glsentrytext} makes the first letter upper case.
-The first form is expandable (unless the text contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+These are like the \acrstyle{long-short}, \acrstyle{long-sc-short},
+\acrstyle{long-sm-short} and \acrstyle{long-sp-short} styles described above, except that the
+\gloskey{description} key must be supplied in the optional argument
+of \ics{newacronym}. They also redefine \ics{acronymentry} to
+\marg{long} (\cs{acronymfont}\marg{short}) and redefine
+\ics{acronymsort}\marg{short}\marg{long} to just \meta{long}.
+This means that the acronyms are sorted according to the long form,
+and in the list of acronyms the name field has the long form
+followed by the short form in parentheses. I~recommend you use
+a~glossary style such as \glostyle{altlist} with these acronym
+styles to allow for the long name field.
 
-\begin{definition}[\DescribeMacro{\glsentryplural}]
-\cs{glsentryplural}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryplural}]
-\cs{Glsentryplural}\marg{label}
-\end{definition}
-These commands display the subsequent use plural text for the
-glossary entry given by \meta{label}, as specified by the
-\gloskey{plural} key. \cs{Glsentryplural} makes the first letter
-upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+\item \acrstyle{short-long-desc}, \acrstyle{sc-short-long-desc},
+\acrstyle{sm-short-long-desc}:
 
-\begin{definition}[\DescribeMacro{\glsentryfirst}]
-\cs{glsentryfirst}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryfirst}]
-\cs{Glsentryfirst}\marg{label}
+These styles are analogous to the above three styles, but the first
+use display style is:
+\begin{definition}
+\cs{firstacronymfont}\marg{short} (\meta{long})
 \end{definition}
-These commands display the \firstusetext\ for the glossary entry
-given by \meta{label}, as specified by the \gloskey{first} key.
-\cs{Glsentryfirst} makes the first letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+The definitions of \cs{acronymsort} and \cs{acronymentry} are the
+same as those for \acrstyle{long-short-desc} etc.
 
-\begin{definition}[\DescribeMacro{\glsentryfirstplural}]
-\cs{glsentryfirstplural}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryfirstplural}]
-\cs{Glsentryfirstplural}\marg{label}
-\end{definition}
-These commands display the plural form of the \firstusetext\ for the
-glossary entry given by \meta{label}, as specified by the
-\gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first
-letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+\item \acrstyle{dua}, \acrstyle{dua-desc}:
 
-\begin{definition}[\DescribeMacro{\glsentrydesc}]
-\cs{glsentrydesc}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrydesc}]
-\cs{Glsentrydesc}\marg{label}
-\end{definition}
-These commands display the description for the glossary entry given
-by \meta{label}. 
+With these styles, the \glslike\ commands always display the long form 
+regardless of whether the entry has been used or not. However, \ics{acrfull}
+and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case
+of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to
+the short form and the description is set to the long form. In the
+case of \acrstyle{dua-desc}, the \gloskey{name} and \gloskey{sort}
+keys are set to the long form and the description is supplied in the
+optional argument of \ics{newacronym}.
 
-\cs{Glsentrydesc} makes the first letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+\item \acrstyle{footnote}, \acrstyle{footnote-sc},
+\acrstyle{footnote-sm}:
 
-\begin{definition}[\DescribeMacro{\glossentrydesc}]
-\cs{glossentrydesc}\marg{label}
+With these three styles, on first use the \glslike\ commands display:
+\begin{definition}
+\cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long}
 \end{definition}
-This is like \cs{glsentrydesc}\marg{label}
-but also checks for the existence of \meta{label}. This command is
-not expandable. It's used in the predefined glossary styles to
-display the description.
-\begin{definition}[\DescribeMacro{\Glossentrydesc}]
-\cs{Glossentrydesc}\marg{label}
+However, \ics{acrfull} and \ics{glsentryfull} are set to 
+\cs{acronymfont}\marg{short} (\meta{long}). On subsequent use the display is:
+\begin{definition}
+\cs{acronymfont}\marg{short}
 \end{definition}
-This is like \cs{glossentrydesc} but converts the first letter to
-upper case. This command is not expandable.
+The \gloskey{sort} and \gloskey{name} keys are set to
+the short form, and the \gloskey{description} is set to the long
+form.
 
-\begin{definition}[\DescribeMacro{\glsentrydescplural}]
-\cs{glsentrydescplural}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrydescplural}]
-\cs{Glsentrydescplural}\marg{label}
-\end{definition}
-These commands display the plural description for the glossary entry
-given by \meta{label}. \cs{Glsentrydescplural} makes the first
-letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+\begin{important}
+In order to avoid nested hyperlinks on \firstuse\ the footnote
+styles automatically implement \pkgopt[false]{hyperfirst} for the
+acronym lists.
+\end{important}
 
+\item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc},
+\acrstyle{footnote-sm-desc}:
 
-\begin{definition}[\DescribeMacro{\glsentrysymbol}]
-\cs{glsentrysymbol}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrysymbol}]
-\cs{Glsentrysymbol}\marg{label}
-\end{definition}
-These commands display the symbol for the glossary entry given by
-\meta{label}.
+These three styles are similar to the previous three styles, but the
+description has to be supplied in the optional argument of
+\ics{newacronym}. The \gloskey{name} key is set to the long form
+followed by the short form in parentheses and the \gloskey{sort} key
+is set to the long form. This means that the acronyms will be sorted
+according to the long form. In addition, since the \gloskey{name}
+will typically be quite wide it's best to choose a glossary style
+that can accommodate this, such as \glostyle{altlist}.
 
-\cs{Glsentrysymbol} makes the first letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
+\end{itemize}
 
+\begin{example}{Adapting a Predefined Acronym Style}{ex:acrstyle}
+Suppose I~want to use the \acrstyle{footnote-sc-desc} style, but 
+I~want the \gloskey{name} key set to the short form followed by the
+long form in parentheses and the \gloskey{sort} key set to the short
+form. Then I need to specify the \acrstyle{footnote-sc-desc} style:
+\begin{verbatim}
+\setacronymstyle{footnote-sc-desc}
+\end{verbatim}
+and then redefine \ics{acronymsort} and \ics{acronymentry}:
+\begin{verbatim}
+\renewcommand*{\acronymsort}[2]{#1}% sort by short form
+\renewcommand*{\acronymentry}[1]{%
+  \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}%
+\end{verbatim}
+(I've used \cs{space} for extra clarity, but you can just use an
+actual space instead.)
 
-\begin{definition}[\DescribeMacro\glsletentryfield]
-\cs{glsletentryfield}\marg{cs}\marg{label}\marg{field}
-\end{definition}
-This command doesn't display anything. It merely fetches the
-value associated with the given field (where the available field names 
-are listed in \tableref{tab:fieldmap}) and stores the result
-in the control sequence \meta{cs}. For example, to store
-the description for the entry whose label is \qt{apple} in the
-control sequence \verb|\tmp|:
+Note that the default Computer Modern fonts don't support bold
+\gls{smallcaps}, so another font is required. For example:
 \begin{verbatim}
-\glsletentryfield{\tmp}{apple}{desc}
+\usepackage[T1]{fontenc}
+\end{verbatim}
+The alternative is to redefine \ics{acronymfont} so that it
+always switches to medium weight to ensure the \gls{smallcaps} setting is
+used. For example:
+\begin{verbatim}
+\renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}}
 \end{verbatim}
 
-\begin{definition}[\DescribeMacro{\glossentrysymbol}]
-\cs{glossentrysymbol}\marg{label}
-\end{definition}
-This is like \cs{glsentrysymbol}\marg{label}
-but also checks for the existence of \meta{label}. This command is
-not expandable. It's used in some of the predefined glossary styles to
-display the symbol.
-\begin{definition}[\DescribeMacro{\Glossentrysymbol}]
-\cs{Glossentrysymbol}\marg{label}
-\end{definition}
-This is like \cs{glossentrysymbol} but converts the first letter to
-upper case. This command is not expandable.
+The sample file \samplefile{FnAcrDesc} illustrates this
+example.
+\end{example}
 
-\begin{definition}[\DescribeMacro{\glsentrysymbolplural}]
-\cs{glsentrysymbolplural}\marg{label}
+\subsection{Defining A Custom Acronym Style}
+\label{sec:customacronym}
+
+You may find that the predefined acronyms styles that come with the
+\styfmt{glossaries} package don't suit your requirements. In this
+case you can define your own style using:
+\begin{definition}[\DescribeMacro{\newacronymstyle}]
+\cs{newacronymstyle}\marg{style name}\marg{display}\marg{definitions}
 \end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrysymbolplural}]
-\cs{Glsentrysymbolplural}\marg{label}
-\end{definition}
-These commands display the plural symbol for the glossary entry
-given by \meta{label}. \cs{Glsentrysymbolplural} makes the first
-letter upper case.
-The first form is expandable (unless the value of that key contains unexpandable
-commands). The second form is not expandable. Neither checks for the
-existence of \meta{label}.
-
-\begin{definition}[\DescribeMacro{\glsentryuseri}]
-\cs{glsentryuseri}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuseri}]
-\cs{Glsentryuseri}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryuserii}]
-\cs{glsentryuserii}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuserii}]
-\cs{Glsentryuserii}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryuseriii}]
-\cs{glsentryuseriii}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuseriii}]
-\cs{Glsentryuseriii}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryuseriv}]
-\cs{glsentryuseriv}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuseriv}]
-\cs{Glsentryuseriv}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryuserv}]
-\cs{glsentryuserv}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuserv}]
-\cs{Glsentryuserv}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryuservi}]
-\cs{glsentryuservi}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryuservi}]
-\cs{Glsentryuservi}\marg{label}
-\end{definition}
-These commands display the value of the user keys for the glossary
-entry given by \meta{label}.
-The lower case forms are expandable (unless the value of the key
-contains unexpandable commands). The commands beginning with an
-upper case letter convert the first letter of the required value to
-upper case and are not expandable. None of these commands check for
-the existence of \meta{label}.
-
-\begin{definition}[\DescribeMacro{\glshyperlink}]
-\cs{glshyperlink}\oarg{link text}\marg{label}
-\end{definition}
-This command provides a hyperlink to the glossary entry given by
-\meta{label} \strong{but does not add any information to the
-glossary file}. The link text is given by
-\ics{glsentrytext}\marg{label} by default\footnote{versions before
-3.0 used \ics{glsentryname} as the default, but this could cause
-problems when \gloskey{name} had been \glsd{sanitize}.}, but can be
-overridden using the optional argument. Note that the hyperlink will
-be suppressed if you have used \ics{glsdisablehyper} or if you
-haven't loaded the \sty{hyperref} package.
-
-\begin{important}
-If you use \cs{glshyperlink}, you need to ensure that the relevant
-entry has been added to the glossary using any of the commands
-described in \sectionref{sec:glslink} or \sectionref{sec:glsadd}
-otherwise you will end up with an undefined link.
-\end{important}
-
-The next two commands are only available with \opt1 or with the
-\pkgopt{savenumberlist} package option:
-\begin{definition}[\DescribeMacro{\glsentrynumberlist}]
-\cs{glsentrynumberlist}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsdisplaynumberlist}]
-\cs{glsdisplaynumberlist}\marg{label}
-\end{definition}
-Both display the \gls{numberlist} for the entry given by
-\meta{label}. When used with \opt1 a~rerun is required to ensure
-this list is up-to-date, when used with \optsor23
-a run of \gls{makeglossaries} (or \gls{makeindex}\slash\gls{xindy})
-followed by one or two runs of \LaTeX\ is required.
-
-The first command, \cs{glsentrynumberlist}, simply displays
-the number list as is. The second command,
-\cs{glsdisplaynumberlist}, formats the list using:
-\begin{definition}[\DescribeMacro{\glsnumlistsep}]
-\cs{glsnumlistsep}
-\end{definition}
-as the separator between all but the last two elements and
-\begin{definition}[\DescribeMacro{\glsnumlistlastsep}]
-\cs{glsnumlistlastsep}
-\end{definition}
-between the final two elements. The defaults are
-\verb*|, | and \verb*| \& |, respectively.
-
-\begin{important}
-\cs{glsdisplaynumberlist} is fairly experimental. It works with
-\opt1, but for \optsor23 it only works when the default counter
-format is used (that is, when the \gloskey[glslink]{format} key is
-set to \texttt{glsnumberformat}).  This command will only work with
-\sty{hyperref} if you choose \opt1.  If you try using this command
-with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be
-used instead.
-\end{important}
-
-For further information see \ifpdf section~\ref*{sec:code:glsnolink}
-\fi \qt{Displaying entry details without adding information to the
-glossary} in the documented code (\texttt{glossaries-code.pdf}).
-
-\chapter{Displaying a glossary}
-\label{sec:printglossary}
-
-All defined glossaries may be displayed using:
-\begin{description}
-\item[\opt1:]
-(Must be used with \ics{makenoidxglossaries} in the preamble.)
-\begin{definition}[\DescribeMacro\printnoidxglossaries]
-\cs{printnoidxglossaries}
-\end{definition}
-
-\item[\optsand23:]
-(Must be used with \ics{makeglossaries} in the preamble.)
-\begin{definition}[\DescribeMacro\printglossaries]
-\cs{printglossaries}
-\end{definition}
-\end{description}
-
-These commands will display all the glossaries in the order in which
-they were defined. 
-
-Note that, in the case of \optsand23, no glossaries will appear
-until you have either used the Perl script \gls{makeglossaries} or
-Lua script \gls{makeglossaries-lite.lua} or have directly used
-\gls{makeindex} or \gls{xindy} (as described in
-\sectionref{sec:makeglossaries}). 
-
-\begin{important}
-While the external files are missing, \cs{printglossary} will just do
-\ics{null} for each missing glossary to assist dictionary style
-documents that just use \cs{glsaddall} without inserting any text.  
-This use of \ics{null} ensures that all indexing information is
-written before the final page is shipped out. Once the external
-files are present \cs{null} will no longer be used. This can cause a
-spurious blank page on the first \LaTeX\ run before the glossary
-files have been created. Once these files are present, \cs{null}
-will no longer be used and so shouldn't cause interference for the
-final document.
-\end{important}
-
-\begin{xtr}
-If you use \gls{glossaries-extra}, it will insert a heading and boilerplate text when the
-external files are missing. The extension package also provides
-\cs{printunsrtglossaries} as an alternative. See the
-\gls{glossaries-extra} manual for further details.
-\end{xtr}
-
-If the glossary still does not appear after you re-\LaTeX\ your
-document, check the \gls*{makeindex}\slash\gls*{xindy} log files to
-see if there is a problem.  With \opt1, you just need two \LaTeX\
-runs to make the glossaries appear, but you may need further runs to
-make the \glspl{numberlist} up-to-date.
-
-An individual glossary can be displayed using:
-\begin{description}
-\itempar{\opt1:}
-\begin{definition}[\DescribeMacro{\printnoidxglossary}]
-\cs{printnoidxglossary}\oarg{options}
-\end{definition}
-(Must be used with \ics{makenoidxglossaries} in the preamble.)
-
-\itempar{\optsand23:}
-\begin{definition}[\DescribeMacro{\printglossary}]
-\cs{printglossary}\oarg{options}
-\end{definition}
-(Must be used with \ics{makeglossaries} in the preamble.)
-\end{description}
-where \meta{options} is a \meta{key}=\meta{value} list of options. 
-(Again, when the associated external file is missing, \cs{null} is
-inserted into the document.)
-
-The following keys are available:
-\begin{description}
-\item[{\gloskey[printglossary]{type}}] The value of this key
-specifies which glossary to print. If omitted, the default
-glossary is assumed. For example, to print the list of acronyms:
-\begin{verbatim}
-\printglossary[type=\acronymtype]
-\end{verbatim}
-Note that you can't display an ignored glossary, so don't try
-setting \gloskey[printglossary]{type} to the name of a glossary that
-was defined using \ics{newignoredglossary}, described in
-\sectionref{sec:newglossary}. (You can display an ignored glossary
-with \cs{printunsrtglossary} provided by \gls{glossaries-extra}.)
-
-\item[{\gloskey[printglossary]{title}}] This is the glossary's
-title (overriding the title specified when the glossary was 
-defined).
-
-\item[{\gloskey[printglossary]{toctitle}}] This is the title
-to use for the table of contents (if the \pkgopt{toc} package
-option has been used). It may also be used for the page header,
-depending on the page style. If omitted, the value of 
-\gloskey[printglossary]{title} is used.
-
-\item[{\gloskey[printglossary]{style}}] This specifies which
-glossary style to use for this glossary, overriding the effect
-of the \pkgopt{style} package option or \ics{glossarystyle}.
-
-\item[{\gloskey[printglossary]{numberedsection}}] This specifies
-whether to use a numbered section for this glossary, overriding
-the effect of the \pkgopt{numberedsection} package option. This
-key has the same syntax as the \pkgopt{numberedsection} package
-option, described in \sectionref{sec:pkgopts-sec}.
-
-\item[{\gloskey[printglossary]{nonumberlist}}] This is a boolean
-key. If true (\verb|nonumberlist=true|) the numberlist is suppressed
-for this glossary. If false (\verb|nonumberlist=false|) the
-numberlist is displayed for this glossary.
-
-\item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean
-key. If true the vertical gap between groups 
-is suppressed for this glossary.
-
-\item[{\gloskey[printglossary]{nopostdot}}] This is a boolean
-key. If true the full stop after the description 
-is suppressed for this glossary.
-
-\item[{\gloskey[printglossary]{entrycounter}}] This is a boolean
-key. Behaves similar to the package option of the same name.
-The corresponding package option must be used to make \ics{glsrefentry}
-work correctly.
-
-\item[{\gloskey[printglossary]{subentrycounter}}] This is a boolean
-key. Behaves similar to the package option of the same name.  If you
-want to set both \gloskey{entrycounter} and
-\gloskey{subentrycounter}, make sure you specify
-\gloskey{entrycounter} first.  The corresponding package option must
-be used to make \ics{glsrefentry} work correctly.
-
-\item[{\gloskey[printnoidxglossary]{sort}}] This key is only
-available for \opt1. Possible values are: \texttt{word} (word
-order), \texttt{letter} (letter order), \texttt{standard} (word or
-letter ordering taken from the \pkgopt{order} package option),
-\texttt{use} (order of use), \texttt{def} (order of definition)
-\texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive).
-Note that the word and letter comparisons (that is, everything other
-than \texttt{sort=use} and \texttt{sort=def}) just use a simple
-character code comparison. For a locale-sensitive sort, you must use
-either \gls{xindy} (\opt3) or \gls{bib2gls} (\opt4). Note that \gls{bib2gls}
-provides many other sort options.
-
-\begin{important}
-If you use the \texttt{use} or \texttt{def} values make sure
-that you select a glossary style that doesn't have a visual
-indicator between groups, as the grouping no longer makes sense.
-Consider using the \pkgopt{nogroupskip} option.
-\end{important}
-
-{\raggedright
-The word and letter order sort methods use
-\sty{datatool}'s
-\ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers.
-The case-insensitive sort method uses \sty{datatool}'s
-\ics{dtlicompare} handler.  The case-sensitive sort method uses 
-\sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool}
-documentation for further details.
-\par}
-
-If you don't get an error with \texttt{sort=use} and
-\texttt{sort=def} but you do get an error with one of the other sort
-options, then you probably need to use the
-\pkgopt[true]{sanitizesort} package option or make sure none of the
-entries have fragile commands in their \gloskey{sort} field.
-
-\item[{\xtrprintglosskey[\marg{label}]{label}}]
-This key is only available with \gls{glossaries-extra} and labels
-the glossary with \cs{label}\marg{label}. This is an alternative to
-the package option \pkgopt[autolabel]{numberedsection}
-
-\item[\xtrprintglosskey{target}] This is a boolean key only
-available with \gls{glossaries-extra}, which can be used to switch
-off the automatic hypertarget for each entry. (This refers to the
-target used by commands like \cs{gls} and \cs{glslink}.)
-
-This option is useful with \ics*{printunsrtglossary} as it allows
-the same list (of sub-list) of entries to be displayed multiple
-times without causing duplicate hypertarget names.
-
-\item[{\xtrprintglosskey[\marg{prefix}]{prefix}}]
-This key is only available with \gls{glossaries-extra} and provides
-another way of avoiding duplicate hypertarget names is to use a
-different prefix for those names. This locally redefines
-\ics{glolinkprefix} but note this will also affect the target for any entry
-referenced within the glossary with commands like \cs{gls},
-\cs{glslink} or \cs{glshypertarget}.
-
-\item[{\xtrprintglosskey[\marg{prefix}]{targetnameprefix}}]
-This key is only available with \gls{glossaries-extra}.
-This is similar to the \pkgoptfmt{prefix} option, but it alters the prefix of
-the hypertarget anchors without changing \ics{glslinkprefix} (so it
-won't change the hyperlinks for any entries referenced in the
-glossary).
-
-\end{description}
-
-By default, the glossary is started either by \ics{chapter*} or by
-\ics{section*}, depending on whether or not \ics{chapter} is defined.
-This can be overridden by the \pkgopt{section} package option or the
-\ics{setglossarysection} command. Numbered sectional units can be
-obtained using the \pkgopt{numberedsection} package option. Each
-glossary sets the page header via the command
-\begin{definition}[\DescribeMacro\glsglossarymark]
-\ics{glsglossarymark}\marg{title}
-\end{definition}
-If this mechanism is unsuitable for your chosen class file or page
-style package, you will need to redefine \ics{glsglossarymark}. Further
-information about these options and commands is given in
-\sectionref{sec:pkgopts-sec}.
-
-Information can be added to the start of the glossary (after the
-title and before the main body of the glossary) by redefining
-\begin{definition}[\DescribeMacro{\glossarypreamble}]
-\cs{glossarypreamble}
-\end{definition}
-For example:
-\begin{verbatim}
-\renewcommand{\glossarypreamble}{Numbers in italic 
-indicate primary definitions.}
-\end{verbatim}
-This needs to be done before the glossary is displayed.
-
-If you want a different preamble per glossary you can use
-\begin{definition}[\DescribeMacro{\setglossarypreamble}]
-\cs{setglossarypreamble}\oarg{type}\marg{preamble text}
-\end{definition}
-If \meta{type} is omitted, \cs{glsdefaulttype} is used.
-
-For example:
+where \meta{style name} is the name of the new style (avoid active
+characters). The second argument, \meta{display}, is equivalent to
+the mandatory argument of \ics{defglsentryfmt}. You can simply use
+\ics{glsgenacfmt} or you can customize the display using commands
+like \ics{ifglsused}, \ics{glsifplural} and \ics{glscapscase}.
+(See \sectionref{sec:glsdisplay} for further details.)
+If the style is likely to be used with a mixed glossary (that is entries in
+that glossary are defined both with \ics{newacronym} and
+\ics{newglossaryentry}) then you can test if the entry is an acronym
+and use \ics{glsgenacfmt} if it is or \ics{glsgenentryfmt} if it
+isn't. For example, the \acrstyle{long-short} style sets
+\meta{display} as
 \begin{verbatim}
-\setglossarypreamble{Numbers in italic 
-indicate primary definitions.}
+\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
 \end{verbatim}
-This will print the given preamble text for the main glossary,
-but not have any preamble text for any other glossaries.
-
-There is an analogous command to \cs{glossarypreamble} called
-\begin{definition}[\DescribeMacro{\glossarypostamble}]
-\cs{glossarypostamble}
-\end{definition}
-which is placed at the end of each glossary.
+(You can use \ics{ifglshasshort} instead of \ics{ifglshaslong} to
+test if the entry is an acronym if you prefer.)
 
-\begin{example}{Switch to Two Column Mode for Glossary}{ex:twocolumn}
-Suppose you are using the \glostyle{superheaderborder}
-style\footnote{you can't use the \glostyle{longheaderborder} style
-for this example as you can't use the \env{longtable} environment in
-two column mode.}, and you want the glossary to be in two columns,
-but after the glossary you want to switch back to one column mode,
-you could do:
-\begin{verbatim}
-\renewcommand*{\glossarysection}[2][]{%
-  \twocolumn[{\chapter*{#2}}]%
-  \setlength\glsdescwidth{0.6\linewidth}%
-  \glsglossarymark{\glossarytoctitle}%
-}
+The third argument, \meta{definitions}, can be used to redefine the
+commands that affect the display style, such as \ics{acronymfont}
+or, if \meta{display} uses \cs{glsgenacfmt}, \ics{genacrfullformat}
+and its variants.
 
-\renewcommand*{\glossarypostamble}{\onecolumn}
-\end{verbatim}
+Note that \ics{setacronymstyle} redefines \ics{glsentryfull} and
+\ics{acrfullfmt} to use \ics{genacrfullformat} (and similarly for
+the plural and upper case variants). If this isn't appropriate for the
+style (as in the case of styles like \acrstyle{footnote} and
+\acrstyle{dua}) \cs{newacronymstyle} should redefine these commands
+within \meta{definitions}.
 
-\end{example}
 
-Within each glossary, each entry name is formatted according to
-\begin{definition}[\DescribeMacro{\glsnamefont}]
-\cs{glsnamefont}\marg{name}
+Within \cs{newacronymstyle}'s \meta{definitions} argument you 
+can also redefine
+\begin{definition}[\DescribeMacro{\GenericAcronymFields}]
+\cs{GenericAcronymFields}
 \end{definition}
-which takes one argument: the entry name. This command is always
-used regardless of the glossary style. By default, \cs{glsnamefont}
-simply displays its argument in whatever the surrounding font
-happens to be. This means that in the list-like glossary styles
-(defined in the \sty{glossary-list} style file) the name will appear
-in bold, since the name is placed in the optional argument of
-\cs{item}, whereas in the tabular styles (defined in the
-\sty{glossary-long} and \sty{glossary-super} style files) the name
-will appear in the normal font. The hierarchical glossary styles
-(defined in the \sty{glossary-tree} style file) also set the name in
-bold.
-
-If you want to change the font for the description, or if you
-only want to change the name font for some types of entries
-but not others, you might want to consider using the
-\gls{glossaries-extra} package.
-
-\begin{example}{Changing the Font Used to Display Entry Names in the
-Glossary}{ex:glsnamefont}
-Suppose you want all the entry names to appear in 
-medium weight small caps in your glossaries, then you can do:
+This is a list of additional fields to be set in \ics{newacronym}.
+You can use the following token registers to access the entry label,
+long form and short form: \DescribeMacro{\glslabeltok}\cs{glslabeltok}, 
+\DescribeMacro{\glslongtok}\cs{glslongtok} and 
+\DescribeMacro{\glsshorttok}\cs{glsshorttok}. As with all \TeX\
+registers, you can access their values by preceding the register
+with \ics{the}.  For example, the \acrstyle{long-short} style does:
 \begin{verbatim}
-\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
+\renewcommand*{\GenericAcronymFields}{%
+   description={\the\glslongtok}}%
 \end{verbatim}
-\end{example}
-
-\chapter[Xindy (Option 3)]{Xindy (\ifpdf\opt3\else Option 3\fi)}
-\label{sec:xindy}
-
-If you want to use \gls{xindy} to sort the glossary, you
-must use the package option \pkgopt{xindy}:
+which sets the \gloskey{description} field to the long form of the
+acronym whereas the \acrstyle{long-short-desc} style does:
 \begin{verbatim}
-\usepackage[xindy]{glossaries}
+\renewcommand*{\GenericAcronymFields}{}%
 \end{verbatim}
-This ensures that the glossary information is written in 
-\gls*{xindy} syntax.
-
-\sectionref{sec:makeglossaries} covers how to use the external
-\gls{indexingapp}, and \sectionref{sec:locationsyntax} covers the
-issues involved in the location syntax. This section covers the
-commands provided by the \styfmt{glossaries} package that allow you
-to adjust the \gls{xindy} style file (\filetype{xdy}) and
-parameters.
-
-To assist writing information to the \gls{xindy} style
-file, the \styfmt{glossaries} package provides the following
-commands:
-\begin{definition}[\DescribeMacro{\glsopenbrace}]
-\cs{glsopenbrace}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsclosebrace}]
-\cs{glsclosebrace}
-\end{definition}
-which produce an open and closing brace. (This is needed because
-\verb|\{| and \verb|\}| don't expand to a simple brace character
-when written to a file.) Similarly, you can write a percent
-character using:
-\begin{definition}[\DescribeMacro{\glspercentchar}]
-\cs{glspercentchar}
-\end{definition}
-and a tilde character using:
-\begin{definition}[\DescribeMacro{\glstildechar}]
-\cs{glstildechar}
-\end{definition}
-For example, a newline character is specified in a \gls{xindy} style
-file using \verb|~n| so you can use \texttt{\cs{glstildechar} n}
-to write this correctly (or you can do \verb|\string~n|).
-A backslash can be written to a file using
-\begin{definition}[\DescribeMacro{\glsbackslash}]
-\cs{glsbackslash}
-\end{definition}
-
-In addition, if you are using a package that makes the double
-quote character active (e.g. \sty{ngerman}) you can use:
-\begin{definition}[\DescribeMacro{\glsquote}]
-\cs{glsquote}\marg{text}
-\end{definition}
-which will produce \verb|"|\meta{text}\verb|"|. Alternatively,
-you can use \verb|\string"| to write the double-quote character. 
-This document assumes that the double quote character has not been
-made active, so the examples just use \verb|"| for clarity.
-
-If you want greater control over the \gls{xindy} style file than is
-available through the \LaTeX\ commands provided by the
-\styfmt{glossaries} package, you will need to edit the \gls*{xindy}
-style file. In which case, you must use \ics{noist} to prevent the
-style file from being overwritten by the \styfmt{glossaries}
-package. For additional information about \gls*{xindy}, read the
-\gls*{xindy} documentation. I'm sorry I can't provide any assistance
-with writing \gls*{xindy} style files. If you need help, I recommend
-you ask on the \gls*{xindy} mailing list
-(\url{http://xindy.sourceforge.net/mailing-list.html}).
-
-\section{Language and Encodings}
-\label{sec:langenc}
+since the description needs to be specified by the user.
 
-When you use \gls{xindy}, you need to specify the language
-and encoding used (unless you have written your own custom
-\gls*{xindy} style file that defines the relevant alphabet
-and sort rules). If you use \gls{makeglossaries},
-this information is obtained from the document's auxiliary 
-(\filetype{aux}) file.  The \gls{makeglossaries} script attempts to 
-find the root language given your document settings, but in the 
-event that it gets it wrong or if \gls*{xindy} doesn't support 
-that language, then you can specify the required language using:
-\begin{definition}[\DescribeMacro{\GlsSetXdyLanguage}]
-\cs{GlsSetXdyLanguage}\oarg{glossary type}\marg{language}
+It may be that you want to define a new acronym style that's based
+on an existing style. Within \meta{display} you can use
+\begin{definition}[\DescribeMacro\GlsUseAcrEntryDispStyle]
+\cs{GlsUseAcrEntryDispStyle}\marg{style name}
 \end{definition}
-where \meta{language} is the name of the language. The
-optional argument can be used if you have multiple glossaries
-in different languages. If \meta{glossary type} is omitted, it
-will be applied to all glossaries, otherwise the language
-setting will only be applied to the glossary given by
-\meta{glossary type}.
-
-If the \sty{inputenc} package is used, the encoding will be
-obtained from the value of \ics{inputencodingname}. 
-Alternatively, you can specify the encoding using:
-\begin{definition}[\DescribeMacro{\GlsSetXdyCodePage}]
-\cs{GlsSetXdyCodePage}\marg{code}
+to use the \meta{display} definition from the style given by
+\meta{style name}. Within \meta{definitions} you can use
+\begin{definition}[\DescribeMacro{\GlsUseAcrStyleDefs}]
+\cs{GlsUseAcrStyleDefs}\marg{style name}
 \end{definition}
-where \meta{code} is the name of the encoding. For example:
-\begin{verbatim}
-\GlsSetXdyCodePage{utf8}
-\end{verbatim}
-
-Note that you can also specify the language and encoding using
-the package option 
-\verb|xindy={language=|\meta{lang}\verb|,codepage=|\meta{code}\verb|}|.
-For example:
-\begin{verbatim}
-\usepackage[xindy={language=english,codepage=utf8}]{glossaries}
-\end{verbatim}
-
-If you write your own custom \gls{xindy} style file that 
-includes the language settings, you need to set the language
-to nothing:
+to use the \meta{definitions} from the style given by \meta{style
+name}. For example, the \acrstyle{long-sc-short} acronym style is
+based on the \acrstyle{long-short} style with minor
+modifications (remember to use \verb|##| instead of \verb|#| within
+\meta{definitions}):
 \begin{verbatim}
-\GlsSetXdyLanguage{}
-\end{verbatim}
-(and remember to use \ics{noist} to prevent the style file from
-being overwritten).
-
-\begin{important}
-The commands \cs{GlsSetXdyLanguage} and \cs{GlsSetXdyCodePage}
-have no effect if you don't use \gls{makeglossaries}. If
-you call \gls{xindy} without \gls*{makeglossaries} you
-need to remember to set the language and encoding using the
-\xdyopt{L} and \xdyopt{C} switches.
-\end{important}
-
-\section{Locations and Number lists}
-\label{sec:xindyloc}
-
-If you use \pkgopt{xindy}, the \styfmt{glossaries} package needs to
-know which counters you will be using in the \gls{numberlist} in order to correctly format the \gls{xindy} style
-file. Counters specified using the \pkgopt{counter} package option
-or the \meta{counter} option of \ics{newglossary} are
-automatically taken care of, but if you plan to use a different
-counter in the \gloskey[glslink]{counter} key for commands like 
-\ics{glslink}, then you need to identify these counters \emph{before} 
-\ics{makeglossaries} using:
-\begin{definition}[\DescribeMacro{\GlsAddXdyCounters}]
-\cs{GlsAddXdyCounters}\marg{counter list}
-\end{definition}
-where \meta{counter list} is a comma-separated list of counter names.
+\newacronymstyle{long-sc-short}%
+{% use the same display as "long-short"
+  \GlsUseAcrEntryDispStyle{long-short}%
+}%
+{% use the same definitions as "long-short"
+  \GlsUseAcrStyleDefs{long-short}%
+  % Minor modifications:
+  \renewcommand{\acronymfont}[1]{\textsc{##1}}%
+  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+}
+\end{verbatim}
+(\DescribeMacro{\glstextup}\cs{glstextup} is used to cancel the effect 
+of \ics{textsc}. This defaults to \ics{textulc}, if defined,
+otherwise \ics{textup}. For example, the plural of \textsc{svm}
+should be rendered as \textsc{svm}s rather than \textsc{svms}.)
 
-The most likely \ixindyattrs attributes used in the \gloskey[glslink]{format} 
-key (\locfmt{textrm}, \locfmt{hyperrm} etc) are automatically added 
-to the \gls{xindy} style file, but if you want to use another 
-attribute, you need to add it using:
-\begin{definition}[\DescribeMacro{\GlsAddXdyAttribute}]
-\cs{GlsAddXdyAttribute}\marg{name}
-\end{definition}
-where \meta{name} is the name of the attribute, as used in
-the \gloskey[glslink]{format} key. 
+\begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle}
+Suppose I want my acronym on \firstuse\ to have the
+short form in the text and the long form with the description in a
+footnote. Suppose also that I want the short form to be put in small
+caps in the main body of the document, but I want it in normal
+capitals in the list of acronyms. In my list of acronyms, I want the
+long form as the name with the short form in brackets followed by
+the description. That is, in the text I want \ics{gls} on \gls{firstuse}
+to display:
+\begin{display}
+\ics{textsc}\marg{abbrv}\cs{footnote}"{"\meta{long}: \meta{description}"}"
+\end{display}
+on subsequent use:
+\begin{display}
+\ics{textsc}\marg{abbrv}
+\end{display}
+and in the list of acronyms, each entry will be displayed in the
+form:
+\begin{display}
+\meta{long} (\meta{short}) \meta{description}
+\end{display}
 
-Take care if you have multiple instances of the same location with
-different formats. The duplicate locations will be discarded
-according to the order in which the \ixindyattrs attributes are listed. Consider
-defining semantic commands to use for primary references. For
-example:
+Let's suppose it's possible that I may have a mixed glossary. I can
+check this in the second argument of \ics{newacronymstyle} using:
 \begin{verbatim}
-\newcommand*{\primary}[1]{\textbf{#1}}
-\GlsAddXdyAttribute{primary}
+\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
 \end{verbatim}
-Then in the document:
+This will use \ics{glsgenentryfmt} if the entry isn't an acronym,
+otherwise it will use \ics{glsgenacfmt}. The third argument
+(\meta{definitions}) of
+\ics{newacronymstyle} needs to redefine \ics{genacrfullformat} etc 
+so that the \firstuse\ displays the short form in the text with the 
+long form in a footnote followed by the description. This is done as
+follows (remember to use \verb|##| instead of \verb|#|):
 \begin{verbatim}
-A \gls[format=primary]{duck} is an aquatic bird.
-There are lots of different types of \gls{duck}.
+ % No case change, singular first use:
+  \renewcommand*{\genacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshort{##1}}##2%
+   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+  }%
+ % First letter upper case, singular first use: 
+  \renewcommand*{\Genacrfullformat}[2]{%
+   \firstacronymfont{\Glsentryshort{##1}}##2%
+   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+  }%
+ % No case change, plural first use:
+  \renewcommand*{\genplacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshortpl{##1}}##2%
+   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+  }%
+ % First letter upper case, plural first use:
+  \renewcommand*{\Genplacrfullformat}[2]{%
+   \firstacronymfont{\Glsentryshortpl{##1}}##2%
+   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+  }%
 \end{verbatim}
-This will give the \verb|format=primary| instance preference over
-the next use that doesn't use the \gloskey[glslink]{format} key.
-
-\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit}
-Suppose I want a bold, italic, hyperlinked location. I first need to define a
-command that will do this:
+If you think it inappropriate for the short form to be capitalised
+at the start of a sentence you can change the above to:
 \begin{verbatim}
-\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
+ % No case change, singular first use:
+  \renewcommand*{\genacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshort{##1}}##2%
+   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+  }%
+ % No case change, plural first use:
+  \renewcommand*{\genplacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshortpl{##1}}##2%
+   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+  }%
+ \let\Genacrfullformat\genacrfullformat
+ \let\Genplacrfullformat\genplacrfullformat
 \end{verbatim}
-but with \gls{xindy}, I also need to add this as an allowed
-\ixindyattrs attribute:
+Another variation is to use \ics{Glsentrylong} and
+\ics{Glsentrylongpl} in the footnote instead of \ics{glsentrylong} and
+\ics{glsentrylongpl}.
+
+Now let's suppose that commands such as \ics{glsentryfull} and
+\ics{acrfull} shouldn't
+use a~footnote, but instead use the format: \meta{long}
+(\meta{short}).
+This means that the style needs to redefine \cs{glsentryfull},
+\ics{acrfullfmt} and their plural and upper case variants.
+
+First, the non-linking commands: 
 \begin{verbatim}
-\GlsAddXdyAttribute{hyperbfit}
+  \renewcommand*{\glsentryfull}[1]{%
+    \glsentrylong{##1}\space
+      (\acronymfont{\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\Glsentryfull}[1]{%
+    \Glsentrylong{##1}\space
+      (\acronymfont{\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\glsentryfullpl}[1]{%
+    \glsentrylongpl{##1}\space
+      (\acronymfont{\glsentryshortpl{##1}})%
+  }%
+  \renewcommand*{\Glsentryfullpl}[1]{%
+    \Glsentrylongpl{##1}\space
+      (\acronymfont{\glsentryshortpl{##1}})%
+  }%
 \end{verbatim}
-Now I can use it in the optional argument of commands like
-\ics{gls}:
+Now for the linking commands:
 \begin{verbatim}
-Here is a \gls[format=hyperbfit]{sample} entry.
+  \renewcommand*{\acrfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \glsentrylong{##2}##3\space
+      (\acronymfont{\glsentryshort{##2}})%
+    }%
+  }%
+  \renewcommand*{\Acrfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \Glsentrylong{##2}##3\space
+      (\acronymfont{\glsentryshort{##2}})%
+    }%
+  }%
+  \renewcommand*{\ACRfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \MakeTextUppercase{%
+       \glsentrylong{##2}##3\space
+         (\acronymfont{\glsentryshort{##2}})%
+     }%
+    }%
+  }%
+  \renewcommand*{\acrfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \glsentrylongpl{##2}##3\space
+       (\acronymfont{\glsentryshortpl{##2}})%
+    }%
+  }%
+  \renewcommand*{\Acrfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \Glsentrylongpl{##2}##3\space
+       (\acronymfont{\glsentryshortpl{##2}})%
+    }%
+  }%
+  \renewcommand*{\ACRfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \MakeTextUppercase{%
+       \glsentrylongpl{##2}##3\space
+         (\acronymfont{\glsentryshortpl{##2}})%
+     }%
+    }%
+  }%
 \end{verbatim}
-(where \texttt{sample} is the label of the required entry).
-\end{example}
-
-\begin{important}
-Note that \cs{GlsAddXdyAttribute} has no effect if \ics{noist} is
-used or if \ics{makeglossaries} is omitted.
-\cs{GlsAddXdyAttribute} must be used before \ics{makeglossaries}.
-Additionally, \cs{GlsAddXdyCounters} must come before
-\cs{GlsAddXdyAttribute}.
-\end{important}
-
-If the location numbers include formatting commands, then
-you need to add a location style in the appropriate format using
-\begin{definition}[\DescribeMacro{\GlsAddXdyLocation}]
-\cs{GlsAddXdyLocation}\oarg{prefix-location}\marg{name}\marg{definition}
-\end{definition}
-where \meta{name} is the name of the format and \meta{definition} is
-the \gls{xindy} definition. The optional argument \meta{prefix-location}
-is needed if \cs{theH}\meta{counter} either isn't defined or is
-different from \cs{the}\meta{counter}.
-Be sure to also read \sectionref{sec:locationsyntax} for some issues
-that you may encounter.
-
-\begin{important}
-Note that \cs{GlsAddXdyLocation} has no effect if \ics{noist} is
-used or if \ics{makeglossaries} is omitted.
-\cs{GlsAddXdyLocation} must be used before \ics{makeglossaries}.
-\end{important}
+(This may cause problems with long hyperlinks, in which case adjust
+the definitions so that, for example, only the short form is inside
+the argument of \ics{glslink}.)
 
-\begin{example}{Custom Numbering System for Locations}{ex:customloc}
-Suppose I decide to use a somewhat eccentric numbering
-system for sections where I redefine \cs{thesection} as follows:
+The style also needs to redefine \ics{acronymsort} so that the
+acronyms are sorted according to the long form:
 \begin{verbatim}
-\renewcommand*{\thesection}{[\thechapter]\arabic{section}}
+  \renewcommand*{\acronymsort}[2]{##2}%
 \end{verbatim}
-If I haven't done "counter=section" in the package
-option, I need to specify that the counter will be used as a
-location number:
+If you prefer them to be sorted according to the short form you can
+change the above to:
 \begin{verbatim}
-\GlsAddXdyCounters{section}
+  \renewcommand*{\acronymsort}[2]{##1}%
 \end{verbatim}
-Next I need to add the location style (\cs{thechapter} is assumed to
-be the standard \verb"\arabic{chapter}"):
+The acronym font needs to be set to \ics{textsc} and the plural
+suffix adjusted so that the \qt{s} suffix in the plural short form
+doesn't get converted to \gls{smallcaps}:
 \begin{verbatim}
-\GlsAddXdyLocation{section}{:sep "[" "arabic-numbers" :sep "]"
-  "arabic-numbers"
-}
+  \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
+  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
 \end{verbatim}
-Note that if I have further decided to use the \sty{hyperref}
-package and want to redefine \cs{theHsection} as:
+There are a number of ways of dealing with the format in the list of
+acronyms. The simplest way is to redefine \ics{acronymentry} to the
+long form followed by the upper case short form in parentheses:
 \begin{verbatim}
-\renewcommand*{\theHsection}{\thepart.\thesection}
-\renewcommand*{\thepart}{\Roman{part}}
+ \renewcommand*{\acronymentry}[1]{%
+   \Glsentrylong{##1}\space
+     (\MakeTextUppercase{\glsentryshort{##1}})}%
 \end{verbatim}
-then I need to modify the \cs{GlsAddXdyLocation} code above to:
+(I've used \ics{Glsentrylong} instead of \ics{glsentrylong} to
+capitalise the name in the glossary.)
+
+An alternative approach is to set \ics{acronymentry} to just the
+long form and redefine \ics{GenericAcronymFields} to set the
+\gloskey{symbol} key to the short form and use a glossary style that
+displays the symbol in parentheses after the \gloskey{name} (such as
+the \glostyle{tree} style) like this:
 \begin{verbatim}
-\GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "[" 
-  "arabic-numbers" :sep "]" "arabic-numbers"
-}
+ \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}%
+ \renewcommand*{\GenericAcronymFields}{%
+    symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}%
 \end{verbatim}
-Since \ics{Roman} will result in an empty string if the counter is
-zero, it's a good idea to add an extra location to catch this:
+I'm going to use the first approach and set
+\ics{GenericAcronymFields} to do nothing:
 \begin{verbatim}
-\GlsAddXdyLocation{zero.section}{:sep "[" 
-  "arabic-numbers" :sep "]" "arabic-numbers"
-}
+ \renewcommand*{\GenericAcronymFields}{}%
 \end{verbatim}
-This example is illustrated in the sample file
-\samplefile{xdy2}.
-\end{example}
 
-\begin{example}{Locations as Dice}{ex:dice}
-Suppose I want a rather eccentric page numbering system that's
-represented by the number of dots on dice. The \sty{stix} package
-provides \cs{dicei}, \ldots, \cs{dicevi} that represent the six
-sides of a die. I can define a command that takes a number as its
-argument. If the number is less than seven, the appropriate
-\cs{dice}\meta{n} command is used otherwise it does \cs{dicevi} the
-required number of times with the leftover in a final
-\cs{dice}\meta{n}. For example, the number 16 is represented by
-\verb|\dicevi\dicevi\diceiv| ($6+6+4=16$). I've called this command
-\cs{tallynum} to match the example given earlier in 
-\sectionref{sec:locationsyntax}:
+Finally, this style needs to switch off hyperlinks on first use to
+avoid nested links:
 \begin{verbatim}
-\newrobustcmd{\tallynum}[1]{%
- \ifnum\number#1<7
-  $\csname dice\romannumeral#1\endcsname$%
- \else
-  $\dicevi$%
-  \expandafter\tallynum\expandafter{\numexpr#1-6}%
- \fi
-}
+ \glshyperfirstfalse
 \end{verbatim}
-Here's the counter command:
+Putting this all together:
 \begin{verbatim}
-newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
+\newacronymstyle{custom-fn}% new style name
+{%
+  \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+}%
+{%
+ \renewcommand*{\GenericAcronymFields}{}%
+ \glshyperfirstfalse
+  \renewcommand*{\genacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshort{##1}}##2%
+   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+  }%
+  \renewcommand*{\Genacrfullformat}[2]{%
+   \firstacronymfont{\Glsentryshort{##1}}##2%
+   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
+  }%
+  \renewcommand*{\genplacrfullformat}[2]{%
+   \firstacronymfont{\glsentryshortpl{##1}}##2%
+   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+  }%
+  \renewcommand*{\Genplacrfullformat}[2]{%
+   \firstacronymfont{\Glsentryshortpl{##1}}##2%
+   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
+  }%
+  \renewcommand*{\glsentryfull}[1]{%
+    \glsentrylong{##1}\space
+      (\acronymfont{\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\Glsentryfull}[1]{%
+    \Glsentrylong{##1}\space
+      (\acronymfont{\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\glsentryfullpl}[1]{%
+    \glsentrylongpl{##1}\space
+      (\acronymfont{\glsentryshortpl{##1}})%
+  }%
+  \renewcommand*{\Glsentryfullpl}[1]{%
+    \Glsentrylongpl{##1}\space
+      (\acronymfont{\glsentryshortpl{##1}})%
+  }%
+  \renewcommand*{\acrfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \glsentrylong{##2}##3\space
+      (\acronymfont{\glsentryshort{##2}})%
+    }%
+  }%
+  \renewcommand*{\Acrfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \Glsentrylong{##2}##3\space
+      (\acronymfont{\glsentryshort{##2}})%
+    }%
+  }%
+  \renewcommand*{\ACRfullfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \MakeTextUppercase{%
+       \glsentrylong{##2}##3\space
+         (\acronymfont{\glsentryshort{##2}})%
+     }%
+    }%
+  }%
+  \renewcommand*{\acrfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \glsentrylongpl{##2}##3\space
+       (\acronymfont{\glsentryshortpl{##2}})%
+    }%
+  }%
+  \renewcommand*{\Acrfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \Glsentrylongpl{##2}##3\space
+       (\acronymfont{\glsentryshortpl{##2}})%
+    }%
+  }%
+  \renewcommand*{\ACRfullplfmt}[3]{%
+    \glslink[##1]{##2}{%
+     \MakeTextUppercase{%
+       \glsentrylongpl{##2}##3\space
+         (\acronymfont{\glsentryshortpl{##2}})%
+     }%
+    }%
+  }%
+  \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
+  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+  \renewcommand*{\acronymsort}[2]{##2}%
+  \renewcommand*{\acronymentry}[1]{%
+   \Glsentrylong{##1}\space
+     (\MakeTextUppercase{\glsentryshort{##1}})}%
+}
 \end{verbatim}
-The \ctr{page} counter representation (\cs{thepage}) needs to be
-changed to use this command:
+
+Now I need to specify that I want to use this new style:
 \begin{verbatim}
-\renewcommand*{\thepage}{\tally{page}}
+\setacronymstyle{custom-fn}
 \end{verbatim}
-The \cs{tally} command expands to \cs{tallynum} \marg{number} so
-this needs a location class that matches this format:
+I also need to use a glossary style that suits this acronym style,
+for example \glostyle{altlist}:
 \begin{verbatim}
-\GlsAddXdyLocation{tally}{% 
- :sep "\string\tallynum\space\glsopenbrace"
- "arabic-numbers"
- :sep "\glsclosebrace"
-}
+\setglossarystyle{altlist}
 \end{verbatim}
-The space between \cs{tallynum} and \marg{number} is
-significant to \gls{xindy} so \cs{space} is required.
-
-Note that \cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define 
-commands in the form:
-\begin{definition}
-\cs{glsX}\meta{counter}"X"\meta{name}\marg{Hprefix}\marg{location}
-\end{definition}
-for each counter that has been identified either by the
-\pkgopt{counter} package option, the \meta{counter} option for
-\ics{newglossary} or in the argument of \ics{GlsAddXdyCounters}.
-The first argument \meta{Hprefix} is only relevant when used with
-the \sty{hyperref} package and indicates that \cs{theH}\meta{counter}
-is given by \cs{Hprefix}"."\cs{the}\meta{counter}. 
 
-The sample file \samplefile{xdy}, which comes with the \styfmt{glossaries}
-package, uses the default \ctr{page} counter for locations, and it
-uses the default \ics{glsnumberformat} and a custom \cs{hyperbfit}
-format. A new \gls{xindy} location called \texttt{tallynum}, as
-illustrated above, is defined to make the page numbers appear as
-dice. In order for the location numbers to
-hyperlink to the relevant pages, I~need to redefine the necessary
-\cs{glsX}\meta{counter}"X"\meta{format} commands:
+Once the acronym style has been set, I can define my acronyms:
 \begin{verbatim}
-\renewcommand{\glsXpageXglsnumberformat}[2]{%
- \linkpagenumber#2%
-}
-
-\renewcommand{\glsXpageXhyperbfit}[2]{%
- \textbf{\em\linkpagenumber#2}%
-}
+\newacronym[description={set of tags for use in 
+developing hypertext documents}]{html}{html}{Hyper 
+Text Markup Language}
 
-\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
-\end{verbatim}
-Note that the second argument of \cs{glsXpageXglsnumberformat} is
-in the format \cs{tallynum}\marg{n} so the line
-\begin{verbatim}
- \linkpagenumber#2%
+\newacronym[description={language used to describe the 
+layout of a document written in a markup language}]{css}
+{css}{Cascading Style Sheet}
 \end{verbatim}
-does
-\begin{alltt}
- \cs{linkpagenumber}\cs{tallynum}\marg{number}
-\end{alltt}
-so \cs{tallynum} is the first argument of \cs{linkpagenumber}
-and \meta{number} is the second argument.
+
+The sample file \samplefile{-custom-acronym} illustrates this
+example.
 \end{example}
 
-\begin{important}
-This method is very sensitive to the internal definition of the
-location command.
-\end{important}
+\begin{example}{Italic and Upright Abbreviations}{ex:font-abbr}
+Suppose I~want to have some abbreviations in italic and some that
+just use the surrounding font. Hard-coding this into the
+\meta{short} argument of \cs{newacronym} can cause complications.
 
-\begin{example}{Locations as Words not Digits}{ex:fmtcount}
-Suppose I want the page numbers written as words
-rather than digits and I~use the \sty{fmtcount} package to
-do this. I~can redefine \ics{thepage} as follows:
+This example uses \ics{glsaddstoragekey} to add an extra field that
+can be used to store the formatting declaration (such as \cs{em}).
 \begin{verbatim}
-\renewcommand*{\thepage}{\Numberstring{page}}
+\glsaddstoragekey{font}{}{\entryfont}
 \end{verbatim}
-This \emph{used} to get expanded to \verb|\protect \Numberstringnum |\marg{n}
-where \meta{n} is the Arabic page number. This means that I~needed to
-define a new location with the form:
+This defines a~new field/key called \texttt{font}, which defaults to
+nothing if it's not explicitly set. This also defines a command
+called \cs{entryfont} that's analogous to \cs{glsentrytext}. A~new
+style is then created to format abbreviations that access this field.
+
+There are two ways to do this. The first is to create a style that
+doesn't use \ics{glsgenacfmt} but instead provides a~modified
+version that doesn't use \cs{acronymfont}\marg{short}
+but instead uses
+\verb|{|\cs{entryfont}\verb|{\glslabel}|\meta{short}\verb|}|.
+The full format given by commands such as \cs{genacrfullformat}
+need to be similarly adjusted. For example:
 \begin{verbatim}
-\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
-  \string\Numberstringnum\space\glsopenbrace"
-  "arabic-numbers" :sep "\glsclosebrace"}
+  \renewcommand*{\genacrfullformat}[2]{%
+   \glsentrylong{##1}##2\space
+   ({\entryfont{##1}\glsentryshort{##1}})%
+  }%
 \end{verbatim}
-and if I'd used the \cs{linkpagenumber} command from the previous
-example, it would need \emph{three} arguments (the first being
-\cs{protect}):
+This will deal with commands like \ics{gls} but not commands like
+\ics{acrshort} which still use \ics{acronymfont}. Another approach
+is to redefine \cs{acronymfont} to look up the required font
+declaration. Since \cs{acronymfont} doesn't take the entry label as
+an argument, the following will only work if \cs{acronymfont} is
+used in a~context where the label is provided by \ics{glslabel}.
+This is true in \cs{gls}, \cs{acrshort} and \cs{acrfull}. The
+redefinition is now:
 \begin{verbatim}
-\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
+\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}%
 \end{verbatim}
-
-The internal definition of \cs{Numberstring} has since changed
-so that it now expands to \verb|\Numberstringnum |\marg{n}
-(no \cs{protect}). This means that the location class definition
-must be changed to:
+So the new style can be defined as:
 \begin{verbatim}
-\GlsAddXdyLocation{Numberstring}{% no \protect now!
-  :sep "\string\Numberstringnum\space\glsopenbrace"
-  "arabic-numbers" :sep "\glsclosebrace"}
+\newacronymstyle{long-font-short}
+{%
+  \GlsUseAcrEntryDispStyle{long-short}%
+}
+{%
+  \GlsUseAcrStyleDefs{long-short}%
+  \renewcommand*{\genacrfullformat}[2]{%
+   \glsentrylong{##1}##2\space
+   ({\entryfont{##1}\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\Genacrfullformat}[2]{%
+   \Glsentrylong{##1}##2\space
+   ({\entryfont{##1}\glsentryshort{##1}})%
+  }%
+  \renewcommand*{\genplacrfullformat}[2]{%
+   \glsentrylongpl{##1}##2\space
+   ({\entryfont{##1}\glsentryshortpl{##1}})%
+  }%
+  \renewcommand*{\Genplacrfullformat}[2]{%
+   \Glsentrylongpl{##1}##2\space
+   ({\entryfont{##1}\glsentryshortpl{##1}})%
+  }%
+  \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}%
+  \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}%
+}
 \end{verbatim}
-and \cs{linkpagenumber} goes back to only two arguments:
+Remember the style needs to be set before defining the entries:
 \begin{verbatim}
-\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
+\setacronymstyle{long-font-short}
 \end{verbatim}
-The other change is that \cs{Numberstring} uses
-\begin{alltt}
-\cs{the}\cs{value}\marg{counter}
-\end{alltt}
-instead of
-\begin{alltt}
-\cs{expandafter}\cs{the}\cs{csname} c@\meta{counter}\cs{endcsname}
-\end{alltt}
-so it hides \cs{c@page} from the location escaping mechanism 
-(see \sectionref{sec:locationsyntax}). This means that the page
-number may be incorrect if the indexing occurs during the output
-routine.
 
-A more recent change to \sty{fmtcount} (v3.03) now puts three
-instances of \cs{expandafter} before \verb|\the\value| which
-no longer hides \cs{c@page} from the location escaping mechanism, so
-the page numbers should once more be correct. Further changes
-to the \sty{fmtcount} package may cause a problem again.
+The complete document is contained in the sample file
+\samplefile{-font-abbr}.
+\end{example}
 
-\begin{important}
-When dealing with custom formats where the internal definitions
-are outside of your control and liable to change, it's best
-to provide a wrapper command.
-\end{important}
+Some writers and publishing houses have started to drop full stops
+(periods) from upper case initials but may still retain them for
+lower case abbreviations, while others may still use them for both
+upper and lower case. This can cause complications. Chapter~12 of
+\emph{The \TeX{}book} discusses the spacing between words but,
+briefly, the default behaviour of \TeX\ is to assume that an upper
+case character followed by a~full stop and space is an abbreviation,
+so the space is the default inter-word space whereas a~lower case
+character followed by a~full stop and space is a word occurring at
+the end of a~sentence. In the event that this isn't true, you need
+to make a~manual adjustment using \verb*| | (back slash space) in
+place of just a~space character for an inter-word mid-sentence space
+and use \verb|\@| before the full stop to indicate the end of the
+sentence.
 
-Instead of directly using \cs{Numberstring} in the definition of
-\cs{thepage}, I can provide a custom command in the same form
-as the earlier \cs{tally} command:
+For example:
 \begin{verbatim}
-\newcommand{\customfmt}[1]{\customfmtnum{\arabic{#1}}}
-\newrobustcmd{\customfmtnum}[1]{\Numberstringnum{#1}}
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
 \end{verbatim}
-This ensures that the location will always be written to
-the indexing file in the form:
-\begin{alltt}
-:locref "\glsopenbrace\glsclosebrace\glsopenbrace\string\\customfmtnum \marg{n}\glsclosebrace"
-\end{alltt}
-So the location class can be defined as:
+is typeset as
+\begin{display}
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{display}
+The spacing is more noticeable with the typewriter font:
 \begin{verbatim}
-\GlsAddXdyLocation{customfmt}{
- :sep "\string\customfmtnum\space\glsopenbrace"
- "arabic-numbers" 
- :sep "\glsclosebrace"}
+\ttfamily
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
 \end{verbatim}
-
-The sample file
-\samplefile{xdy3} illustrates this.
-\end{example}
-
-In the \gls{numberlist}, the locations are sorted according to the list
-of provided location classes. The default ordering is:
-\texttt{roman-page-numbers} (i, ii, \ldots), \texttt{arabic-page-numbers}
-(1, 2, \ldots), \texttt{arabic-section-numbers} (for example, 1.1 if the
-compositor is a full stop or 1-1 if the compositor is a
-hyphen\footnote{see \ics{glsSetCompositor} described in
-\sectionref{sec:setup}}), \texttt{alpha-page-numbers} (a, b, \ldots),
-\texttt{Roman-page-numbers} (I, II, \ldots), \texttt{Alpha-page-numbers}
-(A, B, \ldots), \texttt{Appendix-page-numbers} (for example, A.1 if the Alpha
-compositor is a full stop or A-1 if the Alpha compositor is a
-hyphen\footnote{see \ics{glsSetAlphaCompositor} described in
-\sectionref{sec:setup}}), user defined location names (as specified
-by \ics{GlsAddXdyLocation} in the order in which they were defined),
-and finally \texttt{see} (cross-referenced entries).\footnote{With
-\gls{glossaries-extra} \texttt{seealso} is appended to the end of
-the list.} This ordering can be changed using:
-
-\begin{definition}[\DescribeMacro\GlsSetXdyLocationClassOrder]
-\cs{GlsSetXdyLocationClassOrder}\marg{location names}
-\end{definition}
-where each location name is delimited by double quote marks and
-separated by white space. For example:
+is typeset as
+\begin{display}\ttfamily
+I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\end{display}
+The lower case letter at the end of ``B.Sc.''\ is confusing \TeX\
+into thinking that the full stop after it marks the end of the
+sentence. Whereas the upper case letter at the end of ``Ph.D.'' has
+confused \TeX\ into thinking that the following full stop is just
+part of the abbreviation. These can be corrected:
 \begin{verbatim}
-\GlsSetXdyLocationClassOrder{
-  "arabic-page-numbers"
-  "arabic-section-numbers"
-  "roman-page-numbers"
-  "Roman-page-numbers"
-  "alpha-page-numbers"
-  "Alpha-page-numbers"
-  "Appendix-page-numbers"
-  "see"
-}
+I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.)
 \end{verbatim}
-(Remember to add \verb|"seealso"| if you're using
-\gls{glossaries-extra}.)
 
-\begin{important}
-Note that \cs{GlsSetXdyLocationClassOrder} has no effect if 
-\ics{noist} is used or if \ics{makeglossaries} is omitted.
-\cs{GlsSetXdyLocationClassOrder} must be used before 
-\ics{makeglossaries}.
-\end{important}
+This situation is a bit problematic for \styfmt{glossaries}. The
+full stops can form part of the \meta{short} argument of
+\cs{newacronym} and the \verb*|B.Sc.\ | part can be dealt with by
+remembering to add \verb*|\ | (for example, \verb*|\gls{bsc}\ |)
+but the end of sentence case is more troublesome as you need to omit
+the sentence terminating full stop (to avoid two dots) which can
+make the source code look a little strange but you also need to
+adjust the space factor, which is usually done by inserting \cs{@}
+before the full stop.
 
-If a \gls{numberlist} consists of a sequence of consecutive 
-numbers, the range will be concatenated. The 
-number of consecutive locations that causes a range formation 
-defaults to 2, but can be changed using:
+The next example shows one way of achieving this.
+(Note that the supplemental \gls{glossaries-extra} package provides a much
+simpler way of doing this, which you may prefer to use. See 
+\gallery{sample-initialisms.shtml}{Gallery: Initialisms}.)
 
-\begin{definition}[\DescribeMacro\GlsSetXdyMinRangeLength]
-\cs{GlsSetXdyMinRangeLength}\marg{n}
-\end{definition}
-For example:
-\begin{verbatim}
-\GlsSetXdyMinRangeLength{3}
-\end{verbatim}
-The argument may also be the keyword \texttt{none}, to indicate that
-there should be no range formations. See the \gls{xindy}
-manual for further details on range formations.
+\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr}
+As from version 4.16, there's now a hook (\ics{glspostlinkhook})
+that's called at the very end of the \glslike\ and \glstextlike\
+commands. This can be redefined to check if the following character
+is a full stop. The \sty{amsgen} package (which is automatically
+loaded by \styfmt{glossaries}) provides an internal command
+called \cs{new@ifnextchar} that can be used to determine if the
+given character appears next. (For more information see the
+\sty{amsgen} documentation.)
 
-\begin{important}
-Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist}
-is used or if \ics{makeglossaries} is omitted.
-\cs{GlsSetXdyMinRangeLength} must be used before 
-\ics{makeglossaries}.
-\end{important}
-See also \sectionref{sec:ranges}.
+It's possible that I~may also want acronyms or contractions in my
+document, so I~need some way to differentiate between them.
+Here I'm going to use the same method as in
+example~\ref{ex:addstoragekey} where a~new field is defined
+to indicate the type of abbreviation:
+\begin{verbatim}
+\glsaddstoragekey{abbrtype}{word}{\abbrtype}
 
-\section{Glossary Groups}
-\label{sec:groups}
+\newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]}
+\end{verbatim}
+Now I just use \ics{newacronym} for the acronyms, for example,
+\begin{verbatim}
+\newacronym{laser}{laser}{light amplification by stimulated
+emission of radiation}
+\end{verbatim}
+and my new command \cs{newabbr} for initials, for example,
+\begin{verbatim}
+\newabbr{eg}{e.g.}{exempli gratia}
+\newabbr{ie}{i.e.}{id est}
+\newabbr{bsc}{B.Sc.}{Bachelor of Science}
+\newabbr{ba}{B.A.}{Bachelor of Arts}
+\newabbr{agm}{A.G.M.}{annual general meeting}
+\end{verbatim}
+Within \cs{glspostlinkhook} the entry's label can be accessed using
+\ics{glslabel} and \ics{ifglsfieldeq} can be used to determine if
+the current entry has the new \texttt{abbrtype} field set to
+\qt{initials}. If it doesn't, then nothing needs to happen, but if
+it does, a~check is performed to see if the next character is a~full
+stop. If it is, this signals the end of a~sentence otherwise it's
+mid-sentence.
 
-The glossary is divided into groups according to the first
-letter of the sort key. The \styfmt{glossaries} package also adds
-a number group by default, unless you suppress it in the
-\pkgopt{xindy} package option. For example:
+Remember that internal commands within the document file (rather
+than in a~class or package) need to be placed between
+\ics{makeatletter} and \ics{makeatother}:
 \begin{verbatim}
-\usepackage[xindy={glsnumbers=false}]{glossaries}
+\makeatletter
+\renewcommand{\glspostlinkhook}{%
+ \ifglsfieldeq{\glslabel}{abbrtype}{initials}%
+ {\new@ifnextchar.\doendsentence\doendword}
+ {}%
+}
+\makeatother
 \end{verbatim}
-Any entry that doesn't go in one of the letter groups or the
-number group is placed in the default group. If you want \gls{xindy}
-to sort the number group numerically (rather than by a string sort)
-then you need to use \gls{xindy}['s] \texttt{numeric-sort} module:
+In the event that a full stop is found \cs{doendsentence} is
+performed but it will be followed by the full stop, which needs to
+be discarded. Otherwise \cs{doendword} will be done but it won't be
+followed by a full stop so there's nothing to discard. The
+definitions for these commands are:
 \begin{verbatim}
-\GlsAddXdyStyle{numeric-sort}
+\newcommand{\doendsentence}[1]{\spacefactor=10000{}}
+\newcommand{\doendword}{\spacefactor=1000{}}
 \end{verbatim}
+Now, I can just do \verb|\gls{bsc}| mid-sentence and
+\verb|\gls{phd}.| at the end of the sentence. The terminating full
+stop will be discarded in the latter case, but it won't be discarded
+in, say, \verb|\gls{laser}.| as that doesn't have the
+\texttt{abbrtype} field set to \qt{initials}.
 
-If you don't use \texttt{glsnumbers=false}, the default behaviour is to locate
-the number group before the \qt{A} letter group. If you are not using a
-Roman alphabet, you need to change this using:
+This also works on first use when the style is set to one of the
+\meta{long} (\meta{short}) styles but it will fail with the
+\meta{short} (\meta{long}) styles as in this case the terminating
+full stop shouldn't be discarded. Since \ics{glspostlinkhook} is
+used after the \firstuseflag\ has been unset for the entry, this
+can't be fixed by simply checking with \ics{ifglsused}. One possible
+solution to this is to redefine \ics{glslinkpostsetkeys} to check
+for the \firstuseflag\ and define a macro that can then be used in
+\ics{glspostlinkhook}.
 
+The other thing to consider is what to do with plurals. One
+possibility is to check for plural use within \cs{doendsentence}
+(using \ics{glsifplural}) and put the full stop back if the plural
+has been used.
 
-\begin{definition}[\DescribeMacro\GlsSetXdyFirstLetterAfterDigits]
-\cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter}
-\end{definition}
-where \meta{letter} is the first letter of your alphabet. Take care
-if you're using \sty{inputenc} as non-ASCII characters are actually
-active characters that expand. (This isn't a problem with the native
-UTF-8 engines and \sty{fontspec}.) The starred form will sanitize
-the argument to prevent expansion.
-Alternatively you can use:
+The complete document is contained in the sample file
+\samplefile{-dot-abbr}.
+\end{example}
 
+\section{Displaying the List of Acronyms}
+\label{sec:disploa}
 
-\begin{definition}[\DescribeMacro\GlsSetXdyNumberGroupOrder]
-\cs{GlsSetXdyNumberGroupOrder}\marg{relative location}
-\end{definition}
-to change the default
+The list of acronyms is just like any other type of glossary and can
+be displayed on its own using:
+\begin{description}
+\itempar{\opt1:}
 \begin{alltt}
-:before \cs{string}"\meta{letter}\cs{string}"
+\ics{printnoidxglossary}[type=\ics{acronymtype}]
 \end{alltt}
-to \meta{relative location}. For example:
-\begin{verbatim}
-\GlsSetXdyNumberGroupOrder{:after \string"Z\string"}
-\end{verbatim}
-will put the number group after the \qt{Z} letter group.
-Again take care of active characters. There's a starred version
-that sanitizes the argument (so don't use \cs{string} in it).
+
+\itempar{\optsand23:}
 \begin{alltt}
-\cs{GlsSetXdyNumberGroupOrder}*\{:after "\"O"\}
+\ics{printglossary}[type=\ics{acronymtype}]
 \end{alltt}
 
-\begin{important}
-Note that these commands have no effect if 
-\ics{noist} is used or if \ics{makeglossaries} is omitted.
-\cs{GlsSetXdyFirstLetterAfterDigits} must be used before 
-\ics{makeglossaries}.\par
-\end{important}
+(If you use the
+\pkgopt{acronym} package option you can also use 
+\begin{alltt}
+\ics{printacronyms}\oarg{options}
+\end{alltt}
+as a synonym for
+\begin{alltt}
+\ics{printglossary}[type=\ics{acronymtype},\meta{options}]
+\end{alltt}
+See \sectionref{sec:pkgopts-acronym}.)
 
+\end{description}
+Alternatively the list of acronyms can be displayed with all the other 
+glossaries using:
+\begin{description}
+\item[\opt1:] \ics{printnoidxglossaries}
 
-\chapter{Defining New Glossaries}
-\label{sec:newglossary}
+\item[\optsand23:] \ics{printglossaries}
+\end{description}
 
-A new glossary can be defined using:
-\begin{definition}[\DescribeMacro{\newglossary}]
-\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\linebreak\marg{title}\oarg{counter}
-\end{definition}
-where \meta{name} is the label to assign to this glossary.
-The arguments \meta{in-ext} and \meta{out-ext} specify the extensions to
-give to the input and output files for that glossary, \meta{title}
-is the default title for this new glossary and the final optional
-argument \meta{counter} specifies which counter to use for the
-associated \glspl{numberlist} (see also
-\sectionref{sec:numberlists}). The first optional argument specifies
-the extension for the \gls{makeindex} (\opt2) or \gls{xindy} (\opt3)
-transcript file (this information is only used by
-\gls{makeglossaries} which picks up the information from the
-auxiliary file).  If you use \opt1, the \meta{log-ext},
-\meta{in-ext} and \meta{out-ext} arguments are ignored.
+However, care must be taken to choose a glossary style that's
+appropriate to your acronym style.
+Alternatively, you can define your own custom style (see 
+\sectionref{sec:newglossarystyle} for further details).
 
-\begin{important}
-The glossary label \meta{name} must not contain any active
-characters. It's generally best to stick with just characters that
-have category code~11 (typically the non-extended \glspl{latinchar}
-for standard \LaTeX).
-\end{important}
+\section{Upgrading From the glossary Package}
+\label{sec:oldacronym}
 
-There is also a starred version (new to v4.08):
-\begin{definition}[\DescribeMacro{\newglossary*}]
-\cs{newglossary*}\marg{name}\marg{title}\oarg{counter}
-\end{definition}
-which is equivalent to
-\begin{alltt}
-\cs{newglossary}[\meta{name}-glg]\marg{name}\{\meta{name}-gls\}\{\meta{name}-glo\}\ifpdf\linebreak\fi\marg{title}\oarg{counter}
-\end{alltt}
-or you can also use:
-\begin{definition}[\DescribeMacro{\altnewglossary}]
-\cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter}
-\end{definition}
-which is equivalent to
-\begin{alltt}
-\cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter}
-\end{alltt}
+Users of the obsolete \sty{glossary} package may recall that
+the syntax used to define new acronyms has changed with the
+replacement \styfmt{glossaries} package. In addition, the old
+\sty{glossary} package created the command 
+\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}.
 
-It may be that you have some terms that are so common
-that they don't need to be listed. In this case, you can define 
-a~special type of glossary that doesn't create any associated files.
-This is referred to as an \qt{ignored glossary} and it's ignored by
-commands that iterate over all the glossaries, such as
-\ics{printglossaries}. To define an ignored glossary, use
-\begin{definition}[\DescribeMacro\newignoredglossary]
-\cs{newignoredglossary}\marg{name}
+In order to facilitate migrating from the old package to the new
+one, the \styfmt{glossaries} package\footnote{as from version 1.18} 
+provides the command:
+\begin{definition}[\DescribeMacro{\oldacronym}]
+\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}
 \end{definition}
-where \meta{name} is the name of the glossary (as above). This
-glossary type will automatically be added to the
-\pkgopt{nohypertypes} list, since there are no hypertargets for
-the entries in an ignored glossary.
-(The sample file \samplefile{-entryfmt} defines an ignored glossary.)
+This uses the same syntax as the \sty{glossary} package's
+method of defining acronyms. It is equivalent to:
+\begin{display}
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
+\end{display}
+In addition, \ics{oldacronym} also defines the commands
+\cs{}\meta{label}, which is equivalent to \ics{gls}\marg{label},
+and \cs{}\meta{label}\texttt{*}, which is equivalent to
+\ics{Gls}\marg{label}. If \meta{label} is omitted, \meta{abbrv}
+is used. Since commands names must consist only of alphabetical
+characters, \meta{label} must also only consist of alphabetical
+characters. Note that \cs{}\meta{label} doesn't allow you to use
+the first optional argument of \ics{gls} or \ics{Gls} --- you will
+need to explicitly use \ics{gls} or \ics{Gls} to change the
+settings.
 
-\begin{xtr}
-The \gls{glossaries-extra} package provides a starred version of
-this command that allows hyperlinks (since ignored glossaries can be
-useful with \gls{bib2gls}). There is also an analogous 
-\ics*{provideignoredglossary} command.
-\end{xtr}
+\begin{important}
+Recall that, in general, \LaTeX\ ignores spaces following command 
+names consisting of alphabetical characters. This is also true for 
+\cs{}\meta{label} unless you additionally load the
+\sty{xspace} package, but be aware that there are some issues with
+using \sty{xspace}.\footnotemark
+\end{important}
+\footnotetext{See David Carlisle's explanation in
+\href{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}{Drawbacks
+of xspace}}
 
-You can test if a glossary is an ignored one using:
-\begin{definition}[\DescribeMacro\ifignoredglossary]
-\cs{ifignoredglossary}\marg{name}\marg{true}\marg{false}
-\end{definition}
-This does \meta{true} if \meta{name} was defined as an ignored
-glossary, otherwise it does \meta{false}.
+The \styfmt{glossaries} package doesn't load the \sty{xspace} package
+since there are both advantages and disadvantages to using
+\ics{xspace} in \cs{}\meta{label}. If you don't use the 
+\sty{xspace} package you need to explicitly force a space using
+\verb*|\ | (backslash space) however you can follow \cs{}\meta{label}
+with additional text in square brackets (the final optional
+argument to \ics{gls}). If you use the \sty{xspace} package
+you don't need to escape the spaces but you can't use
+the optional argument to insert text (you will have to explicitly
+use \ics{gls}).
 
-Note that the main (default) glossary is automatically created as:
-\begin{verbatim}
-\newglossary{main}{gls}{glo}{\glossaryname}
-\end{verbatim}
-so it can be identified by the label \texttt{main} (unless the
-\pkgopt{nomain} package option is used). Using the
-\pkgopt{acronym} package option is equivalent to:
+To illustrate this, suppose I define the acronym \qt{abc} as
+follows:
 \begin{verbatim}
-\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
+\oldacronym{abc}{example acronym}{}
 \end{verbatim}
-so it can be identified by the label \texttt{acronym}. If you are
-not sure whether the \pkgopt{acronym} option has been used, you
-can identify the list of acronyms by the command 
-\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to
-\texttt{acronym}, if the \pkgopt{acronym} option has been used,
-otherwise it is set to \texttt{main}. Note that if you are using
-the main glossary as your list of acronyms, you need to declare
-it as a list of acronyms using the package option 
-\pkgopt{acronymlists}.
+This will create the command \cs{abc} and its starred version
+\cs{abc*}. \Tableref{tab:xspace} illustrates the effect of
+\cs{abc} (on subsequent use) according to whether or not the
+\sty{xspace} package has been loaded. As can be seen from the
+final row in the table, the \sty{xspace} package prevents the
+optional argument from being recognised.
 
-The \pkgopt{symbols} package option creates a new glossary with the
-label \texttt{symbols} using:
-\begin{verbatim}
-\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
-\end{verbatim}
-The \pkgopt{numbers} package option creates a new glossary with
-the label \texttt{numbers} using:
-\begin{verbatim}
-\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
-\end{verbatim}
-The \pkgopt{index} package option creates a new glossary with
-the label \texttt{index} using:
+\begin{table}[htbp]
+\caption[The effect of using xspace]{The effect of using 
+\styfmt{xspace} with \cs{oldacronym}}
+\label{tab:xspace}
+\vskip\baselineskip
+\centering
+\begin{tabular}{lll}
+\bfseries Code & \bfseries With \styfmt{xspace} &
+\bfseries Without \styfmt{xspace}\\
+\verb|\abc.| & abc. & abc.\\
+\verb|\abc xyz| & abc xyz & abcxyz\\
+\verb|\abc\ xyz| & abc xyz & abc xyz\\
+\verb|\abc* xyz| & Abc xyz & Abc xyz\\
+\verb|\abc['s] xyz| & abc ['s] xyz & abc's xyz
+\end{tabular}
+\par
+\end{table}
+
+\chapter{Unsetting and Resetting Entry Flags}
+\label{sec:glsunset}
+
+When using the \glslike\ commands it is
+possible that you may want to use the value given by the
+\gloskey{first} key, even though you have already \glslink{firstuse}{used} the glossary
+entry. Conversely, you may want to use the value given by the
+\gloskey{text} key, even though you haven't used the glossary entry.
+The former can be achieved by one of the following commands:
+\begin{definition}[\DescribeMacro{\glsreset}]
+\cs{glsreset}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalreset}]
+\cs{glslocalreset}\marg{label}
+\end{definition}
+while the latter can be achieved by one of the following commands:
+\begin{definition}[\DescribeMacro{\glsunset}]
+\cs{glsunset}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalunset}]
+\cs{glslocalunset}\marg{label}
+\end{definition}
+You can also reset or unset all entries for a given glossary or list of
+glossaries using:
+\begin{definition}[\DescribeMacro{\glsresetall}]
+\cs{glsresetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalresetall}]
+\cs{glslocalresetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glsunsetall}]
+\cs{glsunsetall}\oarg{glossary list}
+\end{definition}
+\begin{definition}[\DescribeMacro{\glslocalunsetall}]
+\cs{glslocalunsetall}\oarg{glossary list}
+\end{definition}
+where \meta{glossary list} is a comma-separated list of 
+glossary labels. If omitted, all defined glossaries are assumed
+(except for the ignored ones).
+For example, to reset all entries in the main glossary and the
+list of acronyms:
 \begin{verbatim}
-\newglossary[ilg]{index}{ind}{idx}{\indexname}
+\glsresetall[main,acronym]
 \end{verbatim}
 
-\begin{important}
-\optsand23: all glossaries must be defined before \ics{makeglossaries} to 
-ensure that the relevant output files are opened.
+You can determine whether an entry's \gls{firstuseflag} is set using:
+\begin{definition}[\DescribeMacro{\ifglsused}]
+\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+where \meta{label} is the label of the required entry. If the
+entry has been used, \meta{true part} will be done, otherwise
+\meta{false part} will be done.
 
-See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname}, 
-especially if you are using \sty{babel} or \sty{translator}.
-(Similarly for \cs{glssymbolsgroupname} and
-\cs{glsnumbersgroupname}.) If you want to redefine \ics{indexname},
-just follow the advice in
-\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fixnam}{How to
-change LaTeX’s \qt{fixed names}}.
+Note that \cs{ifglsused} is unreliable with \gls{bib2gls} as the
+entry isn't defined on the first \LaTeX\ run, which means there's no
+way of determining if it has been used, so
+\gls{glossaries-extra} provides a similar command:
+\begin{definition}
+\ics*{GlsXtrIfUnusedOrUndefined}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+
+\begin{important}
+Be careful when using \glslike\ commands within an
+environment or command argument that gets processed multiple times
+as it can cause unwanted side-effects when the first use displayed
+text is different from subsequent use.
 \end{important}
 
-\chapter{Acronyms and Other Abbreviations}
-\label{sec:acronyms}
+For example, the \env{frame} environment in \cls{beamer} processes
+its argument for each overlay. This means that the \firstuseflag\
+will be unset on the first overlay and subsequent overlays will use
+the non-first use form.
 
-\begin{xtr}
-The \gls{glossaries-extra} package provides superior
-abbreviation handling. You may want to consider using that
-package instead of the commands described here.
-\end{xtr}
+Consider the following example:
+\begin{verbatim}
+\documentclass{beamer}
 
-\begin{important}
-Note that although this chapter uses the term \qt{acronym}, you can also
-use the commands described here for initialisms or contractions
-(as in the case of some of the examples given below).
-If the glossary title is no longer applicable (for example, it
-should be \qt{Abbreviations} rather than \qt{Acronyms}) then
-you can change the title either by redefining \ics{acronymname} (see
-\sectionref{sec:languages}) or by using the \gloskey[printglossary]{title}
-in the optional argument of \ics{printglossary} (or
-\ics{printacronyms}). Alternatively consider using the
-\gls{glossaries-extra} package's \pkgopt*{abbreviations}
-option instead.
-\end{important}
+\usepackage{glossaries}
 
-You may have noticed in \sectionref{sec:newglosentry} that when you
-specify a new entry, you can specify alternate text to use when the
-term is \glsd{firstuse} in the document. This provides a
-useful means to define abbreviations. For convenience, the
-\styfmt{glossaries} package defines the command:
-\begin{definition}[\DescribeMacro{\newacronym}]
-\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
-\end{definition}
+\newacronym{svm}{SVM}{support vector machine}
 
-This uses \ics{newglossaryentry} to create an entry with the given
-label in the glossary given by \ics{acronymtype}. You can specify a
-different glossary using the \gloskey{type} key within the optional
-argument. The \cs{newacronym} command also uses the \gloskey{long},
-\gloskey{longplural}, \gloskey{short} and \gloskey{shortplural} keys
-in \cs{newglossaryentry} to store the long and abbreviated forms and
-their plurals. 
+\begin{document}
 
-Note that the same restrictions on the entry \meta{label}
-in \ics{newglossaryentry} also apply to \cs{newacronym}
-(see \sectionref{sec:newglosentry}).
+\begin{frame}
+ \frametitle{Frame 1}
 
-\begin{important}
-If you haven't identified the specified glossary type as a list of
-acronyms (via the package option
-\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, 
-see \sectionref{sec:pkgopts-acronym}) \cs{newacronym} will add it to
-the list and \emph{reset the display style} for that glossary via
-\ics{defglsentryfmt}. If you have a mixture of acronyms and regular
-entries within the same glossary, care is needed if you want to
-change the display style: you must first identify that glossary as a
-list of acronyms and then use \ics{defglsentryfmt} (not redefine
-\ics{glsentryfmt}) before defining your entries.
-\end{important}
+ \begin{itemize}
+  \item<+-> \gls{svm}
+  \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
 
-The optional argument \marg{key-val list} allows you to specify
-additional information. Any key that can be used in the second
-argument of \ics{newglossaryentry} can also be used here in \meta{key-val
-list}.
-For example, \gloskey{description} (when used with one of the styles that
-require a description, described in
-\sectionref{sec:setacronymstyle}) or you can
-override plural forms of \meta{abbrv} or \meta{long} using the
-\gloskey{shortplural} or \gloskey{longplural} keys.
-For example:
-\begin{verbatim}
-\newacronym[longplural={diagonal matrices}]%
-  {dm}{DM}{diagonal matrix}
+\end{document}
 \end{verbatim}
-If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will
-display: diagonal matrices (DMs). If you want to use
-the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend
-you use \ics{setacronymstyle} to set the display style rather than
-using one of the pre-version 4.02 acronym styles.
-
-As with \gloskey{plural} and \gloskey{firstplural}, if
-\gloskey{longplural} is missing, it's obtained by appended 
-\ics{glspluralsuffix} to the singular form. The short plural
-\gloskey{shortplural} is obtained (is not explicitly set) by appending
-\ics{glsacrpluralsuffix} to the short form. These commands may be
-changed by the associated language files, but they can't be added to
-the usual caption hooks as there's no guarantee when they'll be
-expanded (as \hyperref[pluralsuffix]{discussed earlier}).
-A different approach is used by \styfmt{glossaries-extra}, which has
-\icatattrs category attributes to determine whether or not to append a suffix
-when forming the default value of \gloskey{shortplural}.
-
-Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
-commands like \ics{gls} and \ics{glsreset} as with any other
-glossary entry.
 
-\begin{important}
-Since \cs{newacronym} sets \verb|type=\acronymtype|,
-if you want to load a file containing acronym definitions using
-\ics{loadglsentries}\oarg{type}\marg{filename}, the optional argument
-\meta{type} will not have an effect unless you explicitly set the
-type as \verb|type=\glsdefaulttype| in the optional argument to
-\ics{newacronym}. See \sectionref{sec:loadglsentries}.
-\end{important}
+On the first overlay, \verb|\gls{svm}| produces \qt{support vector
+machine (SVM)} and then unsets the \firstuseflag. When the second
+overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which
+is unlikely to be the desired effect. I~don't know anyway around
+this and I can only offer two suggestions.
 
-\begin{example}{Defining an Abbreviation}{ex:newacronym}
-The following defines the abbreviation IDN:
-\begin{verbatim}
-\newacronym{idn}{IDN}{identification number}
-\end{verbatim}
-\verb|\gls{idn}| will produce \qt{identification number (IDN)} on
-\firstuse\ and \qt{IDN} on subsequent uses. If you want to use one
-of the \gls{smallcaps} acronym styles, described in
-\sectionref{sec:setacronymstyle}, you need to use lower case
-characters for the shortened form:
+Firstly, unset all acronyms at the start of the document and
+explicitly use \ics{acrfull} when you want the full version to be
+displayed:
 \begin{verbatim}
-\newacronym{idn}{idn}{identification number}
-\end{verbatim}
-Now \verb|\gls{idn}| will produce \qt{identification number
-(\textsc{idn})} on \firstuse\ and \qt{\textsc{idn}} on subsequent
-uses.
-\end{example}
+\documentclass{beamer}
 
-\begin{important}
-Avoid nested definitions.
-\end{important}
+\usepackage{glossaries}
 
-Recall from the warning in 
-\sectionref{sec:newglosentry} that you should avoid using
-the \glslike\ and \glstextlike\ commands within the value of
-keys like \gloskey{text} and \gloskey{first} due to complications
-arising from nested links. The same applies to abbreviations
-defined using \cs{newacronym}.
+\newacronym{svm}{SVM}{support vector machine}
 
-For example, suppose you have defined:
-\begin{verbatim}
-\newacronym{ssi}{SSI}{server side includes}
-\newacronym{html}{HTML}{hypertext markup language}
-\end{verbatim}
-you may be tempted to do:
-\begin{verbatim}
-\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
-\end{verbatim}
-\strong{Don't!} This will break the case-changing commands, such
-as \ics{Gls}, it will cause inconsistencies on \firstuse, and,
-if hyperlinks are enabled, will cause nested hyperlinks. It will
-also confuse the commands used by the entry formatting (such as
-\ics{glslabel}).
+\glsunsetall
 
-Instead, consider doing:
-\begin{verbatim}
-\newacronym
- [description={\gls{ssi} enabled \gls{html}}]
- {shtml}{SHTML}{SSI enabled HTML}
+\begin{document}
+\begin{frame}
+ \frametitle{Frame 1}
+
+ \begin{itemize}
+  \item<+-> \acrfull{svm}
+  \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
+\end{document}
 \end{verbatim}
-or
+
+Secondly, explicitly reset each acronym on first use:
 \begin{verbatim}
-\newacronym
- [description={\gls{ssi} enabled \gls{html}}]
- {shtml}{SHTML}
- {server side includes enabled hypertext markup language}
+\begin{frame}
+ \frametitle{Frame 1}
+
+ \begin{itemize}
+  \item<+-> \glsreset{svm}\gls{svm}
+  \item<+-> Stuff.
+ \end{itemize}
+\end{frame}
 \end{verbatim}
-Similarly for the \glstextlike\ commands.
+These are non-optimal, but the \cls{beamer} class is too complex for
+me to provide a programmatic solution. Other potentially problematic
+environments are some \env{tabular}-like environments (but not
+\env{tabular} itself) that process the contents in order to work out
+the column widths and then reprocess the contents to do the actual
+typesetting.
 
-Other approaches are available with \gls{glossaries-extra}.
-See the section \qt{Nested Links} in the \styfmt{glossaries-extra}
-user manual.
+The \sty{amsmath} environments, such as \env{align}, also process
+their contents multiple times, but the \styfmt{glossaries} package now
+checks for this. For \sty{tabularx}, you need to explicitly patch it
+by placing \cs{glspatchtabularx} in the preamble (or anywhere
+before the problematic use of \envfmt{tabularx}).
 
-\begin{important}
-The commands described below are similar to the \glstextlike\
-commands in that they don't modify the \firstuseflag.
-However, their display is governed by \ics{defentryfmt} with
-\ics{glscustomtext} set as appropriate. All caveats that apply to
-the \glstextlike\ commands also apply to the following commands.
-(Including the warning immediately above this box.)
-\end{important}
+\begin{xtr}
+If you need to use commands like \cs{gls} in any problematic context
+that interferes with the \gls{firstuseflag}, then you can try using
+the buffering system provided with \gls{glossaries-extra}. See the
+\qt{First Use Flag} section of the \gls{glossaries-extra} manual.
+\end{xtr}
 
-The optional arguments are the same as those for the \glstextlike\
-commands, and there are similar star and plus variants that switch
-off or on the hyperlinks. As with the \glstextlike\ commands, the
-\gls{linktext} is placed in the argument of \ics{glstextformat}.
+\section{Counting the Number of Times an Entry has been Used (First Use
+Flag Unset)}
+\label{sec:enableentrycount}
+
+As from version 4.14, it's now possible to keep track of how many
+times an entry is used. That is, how many times the \firstuseflag\
+is unset. Note that the supplemental \gls{glossaries-extra} package improves
+this function and also provides per-unit counting, which isn't
+available with the \styfmt{glossaries} package.
+
+\begin{important}
+This function is disabled by default as it adds extra
+overhead to the document build time and also switches
+\ics{newglossaryentry} (and therefore \ics{newacronym}) into
+a~preamble-only command.
+\end{important}
 
-\begin{definition}[\DescribeMacro{\acrshort}]
-\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}
+To enable this function, use
+\begin{definition}[\DescribeMacro\glsenableentrycount]
+\cs{glsenableentrycount}
 \end{definition}
-This sets the \gls{linktext} to the short form (within the argument
-of \ics{acronymfont}) for the entry given by \meta{label}. The short
-form is as supplied by the \gloskey{short} key, which
-\ics{newacronym} implicitly sets.
+before defining your entries. This adds two extra (internal) fields
+to entries: \texttt{currcount} and \texttt{prevcount}.
 
-There are also analogous upper case variants:
-\begin{definition}[\DescribeMacro{\Acrshort}]
-\cs{Acrshort}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\ACRshort}]
-\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-There are also plural versions:
-\begin{definition}[\DescribeMacro\acrshortpl]
-\cs{acrshortpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro\Acrshortpl]
-\cs{Acrshortpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro\ACRshortpl]
-\cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-The short plural form is as supplied
-by the \gloskey{shortplural} key, which \ics{newacronym} implicitly sets.
+The \texttt{currcount} field keeps track of how many times
+\cs{glsunset} is used within the document. A~local unset (using
+\cs{glslocalunset}) performs a~local rather than global increment to
+\texttt{currcount}. Remember that not all commands use
+\cs{glsunset}. Only the \glslike\ commands do this. The reset
+commands \cs{glsreset} and \cs{glslocalreset} reset this field back
+to zero (where \cs{glslocalreset} performs a~local change).
 
-\begin{definition}[\DescribeMacro{\acrlong}]
-\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This sets the \gls{linktext} to the long form for the entry given by 
-\meta{label}. The long form is as supplied
-by the \gloskey{long} key, which \ics{newacronym} implicitly sets.
+The \texttt{prevcount} field stores the final value of the
+\texttt{currcount} field \emph{from the previous run}. This value is
+read from the \filetype{aux} file at the beginning of the
+\env{document} environment.
 
-There are also analogous upper case variants:
-\begin{definition}[\DescribeMacro{\Acrlong}]
-\cs{Acrlong}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\ACRlong}]
-\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-Again there are also plural versions:
-\begin{definition}[\DescribeMacro{\acrlongpl}]
-\cs{acrlongpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Acrlongpl}]
-\cs{Acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+You can access these fields using
+\begin{definition}[\DescribeMacro\glsentrycurrcount]
+\cs{glsentrycurrcount}\marg{label}
 \end{definition}
-\begin{definition}[\DescribeMacro{\ACRlongpl}]
-\cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert}
+for the \texttt{currcount} field, and
+\begin{definition}[\DescribeMacro\glsentryprevcount]
+\cs{glsentryprevcount}\marg{label}
 \end{definition}
-The long plural form is as supplied by the \gloskey{longplural} key,
-which \ics{newacronym} implicitly sets.
+for the \texttt{prevcount} field. 
 
-The commands below display the full form of the acronym, but note
-that this isn't necessarily the same as the form used on \firstuse.
-These full-form commands are shortcuts that use the above commands,
-rather than creating the \gls{linktext} from the complete full form.
-These full-form commands have star and plus variants and optional
-arguments that are passed to the above commands.
+\begin{important}
+These commands are only defined if you have used \cs{glsenableentrycount}.
+\end{important}
 
-\begin{definition}[\DescribeMacro{\acrfull}]
-\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-This is a shortcut for
-\begin{definition}[\DescribeMacro{\acrfullfmt}]
-\cs{acrfullfmt}\marg{options}\marg{label}\marg{insert}
-\end{definition}
-which by default does
-\begin{alltt}
-\cs{acrfullformat}
- \mgroup{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}}
- \mgroup{\cs{acrshort}\oarg{options}\marg{label}}
-\end{alltt}
-where
-\begin{definition}[\DescribeMacro\acrfullformat]
-\cs{acrfullformat}\marg{long}\marg{short}
-\end{definition}
-by default does \meta{long} (\meta{short}). This command is now
-deprecated for new acronym styles but is used by the default for
-backward compatibility if \cs{setacronymstyle}
-(\sectionref{sec:setacronymstyle}) hasn't been used.  (For further
-details of these format commands see \ifpdf
-section~\ref*{sec:code:acronym} in \fi the documented code,
-\texttt{glossaries-code.pdf}.)
+For example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries
 
-There are also analogous upper case variants:
-\begin{definition}[\DescribeMacro{\Acrfull}]
-\cs{Acrfull}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro{\ACRfull}]
-\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-and plural versions:
-\begin{definition}[\DescribeMacro\acrfullpl]
-\cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro\Acrfullpl]
-\cs{Acrfullpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-\begin{definition}[\DescribeMacro\ACRfullpl]
-\cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
+\glsenableentrycount
 
-If you find the above commands too cumbersome to write, you can use
-the \pkgopt{shortcuts} package option to activate the shorter
-command names listed in \tableref{tab:shortcuts}.
+\newglossaryentry{apple}{name=apple,description={a fruit}}
 
-\begin{table}[htbp]
-\caption{Synonyms provided by the package option \pkgoptfmt{shortcuts}}
-\label{tab:shortcuts}
-\vskip\baselineskip
-\centering
-\begin{tabular}{ll}
-\bfseries Shortcut Command & \bfseries Equivalent Command\\
-\ics{acs} & \ics{acrshort}\\
-\ics{Acs} & \ics{Acrshort}\\
-\ics{acsp} & \ics{acrshortpl}\\
-\ics{Acsp} & \ics{Acrshortpl}\\
-\ics{acl} & \ics{acrlong}\\
-\ics{Acl} & \ics{Acrlong}\\
-\ics{aclp} & \ics{acrlongpl}\\
-\ics{Aclp} & \ics{Acrlongpl}\\
-\ics{acf} & \ics{acrfull}\\
-\ics{Acf} & \ics{Acrfull}\\
-\ics{acfp} & \ics{acrfullpl}\\
-\ics{Acfp} & \ics{Acrfullpl}\\
-\ics{ac} & \ics{gls}\\
-\ics{Ac} & \ics{Gls}\\
-\ics{acp} & \ics{glspl}\\
-\ics{Acp} & \ics{Glspl}
-\end{tabular}
-\end{table}
+\begin{document}
+Total usage on previous run: \glsentryprevcount{apple}.
 
-It is also possible to access the long and short forms without
-adding information to the glossary using commands analogous to
-\ics{glsentrytext} (described in \sectionref{sec:glsnolink}).
+\gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}.
+\glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}.
 
-\begin{important}
-The commands that convert the first letter to upper case come with
-the same caveats as those for analogous commands like
-\ics{Glsentrytext} (non-expandable, can't be used in PDF bookmarks,
-care needs to be taken if the first letter is an accented character
-etc). See \sectionref{sec:glsnolink}.
-\end{important}
+Number of times apple has been used: \glsentrycurrcount{apple}.
+\end{document}
+\end{verbatim}
+On the first \LaTeX\ run, \verb|\glsentryprevcount{apple}|
+produces~0. At the end of the document,
+\verb|\glsentrycurrcount{apple}| produces~4. This is because
+the only commands that have incremented the entry count are those
+that use \cs{glsunset}. That is: \cs{gls}, \cs{glsdisp} and
+\cs{Gls}. The other commands used in the above example, \cs{glsadd},
+\cs{glsentrytext} and \cs{glslink}, don't use \cs{glsunset} so they
+don't increment the entry count. On the \emph{next} \LaTeX\ run,
+\verb|\glsentryprevcount{apple}| now produces~4 as that was the
+value of the \texttt{currcount} field for the \texttt{apple} entry
+at the end of the document on the previous run.
 
-The long form can be accessed using:
-\begin{definition}[\DescribeMacro{\glsentrylong}]
-\cs{glsentrylong}\marg{label}
+When you enable the entry count using \cs{glsenableentrycount}, you
+also enable the following commands:
+\begin{definition}[\DescribeMacro\cgls]
+\cs{cgls}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-or, with the first letter converted to upper case:
-\begin{definition}[\DescribeMacro{\Glsentrylong}]
-\cs{Glsentrylong}\marg{label}
+(no case-change, singular)
+\begin{definition}[\DescribeMacro\cglspl]
+\cs{cglspl}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-Plural forms:
-\begin{definition}[\DescribeMacro{\glsentrylongpl}]
-\cs{glsentrylongpl}\marg{label}
+(no case-change, plural)
+\begin{definition}[\DescribeMacro\cGls]
+\cs{cGls}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
-\begin{definition}[\DescribeMacro{\Glsentrylongpl}]
-\cs{Glsentrylongpl}\marg{label}
+(first letter uppercase, singular), and
+\begin{definition}[\DescribeMacro\cGlspl]
+\cs{cGlspl}\oarg{options}\marg{label}\oarg{insert}
 \end{definition}
+(first letter uppercase, plural).
+These all have plus and starred variants like the analogous
+\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl} commands.
 
-Similarly, to access the short form:
-\begin{definition}[\DescribeMacro{\glsentryshort}]
-\cs{glsentryshort}\marg{label}
-\end{definition}
-or, with the first letter converted to upper case:
-\begin{definition}[\DescribeMacro{\Glsentryshort}]
-\cs{Glsentryshort}\marg{label}
-\end{definition}
-Plural forms:
-\begin{definition}[\DescribeMacro{\glsentryshortpl}]
-\cs{glsentryshortpl}\marg{label}
+If you don't use \cs{glsenableentrycount}, these commands behave
+like \cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl},
+respectively, only there will be a warning that you haven't enabled
+entry counting. If you have enabled entry counting with
+\cs{glsenableentrycount} then these commands test if
+\cs{glsentryprevcount}\marg{label} equals~1. If it doesn't then the
+analogous \cs{gls} etc will be used. If it does, then the first optional
+argument will be ignored and 
+\begin{alltt}
+\meta{cs format}\marg{label}\marg{insert}\cs{glsunset}\marg{label}
+\end{alltt}
+will be performed, where \meta{cs format} is a command that takes
+two arguments. The command used depends whether you have used
+\cs{cgls}, \cs{cglspl}, \cs{cGls} or \cs{cGlspl}.
+
+\begin{definition}[\DescribeMacro\cglsformat]
+\cs{cglsformat}\marg{label}\marg{insert}
 \end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryshortpl}]
-\cs{Glsentryshortpl}\marg{label}
+This command is used by \cs{cgls} and defaults to
+\begin{alltt}
+\cs{glsentrylong}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by
+\meta{label} has a~long form or
+\begin{alltt}
+\cs{glsentryfirst}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
+
+\begin{definition}[\DescribeMacro\cglsplformat]
+\cs{cglsplformat}\marg{label}\marg{insert}
 \end{definition}
+This command is used by \cs{cglspl} and defaults to
+\begin{alltt}
+\cs{glsentrylongpl}\marg{label}\meta{insert} 
+\end{alltt}
+if the entry given by
+\meta{label} has a~long form or
+\begin{alltt}
+\cs{glsentryfirstplural}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
 
-And the full form can be obtained using:
-\begin{definition}[\DescribeMacro{\glsentryfull}]
-\cs{glsentryfull}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryfull}]
-\cs{Glsentryfull}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsentryfullpl}]
-\cs{glsentryfullpl}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\Glsentryfullpl}]
-\cs{Glsentryfullpl}\marg{label}
+\begin{definition}[\DescribeMacro\cGlsformat]
+\cs{cGlsformat}\marg{label}\marg{insert}
 \end{definition}
-These again use \ics{acrfullformat} by default, but
-the new styles described in the section below use different
-formatting commands.
-
-\section{Changing the Abbreviation Style}
-\label{sec:setacronymstyle}
+This command is used by \cs{cGls} and defaults to
+\begin{alltt}
+\cs{Glsentrylong}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by \meta{label} has a~long form or
+\begin{alltt}
+\cs{Glsentryfirst}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
 
-It may be that the default style doesn't suit your requirements in
-which case you can switch to another style using
-\begin{definition}[\DescribeMacro{\setacronymstyle}]
-\cs{setacronymstyle}\marg{style name}
+\begin{definition}[\DescribeMacro\cGlsplformat]
+\cs{cGlsplformat}\marg{label}\marg{insert}
 \end{definition}
-where \meta{style name} is the name of the required style.
+This command is used by \cs{cGlspl} and defaults to
+\begin{alltt}
+\cs{Glsentrylongpl}\marg{label}\meta{insert}
+\end{alltt}
+if the entry given by \meta{label} has a~long form or
+\begin{alltt}
+\cs{Glsentryfirstplural}\marg{label}\meta{insert}
+\end{alltt}
+otherwise.
 
-\begin{important}
-You must use \cs{setacronymstyle} \emph{before} you define the
-acronyms with \cs{newacronym}.
-\end{important}
+This means that if the previous count for the given entry was~1, the
+entry won't be hyperlinked with the \cs{cgls}-like commands and they
+won't add a~line to the external glossary file. If you haven't used
+any of the other commands that add information to the glossary file
+(such as \cs{glsadd} or the \glstextlike\ commands) then the entry
+won't appear in the glossary.
 
-For example:
+Remember that since these commands use \cs{glsentryprevcount} you
+need to run \LaTeX\ twice to ensure they work correctly.  The
+document build order is now (at least): \texttt{(pdf)latex},
+\texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}.
+
+\begin{example}{Don't index entries that are only used once}{sec:entrycount}
+In this example, the abbreviations that have only been used once (on the previous run)
+only have their long form shown with \cs{cgls}.
 \begin{verbatim}
-\usepackage[acronym]{glossaries}
+\documentclass{article}
 
+\usepackage[colorlinks]{hyperref}
+\usepackage[acronym]{glossaries}
 \makeglossaries
 
-\setacronymstyle{long-sc-short}
+\glsenableentrycount
 
-\newacronym{html}{html}{hypertext markup language}
-\newacronym{xml}{xml}{extensible markup language}
-\end{verbatim}
-Unpredictable results can occur if you try to use multiple styles.
+\setacronymstyle{long-short}
 
-\begin{important}
-If you need multiple abbreviation styles, then try
-using the \gls{glossaries-extra} package, which has better
-abbreviation management.
-\end{important}
+\newacronym{html}{HTML}{hypertext markup language}
+\newacronym{css}{CSS}{cascading style sheets}
+\newacronym{xml}{XML}{extensible markup language}
+\newacronym{sql}{SQL}{structured query language}
+\newacronym{rdbms}{RDBMS}{relational database management system}
+\newacronym{rdsms}{RDSMS}{relational data stream management system}
 
-Unlike the default behaviour of \cs{newacronym}, the
-styles used via \cs{setacronymstyle} don't use the \gloskey{first}
-or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to
-set a~custom format that uses the \gloskey{long} and \gloskey{short}
-keys (or their plural equivalents). This means that these styles
-cope better with plurals that aren't formed by simply appending the
-singular form with the letter \qt{s}. In fact, most of the predefined
-styles use \ics{glsgenacfmt} and modify the definitions of commands
-like \ics{genacrfullformat}.
+\begin{document}
+These entries are only used once: \cgls{sql}, \cgls{rdbms},
+\cgls{xml}. These entries are used multiple times:
+\cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css},
+\cgls{rdsms}, \cgls{rdsms}.
 
-Note that when you use \cs{setacronymstyle} the \gloskey{name} key
-is set to
-\begin{definition}[\DescribeMacro{\acronymentry}]
-\cs{acronymentry}\marg{label}
-\end{definition}
-and the \gloskey{sort} key is set to
-\begin{definition}[\DescribeMacro{\acronymsort}]
-\cs{acronymsort}\marg{short}\marg{long}
-\end{definition}
-These commands are redefined by the acronym styles. However, you can
-redefine them again after the style has been set but before you use
-\cs{newacronym}. Protected expansion is performed on \cs{acronymsort}
-when the entry is defined.
+\printglossaries
+\end{document}
+\end{verbatim}
+After a complete document build (\texttt{latex}, \texttt{latex},
+\texttt{makeglossaries}, \texttt{latex}) the list of abbreviations only
+includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and
+XML
+only have their long forms displayed and don't have a~hyperlink.
+\end{example}
 
-\subsection{Predefined Acronym Styles}
-\label{sec:predefinedacrstyles}
+Remember that if you don't like typing \cs{cgls} you can create a
+synonym. For example
+\begin{verbatim}
+\let\ac\cgls
+\end{verbatim}
 
-The \styfmt{glossaries} package provides a~number of predefined
-styles. These styles apply
-\begin{definition}[\DescribeMacro{\firstacronymfont}]
-\cs{firstacronymfont}\marg{text}
-\end{definition}
-to the short form on first use and
-\begin{definition}[\DescribeMacro{\acronymfont}]
-\cs{acronymfont}\marg{text}
-\end{definition}
-on subsequent use. The styles modify the definition of
-\cs{acronymfont} as required, but \ics{firstacronymfont} is only set
-once by the package when it's loaded. By default
-\ics{firstacronymfont}\marg{text} is the same as
-\ics{acronymfont}\marg{text}.
-If you want the short form displayed differently on first use, you
-can redefine \ics{firstacronymfont} independently of the acronym
-style.
+\begin{bib2gls}
+With \gls{bib2gls} there's an analogous record counting set of
+commands. See \gls{glossaries-extra} and \gls{bib2gls} manuals for further details. 
+\end{bib2gls}
 
-The predefined styles that contain \texttt{sc} in their name (for
-example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to use
-\ics{textsc}, which means that the short form needs to be specified
-in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces
-\textsc{abc} but \verb|\textsc{ABC}| produces \textsc{ABC}.\fi
+\chapter{Displaying a Glossary}
+\label{sec:printglossary}
 
-\hypertarget{boldsc}{}%
-\begin{important}%
-Some fonts don't support bold \gls{smallcaps}, so you may need to redefine 
-\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to
-medium weight if you are using a glossary style that displays entry
-names in bold and you have chosen an acronym style that uses
-\ics{textsc}.
-\end{important}
+All defined glossaries may be displayed using:
+\begin{description}
+\item[\opt1:]
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+\begin{definition}[\DescribeMacro\printnoidxglossaries]
+\cs{printnoidxglossaries}
+\end{definition}
+which internally uses \cs{printnoidxglossary} for each glossary.
 
-The predefined styles that contain \texttt{sm} in their name
-(for example \acrstyle{long-sm-short}) redefine \cs{acronymfont} to
-use \ics{textsmaller}.  
+\item[\optsand23:]
+(Must be used with \ics{makeglossaries} in the preamble.)
+\begin{definition}[\DescribeMacro\printglossaries]
+\cs{printglossaries}
+\end{definition}
+which internally uses \cs{printglossary} for each glossary.
 
-\hypertarget{smaller}{}%
-\begin{important}
-Note that the \styfmt{glossaries} package doesn't define or load any package that
-defines \ics{textsmaller}. If you use one of the acronym styles that
-set \ics{acronymfont} to \cs{textsmaller} you must
-explicitly load the \sty{relsize} package or otherwise define
-\cs{textsmaller}.
-\end{important}
+\item[\optsto46:] (\gls{glossaries-extra} only)
+\begin{definition}[\DescribeMacro\printunsrtglossaries]
+\cs{printunsrtglossaries}
+\end{definition}
+which internally uses \cs{printunsrtglossary} for each glossary.
+\end{description}
+These commands will display all the glossaries in the order in which
+they were defined. 
 
-The remaining predefined styles redefine \cs{acronymfont}\marg{text}
-to simply do its argument \meta{text}. 
+Note that, in the case of \optsand23, no glossaries will appear
+until you have either used the Perl script \gls{makeglossaries} or
+Lua script \gls{makeglossaries-lite.lua} or have directly used
+\gls{makeindex} or \gls{xindy} (as described in
+\sectionref{sec:makeglossaries}). In the case of \opt4, no glossary
+will appear until you have used \gls{bib2gls}.
 
 \begin{important}
-In most cases, the predefined styles adjust \ics{acrfull} and
-\ics{glsentryfull} (and their plural and upper case variants) to
-reflect the style. The only exceptions to this are the 
-\acrstyle{dua} and \acrstyle{footnote} styles (and their variants).
+While the external files are missing, \cs{printglossary} will just do
+\ics{null} for each missing glossary to assist dictionary style
+documents that just use \cs{glsaddall} without inserting any text.  
+This use of \ics{null} ensures that all indexing information is
+written before the final page is shipped out. Once the external
+files are present \cs{null} will no longer be used. This can cause a
+spurious blank page on the first \LaTeX\ run before the glossary
+files have been created. Once these files are present, \cs{null}
+will no longer be used and so shouldn't cause interference for the
+final document.
 \end{important}
 
-The following styles are supplied by the \styfmt{glossaries}
-package:
-\begin{itemize}
-\item \acrstyle{long-short}, \acrstyle{long-sc-short},
-\acrstyle{long-sm-short}, \acrstyle{long-sp-short}:
+\begin{xtr}
+If you use \gls{glossaries-extra}, it will insert a heading and boilerplate text when the
+external files are missing. See the
+\gls{glossaries-extra} manual for further details.
+\end{xtr}
 
-With these three styles, acronyms are displayed in the form
-\begin{definition}
-\meta{long} (\ics{firstacronymfont}\marg{short})
-\end{definition}
-on first use and
-\begin{definition}
-\ics{acronymfont}\marg{short}
+If the glossary still does not appear after you re-\LaTeX\ your
+document, check the \gls*{makeindex}, \gls*{xindy} or \gls*{bib2gls}
+log files, as applicable, to see if there is a problem.  With \opt1,
+you just need two \LaTeX\ runs to make the glossaries appear, but
+you may need further runs to make the \glspl{numberlist} up-to-date.
+
+An individual glossary can be displayed using:
+\begin{description}
+\itempar{\opt1:}
+\begin{definition}[\DescribeMacro{\printnoidxglossary}]
+\cs{printnoidxglossary}\oarg{options}
 \end{definition}
-on subsequent use.
-They also set \cs{acronymsort}\marg{short}\marg{long} to just
-\meta{short}.  This means that the acronyms are sorted according to
-their short form.  In addition, \cs{acronymentry}\marg{label} is set
-to just the short form (enclosed in \cs{acronymfont}) and the
-\gloskey{description} key is set to the long form.
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
 
-The \acrstyle{long-sp-short} style was introduced in version~4.16
-and uses
-\begin{definition}[\DescribeMacro\glsacspace]
-\cs{glsacspace}\marg{label}
+\itempar{\optsand23:}
+\begin{definition}[\DescribeMacro{\printglossary}]
+\cs{printglossary}\oarg{options}
 \end{definition}
-for the space between the long and short forms. This defaults to
-a~non-breakable space (\verb|~|) if 
-(\cs{acronymfont}\marg{short}) is less than 3em, otherwise it uses
-a~normal space. This may be redefined as required. For example, to
-always use a~non-breakable space:
-\begin{verbatim}
-\renewcommand*{\glsacspace}[1]{~}
-\end{verbatim}
+(Must be used with \ics{makeglossaries} in the preamble.)
 
-\item \acrstyle{short-long}, \acrstyle{sc-short-long},
-\acrstyle{sm-short-long}:
+\itempar{\optsto46:}
+\begin{definition}
+\ics*{printunsrtglossary}\oarg{options}
+\end{definition}
+(May be used with or without \gls{bib2gls}.)
+\end{description}
+where \meta{options} is a \meta{key}=\meta{value} list of options. 
+(Again, when the associated external file is missing, \cs{null} is
+inserted into the document.)
 
-These three styles are analogous to the above three styles, except
-the display order is swapped to
+\begin{xtr}
+The \gls{glossaries-extra} package also provides
 \begin{definition}
-\ics{firstacronymfont}\marg{short} (\meta{long})
+\ics*{printunsrtinnerglossary}\oarg{options}\marg{pre
+code}\marg{post code}
 \end{definition}
-on first use.
+which is designed for inner or nested glossaries. It allows many, but not all,
+of the options listed below.  There's an example available in the gallery: 
+\gallery{index.php?label=bib2gls-inner}{Inner or Nested Glossaries}.
+See the \gls{glossaries-extra} package for further details.
+\end{xtr}
 
-Note, however, that \ics{acronymsort} and \ics{acronymentry} are the
-same as for the \meta{long} (\meta{short}) styles above, so the
-acronyms are still sorted according to the short form.
+The following keys are available in \marg{options}:
+\begin{description}
+\item[{\gloskey[printglossary]{type}}] The value of this key
+specifies which glossary to print. If omitted, the default
+glossary is assumed. For example, to print the list of acronyms:
+\begin{verbatim}
+\printglossary[type=\acronymtype]
+\end{verbatim}
+Note that you can't display an ignored glossary, so don't try
+setting \gloskey[printglossary]{type} to the name of a glossary that
+was defined using \ics{newignoredglossary}, described in
+\sectionref{sec:newglossary}. (You can display an ignored glossary
+with \ics*{printunsrtglossary} provided by \gls{glossaries-extra}.)
 
-\item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc},
-\acrstyle{long-sm-short-desc}, \acrstyle{long-sp-short-desc}:
+\item[{\gloskey[printglossary]{title}}] This is the glossary's
+title (overriding the title specified when the glossary was 
+defined).
 
-These are like the \acrstyle{long-short}, \acrstyle{long-sc-short},
-\acrstyle{long-sm-short} and \acrstyle{long-sp-short} styles described above, except that the
-\gloskey{description} key must be supplied in the optional argument
-of \ics{newacronym}. They also redefine \ics{acronymentry} to
-\marg{long} (\cs{acronymfont}\marg{short}) and redefine
-\ics{acronymsort}\marg{short}\marg{long} to just \meta{long}.
-This means that the acronyms are sorted according to the long form,
-and in the list of acronyms the name field has the long form
-followed by the short form in parentheses. I~recommend you use
-a~glossary style such as \glostyle{altlist} with these acronym
-styles to allow for the long name field.
+\item[{\gloskey[printglossary]{toctitle}}] This is the title
+to use for the table of contents (if the \pkgopt{toc} package
+option has been used). It may also be used for the page header,
+depending on the page style. If omitted, the value of 
+\gloskey[printglossary]{title} is used.
 
-\item \acrstyle{short-long-desc}, \acrstyle{sc-short-long-desc},
-\acrstyle{sm-short-long-desc}:
+\item[{\gloskey[printglossary]{style}}] This specifies which
+glossary style to use for this glossary, overriding the effect
+of the \pkgopt{style} package option or \ics{glossarystyle}.
 
-These styles are analogous to the above three styles, but the first
-use display style is:
-\begin{definition}
-\cs{firstacronymfont}\marg{short} (\meta{long})
-\end{definition}
-The definitions of \cs{acronymsort} and \cs{acronymentry} are the
-same as those for \acrstyle{long-short-desc} etc.
+\item[{\gloskey[printglossary]{numberedsection}}] This specifies
+whether to use a numbered section for this glossary, overriding
+the effect of the \pkgopt{numberedsection} package option. This
+key has the same syntax as the \pkgopt{numberedsection} package
+option, described in \sectionref{sec:pkgopts-sec}.
 
-\item \acrstyle{dua}, \acrstyle{dua-desc}:
+\item[{\gloskey[printglossary]{nonumberlist}}] This is a boolean
+key. If true (\verb|nonumberlist=true|) the numberlist is suppressed
+for this glossary. If false (\verb|nonumberlist=false|) the
+numberlist is displayed for this glossary.
 
-With these styles, the \glslike\ commands always display the long form 
-regardless of whether the entry has been used or not. However, \ics{acrfull}
-and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case
-of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to
-the short form and the description is set to the long form. In the
-case of \acrstyle{dua-desc}, the \gloskey{name} and \gloskey{sort}
-keys are set to the long form and the description is supplied in the
-optional argument of \ics{newacronym}.
+\item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean
+key. If true the vertical gap between groups 
+is suppressed for this glossary.
 
-\item \acrstyle{footnote}, \acrstyle{footnote-sc},
-\acrstyle{footnote-sm}:
+\item[{\gloskey[printglossary]{nopostdot}}] This is a boolean
+key. If true the full stop after the description 
+is suppressed for this glossary.
 
-With these three styles, on first use the \glslike\ commands display:
-\begin{definition}
-\cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long}
-\end{definition}
-However, \ics{acrfull} and \ics{glsentryfull} are set to 
-\cs{acronymfont}\marg{short} (\meta{long}). On subsequent use the display is:
-\begin{definition}
-\cs{acronymfont}\marg{short}
-\end{definition}
-The \gloskey{sort} and \gloskey{name} keys are set to
-the short form, and the \gloskey{description} is set to the long
-form.
+\item[{\gloskey[printglossary]{entrycounter}}] This is a boolean
+key. Behaves similar to the package option of the same name.
+The corresponding package option must be used to make \ics{glsrefentry}
+work correctly.
+
+\item[{\gloskey[printglossary]{subentrycounter}}] This is a boolean
+key. Behaves similar to the package option of the same name.  If you
+want to set both \gloskey{entrycounter} and
+\gloskey{subentrycounter}, make sure you specify
+\gloskey{entrycounter} first.  The corresponding package option must
+be used to make \ics{glsrefentry} work correctly.
+
+\item[{\gloskey[printnoidxglossary]{sort}}] This key is only
+available for \opt1. Possible values are: \texttt{word} (word
+order), \texttt{letter} (letter order), \texttt{standard} (word or
+letter ordering taken from the \pkgopt{order} package option),
+\texttt{use} (order of use), \texttt{def} (order of definition)
+\texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive).
+Note that the word and letter comparisons (that is, everything other
+than \texttt{sort=use} and \texttt{sort=def}) just use a simple
+character code comparison. For a locale-sensitive sort, you must use
+either \gls{xindy} (\opt3) or \gls{bib2gls} (\opt4). Note that \gls{bib2gls}
+provides many other sort options.
 
 \begin{important}
-In order to avoid nested hyperlinks on \firstuse\ the footnote
-styles automatically implement \pkgopt[false]{hyperfirst} for the
-acronym lists.
+If you use the \texttt{use} or \texttt{def} values make sure
+that you select a glossary style that doesn't have a visual
+indicator between groups, as the grouping no longer makes sense.
+Consider using the \pkgopt{nogroupskip} option.
 \end{important}
 
-\item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc},
-\acrstyle{footnote-sm-desc}:
+{\raggedright
+The word and letter order sort methods use
+\sty{datatool}'s
+\ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers.
+The case-insensitive sort method uses \sty{datatool}'s
+\ics{dtlicompare} handler.  The case-sensitive sort method uses 
+\sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool}
+documentation for further details.
+\par}
 
-These three styles are similar to the previous three styles, but the
-description has to be supplied in the optional argument of
-\ics{newacronym}. The \gloskey{name} key is set to the long form
-followed by the short form in parentheses and the \gloskey{sort} key
-is set to the long form. This means that the acronyms will be sorted
-according to the long form. In addition, since the \gloskey{name}
-will typically be quite wide it's best to choose a glossary style
-that can accommodate this, such as \glostyle{altlist}.
+If you don't get an error with \texttt{sort=use} and
+\texttt{sort=def} but you do get an error with one of the other sort
+options, then you probably need to use the
+\pkgopt[true]{sanitizesort} package option or make sure none of the
+entries have fragile commands in their \gloskey{sort} field.
 
-\end{itemize}
+\item[{\xtrprintglosskey[\marg{label}]{label}}]
+This key is only available with \gls{glossaries-extra} and labels
+the glossary with \cs{label}\marg{label}. This is an alternative to
+the package option \pkgopt[autolabel]{numberedsection}
 
-\begin{example}{Adapting a Predefined Acronym Style}{ex:acrstyle}
-Suppose I~want to use the \acrstyle{footnote-sc-desc} style, but 
-I~want the \gloskey{name} key set to the short form followed by the
-long form in parentheses and the \gloskey{sort} key set to the short
-form. Then I need to specify the \acrstyle{footnote-sc-desc} style:
-\begin{verbatim}
-\setacronymstyle{footnote-sc-desc}
-\end{verbatim}
-and then redefine \ics{acronymsort} and \ics{acronymentry}:
+\item[{\xtrprintglosskey[\marg{boolean}]{target}}] This boolean key is only
+available with \gls{glossaries-extra} and can be used to switch
+off the automatic hypertarget for each entry. (This refers to the
+target used by commands like \cs{gls} and \cs{glslink}.)
+
+This option is useful with \ics*{printunsrtglossary} as it allows
+the same list (or sub-list) of entries to be displayed multiple
+times without causing duplicate hypertarget names.
+
+\item[{\xtrprintglosskey[\marg{prefix}]{prefix}}]
+This key is only available with \gls{glossaries-extra} and provides
+another way of avoiding duplicate hypertarget names. In this case it uses a
+different prefix for those names. This locally redefines
+\ics{glolinkprefix} but note this will also affect the target for any entry
+referenced within the glossary with commands like \cs{gls},
+\cs{glslink} or \cs{glshypertarget}.
+
+\item[{\xtrprintglosskey[\marg{prefix}]{targetnameprefix}}]
+This key is only available with \gls{glossaries-extra}.
+This is similar to the \pkgoptfmt{prefix} option, but it alters the prefix of
+the hypertarget anchors without changing \ics{glslinkprefix} (so it
+won't change the hyperlinks for any entries referenced in the
+glossary).
+
+\item[{\xtrprintglosskey[\marg{boolean}]{groups}}]
+This boolean key is only available with \gls{glossaries-extra} and,
+if true, will attempt to perform group formation. See the
+\gls{glossaries-extra} manual for further details.
+
+\item[{\xtrprintglosskey[\marg{n}]{leveloffset}}]
+This key is only available with \ics*{printunsrtglossary}. 
+It can be used to locally adjust the
+hierarchical level used by the glossary style. See the
+\gls{glossaries-extra} manual for further details.
+\end{description}
+
+By default, the glossary is started either by \ics{chapter*} or by
+\ics{section*}, depending on whether or not \ics{chapter} is defined.
+This can be overridden by the \pkgopt{section} package option or the
+\ics{setglossarysection} command. Numbered sectional units can be
+obtained using the \pkgopt{numberedsection} package option. Each
+glossary sets the page header via the command
+\begin{definition}[\DescribeMacro\glsglossarymark]
+\ics{glsglossarymark}\marg{title}
+\end{definition}
+If this mechanism is unsuitable for your chosen class file or page
+style package, you will need to redefine \ics{glsglossarymark}. Further
+information about these options and commands is given in
+\sectionref{sec:pkgopts-sec}.
+
+Information can be added to the start of the glossary (after the
+title and before the main body of the glossary) by redefining
+\begin{definition}[\DescribeMacro{\glossarypreamble}]
+\cs{glossarypreamble}
+\end{definition}
+For example:
 \begin{verbatim}
-\renewcommand*{\acronymsort}[2]{#1}% sort by short form
-\renewcommand*{\acronymentry}[1]{%
-  \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}%
+\renewcommand{\glossarypreamble}{Numbers in italic 
+indicate primary definitions.}
 \end{verbatim}
-(I've used \cs{space} for extra clarity, but you can just use an
-actual space instead.)
+This needs to be done before the glossary is displayed.
 
-Note that the default Computer Modern fonts don't support bold
-\gls{smallcaps}, so another font is required. For example:
+If you want a different preamble per glossary you can use
+\begin{definition}[\DescribeMacro{\setglossarypreamble}]
+\cs{setglossarypreamble}\oarg{type}\marg{preamble text}
+\end{definition}
+If \meta{type} is omitted, \cs{glsdefaulttype} is used.
+
+For example:
 \begin{verbatim}
-\usepackage[T1]{fontenc}
+\setglossarypreamble{Numbers in italic 
+indicate primary definitions.}
 \end{verbatim}
-The alternative is to redefine \ics{acronymfont} so that it
-always switches to medium weight to ensure the \gls{smallcaps} setting is
-used. For example:
+This will print the given preamble text for the main glossary,
+but not have any preamble text for any other glossaries.
+
+There is an analogous command to \cs{glossarypreamble} called
+\begin{definition}[\DescribeMacro{\glossarypostamble}]
+\cs{glossarypostamble}
+\end{definition}
+which is placed at the end of each glossary.
+
+\begin{example}{Switch to Two Column Mode for Glossary}{ex:twocolumn}
+Suppose you are using the \glostyle{superheaderborder}
+style\footnote{you can't use the \glostyle{longheaderborder} style
+for this example as you can't use the \env{longtable} environment in
+two column mode.}, and you want the glossary to be in two columns,
+but after the glossary you want to switch back to one column mode,
+you could do:
 \begin{verbatim}
-\renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}}
+\renewcommand*{\glossarysection}[2][]{%
+  \twocolumn[{\chapter*{#2}}]%
+  \setlength\glsdescwidth{0.6\linewidth}%
+  \glsglossarymark{\glossarytoctitle}%
+}
+
+\renewcommand*{\glossarypostamble}{\onecolumn}
 \end{verbatim}
 
-The sample file \samplefile{FnAcrDesc} illustrates this
-example.
 \end{example}
 
-\subsection{Defining A Custom Acronym Style}
-\label{sec:customacronym}
-
-You may find that the predefined acronyms styles that come with the
-\styfmt{glossaries} package don't suit your requirements. In this
-case you can define your own style using:
-\begin{definition}[\DescribeMacro{\newacronymstyle}]
-\cs{newacronymstyle}\marg{style name}\marg{display}\marg{definitions}
+Within each glossary, each entry name is formatted according to
+\begin{definition}[\DescribeMacro{\glsnamefont}]
+\cs{glsnamefont}\marg{name}
 \end{definition}
-where \meta{style name} is the name of the new style (avoid active
-characters). The second argument, \meta{display}, is equivalent to
-the mandatory argument of \ics{defglsentryfmt}. You can simply use
-\ics{glsgenacfmt} or you can customize the display using commands
-like \ics{ifglsused}, \ics{glsifplural} and \ics{glscapscase}.
-(See \sectionref{sec:glsdisplay} for further details.)
-If the style is likely to be used with a mixed glossary (that is entries in
-that glossary are defined both with \ics{newacronym} and
-\ics{newglossaryentry}) then you can test if the entry is an acronym
-and use \ics{glsgenacfmt} if it is or \ics{glsgenentryfmt} if it
-isn't. For example, the \acrstyle{long-short} style sets
-\meta{display} as
+which takes one argument: the entry name. This command is always
+used regardless of the glossary style. By default, \cs{glsnamefont}
+simply displays its argument in whatever the surrounding font
+happens to be. This means that in the list-like glossary styles
+(defined in the \sty{glossary-list} style file) the name will appear
+in bold, since the name is placed in the optional argument of
+\cs{item}, whereas in the tabular styles (defined in the
+\sty{glossary-long} and \sty{glossary-super} style files) the name
+will appear in the normal font. The hierarchical glossary styles
+(defined in the \sty{glossary-tree} style file) also set the name in
+bold.
+
+If you want to change the font for the description, or if you
+only want to change the name font for some types of entries
+but not others, you might want to consider using the
+\gls{glossaries-extra} package.
+
+\begin{example}{Changing the Font Used to Display Entry Names in the
+Glossary}{ex:glsnamefont}
+Suppose you want all the entry names to appear in 
+medium weight small caps in your glossaries, then you can do:
 \begin{verbatim}
-\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
+\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
 \end{verbatim}
-(You can use \ics{ifglshasshort} instead of \ics{ifglshaslong} to
-test if the entry is an acronym if you prefer.)
+\end{example}
 
-The third argument, \meta{definitions}, can be used to redefine the
-commands that affect the display style, such as \ics{acronymfont}
-or, if \meta{display} uses \cs{glsgenacfmt}, \ics{genacrfullformat}
-and its variants.
+\begin{xtr}
+The \gls{glossaries-extra} package provides additional hooks that
+can be used to make other minor adjustments.
+\end{xtr}
 
-Note that \ics{setacronymstyle} redefines \ics{glsentryfull} and
-\ics{acrfullfmt} to use \ics{genacrfullformat} (and similarly for
-the plural and upper case variants). If this isn't appropriate for the
-style (as in the case of styles like \acrstyle{footnote} and
-\acrstyle{dua}) \cs{newacronymstyle} should redefine these commands
-within \meta{definitions}.
+The letter group titles (which are displayed for styles like
+\glostyle{indexgroup}) can be changed either by redefining the
+corresponding \cs{\meta{group-label}groupname} commands, such as
+\ics{glssymbolsgroupname}, (see \sectionref{sec:fixednames}) or by
+using the \gls{glossaries-extra} commands \ics*{glsxtrsetgrouptitle}
+and \ics*{glsxtrlocalsetgrouptitle}. The \meta{group-label} is
+typically obtained by the \gls{indexingapp}.
 
+\chapter{Defining New Glossaries}
+\label{sec:newglossary}
 
-Within \cs{newacronymstyle}'s \meta{definitions} argument you 
-can also redefine
-\begin{definition}[\DescribeMacro{\GenericAcronymFields}]
-\cs{GenericAcronymFields}
+A new glossary can be defined using:
+\begin{definition}[\DescribeMacro{\newglossary}]
+\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\linebreak\marg{title}\oarg{counter}
 \end{definition}
-This is a list of additional fields to be set in \ics{newacronym}.
-You can use the following token registers to access the entry label,
-long form and short form: \DescribeMacro{\glslabeltok}\cs{glslabeltok}, 
-\DescribeMacro{\glslongtok}\cs{glslongtok} and 
-\DescribeMacro{\glsshorttok}\cs{glsshorttok}. As with all \TeX\
-registers, you can access their values by preceding the register
-with \ics{the}.  For example, the \acrstyle{long-short} style does:
-\begin{verbatim}
-\renewcommand*{\GenericAcronymFields}{%
-   description={\the\glslongtok}}%
-\end{verbatim}
-which sets the \gloskey{description} field to the long form of the
-acronym whereas the \acrstyle{long-short-desc} style does:
-\begin{verbatim}
-\renewcommand*{\GenericAcronymFields}{}%
-\end{verbatim}
-since the description needs to be specified by the user.
+where \meta{name} is the label to assign to this glossary.
+The arguments \meta{in-ext} and \meta{out-ext} specify the extensions to
+give to the input and output files for that glossary, \meta{title}
+is the default title for this new glossary and the final optional
+argument \meta{counter} specifies which counter to use for the
+associated \glspl{numberlist} (see also
+\sectionref{sec:numberlists}). The first optional argument specifies
+the extension for the \gls{makeindex} (\opt2) or \gls{xindy} (\opt3)
+transcript file (this information is only used by
+\gls{makeglossaries} which picks up the information from the
+auxiliary file).  If you use \opt1, the \meta{log-ext},
+\meta{in-ext} and \meta{out-ext} arguments are ignored.
 
-It may be that you want to define a new acronym style that's based
-on an existing style. Within \meta{display} you can use
-\begin{definition}[\DescribeMacro\GlsUseAcrEntryDispStyle]
-\cs{GlsUseAcrEntryDispStyle}\marg{style name}
+\begin{important}
+The glossary label \meta{name} must not contain any active
+characters. It's generally best to stick with just characters that
+have category code~11 (typically the non-extended \glspl{latinchar}
+for standard \LaTeX).
+\end{important}
+
+There is also a starred version (new to v4.08):
+\begin{definition}[\DescribeMacro{\newglossary*}]
+\cs{newglossary*}\marg{name}\marg{title}\oarg{counter}
 \end{definition}
-to use the \meta{display} definition from the style given by
-\meta{style name}. Within \meta{definitions} you can use
-\begin{definition}[\DescribeMacro{\GlsUseAcrStyleDefs}]
-\cs{GlsUseAcrStyleDefs}\marg{style name}
+which is equivalent to
+\begin{alltt}
+\cs{newglossary}[\meta{name}-glg]\marg{name}\{\meta{name}-gls\}\{\meta{name}-glo\}\ifpdf\linebreak\fi\marg{title}\oarg{counter}
+\end{alltt}
+or you can also use:
+\begin{definition}[\DescribeMacro{\altnewglossary}]
+\cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter}
 \end{definition}
-to use the \meta{definitions} from the style given by \meta{style
-name}. For example, the \acrstyle{long-sc-short} acronym style is
-based on the \acrstyle{long-short} style with minor
-modifications (remember to use \verb|##| instead of \verb|#| within
-\meta{definitions}):
-\begin{verbatim}
-\newacronymstyle{long-sc-short}%
-{% use the same display as "long-short"
-  \GlsUseAcrEntryDispStyle{long-short}%
-}%
-{% use the same definitions as "long-short"
-  \GlsUseAcrStyleDefs{long-short}%
-  % Minor modifications:
-  \renewcommand{\acronymfont}[1]{\textsc{##1}}%
-  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
-}
-\end{verbatim}
-(\DescribeMacro{\glstextup}\cs{glstextup} is used to cancel the effect 
-of \ics{textsc}. This defaults to \ics{textulc}, if defined,
-otherwise \ics{textup}. For example, the plural of \textsc{svm}
-should be rendered as \textsc{svm}s rather than \textsc{svms}.)
-
-\begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle}
-Suppose I want my acronym on \firstuse\ to have the
-short form in the text and the long form with the description in a
-footnote. Suppose also that I want the short form to be put in small
-caps in the main body of the document, but I want it in normal
-capitals in the list of acronyms. In my list of acronyms, I want the
-long form as the name with the short form in brackets followed by
-the description. That is, in the text I want \ics{gls} on \gls{firstuse}
-to display:
-\begin{display}
-\ics{textsc}\marg{abbrv}\cs{footnote}"{"\meta{long}: \meta{description}"}"
-\end{display}
-on subsequent use:
-\begin{display}
-\ics{textsc}\marg{abbrv}
-\end{display}
-and in the list of acronyms, each entry will be displayed in the
-form:
-\begin{display}
-\meta{long} (\meta{short}) \meta{description}
-\end{display}
+which is equivalent to
+\begin{alltt}
+\cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter}
+\end{alltt}
 
-Let's suppose it's possible that I may have a mixed glossary. I can
-check this in the second argument of \ics{newacronymstyle} using:
-\begin{verbatim}
-\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
-\end{verbatim}
-This will use \ics{glsgenentryfmt} if the entry isn't an acronym,
-otherwise it will use \ics{glsgenacfmt}. The third argument
-(\meta{definitions}) of
-\ics{newacronymstyle} needs to redefine \ics{genacrfullformat} etc 
-so that the \firstuse\ displays the short form in the text with the 
-long form in a footnote followed by the description. This is done as
-follows (remember to use \verb|##| instead of \verb|#|):
-\begin{verbatim}
- % No case change, singular first use:
-  \renewcommand*{\genacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshort{##1}}##2%
-   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
-  }%
- % First letter upper case, singular first use: 
-  \renewcommand*{\Genacrfullformat}[2]{%
-   \firstacronymfont{\Glsentryshort{##1}}##2%
-   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
-  }%
- % No case change, plural first use:
-  \renewcommand*{\genplacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshortpl{##1}}##2%
-   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
-  }%
- % First letter upper case, plural first use:
-  \renewcommand*{\Genplacrfullformat}[2]{%
-   \firstacronymfont{\Glsentryshortpl{##1}}##2%
-   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
-  }%
-\end{verbatim}
-If you think it inappropriate for the short form to be capitalised
-at the start of a sentence you can change the above to:
-\begin{verbatim}
- % No case change, singular first use:
-  \renewcommand*{\genacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshort{##1}}##2%
-   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
-  }%
- % No case change, plural first use:
-  \renewcommand*{\genplacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshortpl{##1}}##2%
-   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
-  }%
- \let\Genacrfullformat\genacrfullformat
- \let\Genplacrfullformat\genplacrfullformat
-\end{verbatim}
-Another variation is to use \ics{Glsentrylong} and
-\ics{Glsentrylongpl} in the footnote instead of \ics{glsentrylong} and
-\ics{glsentrylongpl}.
+It may be that you have some terms that are so common
+that they don't need to be listed. In this case, you can define 
+a~special type of glossary that doesn't create any associated files.
+This is referred to as an \qt{ignored glossary} and it's ignored by
+commands that iterate over all the glossaries, such as
+\ics{printglossaries}. To define an ignored glossary, use
+\begin{definition}[\DescribeMacro\newignoredglossary]
+\cs{newignoredglossary}\marg{name}
+\end{definition}
+where \meta{name} is the name of the glossary (as above). This
+glossary type will automatically be added to the
+\pkgopt{nohypertypes} list, since there are no hypertargets for
+the entries in an ignored glossary.
+(The sample file \samplefile{-entryfmt} defines an ignored glossary.)
 
-Now let's suppose that commands such as \ics{glsentryfull} and
-\ics{acrfull} shouldn't
-use a~footnote, but instead use the format: \meta{long}
-(\meta{short}).
-This means that the style needs to redefine \cs{glsentryfull},
-\ics{acrfullfmt} and their plural and upper case variants.
+\begin{xtr}
+The \gls{glossaries-extra} package provides a starred version of
+this command that allows hyperlinks (since ignored glossaries can be
+useful with \gls{bib2gls}). There is also an analogous 
+\ics*{provideignoredglossary} command.
+\end{xtr}
 
-First, the non-linking commands: 
+You can test if a glossary is an ignored one using:
+\begin{definition}[\DescribeMacro\ifignoredglossary]
+\cs{ifignoredglossary}\marg{name}\marg{true}\marg{false}
+\end{definition}
+This does \meta{true} if \meta{name} was defined as an ignored
+glossary, otherwise it does \meta{false}.
+
+Note that the main (default) glossary is automatically created as:
 \begin{verbatim}
-  \renewcommand*{\glsentryfull}[1]{%
-    \glsentrylong{##1}\space
-      (\acronymfont{\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\Glsentryfull}[1]{%
-    \Glsentrylong{##1}\space
-      (\acronymfont{\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\glsentryfullpl}[1]{%
-    \glsentrylongpl{##1}\space
-      (\acronymfont{\glsentryshortpl{##1}})%
-  }%
-  \renewcommand*{\Glsentryfullpl}[1]{%
-    \Glsentrylongpl{##1}\space
-      (\acronymfont{\glsentryshortpl{##1}})%
-  }%
+\newglossary{main}{gls}{glo}{\glossaryname}
 \end{verbatim}
-Now for the linking commands:
+so it can be identified by the label \texttt{main} (unless the
+\pkgopt{nomain} package option is used). Using the
+\pkgopt{acronym} package option is equivalent to:
 \begin{verbatim}
-  \renewcommand*{\acrfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \glsentrylong{##2}##3\space
-      (\acronymfont{\glsentryshort{##2}})%
-    }%
-  }%
-  \renewcommand*{\Acrfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \Glsentrylong{##2}##3\space
-      (\acronymfont{\glsentryshort{##2}})%
-    }%
-  }%
-  \renewcommand*{\ACRfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \MakeTextUppercase{%
-       \glsentrylong{##2}##3\space
-         (\acronymfont{\glsentryshort{##2}})%
-     }%
-    }%
-  }%
-  \renewcommand*{\acrfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \glsentrylongpl{##2}##3\space
-       (\acronymfont{\glsentryshortpl{##2}})%
-    }%
-  }%
-  \renewcommand*{\Acrfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \Glsentrylongpl{##2}##3\space
-       (\acronymfont{\glsentryshortpl{##2}})%
-    }%
-  }%
-  \renewcommand*{\ACRfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \MakeTextUppercase{%
-       \glsentrylongpl{##2}##3\space
-         (\acronymfont{\glsentryshortpl{##2}})%
-     }%
-    }%
-  }%
+\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
 \end{verbatim}
-(This may cause problems with long hyperlinks, in which case adjust
-the definitions so that, for example, only the short form is inside
-the argument of \ics{glslink}.)
+so it can be identified by the label \texttt{acronym}. If you are
+not sure whether the \pkgopt{acronym} option has been used, you
+can identify the list of acronyms by the command 
+\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to
+\texttt{acronym}, if the \pkgopt{acronym} option has been used,
+otherwise it is set to \texttt{main}. Note that if you are using
+the main glossary as your list of acronyms, you need to declare
+it as a list of acronyms using the package option 
+\pkgopt{acronymlists}.
 
-The style also needs to redefine \ics{acronymsort} so that the
-acronyms are sorted according to the long form:
-\begin{verbatim}
-  \renewcommand*{\acronymsort}[2]{##2}%
-\end{verbatim}
-If you prefer them to be sorted according to the short form you can
-change the above to:
+The \pkgopt{symbols} package option creates a new glossary with the
+label \texttt{symbols} using:
 \begin{verbatim}
-  \renewcommand*{\acronymsort}[2]{##1}%
+\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
 \end{verbatim}
-The acronym font needs to be set to \ics{textsc} and the plural
-suffix adjusted so that the \qt{s} suffix in the plural short form
-doesn't get converted to \gls{smallcaps}:
+The \pkgopt{numbers} package option creates a new glossary with
+the label \texttt{numbers} using:
 \begin{verbatim}
-  \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
-  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
+\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
 \end{verbatim}
-There are a number of ways of dealing with the format in the list of
-acronyms. The simplest way is to redefine \ics{acronymentry} to the
-long form followed by the upper case short form in parentheses:
+The \pkgopt{index} package option creates a new glossary with
+the label \texttt{index} using:
 \begin{verbatim}
- \renewcommand*{\acronymentry}[1]{%
-   \Glsentrylong{##1}\space
-     (\MakeTextUppercase{\glsentryshort{##1}})}%
+\newglossary[ilg]{index}{ind}{idx}{\indexname}
 \end{verbatim}
-(I've used \ics{Glsentrylong} instead of \ics{glsentrylong} to
-capitalise the name in the glossary.)
 
-An alternative approach is to set \ics{acronymentry} to just the
-long form and redefine \ics{GenericAcronymFields} to set the
-\gloskey{symbol} key to the short form and use a glossary style that
-displays the symbol in parentheses after the \gloskey{name} (such as
-the \glostyle{tree} style) like this:
-\begin{verbatim}
- \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}%
- \renewcommand*{\GenericAcronymFields}{%
-    symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}%
-\end{verbatim}
-I'm going to use the first approach and set
-\ics{GenericAcronymFields} to do nothing:
-\begin{verbatim}
- \renewcommand*{\GenericAcronymFields}{}%
-\end{verbatim}
+\begin{important}
+\optsand23: all glossaries must be defined before \ics{makeglossaries} to 
+ensure that the relevant output files are opened.
 
-Finally, this style needs to switch off hyperlinks on first use to
-avoid nested links:
-\begin{verbatim}
- \glshyperfirstfalse
-\end{verbatim}
-Putting this all together:
-\begin{verbatim}
-\newacronymstyle{custom-fn}% new style name
-{%
-  \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
-}%
-{%
- \renewcommand*{\GenericAcronymFields}{}%
- \glshyperfirstfalse
-  \renewcommand*{\genacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshort{##1}}##2%
-   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
-  }%
-  \renewcommand*{\Genacrfullformat}[2]{%
-   \firstacronymfont{\Glsentryshort{##1}}##2%
-   \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}%
-  }%
-  \renewcommand*{\genplacrfullformat}[2]{%
-   \firstacronymfont{\glsentryshortpl{##1}}##2%
-   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
-  }%
-  \renewcommand*{\Genplacrfullformat}[2]{%
-   \firstacronymfont{\Glsentryshortpl{##1}}##2%
-   \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%
-  }%
-  \renewcommand*{\glsentryfull}[1]{%
-    \glsentrylong{##1}\space
-      (\acronymfont{\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\Glsentryfull}[1]{%
-    \Glsentrylong{##1}\space
-      (\acronymfont{\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\glsentryfullpl}[1]{%
-    \glsentrylongpl{##1}\space
-      (\acronymfont{\glsentryshortpl{##1}})%
-  }%
-  \renewcommand*{\Glsentryfullpl}[1]{%
-    \Glsentrylongpl{##1}\space
-      (\acronymfont{\glsentryshortpl{##1}})%
-  }%
-  \renewcommand*{\acrfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \glsentrylong{##2}##3\space
-      (\acronymfont{\glsentryshort{##2}})%
-    }%
-  }%
-  \renewcommand*{\Acrfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \Glsentrylong{##2}##3\space
-      (\acronymfont{\glsentryshort{##2}})%
-    }%
-  }%
-  \renewcommand*{\ACRfullfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \MakeTextUppercase{%
-       \glsentrylong{##2}##3\space
-         (\acronymfont{\glsentryshort{##2}})%
-     }%
-    }%
-  }%
-  \renewcommand*{\acrfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \glsentrylongpl{##2}##3\space
-       (\acronymfont{\glsentryshortpl{##2}})%
-    }%
-  }%
-  \renewcommand*{\Acrfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \Glsentrylongpl{##2}##3\space
-       (\acronymfont{\glsentryshortpl{##2}})%
-    }%
-  }%
-  \renewcommand*{\ACRfullplfmt}[3]{%
-    \glslink[##1]{##2}{%
-     \MakeTextUppercase{%
-       \glsentrylongpl{##2}##3\space
-         (\acronymfont{\glsentryshortpl{##2}})%
-     }%
-    }%
-  }%
-  \renewcommand*{\acronymfont}[1]{\textsc{##1}}%
-  \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
-  \renewcommand*{\acronymsort}[2]{##2}%
-  \renewcommand*{\acronymentry}[1]{%
-   \Glsentrylong{##1}\space
-     (\MakeTextUppercase{\glsentryshort{##1}})}%
-}
-\end{verbatim}
+See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname}, 
+especially if you are using \sty{babel} or \sty{translator}.
+(Similarly for \cs{glssymbolsgroupname} and
+\cs{glsnumbersgroupname}.) If you want to redefine \ics{indexname},
+just follow the advice in
+\href{https://texfaq.org/FAQ-fixnam}{How to
+change LaTeX’s \qt{fixed names}}.
+\end{important}
 
-Now I need to specify that I want to use this new style:
-\begin{verbatim}
-\setacronymstyle{custom-fn}
-\end{verbatim}
-I also need to use a glossary style that suits this acronym style,
-for example \glostyle{altlist}:
+\chapter{Adding an Entry to the Glossary Without Generating Text}
+\label{sec:glsadd}
+
+It is possible to add a line to the glossary file without
+generating any text at that point in the document using:
+\begin{definition}[\DescribeMacro{\glsadd}]
+\cs{glsadd}\oarg{options}\marg{label}
+\end{definition}
+This is similar to the \glstextlike\ commands, only it doesn't produce
+any text (so therefore, there is no \gloskey[glslink]{hyper} key
+available in \meta{options} but all the other options that can
+be used with \glstextlike\ commands can be passed to \cs{glsadd}).
+
+This command essentially works like \cs{index} (provided by the
+\LaTeX\ kernel) in that it doesn't produce text but it does add a
+line with an associated location to the glossary file. In this case,
+the \qt{encap} (the page encapsulator information) is specified with
+the \gloskey{format} key. (See \sectionref{sec:encap}.)
+
+For example, to add a page range to the glossary number list for the
+entry whose label is given by \texttt{set}:
 \begin{verbatim}
-\setglossarystyle{altlist}
+\glsadd[format=(]{set}
+Lots of text about sets spanning many pages.
+\glsadd[format=)]{set}
 \end{verbatim}
 
-Once the acronym style has been set, I can define my acronyms:
+To add all entries that have been defined, use:
+\begin{definition}[\DescribeMacro{\glsaddall}]
+\cs{glsaddall}\oarg{options}
+\end{definition}
+The optional argument is the same as for \cs{glsadd}, except
+there is also a key \gloskey[glsaddall]{types} which can be
+used to specify which glossaries to use. This should be a
+comma-separated list. For example, if you only want to add
+all the entries belonging to the list of acronyms (specified by
+the glossary type \ics{acronymtype}) and a list of
+notation (specified by the glossary type \texttt{notation}) then you can
+do:
 \begin{verbatim}
-\newacronym[description={set of tags for use in 
-developing hypertext documents}]{html}{html}{Hyper 
-Text Markup Language}
-
-\newacronym[description={language used to describe the 
-layout of a document written in a markup language}]{css}
-{css}{Cascading Style Sheet}
+\glsaddall[types={\acronymtype,notation}]
 \end{verbatim}
 
-The sample file \samplefile{-custom-acronym} illustrates this
-example.
-\end{example}
+\begin{bib2gls}
+If you are using \gls{bib2gls} with \gls{glossaries-extra}, you
+can't use \cs{glsaddall}. Instead use the \optfmt{selection=all}
+resource option to select all entries in the given \filetype{bib} files.
+\end{bib2gls}
 
-\begin{example}{Italic and Upright Abbreviations}{ex:font-abbr}
-Suppose I~want to have some abbreviations in italic and some that
-just use the surrounding font. Hard-coding this into the
-\meta{short} argument of \cs{newacronym} can cause complications.
+\begin{important}
+Note that \cs{glsadd} and \cs{glsaddall} add the current location to
+the \gls{numberlist}. In the case of \cs{glsaddall}, all entries in the
+glossary will have the same location in the number list. If you want
+to use \cs{glsaddall}, it's best to suppress the number list with
+the \pkgopt{nonumberlist} package option. (See
+sections~\ref{sec:pkgopts-printglos} and~\ref{sec:numberlists}.)
+\end{important}
 
-This example uses \ics{glsaddstoragekey} to add an extra field that
-can be used to store the formatting declaration (such as \cs{em}).
-\begin{verbatim}
-\glsaddstoragekey{font}{}{\entryfont}
-\end{verbatim}
-This defines a~new field/key called \texttt{font}, which defaults to
-nothing if it's not explicitly set. This also defines a command
-called \cs{entryfont} that's analogous to \cs{glsentrytext}. A~new
-style is then created to format abbreviations that access this field.
+There is now a variation of \cs{glsaddall} that skips any entries
+that have been \glsdisp{firstuseflag}{marked as used}:
+\begin{definition}[\DescribeMacro\glsaddallunused]
+\cs{glsaddallunused}\oarg{list}
+\end{definition}
+This command uses \cs{glsadd}\texttt{[format=glsignore]} which will
+ignore this location in the number list. (See \sectionref{sec:encap}.) 
+The optional argument \meta{list} is a comma-separated list of
+glossary types. If omitted, it defaults to the list of all defined
+glossaries.
 
-There are two ways to do this. The first is to create a style that
-doesn't use \ics{glsgenacfmt} but instead provides a~modified
-version that doesn't use \cs{acronymfont}\marg{short}
-but instead uses
-\verb|{|\cs{entryfont}\verb|{\glslabel}|\meta{short}\verb|}|.
-The full format given by commands such as \cs{genacrfullformat}
-need to be similarly adjusted. For example:
-\begin{verbatim}
-  \renewcommand*{\genacrfullformat}[2]{%
-   \glsentrylong{##1}##2\space
-   ({\entryfont{##1}\glsentryshort{##1}})%
-  }%
-\end{verbatim}
-This will deal with commands like \ics{gls} but not commands like
-\ics{acrshort} which still use \ics{acronymfont}. Another approach
-is to redefine \cs{acronymfont} to look up the required font
-declaration. Since \cs{acronymfont} doesn't take the entry label as
-an argument, the following will only work if \cs{acronymfont} is
-used in a~context where the label is provided by \ics{glslabel}.
-This is true in \cs{gls}, \cs{acrshort} and \cs{acrfull}. The
-redefinition is now:
+\begin{important}
+If you want to use \cs{glsaddallunused}, it's best to place the
+command at the end of the document to ensure that all the commands
+you intend to use have already been used. Otherwise you could end up
+with a spurious comma or dash in the location list.
+\end{important}
+
+\begin{bib2gls}
+With \gls{glossaries-extra} and \gls{bib2gls}, \texttt{glsignore}
+indicates an \qt{ignored location} which influences selection but
+isn't added to the location list. In this case, if you use
+\optfmt{selection=all} then only those entries that have been
+explicitly indexed in the document will have location lists. The
+other entries that were selected as a result of
+\optfmt{selection=all} won't have location lists.
+\end{bib2gls}
+
+Base \sty{glossaries} package only:
 \begin{verbatim}
-\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}%
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries
+\newglossaryentry{cat}{name={cat},description={feline}}
+\newglossaryentry{dog}{name={dog},description={canine}}
+\begin{document}
+\gls{cat}.
+\printglossaries
+\glsaddallunused % <- make sure dog is also listed
+\end{document}
 \end{verbatim}
-So the new style can be defined as:
+Corresponding \gls{glossaries-extra} and \gls{bib2gls} document code:
 \begin{verbatim}
-\newacronymstyle{long-font-short}
-{%
-  \GlsUseAcrEntryDispStyle{long-short}%
-}
-{%
-  \GlsUseAcrStyleDefs{long-short}%
-  \renewcommand*{\genacrfullformat}[2]{%
-   \glsentrylong{##1}##2\space
-   ({\entryfont{##1}\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\Genacrfullformat}[2]{%
-   \Glsentrylong{##1}##2\space
-   ({\entryfont{##1}\glsentryshort{##1}})%
-  }%
-  \renewcommand*{\genplacrfullformat}[2]{%
-   \glsentrylongpl{##1}##2\space
-   ({\entryfont{##1}\glsentryshortpl{##1}})%
-  }%
-  \renewcommand*{\Genplacrfullformat}[2]{%
-   \Glsentrylongpl{##1}##2\space
-   ({\entryfont{##1}\glsentryshortpl{##1}})%
-  }%
-  \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}%
-  \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}%
-}
+\documentclass{article}
+\usepackage[record]{glossaries-extra}
+\GlsXtrLoadResources[src={entries},selection=all]
+\begin{document}
+\gls{cat}.
+\printunsrtglossaries
+\end{document}
 \end{verbatim}
-Remember the style needs to be set before defining the entries:
+With the file \texttt{entries.bib}:
 \begin{verbatim}
-\setacronymstyle{long-font-short}
+@entry{cat,name={cat},description={feline}}
+@entry{dog,name={dog},description={canine}}
 \end{verbatim}
 
-The complete document is contained in the sample file
-\samplefile{-font-abbr}.
-\end{example}
-
-Some writers and publishing houses have started to drop full stops
-(periods) from upper case initials but may still retain them for
-lower case abbreviations, while others may still use them for both
-upper and lower case. This can cause complications. Chapter~12 of
-\emph{The \TeX{}book} discusses the spacing between words but,
-briefly, the default behaviour of \TeX\ is to assume that an upper
-case character followed by a~full stop and space is an abbreviation,
-so the space is the default inter-word space whereas a~lower case
-character followed by a~full stop and space is a word occurring at
-the end of a~sentence. In the event that this isn't true, you need
-to make a~manual adjustment using \verb*| | (back slash space) in
-place of just a~space character for an inter-word mid-sentence space
-and use \verb|\@| before the full stop to indicate the end of the
-sentence.
-
-For example:
+\begin{example}{Dual Entries}{ex:dual}
+The example file \samplefile{-dual} makes use of \cs{glsadd} to
+allow for an entry that should appear both in the main glossary and
+in the list of acronyms. This example sets up the list of acronyms
+using the \pkgopt{acronym} package option:
 \begin{verbatim}
-I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\usepackage[acronym]{glossaries}
 \end{verbatim}
-is typeset as
-\begin{display}
-I was awarded a B.Sc. and a Ph.D. (From the same place.)
-\end{display}
-The spacing is more noticeable with the typewriter font:
+A new command is then defined to make it easier to define dual
+entries:
 \begin{verbatim}
-\ttfamily
-I was awarded a B.Sc. and a Ph.D. (From the same place.)
+\newcommand*{\newdualentry}[5][]{%
+  \newglossaryentry{main-#2}{name={#4},%
+  text={#3\glsadd{#2}},%
+  description={#5},%
+  #1
+  }%
+  \newacronym{#2}{#3\glsadd{main-#2}}{#4}%
+}
 \end{verbatim}
-is typeset as
-\begin{display}\ttfamily
-I was awarded a B.Sc. and a Ph.D. (From the same place.)
-\end{display}
-The lower case letter at the end of ``B.Sc.''\ is confusing \TeX\
-into thinking that the full stop after it marks the end of the
-sentence. Whereas the upper case letter at the end of ``Ph.D.'' has
-confused \TeX\ into thinking that the following full stop is just
-part of the abbreviation. These can be corrected:
+This has the following syntax:
+\begin{alltt}
+\ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description}
+\end{alltt}
+You can then define a new dual entry:
 \begin{verbatim}
-I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.)
+\newdualentry{svm}% label
+  {SVM}% abbreviation
+  {support vector machine}% long form
+  {Statistical pattern recognition technique}% description
 \end{verbatim}
+Now you can reference the acronym with \verb|\gls{svm}| or you can
+reference the entry in the main glossary with \verb|\gls{main-svm}|.
 
-This situation is a bit problematic for \styfmt{glossaries}. The
-full stops can form part of the \meta{short} argument of
-\cs{newacronym} and the \verb*|B.Sc.\ | part can be dealt with by
-remembering to add \verb*|\ | (for example, \verb*|\gls{bsc}\ |)
-but the end of sentence case is more troublesome as you need to omit
-the sentence terminating full stop (to avoid two dots) which can
-make the source code look a little strange but you also need to
-adjust the space factor, which is usually done by inserting \cs{@}
-before the full stop.
+This is just an example.
+In general, think twice before you add this kind of duplication.
+If all information (short, long and description) can be provided in
+a single list, it's redundant to provide a second list unless any
+of the short forms start with a different letter to the associated
+long form, which may make it harder to lookup.
 
-The next example shows one way of achieving this.
-(Note that the supplemental \gls{glossaries-extra} package provides a much
-simpler way of doing this, which you may prefer to use. See the
-\gallery{sample-initialisms.shtml}{initialisms example}.)
+\begin{bib2gls}
+Note that with \gls{bib2gls}, there are special dual entry types
+that implement this behaviour. That is, if an entry is referenced
+then its corresponding dual entry will automatically be selected as
+well. So there is less need for \cs{glsadd} with \gls{bib2gls}.
+(Although it can still be useful, as shown in \opt6.)
+\end{bib2gls}
+\end{example}
 
-\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr}
-As from version 4.16, there's now a hook (\ics{glspostlinkhook})
-that's called at the very end of the \glslike\ and \glstextlike\
-commands. This can be redefined to check if the following character
-is a full stop. The \sty{amsgen} package (which is automatically
-loaded by \styfmt{glossaries}) provides an internal command
-called \cs{new@ifnextchar} that can be used to determine if the
-given character appears next. (For more information see the
-\sty{amsgen} documentation.)
+\chapter{Cross-Referencing Entries}
+\label{sec:crossref}
 
-It's possible that I~may also want acronyms or contractions in my
-document, so I~need some way to differentiate between them.
-Here I'm going to use the same method as in
-example~\ref{ex:addstoragekey} where a~new field is defined
-to indicate the type of abbreviation:
+\begin{important}
+You must use \ics{makeglossaries} (\optsor23) or
+\ics{makenoidxglossaries} (\opt1) \emph{before} defining any
+terms that cross-reference entries. If any of the terms that you have
+cross-referenced don't appear in the glossary, check that you have
+put \cs{makeglossaries}\slash\cs{makenoidxglossaries} before all 
+entry definitions. The \gls{glossaries-extra} package provides
+better cross-reference handling.
+\end{important}
+
+There are several ways of cross-referencing entries in the 
+glossary: 
+
+\begin{enumerate}
+\item You can use commands such as \ics{gls} in the
+entries description. For example:
 \begin{verbatim}
-\glsaddstoragekey{abbrtype}{word}{\abbrtype}
+\newglossaryentry{apple}{name=apple,
+description={firm, round fruit. See also \gls{pear}}}
+\end{verbatim}
+Note that with this method, if you don't use the cross-referenced term 
+in the main part of the document, you will need two runs of
+\gls{makeglossaries}:
+\begin{prompt}
+pdflatex filename
+makeglossaries filename
+pdflatex filename
+makeglossaries filename
+pdflatex filename
+\end{prompt}
+This is because the \cs{gls} in the description won't be detected
+until the glossary has been created (unless the description is used
+elsewhere in the document with \ics{glsentrydesc}). Take care not to
+use \ics{glsdesc} (or \ics{Glsdesc}) in this case as it will cause a
+nested link.
 
-\newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]}
+\item As described in \sectionref{sec:newglosentry}, you can use the
+\gloskey{see} key when you define the entry. For example:
+\begin{verbatim}
+\newglossaryentry{MaclaurinSeries}{name={Maclaurin 
+series},
+description={Series expansion},
+see={TaylorsTheorem}}
 \end{verbatim}
-Now I just use \ics{newacronym} for the acronyms, for example,
+Note that in this case, the entry with the \gloskey{see} key will
+automatically be added to the glossary, but the cross-referenced
+entry won't. You therefore need to ensure that you use the
+cross-referenced term with the commands described in
+\sectionref{sec:glslink} or \sectionref{sec:glsadd}.
+
+The \qt{see} tag is produce using \ics{seename}, but can be
+overridden in specific instances using square brackets
+at the start of the \gloskey{see} value. For example:
 \begin{verbatim}
-\newacronym{laser}{laser}{light amplification by stimulated
-emission of radiation}
+\newglossaryentry{MaclaurinSeries}{name={Maclaurin 
+series},
+description={Series expansion},
+see=[see also]{TaylorsTheorem}}
 \end{verbatim}
-and my new command \cs{newabbr} for initials, for example,
+Take care if you want to use the optional argument of commands such
+as \ics{newacronym} or \ics{newterm} as the value will need to be
+grouped. For example:
 \begin{verbatim}
-\newabbr{eg}{e.g.}{exempli gratia}
-\newabbr{ie}{i.e.}{id est}
-\newabbr{bsc}{B.Sc.}{Bachelor of Science}
-\newabbr{ba}{B.A.}{Bachelor of Arts}
-\newabbr{agm}{A.G.M.}{annual general meeting}
+\newterm{seal}
+\newterm[see={[see also]seal}]{sea lion}
 \end{verbatim}
-Within \cs{glspostlinkhook} the entry's label can be accessed using
-\ics{glslabel} and \ics{ifglsfieldeq} can be used to determine if
-the current entry has the new \texttt{abbrtype} field set to
-\qt{initials}. If it doesn't, then nothing needs to happen, but if
-it does, a~check is performed to see if the next character is a~full
-stop. If it is, this signals the end of a~sentence otherwise it's
-mid-sentence.
-
-Remember that internal commands within the document file (rather
-than in a~class or package) need to be placed between
-\ics{makeatletter} and \ics{makeatother}:
+Similarly if the value contains a list. For example:
 \begin{verbatim}
-\makeatletter
-\renewcommand{\glspostlinkhook}{%
- \ifglsfieldeq{\glslabel}{abbrtype}{initials}%
- {\new@ifnextchar.\doendsentence\doendword}
- {}%
+\glossaryentry{lemon}{
+  name={lemon},
+  description={Yellow citrus fruit}
+}
+\glossaryentry{lime}
+{
+  name={lime},
+  description={Green citrus fruit}
+}
+\glossaryentry{citrus}
+{
+  name={citrus},
+  description={Plant in the Rutaceae family},
+  see={lemon,lime}
 }
-\makeatother
 \end{verbatim}
-In the event that a full stop is found \cs{doendsentence} is
-performed but it will be followed by the full stop, which needs to
-be discarded. Otherwise \cs{doendword} will be done but it won't be
-followed by a full stop so there's nothing to discard. The
-definitions for these commands are:
+
+\item After you have defined the entry, use
+\begin{definition}[\DescribeMacro{\glssee}]
+\cs{glssee}\oarg{tag}\marg{label}\marg{xr label list}
+\end{definition}
+where \meta{xr label list} is a comma-separated list of entry 
+labels to be cross-referenced, \meta{label} is the label of the
+entry doing the cross-referencing and \meta{tag} is the \qt{see} tag.
+(The default value of \meta{tag} is \ics{seename}.)
+For example:
 \begin{verbatim}
-\newcommand{\doendsentence}[1]{\spacefactor=10000{}}
-\newcommand{\doendword}{\spacefactor=1000{}}
+\glssee[see also]{series}{FourierSeries,TaylorsTheorem}
 \end{verbatim}
-Now, I can just do \verb|\gls{bsc}| mid-sentence and
-\verb|\gls{phd}.| at the end of the sentence. The terminating full
-stop will be discarded in the latter case, but it won't be discarded
-in, say, \verb|\gls{laser}.| as that doesn't have the
-\texttt{abbrtype} field set to \qt{initials}.
+Note that this automatically adds the entry given by \meta{label} to
+the glossary but doesn't add the cross-referenced entries (specified
+by \meta{xr label list}) to the glossary.
+\end{enumerate}
 
-This also works on first use when the style is set to one of the
-\meta{long} (\meta{short}) styles but it will fail with the
-\meta{short} (\meta{long}) styles as in this case the terminating
-full stop shouldn't be discarded. Since \ics{glspostlinkhook} is
-used after the \firstuseflag\ has been unset for the entry, this
-can't be fixed by simply checking with \ics{ifglsused}. One possible
-solution to this is to redefine \ics{glslinkpostsetkeys} to check
-for the \firstuseflag\ and define a macro that can then be used in
-\ics{glspostlinkhook}.
+In both cases~2 and 3 above, the cross-referenced information
+appears in the \gls{numberlist}, whereas in case~1, the
+cross-referenced information appears in the description. (See the
+\samplefile{-crossref} example file that comes with this package.)
+This means that in cases~2 and~3, the cross-referencing information
+won't appear if you have suppressed the \gls*{numberlist}. In this
+case, you will need to activate the \gls*{numberlist} for the given
+entries using \gloskey{nonumberlist=false}. Alternatively, if you
+just use the \gloskey{see} key instead of \ics{glssee}, you can
+automatically activate the \gls*{numberlist} using the
+\pkgopt{seeautonumberlist} package option.
 
-The other thing to consider is what to do with plurals. One
-possibility is to check for plural use within \cs{doendsentence}
-(using \ics{glsifplural}) and put the full stop back if the plural
-has been used.
+\begin{bib2gls}
+\gls{bib2gls} provides much better support for cross-references.
+See, for example, 
+\gallery{index.php?label=bib2gls-xr}{Gallery: Cross-References (bib2gls)}.
+\end{bib2gls}
 
-The complete document is contained in the sample file
-\samplefile{-dot-abbr}.
-\end{example}
+\section{Customising Cross-reference Text}
+\label{sec:customxr}
 
-\section{Displaying the List of Acronyms}
-\label{sec:disploa}
+When you use either the \gloskey{see} key or the command
+\cs{glssee}, the cross-referencing information will be typeset in the 
+glossary according to:
+\begin{definition}[\DescribeMacro{\glsseeformat}]
+\cs{glsseeformat}\oarg{tag}\marg{label-list}\marg{location}
+\end{definition}
+The default definition of \cs{glsseeformat} is:
+\begin{display}
+\cs{emph}\marg{tag} \cs{glsseelist}\marg{label-list}
+\end{display}
+Note that the location is always ignored.\footnote{\gls{makeindex}
+will always assign a location number, even if it's not needed, so it
+needs to be discarded.} For example, if you want the tag to appear
+in bold, you can do:\footnote{If you redefine \cs{glsseeformat},
+keep the default value of the optional argument as \ics{seename} as
+both \gloskey{see} and \cs{glssee} explicitly write
+\texttt[\cs{seename}\texttt] in the output file if no optional
+argument is given.}
+\begin{verbatim}
+\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} 
+ \glsseelist{#2}}
+\end{verbatim}
 
-The list of acronyms is just like any other type of glossary and can
-be displayed on its own using:
-\begin{description}
-\itempar{\opt1:}
-\begin{alltt}
-\ics{printnoidxglossary}[type=\ics{acronymtype}]
-\end{alltt}
 
-\itempar{\optsand23:}
-\begin{alltt}
-\ics{printglossary}[type=\ics{acronymtype}]
-\end{alltt}
+The list of labels is dealt with by \cs{glsseelist}, which iterates
+through the list and typesets each entry in the label. The entries
+are separated by
+\begin{definition}[\DescribeMacro{\glsseesep}]
+\cs{glsseesep}
+\end{definition}
+or (for the last pair)
+\begin{definition}[\DescribeMacro{\glsseelastsep}]
+\cs{glsseelastsep}
+\end{definition}
+These default to ``",\space"'' and
+\qt{\cs{space}\ics{andname}\cs{space}} respectively. The list entry text
+is displayed using:
+\begin{definition}[\DescribeMacro{\glsseeitemformat}]
+\cs{glsseeitemformat}\marg{label}
+\end{definition}
+This defaults to \ics{glsentrytext}\marg{label}.\footnote{In
+versions before 3.0, \cs{glsentryname} was used, but this could cause
+problems when the \gloskey{name} key was \glsd{sanitize}.} For example, to
+make the cross-referenced list use small caps:
+\begin{verbatim}
+\renewcommand{\glsseeitemformat}[1]{%
+  \textsc{\glsentrytext{#1}}}
+\end{verbatim}
+\begin{xtr}
+The \gls{glossaries-extra} package redefines \cs{glsseeitemformat}
+and additionally provides \ics*{glsxtrhiername} which can be used
+as an alternative to \cs{glsentrytext}. See the
+\gls{glossaries-extra} manual for further details.
+\end{xtr}
 
-(If you use the
-\pkgopt{acronym} package option you can also use 
-\begin{alltt}
-\ics{printacronyms}\oarg{options}
-\end{alltt}
-as a synonym for
-\begin{alltt}
-\ics{printglossary}[type=\ics{acronymtype},\meta{options}]
-\end{alltt}
-See \sectionref{sec:pkgopts-acronym}.)
+\begin{important}
+You can use \ics{glsseeformat} and \ics{glsseelist} in the main body
+of the text, but they won't automatically add the cross-referenced
+entries to the glossary. If you want them added with that location,
+you can do:
+\begin{verbatim}
+Some information (see also 
+\glsseelist{FourierSeries,TaylorsTheorem}%
+\glsadd{FourierSeries}\glsadd{TaylorsTheorem}).
+\end{verbatim}
+\end{important}
 
-\end{description}
-Alternatively the list of acronyms can be displayed with all the other 
-glossaries using:
-\begin{description}
-\item[\opt1:] \ics{printnoidxglossaries}
+\chapter{Number Lists}
+\label{sec:numberlists}
+
+Each entry in the glossary has an associated \gls{numberlist}.
+By default, these numbers refer to the pages on which that entry has
+been indexed (using any of the commands described in
+\sectionref{sec:glslink} and \sectionref{sec:glsadd}). The number
+list can be suppressed using the \pkgopt{nonumberlist} package
+option, or an alternative counter can be set as the default using
+the \pkgopt{counter} package option. The number list is also
+referred to as the location list\index{location list|see{number list}}.
+
+\Glspl{numberlist} are more common with indexes rather than
+glossaries (although you can use the \styfmt{glossaries} package for
+indexes as well). However, the \styfmt{glossaries} package makes use
+of \gls{makeindex} or \gls{xindy} to hierarchically sort and collate the
+entries since they are readily available with most modern \TeX\
+distributions. Since these are both designed as \glspl{indexingapp}
+they both require that terms either have a valid location or a
+cross-reference. Even if you use \pkgopt{nonumberlist}, the
+locations must still be provided and acceptable to the
+\gls{indexingapp} or they will cause an error during the indexing
+stage, which will interrupt the document build. However, if you're
+not interested in the locations, each entry only needs to be indexed
+once, so consider using \pkgopt{indexonlyfirst}, which can improve the
+document build time by only indexing the \gls{firstuse} of each term.
 
-\item[\optsand23:] \ics{printglossaries}
-\end{description}
+The \ics{glsaddall} command (see \sectionref{sec:glsadd}), which is used to
+automatically index all entries, iterates over all defined entries
+and does \cs{glsadd}\marg{label} for each entry (where \meta{label}
+is that entry's label). This means that \cs{glsaddall} automatically
+adds the same location to every entry's \gls{numberlist}, which
+looks weird if the \gls*{numberlist} hasn't been suppressed.
 
-However, care must be taken to choose a glossary style that's
-appropriate to your acronym style.
-Alternatively, you can define your own custom style (see 
-\sectionref{sec:newglossarystyle} for further details).
+With \opt4, the indexing is performed by \gls{bib2gls}, which was
+specifically designed for the \gls{glossaries-extra} package. So it
+will allow any location format, and its \texttt{selection=all}
+option will select all entries without adding an unwanted location to the
+\gls{numberlist}. If \gls{bib2gls} can deduce a numerical value for
+a location, it will attempt to form a range over consecutive
+locations, otherwise it won't try to form a range and the
+location will just form an individual item in the list.
+\opt1 also allows any location but it doesn't form ranges.
 
-\section{Upgrading From the glossary Package}
-\label{sec:oldacronym}
+\section{Encap Values (Location Formats)}
+\label{sec:encap}
 
-Users of the obsolete \sty{glossary} package may recall that
-the syntax used to define new acronyms has changed with the
-replacement \styfmt{glossaries} package. In addition, the old
-\sty{glossary} package created the command 
-\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}.
+Each location in the \gls{numberlist} is encapsulated with a
+command formed from the \termdef{encap} value.  By
+default this is the \ics{glsnumberformat} command, which corresponds
+to the encap \texttt{glsnumberformat}, but this may be
+overridden using the \gloskey[glslink]{format} key in the optional
+argument to commands like \cs{gls}. (See \sectionref{sec:glslink}.)
+For example, you may want the location to appear in bold to indicate
+the principle use of a term or symbol. If the encap starts with an
+open parenthesis~\verb|(| this signifies the start of a range and if
+the encap starts with close parenthesis~\verb|)| this signifies the
+end of a range. These must always occur in matching pairs.
 
-In order to facilitate migrating from the old package to the new
-one, the \styfmt{glossaries} package\footnote{as from version 1.18} 
-provides the command:
-\begin{definition}[\DescribeMacro{\oldacronym}]
-\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}
+The \styfmt{glossaries} package provides the command:
+\begin{definition}[\glsignore]
+\cs{glsignore}\marg{text}
 \end{definition}
-This uses the same syntax as the \sty{glossary} package's
-method of defining acronyms. It is equivalent to:
-\begin{display}
-\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
-\end{display}
-In addition, \ics{oldacronym} also defines the commands
-\cs{}\meta{label}, which is equivalent to \ics{gls}\marg{label},
-and \cs{}\meta{label}\texttt{*}, which is equivalent to
-\ics{Gls}\marg{label}. If \meta{label} is omitted, \meta{abbrv}
-is used. Since commands names must consist only of alphabetical
-characters, \meta{label} must also only consist of alphabetical
-characters. Note that \cs{}\meta{label} doesn't allow you to use
-the first optional argument of \ics{gls} or \ics{Gls} --- you will
-need to explicitly use \ics{gls} or \ics{Gls} to change the
-settings.
-
-\begin{important}
-Recall that, in general, \LaTeX\ ignores spaces following command 
-names consisting of alphabetical characters. This is also true for 
-\cs{}\meta{label} unless you additionally load the
-\sty{xspace} package, but be aware that there are some issues with
-using \sty{xspace}.\footnotemark
-\end{important}
-\footnotetext{See David Carlisle's explanation in
-\href{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}{Drawbacks
-of xspace}}
+which ignores its argument. This is the format used by
+\cs{glsaddallunused} to suppress the location, which works fine as
+long as no other locations are added to the \gls{numberlist}. For
+example, if you use \verb|\gls{sample}| on page~2 then reset the
+\gls{firstuseflag} and then use \cs{glsaddallunused} on page~10, the
+\gls{numberlist} for \texttt{sample} will be \verb|2, \glsignore{10}| 
+which will result in \qt{2,~} which has a spurious comma.
 
-The \styfmt{glossaries} package doesn't load the \sty{xspace} package
-since there are both advantages and disadvantages to using
-\ics{xspace} in \cs{}\meta{label}. If you don't use the 
-\sty{xspace} package you need to explicitly force a space using
-\verb*|\ | (backslash space) however you can follow \cs{}\meta{label}
-with additional text in square brackets (the final optional
-argument to \ics{gls}). If you use the \sty{xspace} package
-you don't need to escape the spaces but you can't use
-the optional argument to insert text (you will have to explicitly
-use \ics{gls}).
+This isn't a problem with \gls{bib2gls} because you would need to use
+\texttt{selection=all} instead of \cs{glsaddallunused}, but even if
+you explicitly had used \texttt{glsignore}, for example, 
+\cs{gls}\texttt{[format=glsignore]}\marg{label}, then \gls{bib2gls} 
+will recognise \texttt{glsignore} as
+a special encap indicating an ignored location, so it will select
+the entry but not add that location to the \gls{numberlist}. It's a
+problem for all the other indexing options.
 
-To illustrate this, suppose I define the acronym \qt{abc} as
-follows:
-\begin{verbatim}
-\oldacronym{abc}{example acronym}{}
-\end{verbatim}
-This will create the command \cs{abc} and its starred version
-\cs{abc*}. \Tableref{tab:xspace} illustrates the effect of
-\cs{abc} (on subsequent use) according to whether or not the
-\sty{xspace} package has been loaded. As can be seen from the
-final row in the table, the \sty{xspace} package prevents the
-optional argument from being recognised.
+Complications can arise if you use different encap values for the
+same location. For example, suppose on page~10 you have both the
+default \texttt{glsnumberformat} and \texttt{textbf} encaps.  While it may
+seem apparent that \texttt{textbf} should override \texttt{glsnumberformat}
+in this situation, the \gls{indexingapp} may not know it.
+This is therefore something you need to be careful about if you use the
+\gloskey[glslink]{format} key or if you use a command that
+implicitly sets it.
 
-\begin{table}[htbp]
-\caption[The effect of using xspace]{The effect of using 
-\styfmt{xspace} with \cs{oldacronym}}
-\label{tab:xspace}
-\vskip\baselineskip
-\centering
-\begin{tabular}{lll}
-\bfseries Code & \bfseries With \styfmt{xspace} &
-\bfseries Without \styfmt{xspace}\\
-\verb|\abc.| & abc. & abc.\\
-\verb|\abc xyz| & abc xyz & abcxyz\\
-\verb|\abc\ xyz| & abc xyz & abc xyz\\
-\verb|\abc* xyz| & Abc xyz & Abc xyz\\
-\verb|\abc['s] xyz| & abc ['s] xyz & abc's xyz
-\end{tabular}
-\par
-\end{table}
+In the case of \gls{xindy}, it only accepts one encap (according to
+the order of precedence given in the \gls{xindy} module) and discards the
+others for identical locations (for the same entry). This can cause
+a problem if a discarded location forms the start or end of a range. 
 
-\chapter{Unsetting and Resetting Entry Flags}
-\label{sec:glsunset}
+In the case of \gls{makeindex}, it accepts different encaps for the
+same location, but warns about it.  This leads to a \gls{numberlist}
+with the same location repeated in different formats.  If you use
+the \gls{makeglossaries} Perl script with \opt2 it will detect
+\gls{makeindex}'s warning and attempt to fix the problem, ensuring
+that the \texttt{glsnumberformat} encap always has the least precedence
+unless it includes a range identifier. Other conflicting encaps will
+have the last one override earlier ones for the same location with
+range identifiers taking priority.
 
-When using the \glslike\ commands it is
-possible that you may want to use the value given by the
-\gloskey{first} key, even though you have already \glslink{firstuse}{used} the glossary
-entry. Conversely, you may want to use the value given by the
-\gloskey{text} key, even though you haven't used the glossary entry.
-The former can be achieved by one of the following commands:
-\begin{definition}[\DescribeMacro{\glsreset}]
-\cs{glsreset}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glslocalreset}]
-\cs{glslocalreset}\marg{label}
-\end{definition}
-while the latter can be achieved by one of the following commands:
-\begin{definition}[\DescribeMacro{\glsunset}]
-\cs{glsunset}\marg{label}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glslocalunset}]
-\cs{glslocalunset}\marg{label}
-\end{definition}
-You can also reset or unset all entries for a given glossary or list of
-glossaries using:
-\begin{definition}[\DescribeMacro{\glsresetall}]
-\cs{glsresetall}\oarg{glossary list}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glslocalresetall}]
-\cs{glslocalresetall}\oarg{glossary list}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glsunsetall}]
-\cs{glsunsetall}\oarg{glossary list}
-\end{definition}
-\begin{definition}[\DescribeMacro{\glslocalunsetall}]
-\cs{glslocalunsetall}\oarg{glossary list}
-\end{definition}
-where \meta{glossary list} is a comma-separated list of 
-glossary labels. If omitted, all defined glossaries are assumed
-(except for the ignored ones).
-For example, to reset all entries in the main glossary and the
-list of acronyms:
-\begin{verbatim}
-\glsresetall[main,acronym]
-\end{verbatim}
+No discard occurs with \opt1 so again you get the same location
+repeated in different formats. With \opt4, \gls{bib2gls} will discard
+according to order of precedence, giving priority to start and end
+range encaps.  (See the \gls{bib2gls} manual for further details.)
 
-You can determine whether an entry's \gls{firstuseflag} is set using:
-\begin{definition}[\DescribeMacro{\ifglsused}]
-\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}
-\end{definition}
-where \meta{label} is the label of the required entry. If the
-entry has been used, \meta{true part} will be done, otherwise
-\meta{false part} will be done.
+\section{Locations}
+\label{sec:locationsyntax}
 
-\begin{important}
-Be careful when using \glslike\ commands within an
-environment or command argument that gets processed multiple times
-as it can cause unwanted side-effects when the first use displayed
-text is different from subsequent use.
-\end{important}
+Neither \opt1 nor \opt4 care about the location syntax as long as
+it's valid \LaTeX\ code (and doesn't contain fragile commands). In
+both cases, the indexing is performed by writing a line to the
+\filetype{aux} file. The write operation is deferred to avoid the
+problems associated with \TeX's asynchronous output routine.
+(See, for example,
+\href{https://texfaq.org/FAQ-oddpage}{Finding
+if you're on an odd or an even page} for more details on this issue.)
+Unfortunately \optsand23 are far more problematic and need some
+complex code to deal with awkward locations.
 
-For example, the \env{frame} environment in \cls{beamer} processes
-its argument for each overlay. This means that the \firstuseflag\
-will be unset on the first overlay and subsequent overlays will use
-the non-first use form.
+If you know that your locations will always expand to a format
+acceptable to your chosen \gls{indexingapp} then use the package
+option \pkgopt[false]{esclocations} to bypass this operation. This setting
+only affects \optsand23 as the problem doesn't arise with the other
+indexing options.
 
-Consider the following example:
+Both \gls{makeindex} and \gls{xindy} are fussy about the syntax of
+the locations. In the case of \gls{makeindex}, only the numbering
+system obtained with \cs{arabic}, \cs{roman}, \cs{Roman}, \cs{alph}
+and \cs{Alph} or composites formed from them with the same separator
+(set with \cs{glsSetCompositor}\marg{char}) are accepted.
+(\gls{makeindex} won't accept an empty location.) In the case of
+\gls{xindy}, you can define your own location classes, but if the
+location contains a robust command then the leading backslash must
+be escaped. The \sty{glossaries} package tries to do this, but it's
+caught between two conflicting requirements:
+\begin{enumerate}
+\item The location must be fully expanded before \verb|\| can be
+converted to \verb|\\| (there's no point converting \verb|\thepage|
+to \verb|\\thepage|);
+\item The page number can't be expanded until the deferred write
+operation (so \verb|\c@page| mustn't expand in the previous step
+but \verb|\the\c@page| mustn't be converted to \verb|\\the\\c@page| 
+and \verb|\number\c@page| mustn't be converted to
+\verb|\\number\\c@page| etc).
+\end{enumerate}
+There's a certain amount of trickery needed to deal with this
+conflict and the code requires the location to be in a form that
+doesn't embed the counter's internal register in commands like
+\cs{value}.  For example, suppose you have a robust command called
+\cs{tallynum} that takes a number as the argument and an expandable
+command called \cs{tally} that converts a counter name into the
+associated register or number to pass to \cs{tallynum}. Let's
+suppose that this command is used to represent the page number:
+\begin{verbatim}
+\renewcommand{\thepage}{\tally{page}}
+\end{verbatim}
+Now let's suppose that a term is indexed at the beginning of page~2
+at the end of a paragraph that started on page~1. With \gls{xindy},
+the location \verb|\tally{page}| needs to be written to the file
+as \verb|\\tallynum{2}|. If it's written as \verb|\tallynum{2}| then
+\gls{xindy} will interpret \verb|\t| as the character \qt{t}
+(which means the location would appear as \qt{tallynum2}). So
+\sty{glossaries} tries to expand \cs{thepage} without expanding
+\cs{c@page} and then escapes all the backslashes, except for the
+page counter's internal command. The following definitions of
+\cs{tally} will work:
+\begin{itemize}
+\item In the following, \cs{arabic} works as its internal command \cs{c@arabic} is
+temporarily redefined to check for \cs{c@page}:
 \begin{verbatim}
-\documentclass{beamer}
-
-\usepackage{glossaries}
-
-\newacronym{svm}{SVM}{support vector machine}
-
-\begin{document}
-
-\begin{frame}
- \frametitle{Frame 1}
-
- \begin{itemize}
-  \item<+-> \gls{svm}
-  \item<+-> Stuff.
- \end{itemize}
-\end{frame}
-
-\end{document}
+\newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
 \end{verbatim}
 
-On the first overlay, \verb|\gls{svm}| produces \qt{support vector
-machine (SVM)} and then unsets the \firstuseflag. When the second
-overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which
-is unlikely to be the desired effect. I~don't know anyway around
-this and I can only offer two suggestions.
-
-Firstly, unset all acronyms at the start of the document and
-explicitly use \ics{acrfull} when you want the full version to be
-displayed:
+\item The form \verb|\expandafter\the\csname c@|\meta{counter}\verb|\endcsname|
+also works (provided \cs{the} is allowed to be temporarily redefined, 
+see below):
 \begin{verbatim}
-\documentclass{beamer}
-
-\usepackage{glossaries}
-
-\newacronym{svm}{SVM}{support vector machine}
-
-\glsunsetall
-
-\begin{document}
-\begin{frame}
- \frametitle{Frame 1}
-
- \begin{itemize}
-  \item<+-> \acrfull{svm}
-  \item<+-> Stuff.
- \end{itemize}
-\end{frame}
-\end{document}
+\newcommand{\tally}[1]{%
+ \tallynum{\expandafter\the\csname c@#1\endcsname}}
 \end{verbatim}
 
-Secondly, explicitly reset each acronym on first use:
+\item \verb|\expandafter\the\value|\marg{counter} now also works
+(with the same condition as above):
 \begin{verbatim}
-\begin{frame}
- \frametitle{Frame 1}
-
- \begin{itemize}
-  \item<+-> \glsreset{svm}\gls{svm}
-  \item<+-> Stuff.
- \end{itemize}
-\end{frame}
+\newcommand{\tally}[1]{\tallynum{\expandafter\the\value{#1}}}
 \end{verbatim}
-These are non-optimal, but the \cls{beamer} class is too complex for
-me to provide a programmatic solution. Other potentially problematic
-environments are some \env{tabular}-like environments (but not
-\env{tabular} itself) that process the contents in order to work out
-the column widths and then reprocess the contents to do the actual
-typesetting.
-
-The \sty{amsmath} environments, such as \env{align}, also process
-their contents multiple times, but the \styfmt{glossaries} package now
-checks for this. For \sty{tabularx}, you need to explicitly patch it
-by placing \cs{glspatchtabularx} in the preamble (or anywhere
-before the problematic use of \envfmt{tabularx}).
-
-\begin{xtr}
-If you need to use commands like \cs{gls} in any problematic context
-that interferes with the \gls{firstuseflag}, then you can try using
-the buffering system provided with \gls{glossaries-extra}. See the
-\qt{First Use Flag} section of the \gls{glossaries-extra} manual.
-\end{xtr}
-
-\section{Counting the Number of Times an Entry has been Used (First Use
-Flag Unset)}
-\label{sec:enableentrycount}
-
-As from version 4.14, it's now possible to keep track of how many
-times an entry is used. That is, how many times the \firstuseflag\
-is unset. Note that the supplemental \gls{glossaries-extra} package improves
-this function and also provides per-unit counting, which isn't
-available with the \styfmt{glossaries} package.
 
-\begin{important}
-This function is disabled by default as it adds extra
-overhead to the document build time and also switches
-\ics{newglossaryentry} (and therefore \ics{newacronym}) into
-a~preamble-only command.
-\end{important}
+\item Another variation that will work:
+\begin{verbatim}
+\newcommand{\tally}[1]{%
+  \expandafter\tallynum\expandafter{\the\csname c@#1\endcsname}}
+\end{verbatim}
 
-To enable this function, use
-\begin{definition}[\DescribeMacro\glsenableentrycount]
-\cs{glsenableentrycount}
+\item and also:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\the\csname c@#1\endcsname}}
+\end{verbatim}
+\end{itemize}
+The following \emph{don't work}:
+\begin{itemize}
+\item This definition leads to the premature expansion of \cs{c@page}
+to \qt{1} when, in this case, it should be \qt{2}:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\the\value{#1}}}
+\end{verbatim}
+\item This definition leads to \verb|\\c@page| in the glossary file:
+\begin{verbatim}
+\newcommand{\tally}[1]{\tallynum{\csname c@#1\endcsname}}
+\end{verbatim}
+\end{itemize}
+If you have a numbering system where 
+\verb|\|\meta{cs name}\verb|{page}| expands to
+\verb|\|\meta{internal cs name}\cs{c@page} (for example, if
+\verb|\tally{page}| expands to \verb|\tallynum\c@page|) then you
+need to use:
+\begin{definition}[\DescribeMacro\glsaddprotectedpagefmt]
+\cs{glsaddprotectedpagefmt}\marg{internal cs name}
 \end{definition}
-before defining your entries. This adds two extra (internal) fields
-to entries: \texttt{currcount} and \texttt{prevcount}.
-
-The \texttt{currcount} field keeps track of how many times
-\cs{glsunset} is used within the document. A~local unset (using
-\cs{glslocalunset}) performs a~local rather than global increment to
-\texttt{currcount}. Remember that not all commands use
-\cs{glsunset}. Only the \glslike\ commands do this. The reset
-commands \cs{glsreset} and \cs{glslocalreset} reset this field back
-to zero (where \cs{glslocalreset} performs a~local change).
+Note that the backslash must be omitted from \meta{internal cs name}
+and the corresponding command must be able to process a count
+register as the (sole) argument.
 
-The \texttt{prevcount} field stores the final value of the
-\texttt{currcount} field \emph{from the previous run}. This value is
-read from the \filetype{aux} file at the beginning of the
-\env{document} environment.
+For example, suppose you have a style \texttt{samplenum} that is
+implemented as follows:
+\begin{verbatim}
+ \newcommand*{\samplenum}[1]{%
+   \expandafter\@samplenum\csname c@#1\endcsname}
+ \newcommand*{\@samplenum}[1]{\two@digits{#1}}
 
-You can access these fields using
-\begin{definition}[\DescribeMacro\glsentrycurrcount]
-\cs{glsentrycurrcount}\marg{label}
-\end{definition}
-for the \texttt{currcount} field, and
-\begin{definition}[\DescribeMacro\glsentryprevcount]
-\cs{glsentryprevcount}\marg{label}
-\end{definition}
-for the \texttt{prevcount} field. 
+\end{verbatim}
+(That is, it displays the value of the counter as a two-digit
+number.) Then to ensure the location is correct for entries in 
+page-spanning paragraphs, you need to do:
+\begin{verbatim}
+\glsaddprotectedpagefmt{@samplenum}
+\end{verbatim}
+(If you are using a different counter for the location, such as
+\texttt{section} or \texttt{equation}, you don't need to worry about
+this provided the inner command is expandable.)
 
-\begin{important}
-These commands are only defined if you have used \cs{glsenableentrycount}.
-\end{important}
+If the inner macro (as given by \verb|\|\meta{internal cs name}) contains
+non-expandable commands then you may need to redefine
+\cs{gls}\meta{internal cs name}\texttt{page} after using
+\begin{alltt}
+\cs{glsaddprotectedpagefmt}\marg{internal cs name}
+\end{alltt}
+This command doesn't take any arguments
+as \emph{the location is assumed to be given by \cs{c@page}} because
+that's the only occasion this command should be used. For example, 
+suppose now my page counter format uses small caps Roman numerals:
+\begin{verbatim}
+ \newcommand*{\samplenum}[1]{%
+  \expandafter\@samplenum\csname c@#1\endcsname}
+ \newcommand*{\@samplenum}[1]{\textsc{\romannumeral#1}}
+\end{verbatim}
+Again, the inner macro needs to be identified using:
+\begin{verbatim}
+\glsaddprotectedpagefmt{@samplenum}
+\end{verbatim}
+However, since \cs{textsc} isn't fully expandable, the location
+is written to the file as \verb|\textsc  {i}| (for page~1), 
+\verb|\textsc  {ii}| (for page~2), etc. This format may cause a problem for
+the \gls{indexingapp} (particularly for \gls{makeindex}).
+To compensate for this, the \cs{gls}\meta{internal cs
+name}\texttt{page} command may be redefined so that it expands to a
+format that's acceptable to the \gls*{indexingapp}. For example:
+\begin{verbatim}
+\renewcommand*{\gls@samplenumpage}{\romannumeral\c@page}
+\end{verbatim}
+While this modification means that the \gls{numberlist} in the glossary
+won't exactly match the format of the page numbers (displaying
+lower case Roman numbers instead of small cap Roman numerals)
+this method will at least work correctly for both \gls{makeindex}
+and \gls{xindy}. If you are using \gls{xindy}, the following
+definition:
+\begin{verbatim}
+ \renewcommand*{\gls@samplenumpage}{%
+   \glsbackslash\string\textsc{\romannumeral\c@page}}
+\end{verbatim}
+combined with
+\begin{verbatim}
+\GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace"
+ "roman-numbers-lowercase" :sep "\glsclosebrace"}
+\end{verbatim}
+will now have lowercase Roman numerals in the location list
+(see \sectionref{sec:xindyloc} for further details on that command).
+Take care of the backslashes. The location (which ends up in 
+the \xindyattr{:locref} attribute) needs \verb|\\| but the location class
+(identified with \cs{GlsAddXdyLocation}) just has a single
+backslash.  Note that this example will cause problems if your
+locations should be hyperlinks.
 
-For example:
+Another possibility that may work with both \gls{makeindex} and
+\gls{xindy} is to redefine \cs{gls}\meta{internal cs
+name}\texttt{page} (\cs{gls@samplenumpage} in this example)
+to just expand to the decimal page number (\verb|\number\c@page|) and redefine
+\ics{glsnumberformat} to change the displayed format:
 \begin{verbatim}
-\documentclass{article}
-\usepackage{glossaries}
-\makeglossaries
+\renewcommand*{\gls@samplenumpage}{\number\c@page}
+\renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}}
+\end{verbatim}
 
-\glsenableentrycount
+\begin{important}
+If you redefine \cs{gls}\meta{internal cs name}\texttt{page},
+you must make sure that \cs{c@page} is expanded when it's written to
+the file. (So don't, for example, hide \cs{c@page} inside a robust
+command.)
+\end{important}
 
-\newglossaryentry{apple}{name=apple,description={a fruit}}
+The mechanism that allows this to work temporarily redefines
+\ics{the} and \ics{number} while it processes the location. If this
+causes a problem you can disallow it using
+\begin{definition}[\DescribeMacro\glswrallowprimitivemodsfalse]
+\cs{glswrallowprimitivemodsfalse}
+\end{definition}
+but you will need to find some other way to ensure the location expands
+correctly.
 
-\begin{document}
-Total usage on previous run: \glsentryprevcount{apple}.
+\section{Range Formations}
+\label{sec:ranges}
 
-\gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}.
-\glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}.
+Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a
+sequence of~3 or more consecutive pages into~a range. With 
+\gls*{xindy} (\opt3) you can vary the minimum sequence length using
+\ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either
+an integer or the keyword \texttt{none} which indicates that there
+should be no range formation (see \sectionref{sec:xindyloc} for
+further details).
 
-Number of times apple has been used: \glsentrycurrcount{apple}.
-\end{document}
-\end{verbatim}
-On the first \LaTeX\ run, \verb|\glsentryprevcount{apple}|
-produces~0. At the end of the document,
-\verb|\glsentrycurrcount{apple}| produces~4. This is because
-the only commands that have incremented the entry count are those
-that use \cs{glsunset}. That is: \cs{gls}, \cs{glsdisp} and
-\cs{Gls}. The other commands used in the above example, \cs{glsadd},
-\cs{glsentrytext} and \cs{glslink}, don't use \cs{glsunset} so they
-don't increment the entry count. On the \emph{next} \LaTeX\ run,
-\verb|\glsentryprevcount{apple}| now produces~4 as that was the
-value of the \texttt{currcount} field for the \texttt{apple} entry
-at the end of the document on the previous run.
+\begin{important}
+Note that \cs{GlsSetXdyMinRangeLength} must be used before
+\ics{makeglossaries} and has no effect if \ics{noist} is used.
+\end{important}
 
-When you enable the entry count using \cs{glsenableentrycount}, you
-also enable the following commands:
-\begin{definition}[\DescribeMacro\cgls]
-\cs{cgls}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-(no case-change, singular)
-\begin{definition}[\DescribeMacro\cglspl]
-\cs{cglspl}\oarg{options}\marg{label}\oarg{insert}
-\end{definition}
-(no case-change, plural)
-\begin{definition}[\DescribeMacro\cGls]
-\cs{cGls}\oarg{options}\marg{label}\oarg{insert}
+With both \gls{makeindex} and \gls{xindy} (\optsand23), you can replace
+the separator and the closing number in the range using:
+\begin{definition}[\DescribeMacro{\glsSetSuffixF}]
+\cs{glsSetSuffixF}\marg{suffix}
 \end{definition}
-(first letter uppercase, singular), and
-\begin{definition}[\DescribeMacro\cGlspl]
-\cs{cGlspl}\oarg{options}\marg{label}\oarg{insert}
+\begin{definition}[\DescribeMacro{\glsSetSuffixFF}]
+\cs{glsSetSuffixFF}\marg{suffix}
 \end{definition}
-(first letter uppercase, plural).
-These all have plus and starred variants like the analogous
-\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl} commands.
+where the former command specifies the suffix to use for a 2 page
+list and the latter specifies the suffix to use for longer lists.
+For example:
+\begin{verbatim}
+\glsSetSuffixF{f.}
+\glsSetSuffixFF{ff.}
+\end{verbatim}
+Note that if you use \gls{xindy} (\opt3), you will also need to
+set the minimum range length to 1 if you want to change these
+suffixes:
+\begin{verbatim}
+\GlsSetXdyMinRangeLength{1}
+\end{verbatim}
+Note that if you use the \sty{hyperref} package, you will need
+to use \ics{nohyperpage} in the suffix to ensure that the hyperlinks
+work correctly. For example:
+\begin{verbatim}
+\glsSetSuffixF{\nohyperpage{f.}}
+\glsSetSuffixFF{\nohyperpage{ff.}}
+\end{verbatim}
 
-If you don't use \cs{glsenableentrycount}, these commands behave
-like \cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl},
-respectively, only there will be a warning that you haven't enabled
-entry counting. If you have enabled entry counting with
-\cs{glsenableentrycount} then these commands test if
-\cs{glsentryprevcount}\marg{label} equals~1. If it doesn't then the
-analogous \cs{gls} etc will be used. If it does, then the first optional
-argument will be ignored and 
-\begin{alltt}
-\meta{cs format}\marg{label}\marg{insert}\cs{glsunset}\marg{label}
-\end{alltt}
-will be performed, where \meta{cs format} is a command that takes
-two arguments. The command used depends whether you have used
-\cs{cgls}, \cs{cglspl}, \cs{cGls} or \cs{cGlspl}.
+\begin{important}
+Note that \cs{glsSetSuffixF} and \cs{glsSetSuffixFF} must be used 
+before \ics{makeglossaries} and have no effect if \ics{noist} is 
+used.
+\end{important}
 
-\begin{definition}[\DescribeMacro\cglsformat]
-\cs{cglsformat}\marg{label}\marg{insert}
-\end{definition}
-This command is used by \cs{cgls} and defaults to
-\begin{alltt}
-\cs{glsentrylong}\marg{label}\meta{insert}
-\end{alltt}
-if the entry given by
-\meta{label} has a~long form or
-\begin{alltt}
-\cs{glsentryfirst}\marg{label}\meta{insert}
-\end{alltt}
-otherwise.
+It's also possible to concatenate a sequence of consecutive
+locations into a range or have suffixes with \opt4, but with
+\gls{bib2gls} these implicit ranges can't be merged with explicit
+ranges (created with the \verb|(| and \verb|)| encaps). See
+the \gls{bib2gls} manual for further details.
 
-\begin{definition}[\DescribeMacro\cglsplformat]
-\cs{cglsplformat}\marg{label}\marg{insert}
+\opt1 doesn't form ranges. However, with this option you
+can iterate over an entry's \gls{numberlist} using:
+\begin{definition}[\DescribeMacro\glsnumberlistloop]
+\cs{glsnumberlistloop}\marg{label}\marg{handler cs}\marg{xr handler
+cs}
 \end{definition}
-This command is used by \cs{cglspl} and defaults to
-\begin{alltt}
-\cs{glsentrylongpl}\marg{label}\meta{insert} 
-\end{alltt}
-if the entry given by
-\meta{label} has a~long form or
-\begin{alltt}
-\cs{glsentryfirstplural}\marg{label}\meta{insert}
-\end{alltt}
-otherwise.
-
-\begin{definition}[\DescribeMacro\cGlsformat]
-\cs{cGlsformat}\marg{label}\marg{insert}
+where \meta{label} is the entry's label and \meta{handler cs} is a
+handler control sequence of the form:
+\begin{definition}
+\meta{handler cs}\marg{prefix}\marg{counter}\marg{format}\marg{location}
 \end{definition}
-This command is used by \cs{cGls} and defaults to
-\begin{alltt}
-\cs{Glsentrylong}\marg{label}\meta{insert}
-\end{alltt}
-if the entry given by \meta{label} has a~long form or
-\begin{alltt}
-\cs{Glsentryfirst}\marg{label}\meta{insert}
-\end{alltt}
-otherwise.
-
-\begin{definition}[\DescribeMacro\cGlsplformat]
-\cs{cGlsplformat}\marg{label}\marg{insert}
+where \meta{prefix} is the \sty{hyperref} prefix, \meta{counter} is
+the name of the counter used for the location, \meta{format} is the
+format used to display the location (e.g.\ \texttt{textbf})
+and \meta{location} is the location. The third argument is the
+control sequence to use for any cross-references in the list. This
+handler should have the syntax:
+\begin{definition}
+\meta{xr handler cs}\oarg{tag}\marg{xr list}
 \end{definition}
-This command is used by \cs{cGlspl} and defaults to
-\begin{alltt}
-\cs{Glsentrylongpl}\marg{label}\meta{insert}
-\end{alltt}
-if the entry given by \meta{label} has a~long form or
-\begin{alltt}
-\cs{Glsentryfirstplural}\marg{label}\meta{insert}
-\end{alltt}
-otherwise.
-
-This means that if the previous count for the given entry was~1, the
-entry won't be hyperlinked with the \cs{cgls}-like commands and they
-won't add a~line to the external glossary file. If you haven't used
-any of the other commands that add information to glossary file
-(such as \cs{glsadd} or the \glstextlike\ commands) then the entry
-won't appear in the glossary.
-
-Remember that since these commands use \cs{glsentryprevcount} you
-need to run \LaTeX\ twice to ensure they work correctly.  The
-document build order is now (at least): \texttt{(pdf)latex},
-\texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}.
+where \meta{tag} is the cross-referenced text (e.g.\ \qt{see}) and
+\meta{xr list} is a~comma-separated list of labels. (This actually
+has a third argument but it's always empty when used with \opt1.)
 
-\begin{example}{Don't index entries that are only used once}{sec:entrycount}
-In this example, the abbreviations that have only been used once (on the previous run)
-only have their long form shown with \cs{cgls}.
+For example, if on page~12
+I~have used
 \begin{verbatim}
-\documentclass{article}
-
-\usepackage[colorlinks]{hyperref}
-\usepackage[acronym]{glossaries}
-\makeglossaries
-
-\glsenableentrycount
-
-\setacronymstyle{long-short}
-
-\newacronym{html}{HTML}{hypertext markup language}
-\newacronym{css}{CSS}{cascading style sheets}
-\newacronym{xml}{XML}{extensible markup language}
-\newacronym{sql}{SQL}{structured query language}
-\newacronym{rdbms}{RDBMS}{relational database management system}
-\newacronym{rdsms}{RDSMS}{relational data stream management system}
+\gls[format=textbf]{apple}
+\end{verbatim}
+and on page~18 I~have used
+\begin{verbatim}
+\gls[format=emph]{apple}
+\end{verbatim}
+then
+\begin{verbatim}
+\glsnumberlistloop{apple}{\myhandler}
+\end{verbatim}
+will be equivalent to:
+\begin{verbatim}
+\myhandler{}{page}{textbf}{12}%
+\myhandler{}{page}{emph}{18}%
+\end{verbatim}
+There is a predefined handler that's used to display the
+\gls{numberlist} in the glossary:
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+The predefined handler used for the cross-references in the glossary is:
+\begin{definition}
+\cs{glsseeformat}\oarg{tag}\marg{xr list}\marg{location}
+\end{definition}
+which is described in \sectionref{sec:customxr}.
 
-\begin{document}
-These entries are only used once: \cgls{sql}, \cgls{rdbms},
-\cgls{xml}. These entries are used multiple times:
-\cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css},
-\cgls{rdsms}, \cgls{rdsms}.
+\begin{important}
+\cs{glsnumberlistloop} is not available for \optsand23.
+\end{important}
 
-\printglossaries
-\end{document}
-\end{verbatim}
-After a complete document build (\texttt{latex}, \texttt{latex},
-\texttt{makeglossaries}, \texttt{latex}) the list of abbrevaitions only
-includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and
-XML
-only have their long forms displayed and don't have a~hyperlink.
-\end{example}
+\section{Style Hook}
+\label{sec:isthook}
 
-Remember that if you don't like typing \cs{cgls} you can create a
-synonym. For example
+As from version 4.24, there's a hook that's used near the end of
+\ics{writeist} before the file is closed. You can set the code 
+to be performed then using:
+\begin{definition}[\DescribeMacro\GlsSetWriteIstHook]
+\cs{GlsSetWriteIstHook}\marg{code}
+\end{definition}
+If you want the \meta{code} to write any information to the 
+file, you need to use
+\begin{definition}[\DescribeMacro\glswrite]
+\cs{write}\cs{glswrite}\marg{style information}
+\end{definition}
+Make sure you use the correct format within \meta{style
+information}. For example, if you are using \app{makeindex}:
 \begin{verbatim}
-\let\ac\cgls
+\GlsSetWriteIstHook{%
+ \write\glswrite{page_precedence "arnAR"}%
+ \write\glswrite{line_max 80}%
+}
 \end{verbatim}
+This changes the page type precedence\index{page type precedence|main} and the maximum line length
+used by \app{makeindex}.
 
-\begin{bib2gls}
-With \gls{bib2gls} there's an analogous record counting set of
-commands. See \gls{glossaries-extra} and \gls{bib2gls} manuals for further details. 
-\end{bib2gls}
+Remember that if you switch to \app{xindy}, this will no longer be
+valid code.
 
 \chapter{Glossary Styles}
 \label{sec:styles}
@@ -11867,7 +11708,7 @@ with a number of pre-defined glossary styles, described in
 best suits your type of glossary or, if none of them suit your
 document, you can defined your own style (see
 \sectionref{sec:newglossarystyle}). There are some examples
-of glossary styles available at \gallerytopic{glossaries}.
+of glossary styles available at the \gallerytopic{glossaries}.
 
 The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
 argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary}
@@ -11904,9 +11745,9 @@ of available styles in \tableref{tab:styles}.
 You can view samples of all the predefined styles at
 \galleryurl{glossaries-styles/}.
 Note that \gls{glossaries-extra} provides additional styles
-in the supplementary packages \sty{glossary-bookindex} and
-\sty{glossary-longnoloc}. See the \gls{glossaries-extra} manual for
-further details.
+in the supplementary packages \sty{glossary-bookindex},
+\sty{glossary-topic} and \sty{glossary-longextra}. See the
+\gls{glossaries-extra} manual for further details.
 
 \begin{important}
 Note that the group styles (such as \glostyle{listgroup}) will
@@ -12463,874 +12304,1443 @@ width of the second column is governed by the length
 \ics{glsdescwidth}. The width of the third column is governed by the
 length \ics{glspagelistwidth}.
 
-\item[super3colborder] The \glostyle{super3colborder} style is like
-the \glostyle{super3col} style but has horizontal and vertical
-lines around it.
+\item[super3colborder] The \glostyle{super3colborder} style is like
+the \glostyle{super3col} style but has horizontal and vertical
+lines around it.
+
+\item[super3colheader] The \glostyle{super3colheader} style is like
+\glostyle{super3col} but has a header row.
+
+\item[super3colheaderborder] The \glostyle{super3colheaderborder} style
+is like the \glostyle{super3colheader} style but has horizontal and vertical
+lines around it.
+
+\item[super4col] The \glostyle{super4col} style is like 
+\glostyle{super3col} but has an additional column in which the
+entry's associated symbol appears. This style is designed for
+entries with brief single line descriptions. The column widths are governed by the
+widest entry in the given column. Use \glostyle{altsuper4col}
+for multi-line descriptions.
+
+\item[super4colborder] The \glostyle{super4colborder} style is like
+the \glostyle{super4col} style but has horizontal and vertical
+lines around it.
+
+\item[super4colheader] The \glostyle{super4colheader} style is like
+\glostyle{super4col} but has a header row.
+
+\item[super4colheaderborder] The \glostyle{super4colheaderborder} style
+is like the \glostyle{super4colheader} style but has horizontal and vertical
+lines around it.
+
+\item[altsuper4col] The \glostyle{altsuper4col} style is like 
+\glostyle{super4col} but allows multi-line descriptions and page
+lists.
+The width of the description column is governed by the length
+\ics{glsdescwidth} and the width of the page list column is
+governed by the length \ics{glspagelistwidth}. The width of the name 
+and symbol columns is governed by the widest entry in the 
+given column.
+
+\item[altsuper4colborder] The \glostyle{altsuper4colborder} style is like
+the \glostyle{super4colborder} style but allows multi-line descriptions
+and page lists.
+
+\item[altsuper4colheader] The \glostyle{altsuper4colheader} style is like
+\glostyle{super4colheader} but allows multi-line descriptions and
+page lists.
+
+\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder}
+style is like \glostyle{super4colheaderborder} but allows multi-line
+descriptions and page lists.
+\end{description}
+
+
+\subsection{Supertabular Styles (Ragged Right)}
+\label{sec:superraggedstyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-superragged}. These styles are analogous to those
+defined in \sty{glossary-super} but the multiline columns are left
+justified instead of fully justified. Since these styles all use the
+\env{supertabular} environment, they are governed by the same
+parameters as that environment. The \sty{glossary-superragged}
+package additionally requires the \sty{array} package.  Note that
+these styles will only be available if you explicitly load
+\sty{glossary-superragged}:
+\begin{verbatim}
+\usepackage{glossaries}
+\usepackage{glossary-superragged}
+\end{verbatim}
+Note that you can't set these styles using the \pkgopt{style}
+package option since the styles aren't defined until after
+the \styfmt{glossaries} package has been loaded.
+
+\begin{description}
+\item[superragged] The \glostyle{superragged} style uses the
+\env{supertabular} environment (defined by the
+\sty{supertabular} package). It has two columns: the first column
+contains the entry's name and the second column contains the (left
+justified) description followed by the \gls{numberlist}.  The
+entry's symbol is ignored.  Sub groups are separated with a blank
+row. The width of the first column is governed by the widest entry
+in that column. The width of the second column is governed by the
+length \ics{glsdescwidth}. Child entries have a similar format to
+the parent entries except that their name is suppressed.
+
+\item[superraggedborder] The \glostyle{superraggedborder} style is
+like \glostyle{superragged} but has horizontal and vertical lines
+around it.
+
+\item[superraggedheader] The \glostyle{superraggedheader} style is
+like \glostyle{superragged} but has a header row.
+
+\item[superraggedheaderborder] The
+\glostyle{superraggedheaderborder} style is like
+\glostyle{superraggedheader} but has horizontal and vertical lines
+around it.
+
+\item[superragged3col] The \glostyle{superragged3col} style is like
+\glostyle{superragged} but has three columns. The first column
+contains the entry's name, the second column contains the (left
+justified) description and the third column contains the (left
+justified) \gls{numberlist}. The entry's symbol is ignored. The
+width of the first column is governed by the widest entry in that
+column. The width of the second column is governed by the length
+\ics{glsdescwidth}. The width of the third column is governed by the
+length \ics{glspagelistwidth}.
+
+\item[superragged3colborder] The \glostyle{superragged3colborder}
+style is like the \glostyle{superragged3col} style but has
+horizontal and vertical lines around it.
+
+\item[superragged3colheader] The \glostyle{superragged3colheader}
+style is like \glostyle{superragged3col} but has a header row.
+
+\item[superragged3colheaderborder] The
+\glostyle{superragged3colheaderborder} style is like
+the above but has horizontal and vertical
+lines around it.
+
+\item[altsuperragged4col] The \glostyle{altsuperragged4col} style is
+like \glostyle{superragged3col} but has an additional column in
+which the entry's associated symbol appears. The column widths for
+the name and symbol column are governed by the widest entry in the
+given column.
+
+\item[altsuperragged4colborder] The
+\glostyle{altsuperragged4colborder} style is like the
+\glostyle{altsuperragged4col} style but has horizontal and vertical
+lines around it.
+
+\item[altsuperragged4colheader] The
+\glostyle{altsuperragged4colheader} style is like
+\glostyle{altsuperragged4col} but has a header row.
+
+\item[altsuperragged4colheaderborder] The
+\glostyle{altsuperragged4colheaderborder} style is like
+the above but has horizontal and vertical
+lines around it.
+
+\end{description}
+
+\subsection{Tree-Like Styles}
+\label{sec:treestyles}
+
+The styles described in this section are all defined in the package
+\sty{glossary-tree}. These styles are designed for hierarchical
+glossaries but can also be used with glossaries that don't have
+sub-entries. These styles will display the entry's symbol if it
+exists. Note that these styles will automatically be available
+unless you use the \pkgopt{notree} or \pkgopt{nostyles} package
+options. 
+
+These styles all format the entry name using:
+\begin{definition}[\DescribeMacro\glstreenamefmt]
+\cs{glstreenamefmt}\marg{name}
+\end{definition}
+This defaults to \cs{textbf}\marg{name}, but note that \meta{name}
+includes \ics{glsnamefont} so the bold setting in \cs{glstreenamefont}
+may be counteracted by another font change in \cs{glsnamefont} (or
+in \cs{acronymfont}). The tree-like styles that also display the
+header use
+\begin{definition}[\DescribeMacro\glstreegroupheaderfmt]
+\cs{glstreegroupheaderfmt}\marg{text}
+\end{definition}
+to format the heading. This defaults to
+\cs{glstreenamefmt}\marg{text}. The tree-like styles that display
+navigation links to the groups (such as \glostyle{indexhypergroup}), format
+the navigation line using
+\begin{definition}[\DescribeMacro\glstreenavigationfmt]
+\cs{glstreenavigationfmt}\marg{text}
+\end{definition}
+which defaults to \cs{glstreenamefmt}\marg{text}. 
+
+Note that this is
+different from \cs{glslistnavigationitem}, provided with the styles
+such as \glostyle{listhypergroup}, as that also includes \cs{item}.
+
+With the exception of the \glostyle{alttree} style (and those
+derived from it), the space before the description for top-level
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreepredesc]
+\cs{glstreepredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+With the exception of the \glostyle{treenoname} and
+\glostyle{alttree} styles (and those derived from them), the 
+space before the description for child
+entries is produced with
+\begin{definition}[\DescribeMacro\glstreechildpredesc]
+\cs{glstreechildpredesc}
+\end{definition}
+This defaults to \cs{space}.
+
+\begin{important}
+Most of these styles are not designed for multi-paragraph 
+descriptions. (The \glostyle{tree} style isn't too bad for
+multi-paragraph top-level entry descriptions, or you can use the
+\glostyle{index} style with the adjustment shown below.)
+\end{important}
+
+\begin{description}
+\item[index] The \glostyle{index} style is similar to the way
+indices are usually formatted in that it has a hierarchical
+structure up to three levels (the main level plus two sub-levels).
+The name is typeset in bold, and if the symbol is present it is set
+in parentheses after the name and before the description.
+Sub-entries are indented and also include the name, the symbol
+in brackets (if present) and the description.  Groups are separated
+using \ics{indexspace}.
+
+Each main level item is started with
+\begin{definition}[\DescribeMacro\glstreeitem]
+\cs{glstreeitem}
+\end{definition}
+The level~1 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubitem]
+\cs{glstreesubitem}
+\end{definition}
+
+The level~2 entries are started with
+\begin{definition}[\DescribeMacro\glstreesubsubitem]
+\cs{glstreesubsubitem}
+\end{definition}
+
+Note that the \glostyle{index} style automatically sets
+\begin{verbatim}
+\let\item\glstreeitem
+\let\subitem\glstreesubitem
+\let\subsubitem\glstreesubsubitem
+\end{verbatim}
+at the start of the glossary for backward compatibility.
+
+The \glostyle{index} style isn't suitable for multi-paragraph
+descriptions, but this limitation can be overcome by redefining
+the above commands. For example:
+\begin{verbatim}
+\renewcommand{\glstreeitem}{%
+ \parindent0pt\par\hangindent40pt
+ \everypar{\parindent50pt\hangindent40pt}}
+\end{verbatim}
 
-\item[super3colheader] The \glostyle{super3colheader} style is like
-\glostyle{super3col} but has a header row.
+\item[indexgroup] The \glostyle{indexgroup} style is similar to
+the \glostyle{index} style except that each group has a heading
+obtained using \cs{glsgetgrouptitle}\marg{label},
+which is described in \sectionref{sec:newglossarystyle}.
 
-\item[super3colheaderborder] The \glostyle{super3colheaderborder} style
-is like the \glostyle{super3colheader} style but has horizontal and vertical
-lines around it.
+\item[indexhypergroup] The \glostyle{indexhypergroup} style is like 
+\glostyle{indexgroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above, but is formatted using
+\cs{glstreenavigationfmt}.
 
-\item[super4col] The \glostyle{super4col} style is like 
-\glostyle{super3col} but has an additional column in which the
-entry's associated symbol appears. This style is designed for
-entries with brief single line descriptions. The column widths are governed by the
-widest entry in the given column. Use \glostyle{altsuper4col}
-for multi-line descriptions.
+\item[tree] The \glostyle{tree} style is similar to the
+\glostyle{index} style except that it can have arbitrary levels.
+(Note that \gls{makeindex} is limited to three levels, so
+you will need to use \gls{xindy} if you want more than 
+three levels.) Each sub-level is indented by 
+\DescribeMacro{\glstreeindent}\cs{glstreeindent}. Note that the
+name, symbol (if present) and description are placed in the
+same paragraph block. If you want the name to be apart from the
+description, use the \glostyle{alttree} style instead. (See below.)
 
-\item[super4colborder] The \glostyle{super4colborder} style is like
-the \glostyle{super4col} style but has horizontal and vertical
-lines around it.
+\item[treegroup] The \glostyle{treegroup} style is similar to
+the \glostyle{tree} style except that each group has a heading.
 
-\item[super4colheader] The \glostyle{super4colheader} style is like
-\glostyle{super4col} but has a header row.
+\item[treehypergroup] The \glostyle{treehypergroup} style is like 
+\glostyle{treegroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above, but is formatted using
+\cs{glstreenavigationfmt}.
 
-\item[super4colheaderborder] The \glostyle{super4colheaderborder} style
-is like the \glostyle{super4colheader} style but has horizontal and vertical
-lines around it.
+\item[treenoname] The \glostyle{treenoname} style is like
+the \glostyle{tree} style except that the name for each sub-entry
+is ignored.
 
-\item[altsuper4col] The \glostyle{altsuper4col} style is like 
-\glostyle{super4col} but allows multi-line descriptions and page
-lists.
-The width of the description column is governed by the length
-\ics{glsdescwidth} and the width of the page list column is
-governed by the length \ics{glspagelistwidth}. The width of the name 
-and symbol columns is governed by the widest entry in the 
-given column.
+\item[treenonamegroup] The \glostyle{treenonamegroup} style is 
+similar to the \glostyle{treenoname} style except that each group 
+has a heading.
 
-\item[altsuper4colborder] The \glostyle{altsuper4colborder} style is like
-the \glostyle{super4colborder} style but allows multi-line descriptions
-and page lists.
+\item[treenonamehypergroup] The \glostyle{treenonamehypergroup} 
+style is like \glostyle{treenonamegroup} but has a set of links to 
+the glossary groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above, but is formatted using
+\cs{glstreenavigationfmt}.
 
-\item[altsuper4colheader] The \glostyle{altsuper4colheader} style is like
-\glostyle{super4colheader} but allows multi-line descriptions and
-page lists.
+\item[alttree] The \glostyle{alttree} style is similar to the
+\glostyle{tree} style except that the indentation for each level
+is determined by the width of the text specified by
+\begin{definition}[\DescribeMacro{\glssetwidest}]
+\cs{glssetwidest}\oarg{level}\marg{text}
+\end{definition}
+The optional argument \meta{level} indicates the level, where
+0 indicates the top-most level, 1 indicates the first level 
+sub-entries, etc. If \cs{glssetwidest} hasn't been used for a 
+given sub-level, the level~0 widest text is used instead. If
+\meta{level} is omitted, 0 is assumed.
 
-\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder}
-style is like \glostyle{super4colheaderborder} but allows multi-line
-descriptions and page lists.
-\end{description}
+As from v4.22, the \sty{glossary-tree} package also provides
+\begin{definition}[\DescribeMacro\glsfindwidesttoplevelname]
+\cs{glsfindwidesttoplevelname}\oarg{glossary list}
+\end{definition}
+This iterates over all parentless entries in the given glossary
+lists and determines the widest entry. If the optional argument is
+omitted, all glossaries are assumed (as per \cs{forallglossaries}).
 
+For example, to have the same name width for all glossaries:
+\begin{verbatim}
+\glsfindwidesttoplevelname
+\setglossarystyle{alttree}
+\printglossaries
+\end{verbatim}
+Alternatively, to compute the widest entry for each glossary
+before it's displayed:
+\begin{verbatim}
+\renewcommand{\glossarypreamble}{%
+  \glsfindwidesttoplevelname[\currentglossary]}
+\setglossarystyle{alttree}
+\printglossaries
+\end{verbatim}
 
-\subsection{Supertabular Styles (Ragged Right)}
-\label{sec:superraggedstyles}
+\begin{important}
+These commands only affects the \glostyle{alttree} styles, including those 
+listed below and the ones in the \sty{glossary-mcols} package.
+If you forget to set the widest entry name, the description will
+overwrite the name.
+\end{important}
 
-The styles described in this section are all defined in the package
-\sty{glossary-superragged}. These styles are analogous to those
-defined in \sty{glossary-super} but the multiline columns are left
-justified instead of fully justified. Since these styles all use the
-\env{supertabular} environment, they are governed by the same
-parameters as that environment. The \sty{glossary-superragged}
-package additionally requires the \sty{array} package.  Note that
-these styles will only be available if you explicitly load
-\sty{glossary-superragged}:
+For each level, the name is placed to the left of the paragraph
+block containing the symbol (optional) and the description. If the
+symbol is present, it is placed in parentheses before the
+description.
+
+The name is placed inside a left-aligned \cs{makebox}. As from
+v4.19, this can now be adjusted by redefining
+\begin{definition}[\DescribeMacro\glstreenamebox]
+\cs{glstreenamebox}\marg{width}\marg{text}
+\end{definition}
+where \meta{width} is the width of the box and \meta{text} is the
+contents of the box. For example, to make the name right-aligned:
 \begin{verbatim}
-\usepackage{glossaries}
-\usepackage{glossary-superragged}
+\renewcommand*{\glstreenamebox}[2]{%
+  \makebox[#1][r]{#2}%
+}
 \end{verbatim}
-Note that you can't set these styles using the \pkgopt{style}
-package option since the styles aren't defined until after
-the \styfmt{glossaries} package has been loaded.
 
-\begin{description}
-\item[superragged] The \glostyle{superragged} style uses the
-\env{supertabular} environment (defined by the
-\sty{supertabular} package). It has two columns: the first column
-contains the entry's name and the second column contains the (left
-justified) description followed by the \gls{numberlist}.  The
-entry's symbol is ignored.  Sub groups are separated with a blank
-row. The width of the first column is governed by the widest entry
-in that column. The width of the second column is governed by the
-length \ics{glsdescwidth}. Child entries have a similar format to
-the parent entries except that their name is suppressed.
+\item[alttreegroup] The \glostyle{alttreegroup} is like the
+\glostyle{alttree} style except that each group has a heading.
 
-\item[superraggedborder] The \glostyle{superraggedborder} style is
-like \glostyle{superragged} but has horizontal and vertical lines
-around it.
+\item[alttreehypergroup] The \glostyle{alttreehypergroup} style is 
+like \glostyle{alttreegroup} but has a set of links to the glossary 
+groups. The navigation line is the same as that for 
+\glostyle{listhypergroup}, described above.
 
-\item[superraggedheader] The \glostyle{superraggedheader} style is
-like \glostyle{superragged} but has a header row.
+\end{description}
 
-\item[superraggedheaderborder] The
-\glostyle{superraggedheaderborder} style is like
-\glostyle{superraggedheader} but has horizontal and vertical lines
-around it.
+\subsection{Multicols Style}
+\label{sec:mcolstyles}
 
-\item[superragged3col] The \glostyle{superragged3col} style is like
-\glostyle{superragged} but has three columns. The first column
-contains the entry's name, the second column contains the (left
-justified) description and the third column contains the (left
-justified) \gls{numberlist}. The entry's symbol is ignored. The
-width of the first column is governed by the widest entry in that
-column. The width of the second column is governed by the length
-\ics{glsdescwidth}. The width of the third column is governed by the
-length \ics{glspagelistwidth}.
+The \sty{glossary-mcols} package provides tree-like styles that are
+in the \env{multicols} environment (defined by the \sty{multicol}
+package). The style names are as their analogous tree styles (as
+defined in \sectionref{sec:treestyles}) but are prefixed with
+\qt{mcol}.
+For example, the \glostyle{mcolindex} style is essentially the
+\glostyle{index} style but put in a \env{multicols} environment.
+For the complete list, see \tableref{tab:mcols}. The
+\sty{glossary-tree} package is automatically loaded by
+\sty{glossary-mcols} (even if the \pkgopt{notree} package option is
+used when loading \styfmt{glossaries}). The formatting commands
+\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
+\cs{glstreenavigationfmt} are all used by the corresponding
+\sty{glossary-mcols} styles.
 
-\item[superragged3colborder] The \glostyle{superragged3colborder}
-style is like the \glostyle{superragged3col} style but has
-horizontal and vertical lines around it.
+\begin{important}
+Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If
+you want to use any of the multicol styles in that package you need
+to load it explicitly with \cs{usepackage} and set the required glossary
+style using \ics{setglossarystyle}.
+\end{important}
 
-\item[superragged3colheader] The \glostyle{superragged3colheader}
-style is like \glostyle{superragged3col} but has a header row.
+The default number of columns is 2, but can be changed by redefining
+\begin{definition}[\DescribeMacro{\glsmcols}]
+\cs{glsmcols}
+\end{definition}
+to the required number. For example, for a three column glossary:
+\begin{verbatim}
+\usepackage{glossary-mcols}
+\renewcommand*{\glsmcols}{3}
+\setglossarystyle{mcolindex}
+\end{verbatim}
 
-\item[superragged3colheaderborder] The
-\glostyle{superragged3colheaderborder} style is like
-the above but has horizontal and vertical
-lines around it.
+\begin{table}[htbp]
+\caption{Multicolumn Styles}
+\label{tab:mcols}
+\centering
+\begin{tabular}{ll}
+\bfseries
+\sty{glossary-mcols} Style &
+\bfseries
+Analogous Tree Style\\
+\glostyle{mcolindex} & \glostyle{index}\\
+\glostyle{mcolindexgroup} & \glostyle{indexgroup}\\
+\glostyle{mcolindexhypergroup} or \glostyle{mcolindexspannav} & \glostyle{indexhypergroup}\\
+\glostyle{mcoltree} & \glostyle{tree}\\
+\glostyle{mcoltreegroup} & \glostyle{treegroup}\\
+\glostyle{mcoltreehypergroup} or \glostyle{mcoltreespannav} & \glostyle{treehypergroup}\\
+\glostyle{mcoltreenoname} & \glostyle{treenoname}\\
+\glostyle{mcoltreenonamegroup} & \glostyle{treenonamegroup}\\
+\glostyle{mcoltreenonamehypergroup} or
+\glostyle{mcoltreenonamespannav} & \glostyle{treenonamehypergroup}\\
+\glostyle{mcolalttree} & \glostyle{alttree}\\
+\glostyle{mcolalttreegroup} & \glostyle{alttreegroup}\\
+\glostyle{mcolalttreehypergroup} or \glostyle{mcolalttreespannav} & \glostyle{alttreehypergroup}
+\end{tabular}
+\end{table}
 
-\item[altsuperragged4col] The \glostyle{altsuperragged4col} style is
-like \glostyle{superragged3col} but has an additional column in
-which the entry's associated symbol appears. The column widths for
-the name and symbol column are governed by the widest entry in the
-given column.
+The styles with a navigation line, such as
+\glostyle{mcoltreehypergroup}, now have a variant (as from v4.22)
+with \qt{hypergroup} replaced with \qt{spannav} in the style name.
+The original \qt{hypergroup} styles place the navigation line at the
+start of the first column. The newer \qt{spannav} styles put the
+navigation line in the optional argument of the \env{multicols}
+environment so that it spans across all the columns.
 
-\item[altsuperragged4colborder] The
-\glostyle{altsuperragged4colborder} style is like the
-\glostyle{altsuperragged4col} style but has horizontal and vertical
-lines around it.
+\subsection{In-Line Style}
+\label{sec:inline}
 
-\item[altsuperragged4colheader] The
-\glostyle{altsuperragged4colheader} style is like
-\glostyle{altsuperragged4col} but has a header row.
+This section covers the \sty{glossary-inline} package that supplies
+the \glostyle{inline} style. This is a style that is designed for
+in-line use (as opposed to block styles, such as lists or tables).
+This style doesn't display the \gls{numberlist}.
 
-\item[altsuperragged4colheaderborder] The
-\glostyle{altsuperragged4colheaderborder} style is like
-the above but has horizontal and vertical
-lines around it.
+You will most likely need to redefine \ics{glossarysection} with
+this style. For example, suppose you are required to have your
+glossaries and list of acronyms in a footnote, you can do:
+\begin{verbatim}
+ \usepackage{glossary-inline}
 
-\end{description}
+ \renewcommand*{\glossarysection}[2][]{\textbf{#1}: }
+ \setglossarystyle{inline}
+\end{verbatim}
 
-\subsection{Tree-Like Styles}
-\label{sec:treestyles}
+\begin{important}
+Note that you need to include \sty{glossary-inline} with
+\cs{usepackage} as it's not automatically included by the
+\styfmt{glossaries} package and then set the style using 
+\ics{setglossarystyle}.
+\end{important}
 
-The styles described in this section are all defined in the package
-\sty{glossary-tree}. These styles are designed for hierarchical
-glossaries but can also be used with glossaries that don't have
-sub-entries. These styles will display the entry's symbol if it
-exists. Note that these styles will automatically be available
-unless you use the \pkgopt{notree} or \pkgopt{nostyles} package
-options. 
+Where you need to include your glossaries as a footnote you can do:
+\begin{verbatim}
+\footnote{\printglossaries}
+\end{verbatim}
 
-These styles all format the entry name using:
-\begin{definition}[\DescribeMacro\glstreenamefmt]
-\cs{glstreenamefmt}\marg{name}
+The \glostyle{inline} style is governed by the following:
+\begin{definition}[\DescribeMacro{\glsinlineseparator}]
+\ics{glsinlineseparator}
 \end{definition}
-This defaults to \cs{textbf}\marg{name}, but note that \meta{name}
-includes \ics{glsnamefont} so the bold setting in \cs{glstreenamefont}
-may be counteracted by another font change in \cs{glsnamefont} (or
-in \cs{acronymfont}). The tree-like styles that also display the
-header use
-\begin{definition}[\DescribeMacro\glstreegroupheaderfmt]
-\cs{glstreegroupheaderfmt}\marg{text}
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used between
+main (i.e.\ level~0) entries.
+\begin{definition}[\DescribeMacro{\glsinlinesubseparator}]
+\ics{glsinlinesubseparator}
 \end{definition}
-to format the heading. This defaults to
-\cs{glstreenamefmt}\marg{text}. The tree-like styles that display
-navigation links to the groups (such as \glostyle{indexhypergroup}), format
-the navigation line using
-\begin{definition}[\DescribeMacro\glstreenavigationfmt]
-\cs{glstreenavigationfmt}\marg{text}
+This defaults to \qt{\texttt{\glsinlinesubseparator}} and is used between
+sub-entries.
+\begin{definition}[\DescribeMacro{\glsinlineparentchildseparator}]
+\ics{glsinlineparentchildseparator}
 \end{definition}
-which defaults to \cs{glstreenamefmt}\marg{text}. 
-
-Note that this is
-different from \cs{glslistnavigationitem}, provided with the styles
-such as \glostyle{listhypergroup}, as that also includes \cs{item}.
+This defaults to \qt{\texttt{\glsinlineparentchildseparator}} and is used between
+a parent main entry and its first sub-entry.
+\begin{definition}[\DescribeMacro{\glspostinline}]
+\ics{glspostinline}
+\end{definition}
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used at the end
+of the glossary.
+\begin{definition}[\DescribeMacro\glsinlinenameformat]
+\cs{glsinlinenameformat}\marg{label}\marg{name}
+\end{definition}
+This is used to format the entry name and defaults to 
+\cs{glstarget}\marg{label}\marg{name}, where \meta{name} is provided
+in the form \cs{glossentryname}\marg{label} and \meta{label} is the
+entry's label. For example, if you want the name to appear in
+\gls{smallcaps}:
+\begin{verbatim}
+\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}}
+\end{verbatim}
+Sub-entry names are formatted according to
+\begin{definition}[\DescribeMacro\glsinlinesubnameformat]
+\cs{glsinlinesubnameformat}\marg{label}\marg{name}
+\end{definition}
+This defaults to \cs{glstarget}\marg{label}\verb|{}| so the
+sub-entry name is ignored.
 
-With the exception of the \glostyle{alttree} style (and those
-derived from it), the space before the description for top-level
-entries is produced with
-\begin{definition}[\DescribeMacro\glstreepredesc]
-\cs{glstreepredesc}
+If the description has been suppressed (according to
+\cs{ifglsdescsuppressed}) then 
+\begin{definition}[\DescribeMacro\glsinlineemptydescformat]
+\cs{glsinlineemptydescformat}\marg{symbol}\marg{number list}
 \end{definition}
-This defaults to \cs{space}.
+(which defaults to nothing) is used,
+otherwise the description is formatted according to
+\begin{definition}[\DescribeMacro\glsinlinedescformat]
+\cs{glsinlinedescformat}\marg{description}\marg{symbol}\marg{number
+list}
+\end{definition}
+This defaults to just \cs{space}\meta{description} so the symbol and
+location list are ignored. If the description is missing (according
+to \cs{ifglshasdesc}), then \cs{glsinlineemptydescformat} is used
+instead.
 
-With the exception of the \glostyle{treenoname} and
-\glostyle{alttree} styles (and those derived from them), the 
-space before the description for child
-entries is produced with
-\begin{definition}[\DescribeMacro\glstreechildpredesc]
-\cs{glstreechildpredesc}
+For example, if you want a colon between the name and the
+description:
+\begin{verbatim}
+\renewcommand*{\glsinlinedescformat}[3]{: #1}
+\end{verbatim}
+
+The sub-entry description is formatted according to:
+\begin{definition}[\DescribeMacro\glsinlinesubdescformat]
+\cs{glsinlinesubdescformat}\marg{description}\marg{symbol}\marg{number
+list}
 \end{definition}
-This defaults to \cs{space}.
+This defaults to just \meta{description}.
+
+\section{Defining your own glossary style}
+\label{sec:newglossarystyle}
 
 \begin{important}
-Most of these styles are not designed for multi-paragraph 
-descriptions. (The \glostyle{tree} style isn't too bad for
-multi-paragraph top-level entry descriptions, or you can use the
-\glostyle{index} style with the adjustment shown below.)
+Commands like \cs{printglossary} are designed to produce content in
+the PDF. If your intention is to design a style that doesn't print
+any content (for example, to simply capture information) then you
+are likely to experience unwanted side-effects. If you just want to
+capture indexing information (such as locations) then a much better
+approach is to use \gls{bib2gls}, which automatically stores this
+information in dedicated fields when the entry is defined.
 \end{important}
 
-\begin{description}
-\item[index] The \glostyle{index} style is similar to the way
-indices are usually formatted in that it has a hierarchical
-structure up to three levels (the main level plus two sub-levels).
-The name is typeset in bold, and if the symbol is present it is set
-in parentheses after the name and before the description.
-Sub-entries are indented and also include the name, the symbol
-in brackets (if present) and the description.  Groups are separated
-using \ics{indexspace}.
-
-Each main level item is started with
-\begin{definition}[\DescribeMacro\glstreeitem]
-\cs{glstreeitem}
-\end{definition}
-The level~1 entries are started with
-\begin{definition}[\DescribeMacro\glstreesubitem]
-\cs{glstreesubitem}
+If the predefined styles don't fit your requirements, you can
+define your own style using:
+\begin{definition}[\DescribeMacro{\newglossarystyle}]
+\cs{newglossarystyle}\marg{name}\marg{definitions}
 \end{definition}
+where \meta{name} is the name of the new glossary style (to be
+used in \cs{setglossarystyle}). The second argument \meta{definitions}
+needs to redefine all of the following:
 
-The level~2 entries are started with
-\begin{definition}[\DescribeMacro\glstreesubsubitem]
-\cs{glstreesubsubitem}
+\begin{definition}[\DescribeEnv{theglossary}]
+\env{theglossary}
 \end{definition}
+This environment defines how the main body of the glossary should
+be typeset. 
 
-Note that the \glostyle{index} style automatically sets
-\begin{verbatim}
-\let\item\glstreeitem
-\let\subitem\glstreesubitem
-\let\subsubitem\glstreesubsubitem
-\end{verbatim}
-at the start of the glossary for backward compatibility.
+Note that this does not include the section heading,
+the glossary preamble (defined by \ics{glossarypreamble}) or the
+glossary postamble (defined by \ics{glossarypostamble}). For example,
+the \glostyle{list} style uses the \env{description} environment,
+so the \env{theglossary} environment is simply redefined to begin
+and end the \env{description} environment.
 
-The \glostyle{index} style isn't suitable for multi-paragraph
-descriptions, but this limitation can be overcome by redefining
-the above commands. For example:
-\begin{verbatim}
-\renewcommand{\glstreeitem}{%
- \parindent0pt\par\hangindent40pt
- \everypar{\parindent50pt\hangindent40pt}}
-\end{verbatim}
+\begin{definition}[\DescribeMacro{\glossaryheader}]
+\cs{glossaryheader}
+\end{definition}
+This macro indicates what to do at the start of the main body
+of the glossary. Note that this is not the same as 
+\ics{glossarypreamble}, which should not be affected by changes in
+the glossary style. The \glostyle{list} glossary style redefines
+\ics{glossaryheader} to do nothing, whereas the \glostyle{longheader}
+glossary style redefines \cs{glossaryheader} to do a header row.
 
-\item[indexgroup] The \glostyle{indexgroup} style is similar to
-the \glostyle{index} style except that each group has a heading
-obtained using \cs{glsgetgrouptitle}\marg{label},
-which is described in \sectionref{sec:newglossarystyle}.
+\begin{definition}[\DescribeMacro{\glsgroupheading}]
+\cs{glsgroupheading}\marg{label}
+\end{definition}
+This macro indicates
+what to do at the start of each logical block within the main body
+of the glossary. If you use \gls{makeindex} the glossary is
+sub-divided into a maximum of twenty-eight logical blocks that are
+determined by the first character of the \gloskey{sort} key (or
+\gloskey{name} key if the \gloskey{sort} key is omitted). The
+sub-divisions are in the following order: symbols, numbers, A,
+\ldots, Z\@. If you use \gls{xindy}, the sub-divisions depend on
+the language settings.
 
-\item[indexhypergroup] The \glostyle{indexhypergroup} style is like 
-\glostyle{indexgroup} but has a set of links to the glossary 
-groups. The navigation line is the same as that for 
-\glostyle{listhypergroup}, described above, but is formatted using
-\cs{glstreenavigationfmt}.
+Note that the argument to \cs{glsgroupheading}
+is a label \emph{not} the group title. The group title can be obtained
+via
+\begin{definition}[\DescribeMacro{\glsgetgrouptitle}]
+\cs{glsgetgrouptitle}\marg{label}
+\end{definition}
+This obtains the title as follows: if \meta{label} consists of a
+single non-active character or \meta{label} is equal to
+\texttt{glssymbols} or \texttt{glsnumbers} and
+\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the 
+title, otherwise the title is just \meta{label}. (The \qt{symbols}
+group has the label \texttt{glssymbols}, so the command 
+\ics{glssymbolsgroupname} is used, and the \qt{numbers} group has the
+label \texttt{glsnumbers}, so the command \ics{glsnumbersgrouptitle}
+is used.) If you are using \gls{xindy}, \meta{label} may be an
+active character (for example \o), in which case the title will be
+set to just \meta{label}. You can redefine \cs{glsgetgrouptitle} if
+this is unsuitable for your document.
 
-\item[tree] The \glostyle{tree} style is similar to the
-\glostyle{index} style except that it can have arbitrary levels.
-(Note that \gls{makeindex} is limited to three levels, so
-you will need to use \gls{xindy} if you want more than 
-three levels.) Each sub-level is indented by 
-\DescribeMacro{\glstreeindent}\cs{glstreeindent}. Note that the
-name, symbol (if present) and description are placed in the
-same paragraph block. If you want the name to be apart from the
-description, use the \glostyle{alttree} style instead. (See below.)
+A navigation hypertarget can be created using
+\begin{definition}[\DescribeMacro{\glsnavhypertarget}]
+\cs{glsnavhypertarget}\marg{label}\marg{text}
+\end{definition}
+This typically requires \cs{glossaryheader} to be redefined to use
+\begin{definition}[\DescribeMacro\glsnavigation]
+\cs{glsnavigation}
+\end{definition}
+which displays the navigation line.
 
-\item[treegroup] The \glostyle{treegroup} style is similar to
-the \glostyle{tree} style except that each group has a heading.
+For further details about \cs{glsnavhypertarget}, see
+\ifpdf section~\ref*{sec:code:hypernav} in \fi the documented code 
+(\texttt{glossaries-code.pdf}).
 
-\item[treehypergroup] The \glostyle{treehypergroup} style is like 
-\glostyle{treegroup} but has a set of links to the glossary 
-groups. The navigation line is the same as that for 
-\glostyle{listhypergroup}, described above, but is formatted using
-\cs{glstreenavigationfmt}.
+Most of the predefined glossary styles redefine \cs{glsgroupheading}
+to simply ignore its argument.  The \glostyle{listhypergroup} style
+redefines \cs{glsgroupheading} as follows:
+\begin{verbatim}
+\renewcommand*{\glsgroupheading}[1]{%
+\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]}
+\end{verbatim}
+See also \cs{glsgroupskip} below. 
 
-\item[treenoname] The \glostyle{treenoname} style is like
-the \glostyle{tree} style except that the name for each sub-entry
-is ignored.
+Note that command definitions within 
+\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc.
 
-\item[treenonamegroup] The \glostyle{treenonamegroup} style is 
-similar to the \glostyle{treenoname} style except that each group 
-has a heading.
+\begin{definition}[\DescribeMacro{\glsgroupskip}]
+\cs{glsgroupskip}
+\end{definition}
+This macro determines what to do after one logical group but before
+the header for the next logical group. The \glostyle{list} glossary
+style simply redefines \cs{glsgroupskip} to be \ics{indexspace},
+whereas the tabular-like styles redefine \cs{glsgroupskip} to
+produce a blank row.
 
-\item[treenonamehypergroup] The \glostyle{treenonamehypergroup} 
-style is like \glostyle{treenonamegroup} but has a set of links to 
-the glossary groups. The navigation line is the same as that for 
-\glostyle{listhypergroup}, described above, but is formatted using
-\cs{glstreenavigationfmt}.
+As from version 3.03, the package option \pkgopt{nogroupskip} can be
+used to suppress this default gap for the predefined styles.
 
-\item[alttree] The \glostyle{alttree} style is similar to the
-\glostyle{tree} style except that the indentation for each level
-is determined by the width of the text specified by
-\begin{definition}[\DescribeMacro{\glssetwidest}]
-\cs{glssetwidest}\oarg{level}\marg{text}
+\begin{definition}[\DescribeMacro{\glossentry}]
+\cs{glossentry}\marg{label}\marg{number list}
 \end{definition}
-The optional argument \meta{level} indicates the level, where
-0 indicates the top-most level, 1 indicates the first level 
-sub-entries, etc. If \cs{glssetwidest} hasn't been used for a 
-given sub-level, the level~0 widest text is used instead. If
-\meta{level} is omitted, 0 is assumed.
+This macro indicates what to do for each top-level (level~0) glossary entry.
+The entry label is given by \meta{label} and the associated
+\gls{numberlist} is given by \meta{number list}. You can redefine
+\ics{glossentry} to use commands like \ics{glossentryname}\marg{label},
+\ics{glossentrydesc}\marg{label} and \ics{glossentrysymbol}\marg{label} 
+to display the name, description and symbol fields, or to access
+other fields, use commands like \ics{glsentryuseri}\marg{label}.
+(See \sectionref{sec:glsnolink} for further details.) You can also
+use the following commands:
 
-As from v4.22, the \sty{glossary-tree} package also provides
-\begin{definition}[\DescribeMacro\glsfindwidesttoplevelname]
-\cs{glsfindwidesttoplevelname}\oarg{glossary list}
+\begin{definition}[\DescribeMacro{\glsentryitem}]
+\cs{glsentryitem}\marg{label}
+\end{definition}
+This macro will increment and display the associated counter for the
+main (level~0) entries if the \pkgopt{entrycounter} or
+\pkgopt{counterwithin} package options have been used. This macro
+is typically called by \cs{glossentry} before \cs{glstarget}. 
+The format of the counter is controlled by the macro
+\begin{definition}[\DescribeMacro{\glsentrycounterlabel}]
+\cs{glsentrycounterlabel}
 \end{definition}
-This iterates over all parentless entries in the given glossary
-lists and determines the widest entry. If the optional argument is
-omitted, all glossaries are assumed (as per \cs{forallglossaries}).
 
-For example, to have the same name width for all glossaries:
-\begin{verbatim}
-\glsfindwidesttoplevelname
-\setglossarystyle{alttree}
-\printglossaries
-\end{verbatim}
-Alternatively, to compute the widest entry for each glossary
-before it's displayed:
+Each time you use a glossary entry it creates a hyperlink (if
+hyperlinks are enabled) to the relevant line in the glossary.
+Your new glossary style must therefore redefine
+\cs{glossentry} to set the appropriate target. This
+is done using
+\begin{definition}[\DescribeMacro{\glstarget}]
+\cs{glstarget}\marg{label}\marg{text}
+\end{definition}
+where \meta{label} is the entry's label. Note that you
+don't need to worry about whether the \sty{hyperref} package has
+been loaded, as \cs{glstarget} won't create a target if
+\cs{hypertarget} hasn't been defined.
+
+For example, the \glostyle{list} style defines \cs{glossentry} as follows:
 \begin{verbatim}
-\renewcommand{\glossarypreamble}{%
-  \glsfindwidesttoplevelname[\currentglossary]}
-\setglossarystyle{alttree}
-\printglossaries
+  \renewcommand*{\glossentry}[2]{%
+    \item[\glsentryitem{##1}%
+          \glstarget{##1}{\glossentryname{##1}}]
+       \glossentrydesc{##1}\glspostdescription\space ##2}
 \end{verbatim}
 
-\begin{important}
-These commands only affects the \glostyle{alttree} styles, including those 
-listed below and the ones in the \sty{glossary-mcols} package.
-If you forget to set the widest entry name, the description will
-overwrite the name.
-\end{important}
+Note also that \meta{number list} will always be of the form
+\begin{definition}
+\ics{glossaryentrynumbers}\{\cs{relax}\\
+\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}\}
+\end{definition}
+where \meta{number(s)}
+may contain \ics{delimN} (to delimit individual numbers) and/or
+\ics{delimR} (to indicate a range of numbers). There may be 
+multiple occurrences of 
+\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}, but note
+that the entire number list is enclosed within the argument
+of \ics{glossaryentrynumbers}. The user can redefine this to change
+the way the entire number list is formatted, regardless of 
+the glossary style. However the most common use of
+\ics{glossaryentrynumbers} is to provide a means of suppressing the
+number list altogether. (In fact, the \pkgopt{nonumberlist} option 
+redefines \ics{glossaryentrynumbers} to ignore its argument.)
+Therefore, when you define a new glossary style, you don't need
+to worry about whether the user has specified the 
+\pkgopt{nonumberlist} package option.
 
-For each level, the name is placed to the left of the paragraph
-block containing the symbol (optional) and the description. If the
-symbol is present, it is placed in parentheses before the
-description.
+\begin{definition}[\DescribeMacro{\subglossentry}]
+\cs{subglossentry}\marg{level}\marg{label}\marg{number list}
+\end{definition}
+This is used to display sub-entries.
+The first argument, \meta{level}, indicates the sub-entry level.
+This must be an integer from 1 (first sub-level) onwards. The
+remaining arguments are analogous to those for
+\ics{glossentry} described above.
 
-The name is placed inside a left-aligned \cs{makebox}. As from
-v4.19, this can now be adjusted by redefining
-\begin{definition}[\DescribeMacro\glstreenamebox]
-\cs{glstreenamebox}\marg{width}\marg{text}
+\begin{definition}[\DescribeMacro{\glssubentryitem}]
+\cs{glssubentryitem}\marg{label}
+\end{definition}
+This macro will increment and display the associated counter for the
+level~1 entries if the \pkgopt{subentrycounter} package option has
+been used. This macro is typically called by \cs{subglossentry}
+before \ics{glstarget}. The format of the counter is controlled by
+the macro
+\begin{definition}[\DescribeMacro{\glssubentrycounterlabel}]
+\cs{glssubentrycounterlabel}
 \end{definition}
-where \meta{width} is the width of the box and \meta{text} is the
-contents of the box. For example, to make the name right-aligned:
-\begin{verbatim}
-\renewcommand*{\glstreenamebox}[2]{%
-  \makebox[#1][r]{#2}%
-}
-\end{verbatim}
 
-\item[alttreegroup] The \glostyle{alttreegroup} is like the
-\glostyle{alttree} style except that each group has a heading.
+Note that \ics{printglossary} (which \ics{printglossaries} calls)
+sets
+\begin{definition}[\DescribeMacro{\currentglossary}]
+\cs{currentglossary}
+\end{definition}
+to the current glossary label, so it's possible to create a glossary
+style that varies according to the glossary type.
 
-\item[alttreehypergroup] The \glostyle{alttreehypergroup} style is 
-like \glostyle{alttreegroup} but has a set of links to the glossary 
-groups. The navigation line is the same as that for 
-\glostyle{listhypergroup}, described above.
+For further details of these commands, see \ifpdf
+section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary}
+in the documented code (\texttt{glossaries-code.pdf}).
 
-\end{description}
+\begin{example}{Creating a completely new style}{sec:exnewstyle}
 
-\subsection{Multicols Style}
-\label{sec:mcolstyles}
+If you want a completely new style, you will need to redefine all
+of the commands and the environment listed above. 
 
-The \sty{glossary-mcols} package provides tree-like styles that are
-in the \env{multicols} environment (defined by the \sty{multicol}
-package). The style names are as their analogous tree styles (as
-defined in \sectionref{sec:treestyles}) but are prefixed with
-\qt{mcol}.
-For example, the \glostyle{mcolindex} style is essentially the
-\glostyle{index} style but put in a \env{multicols} environment.
-For the complete list, see \tableref{tab:mcols}. The
-\sty{glossary-tree} package is automatically loaded by
-\sty{glossary-mcols} (even if the \pkgopt{notree} package option is
-used when loading \styfmt{glossaries}). The formatting commands
-\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
-\cs{glstreenavigationfmt} are all used by the corresponding
-\sty{glossary-mcols} styles.
+For example, suppose you want each entry to start with a bullet point.
+This means that the glossary should be placed in the \env{itemize}
+environment, so \env{theglossary} should start and end that
+environment. Let's also suppose that you don't want anything between
+the glossary groups (so \ics{glsgroupheading} and \ics{glsgroupskip}
+should do nothing) and suppose you don't want anything to appear
+immediately after \verb|\begin{theglossary}| (so \ics{glossaryheader}
+should do nothing). In addition, let's suppose the symbol should
+appear in brackets after the name, followed by the description and
+last of all the \gls{numberlist} should appear within square brackets
+at the end. Then you can create this new glossary style, called, say,
+\texttt{mylist}, as follows:
+\begin{verbatim}
+ \newglossarystyle{mylist}{%
+ % put the glossary in the itemize environment:
+ \renewenvironment{theglossary}%
+   {\begin{itemize}}{\end{itemize}}%
+ % have nothing after \begin{theglossary}:
+ \renewcommand*{\glossaryheader}{}%
+ % have nothing between glossary groups:
+ \renewcommand*{\glsgroupheading}[1]{}%
+ \renewcommand*{\glsgroupskip}{}%
+ % set how each entry should appear:
+ \renewcommand*{\glossentry}[2]{%
+ \item % bullet point
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \space (\glossentrysymbol{##1})% the symbol in brackets
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
+ }%
+ % set how sub-entries appear:
+ \renewcommand*{\subglossentry}[3]{%
+   \glossentry{##2}{##3}}%
+ }
+\end{verbatim}
+Note that this style creates a flat glossary, where sub-entries
+are displayed in exactly the same way as the top level entries.
+It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so
+it won't be affected by the \pkgopt{entrycounter},
+\pkgopt{counterwithin} or \pkgopt{subentrycounter} package options.
 
-\begin{important}
-Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If
-you want to use any of the multicol styles in that package you need
-to load it explicitly with \cs{usepackage} and set the required glossary
-style using \ics{setglossarystyle}.
-\end{important}
+Variations:
+\begin{itemize}
+\item You might want the entry name to be capitalised, in
+which case use \ics{Glossentryname} instead of \ics{glossentryname}.
 
-The default number of columns is 2, but can be changed by redefining
-\begin{definition}[\DescribeMacro{\glsmcols}]
-\cs{glsmcols}
-\end{definition}
-to the required number. For example, for a three column glossary:
+\item You might want to check if the symbol hasn't been set and omit
+the parentheses if the symbol is absent. In this case you can use
+\ics{ifglshassymbol} (see \sectionref{sec:utilities}):
 \begin{verbatim}
-\usepackage{glossary-mcols}
-\renewcommand*{\glsmcols}{3}
-\setglossarystyle{mcolindex}
+ \renewcommand*{\glossentry}[2]{%
+ \item % bullet point
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \ifglshassymbol{##1}% check if symbol exists
+ {%
+   \space (\glossentrysymbol{##1})% the symbol in brackets
+ }%
+ {}% no symbol so do nothing
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
+ }%
 \end{verbatim}
+\end{itemize}
+\end{example}
 
-\begin{table}[htbp]
-\caption{Multicolumn Styles}
-\label{tab:mcols}
-\centering
-\begin{tabular}{ll}
-\bfseries
-\sty{glossary-mcols} Style &
-\bfseries
-Analogous Tree Style\\
-\glostyle{mcolindex} & \glostyle{index}\\
-\glostyle{mcolindexgroup} & \glostyle{indexgroup}\\
-\glostyle{mcolindexhypergroup} or \glostyle{mcolindexspannav} & \glostyle{indexhypergroup}\\
-\glostyle{mcoltree} & \glostyle{tree}\\
-\glostyle{mcoltreegroup} & \glostyle{treegroup}\\
-\glostyle{mcoltreehypergroup} or \glostyle{mcoltreespannav} & \glostyle{treehypergroup}\\
-\glostyle{mcoltreenoname} & \glostyle{treenoname}\\
-\glostyle{mcoltreenonamegroup} & \glostyle{treenonamegroup}\\
-\glostyle{mcoltreenonamehypergroup} or
-\glostyle{mcoltreenonamespannav} & \glostyle{treenonamehypergroup}\\
-\glostyle{mcolalttree} & \glostyle{alttree}\\
-\glostyle{mcolalttreegroup} & \glostyle{alttreegroup}\\
-\glostyle{mcolalttreehypergroup} or \glostyle{mcolalttreespannav} & \glostyle{alttreehypergroup}
-\end{tabular}
-\end{table}
-
-The styles with a navigation line, such as
-\glostyle{mcoltreehypergroup}, now have a variant (as from v4.22)
-with \qt{hypergroup} replaced with \qt{spannav} in the style name.
-The original \qt{hypergroup} styles place the navigation line at the
-start of the first column. The newer \qt{spannav} styles put the
-navigation line in the optional argument of the \env{multicols}
-environment so that it spans across all the columns.
+\begin{example}{Creating a new glossary style based on an
+existing style}{sec:exadaptstyle}
 
-\subsection{In-Line Style}
-\label{sec:inline}
+If you want to define a new style that is a slightly modified
+version of an existing style, you can use \ics{setglossarystyle}
+within the second argument of \ics{newglossarystyle} followed by
+whatever alterations you require. For example, suppose you want 
+a style like the \glostyle{list} style but you don't want the extra
+vertical space created by \ics{indexspace} between groups, then you
+can create a new glossary style called, say, \texttt{mylist} as
+follows:
+\begin{verbatim}
+\newglossarystyle{mylist}{%
+\setglossarystyle{list}% base this style on the list style
+\renewcommand{\glsgroupskip}{}% make nothing happen 
+                              % between groups
+}
+\end{verbatim} 
+(In this case, you can actually achieve the same effect using the
+\glostyle{list} style in combination with the package option
+\pkgopt{nogroupskip}.)
+\end{example}
 
-This section covers the \sty{glossary-inline} package that supplies
-the \glostyle{inline} style. This is a style that is designed for
-in-line use (as opposed to block styles, such as lists or tables).
-This style doesn't display the \gls{numberlist}.
+\begin{example}{Example: creating a glossary style that uses the
+\texorpdfstring{\gloskey{user1}}{user1}, \ldots, 
+\texorpdfstring{\gloskey{user6}}{user6} keys}{sec:exuserstyle}
 
-You will most likely need to redefine \ics{glossarysection} with
-this style. For example, suppose you are required to have your
-glossaries and list of acronyms in a footnote, you can do:
+Suppose each entry not only has an associated symbol,
+but also units (stored in \gloskey{user1}) and dimension
+(stored in \gloskey{user2}). Then you can define a glossary style
+that displays each entry in a \env{longtable} as follows:
 \begin{verbatim}
- \usepackage{glossary-inline}
-
- \renewcommand*{\glossarysection}[2][]{\textbf{#1}: }
- \setglossarystyle{inline}
+\newglossarystyle{long6col}{%
+ % put the glossary in a longtable environment:
+ \renewenvironment{theglossary}%
+  {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}%
+  {\end{longtable}}%
+ % Set the table's header:
+ \renewcommand*{\glossaryheader}{%
+  \bfseries Term & \bfseries Description & \bfseries Symbol &
+  \bfseries Units & \bfseries Dimensions & \bfseries Page List
+  \\\endhead}%
+ % No heading between groups:
+  \renewcommand*{\glsgroupheading}[1]{}%
+ % Main (level 0) entries displayed in a row optionally numbered:
+  \renewcommand*{\glossentry}[2]{%
+    \glsentryitem{##1}% Entry number if required
+    \glstarget{##1}{\glossentryname{##1}}% Name
+    & \glossentrydesc{##1}% Description
+    & \glossentrysymbol{##1}% Symbol
+    & \glsentryuseri{##1}% Units
+    & \glsentryuserii{##1}% Dimensions
+    & ##2% Page list
+    \tabularnewline % end of row
+  }%
+ % Similarly for sub-entries (no sub-entry numbers):
+ \renewcommand*{\subglossentry}[3]{%
+    % ignoring first argument (sub-level)
+    \glstarget{##2}{\glossentryname{##2}}% Name
+    & \glossentrydesc{##2}% Description
+    & \glossentrysymbol{##2}% Symbol
+    & \glsentryuseri{##2}% Units
+    & \glsentryuserii{##2}% Dimensions
+    & ##3% Page list
+    \tabularnewline % end of row
+  }%
+ % Nothing between groups:
+ \renewcommand*{\glsgroupskip}{}%
+}
 \end{verbatim}
+\end{example}
 
-\begin{important}
-Note that you need to include \sty{glossary-inline} with
-\cs{usepackage} as it's not automatically included by the
-\styfmt{glossaries} package and then set the style using 
-\ics{setglossarystyle}.
-\end{important}
+\chapter[Xindy (Option 3)]{Xindy (\ifpdf\opt3\else Option 3\fi)}
+\label{sec:xindy}
 
-Where you need to include your glossaries as a footnote you can do:
+If you want to use \gls{xindy} to sort the glossary, you
+must use the package option \pkgopt{xindy}:
 \begin{verbatim}
-\footnote{\printglossaries}
+\usepackage[xindy]{glossaries}
 \end{verbatim}
+This ensures that the glossary information is written in 
+\gls*{xindy} syntax.
 
-The \glostyle{inline} style is governed by the following:
-\begin{definition}[\DescribeMacro{\glsinlineseparator}]
-\ics{glsinlineseparator}
+\sectionref{sec:makeglossaries} covers how to use the external
+\gls{indexingapp}, and \sectionref{sec:locationsyntax} covers the
+issues involved in the location syntax. This section covers the
+commands provided by the \styfmt{glossaries} package that allow you
+to adjust the \gls{xindy} style file (\filetype{xdy}) and
+parameters.
+
+To assist writing information to the \gls{xindy} style
+file, the \styfmt{glossaries} package provides the following
+commands:
+\begin{definition}[\DescribeMacro{\glsopenbrace}]
+\cs{glsopenbrace}
 \end{definition}
-This defaults to \qt{\texttt{\glsinlineseparator}} and is used between
-main (i.e.\ level~0) entries.
-\begin{definition}[\DescribeMacro{\glsinlinesubseparator}]
-\ics{glsinlinesubseparator}
+\begin{definition}[\DescribeMacro{\glsclosebrace}]
+\cs{glsclosebrace}
 \end{definition}
-This defaults to \qt{\texttt{\glsinlinesubseparator}} and is used between
-sub-entries.
-\begin{definition}[\DescribeMacro{\glsinlineparentchildseparator}]
-\ics{glsinlineparentchildseparator}
+which produce an open and closing brace. (This is needed because
+\verb|\{| and \verb|\}| don't expand to a simple brace character
+when written to a file.) Similarly, you can write a percent
+character using:
+\begin{definition}[\DescribeMacro{\glspercentchar}]
+\cs{glspercentchar}
 \end{definition}
-This defaults to \qt{\texttt{\glsinlineparentchildseparator}} and is used between
-a parent main entry and its first sub-entry.
-\begin{definition}[\DescribeMacro{\glspostinline}]
-\ics{glspostinline}
+and a tilde character using:
+\begin{definition}[\DescribeMacro{\glstildechar}]
+\cs{glstildechar}
 \end{definition}
-This defaults to \qt{\texttt{\glsinlineseparator}} and is used at the end
-of the glossary.
-\begin{definition}[\DescribeMacro\glsinlinenameformat]
-\cs{glsinlinenameformat}\marg{label}\marg{name}
+For example, a newline character is specified in a \gls{xindy} style
+file using \verb|~n| so you can use \texttt{\cs{glstildechar} n}
+to write this correctly (or you can do \verb|\string~n|).
+A backslash can be written to a file using
+\begin{definition}[\DescribeMacro{\glsbackslash}]
+\cs{glsbackslash}
+\end{definition}
+
+In addition, if you are using a package that makes the double
+quote character active (e.g. \sty{ngerman}) you can use:
+\begin{definition}[\DescribeMacro{\glsquote}]
+\cs{glsquote}\marg{text}
+\end{definition}
+which will produce \verb|"|\meta{text}\verb|"|. Alternatively,
+you can use \verb|\string"| to write the double-quote character. 
+This document assumes that the double quote character has not been
+made active, so the examples just use \verb|"| for clarity.
+
+If you want greater control over the \gls{xindy} style file than is
+available through the \LaTeX\ commands provided by the
+\styfmt{glossaries} package, you will need to edit the \gls*{xindy}
+style file. In which case, you must use \ics{noist} to prevent the
+style file from being overwritten by the \styfmt{glossaries}
+package. For additional information about \gls*{xindy}, read the
+\gls*{xindy} documentation. I'm sorry I can't provide any assistance
+with writing \gls*{xindy} style files. If you need help, I recommend
+you ask on the \gls*{xindy} mailing list
+(\url{http://xindy.sourceforge.net/mailing-list.html}).
+
+\section{Language and Encodings}
+\label{sec:langenc}
+
+When you use \gls{xindy}, you need to specify the language
+and encoding used (unless you have written your own custom
+\gls*{xindy} style file that defines the relevant alphabet
+and sort rules). If you use \gls{makeglossaries},
+this information is obtained from the document's auxiliary 
+(\filetype{aux}) file.  The \gls{makeglossaries} script attempts to 
+find the root language given your document settings, but in the 
+event that it gets it wrong or if \gls*{xindy} doesn't support 
+that language, then you can specify the required language using:
+\begin{definition}[\DescribeMacro{\GlsSetXdyLanguage}]
+\cs{GlsSetXdyLanguage}\oarg{glossary type}\marg{language}
+\end{definition}
+where \meta{language} is the name of the language. The
+optional argument can be used if you have multiple glossaries
+in different languages. If \meta{glossary type} is omitted, it
+will be applied to all glossaries, otherwise the language
+setting will only be applied to the glossary given by
+\meta{glossary type}.
+
+If the \sty{inputenc} package is used, the encoding will be
+obtained from the value of \ics{inputencodingname}. 
+Alternatively, you can specify the encoding using:
+\begin{definition}[\DescribeMacro{\GlsSetXdyCodePage}]
+\cs{GlsSetXdyCodePage}\marg{code}
 \end{definition}
-This is used to format the entry name and defaults to 
-\cs{glstarget}\marg{label}\marg{name}, where \meta{name} is provided
-in the form \cs{glossentryname}\marg{label} and \meta{label} is the
-entry's label. For example, if you want the name to appear in
-\gls{smallcaps}:
+where \meta{code} is the name of the encoding. For example:
 \begin{verbatim}
-\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}}
+\GlsSetXdyCodePage{utf8}
 \end{verbatim}
-Sub-entry names are formatted according to
-\begin{definition}[\DescribeMacro\glsinlinesubnameformat]
-\cs{glsinlinesubnameformat}\marg{label}\marg{name}
-\end{definition}
-This defaults to \cs{glstarget}\marg{label}\verb|{}| so the
-sub-entry name is ignored.
 
-If the description has been suppressed (according to
-\cs{ifglsdescsuppressed}) then 
-\begin{definition}[\DescribeMacro\glsinlineemptydescformat]
-\cs{glsinlineemptydescformat}\marg{symbol}\marg{number list}
-\end{definition}
-(which defaults to nothing) is used,
-otherwise the description is formatted according to
-\begin{definition}[\DescribeMacro\glsinlinedescformat]
-\cs{glsinlinedescformat}\marg{description}\marg{symbol}\marg{number
-list}
-\end{definition}
-This defaults to just \cs{space}\meta{description} so the symbol and
-location list are ignored. If the description is missing (according
-to \cs{ifglshasdesc}), then \cs{glsinlineemptydescformat} is used
-instead.
+Note that you can also specify the language and encoding using
+the package option 
+\verb|xindy={language=|\meta{lang}\verb|,codepage=|\meta{code}\verb|}|.
+For example:
+\begin{verbatim}
+\usepackage[xindy={language=english,codepage=utf8}]{glossaries}
+\end{verbatim}
 
-For example, if you want a colon between the name and the
-description:
+If you write your own custom \gls{xindy} style file that 
+includes the language settings, you need to set the language
+to nothing:
 \begin{verbatim}
-\renewcommand*{\glsinlinedescformat}[3]{: #1}
+\GlsSetXdyLanguage{}
 \end{verbatim}
+(and remember to use \ics{noist} to prevent the style file from
+being overwritten).
 
-The sub-entry description is formatted according to:
-\begin{definition}[\DescribeMacro\glsinlinesubdescformat]
-\cs{glsinlinesubdescformat}\marg{description}\marg{symbol}\marg{number
-list}
-\end{definition}
-This defaults to just \meta{description}.
+\begin{important}
+The commands \cs{GlsSetXdyLanguage} and \cs{GlsSetXdyCodePage}
+have no effect if you don't use \gls{makeglossaries}. If
+you call \gls{xindy} without \gls*{makeglossaries} you
+need to remember to set the language and encoding using the
+\xdyopt{L} and \xdyopt{C} switches.
+\end{important}
 
-\section{Defining your own glossary style}
-\label{sec:newglossarystyle}
+\section{Locations and Number lists}
+\label{sec:xindyloc}
 
-If the predefined styles don't fit your requirements, you can
-define your own style using:
-\begin{definition}[\DescribeMacro{\newglossarystyle}]
-\cs{newglossarystyle}\marg{name}\marg{definitions}
+If you use \pkgopt{xindy}, the \styfmt{glossaries} package needs to
+know which counters you will be using in the \gls{numberlist} in order to correctly format the \gls{xindy} style
+file. Counters specified using the \pkgopt{counter} package option
+or the \meta{counter} option of \ics{newglossary} are
+automatically taken care of, but if you plan to use a different
+counter in the \gloskey[glslink]{counter} key for commands like 
+\ics{glslink}, then you need to identify these counters \emph{before} 
+\ics{makeglossaries} using:
+\begin{definition}[\DescribeMacro{\GlsAddXdyCounters}]
+\cs{GlsAddXdyCounters}\marg{counter list}
 \end{definition}
-where \meta{name} is the name of the new glossary style (to be
-used in \cs{setglossarystyle}). The second argument \meta{definitions}
-needs to redefine all of the following:
+where \meta{counter list} is a comma-separated list of counter names.
 
-\begin{definition}[\DescribeEnv{theglossary}]
-\env{theglossary}
+The most likely \ixindyattrs attributes used in the \gloskey[glslink]{format} 
+key (\locfmt{textrm}, \locfmt{hyperrm} etc) are automatically added 
+to the \gls{xindy} style file, but if you want to use another 
+attribute, you need to add it using:
+\begin{definition}[\DescribeMacro{\GlsAddXdyAttribute}]
+\cs{GlsAddXdyAttribute}\marg{name}
 \end{definition}
-This environment defines how the main body of the glossary should
-be typeset. 
+where \meta{name} is the name of the attribute, as used in
+the \gloskey[glslink]{format} key. 
 
-Note that this does not include the section heading,
-the glossary preamble (defined by \ics{glossarypreamble}) or the
-glossary postamble (defined by \ics{glossarypostamble}). For example,
-the \glostyle{list} style uses the \env{description} environment,
-so the \env{theglossary} environment is simply redefined to begin
-and end the \env{description} environment.
+Take care if you have multiple instances of the same location with
+different formats. The duplicate locations will be discarded
+according to the order in which the \ixindyattrs attributes are listed. Consider
+defining semantic commands to use for primary references. For
+example:
+\begin{verbatim}
+\newcommand*{\primary}[1]{\textbf{#1}}
+\GlsAddXdyAttribute{primary}
+\end{verbatim}
+Then in the document:
+\begin{verbatim}
+A \gls[format=primary]{duck} is an aquatic bird.
+There are lots of different types of \gls{duck}.
+\end{verbatim}
+This will give the \verb|format=primary| instance preference over
+the next use that doesn't use the \gloskey[glslink]{format} key.
 
-\begin{definition}[\DescribeMacro{\glossaryheader}]
-\cs{glossaryheader}
-\end{definition}
-This macro indicates what to do at the start of the main body
-of the glossary. Note that this is not the same as 
-\ics{glossarypreamble}, which should not be affected by changes in
-the glossary style. The \glostyle{list} glossary style redefines
-\ics{glossaryheader} to do nothing, whereas the \glostyle{longheader}
-glossary style redefines \cs{glossaryheader} to do a header row.
+\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit}
+Suppose I want a bold, italic, hyperlinked location. I first need to define a
+command that will do this:
+\begin{verbatim}
+\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
+\end{verbatim}
+but with \gls{xindy}, I also need to add this as an allowed
+\ixindyattrs attribute:
+\begin{verbatim}
+\GlsAddXdyAttribute{hyperbfit}
+\end{verbatim}
+Now I can use it in the optional argument of commands like
+\ics{gls}:
+\begin{verbatim}
+Here is a \gls[format=hyperbfit]{sample} entry.
+\end{verbatim}
+(where \texttt{sample} is the label of the required entry).
+\end{example}
 
-\begin{definition}[\DescribeMacro{\glsgroupheading}]
-\cs{glsgroupheading}\marg{label}
+\begin{important}
+Note that \cs{GlsAddXdyAttribute} has no effect if \ics{noist} is
+used or if \ics{makeglossaries} is omitted.
+\cs{GlsAddXdyAttribute} must be used before \ics{makeglossaries}.
+Additionally, \cs{GlsAddXdyCounters} must come before
+\cs{GlsAddXdyAttribute}.
+\end{important}
+
+If the location numbers include formatting commands, then
+you need to add a location style in the appropriate format using
+\begin{definition}[\DescribeMacro{\GlsAddXdyLocation}]
+\cs{GlsAddXdyLocation}\oarg{prefix-location}\marg{name}\marg{definition}
 \end{definition}
-This macro indicates
-what to do at the start of each logical block within the main body
-of the glossary. If you use \gls{makeindex} the glossary is
-sub-divided into a maximum of twenty-eight logical blocks that are
-determined by the first character of the \gloskey{sort} key (or
-\gloskey{name} key if the \gloskey{sort} key is omitted). The
-sub-divisions are in the following order: symbols, numbers, A,
-\ldots, Z\@. If you use \gls{xindy}, the sub-divisions depend on
-the language settings.
+where \meta{name} is the name of the format and \meta{definition} is
+the \gls{xindy} definition. The optional argument \meta{prefix-location}
+is needed if \cs{theH}\meta{counter} either isn't defined or is
+different from \cs{the}\meta{counter}.
+Be sure to also read \sectionref{sec:locationsyntax} for some issues
+that you may encounter.
+
+\begin{important}
+Note that \cs{GlsAddXdyLocation} has no effect if \ics{noist} is
+used or if \ics{makeglossaries} is omitted.
+\cs{GlsAddXdyLocation} must be used before \ics{makeglossaries}.
+\end{important}
+
+\begin{example}{Custom Numbering System for Locations}{ex:customloc}
+Suppose I decide to use a somewhat eccentric numbering
+system for sections where I redefine \cs{thesection} as follows:
+\begin{verbatim}
+\renewcommand*{\thesection}{[\thechapter]\arabic{section}}
+\end{verbatim}
+If I haven't done "counter=section" in the package
+option, I need to specify that the counter will be used as a
+location number:
+\begin{verbatim}
+\GlsAddXdyCounters{section}
+\end{verbatim}
+Next I need to add the location style (\cs{thechapter} is assumed to
+be the standard \verb"\arabic{chapter}"):
+\begin{verbatim}
+\GlsAddXdyLocation{section}{:sep "[" "arabic-numbers" :sep "]"
+  "arabic-numbers"
+}
+\end{verbatim}
+Note that if I have further decided to use the \sty{hyperref}
+package and want to redefine \cs{theHsection} as:
+\begin{verbatim}
+\renewcommand*{\theHsection}{\thepart.\thesection}
+\renewcommand*{\thepart}{\Roman{part}}
+\end{verbatim}
+then I need to modify the \cs{GlsAddXdyLocation} code above to:
+\begin{verbatim}
+\GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "[" 
+  "arabic-numbers" :sep "]" "arabic-numbers"
+}
+\end{verbatim}
+Since \ics{Roman} will result in an empty string if the counter is
+zero, it's a good idea to add an extra location to catch this:
+\begin{verbatim}
+\GlsAddXdyLocation{zero.section}{:sep "[" 
+  "arabic-numbers" :sep "]" "arabic-numbers"
+}
+\end{verbatim}
+This example is illustrated in the sample file
+\samplefile{xdy2}.
+\end{example}
+
+\begin{example}{Locations as Dice}{ex:dice}
+Suppose I want a rather eccentric page numbering system that's
+represented by the number of dots on dice. The \sty{stix} package
+provides \cs{dicei}, \ldots, \cs{dicevi} that represent the six
+sides of a die. I can define a command that takes a number as its
+argument. If the number is less than seven, the appropriate
+\cs{dice}\meta{n} command is used otherwise it does \cs{dicevi} the
+required number of times with the leftover in a final
+\cs{dice}\meta{n}. For example, the number 16 is represented by
+\verb|\dicevi\dicevi\diceiv| ($6+6+4=16$). I've called this command
+\cs{tallynum} to match the example given earlier in 
+\sectionref{sec:locationsyntax}:
+\begin{verbatim}
+\newrobustcmd{\tallynum}[1]{%
+ \ifnum\number#1<7
+  $\csname dice\romannumeral#1\endcsname$%
+ \else
+  $\dicevi$%
+  \expandafter\tallynum\expandafter{\numexpr#1-6}%
+ \fi
+}
+\end{verbatim}
+Here's the counter command:
+\begin{verbatim}
+newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
+\end{verbatim}
+The \ctr{page} counter representation (\cs{thepage}) needs to be
+changed to use this command:
+\begin{verbatim}
+\renewcommand*{\thepage}{\tally{page}}
+\end{verbatim}
+The \cs{tally} command expands to \cs{tallynum} \marg{number} so
+this needs a location class that matches this format:
+\begin{verbatim}
+\GlsAddXdyLocation{tally}{% 
+ :sep "\string\tallynum\space\glsopenbrace"
+ "arabic-numbers"
+ :sep "\glsclosebrace"
+}
+\end{verbatim}
+The space between \cs{tallynum} and \marg{number} is
+significant to \gls{xindy} so \cs{space} is required.
 
-Note that the argument to \cs{glsgroupheading}
-is a label \emph{not} the group title. The group title can be obtained
-via
-\begin{definition}[\DescribeMacro{\glsgetgrouptitle}]
-\cs{glsgetgrouptitle}\marg{label}
+Note that \cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define 
+commands in the form:
+\begin{definition}
+\cs{glsX}\meta{counter}"X"\meta{name}\marg{Hprefix}\marg{location}
 \end{definition}
-This obtains the title as follows: if \meta{label} consists of a
-single non-active character or \meta{label} is equal to
-\texttt{glssymbols} or \texttt{glsnumbers} and
-\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the 
-title, otherwise the title is just \meta{label}. (The \qt{symbols}
-group has the label \texttt{glssymbols}, so the command 
-\ics{glssymbolsgroupname} is used, and the \qt{numbers} group has the
-label \texttt{glsnumbers}, so the command \ics{glsnumbersgrouptitle}
-is used.) If you are using \gls{xindy}, \meta{label} may be an
-active character (for example \o), in which case the title will be
-set to just \meta{label}. You can redefine \cs{glsgetgrouptitle} if
-this is unsuitable for your document.
+for each counter that has been identified either by the
+\pkgopt{counter} package option, the \meta{counter} option for
+\ics{newglossary} or in the argument of \ics{GlsAddXdyCounters}.
+The first argument \meta{Hprefix} is only relevant when used with
+the \sty{hyperref} package and indicates that \cs{theH}\meta{counter}
+is given by \cs{Hprefix}"."\cs{the}\meta{counter}. 
 
-A navigation hypertarget can be created using
-\begin{definition}[\DescribeMacro{\glsnavhypertarget}]
-\cs{glsnavhypertarget}\marg{label}\marg{text}
-\end{definition}
-This typically requires \cs{glossaryheader} to be redefined to use
-\begin{definition}[\DescribeMacro\glsnavigation]
-\cs{glsnavigation}
-\end{definition}
-which displays the navigation line.
+The sample file \samplefile{xdy}, which comes with the \styfmt{glossaries}
+package, uses the default \ctr{page} counter for locations, and it
+uses the default \ics{glsnumberformat} and a custom \cs{hyperbfit}
+format. A new \gls{xindy} location called \texttt{tallynum}, as
+illustrated above, is defined to make the page numbers appear as
+dice. In order for the location numbers to
+hyperlink to the relevant pages, I~need to redefine the necessary
+\cs{glsX}\meta{counter}"X"\meta{format} commands:
+\begin{verbatim}
+\renewcommand{\glsXpageXglsnumberformat}[2]{%
+ \linkpagenumber#2%
+}
 
-For further details about \cs{glsnavhypertarget}, see
-\ifpdf section~\ref*{sec:code:hypernav} in \fi the documented code 
-(\texttt{glossaries-code.pdf}).
+\renewcommand{\glsXpageXhyperbfit}[2]{%
+ \textbf{\em\linkpagenumber#2}%
+}
 
-Most of the predefined glossary styles redefine \cs{glsgroupheading}
-to simply ignore its argument.  The \glostyle{listhypergroup} style
-redefines \cs{glsgroupheading} as follows:
+\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
+\end{verbatim}
+Note that the second argument of \cs{glsXpageXglsnumberformat} is
+in the format \cs{tallynum}\marg{n} so the line
 \begin{verbatim}
-\renewcommand*{\glsgroupheading}[1]{%
-\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]}
+ \linkpagenumber#2%
 \end{verbatim}
-See also \cs{glsgroupskip} below. 
-
-Note that command definitions within 
-\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc.
+does
+\begin{alltt}
+ \cs{linkpagenumber}\cs{tallynum}\marg{number}
+\end{alltt}
+so \cs{tallynum} is the first argument of \cs{linkpagenumber}
+and \meta{number} is the second argument.
+\end{example}
 
-\begin{definition}[\DescribeMacro{\glsgroupskip}]
-\cs{glsgroupskip}
-\end{definition}
-This macro determines what to do after one logical group but before
-the header for the next logical group. The \glostyle{list} glossary
-style simply redefines \cs{glsgroupskip} to be \ics{indexspace},
-whereas the tabular-like styles redefine \cs{glsgroupskip} to
-produce a blank row.
+\begin{important}
+This method is very sensitive to the internal definition of the
+location command.
+\end{important}
 
-As from version 3.03, the package option \pkgopt{nogroupskip} can be
-used to suppress this default gap for the predefined styles.
+\begin{example}{Locations as Words not Digits}{ex:fmtcount}
+Suppose I want the page numbers written as words
+rather than digits and I~use the \sty{fmtcount} package to
+do this. I~can redefine \ics{thepage} as follows:
+\begin{verbatim}
+\renewcommand*{\thepage}{\Numberstring{page}}
+\end{verbatim}
+This \emph{used} to get expanded to \verb|\protect \Numberstringnum |\marg{n}
+where \meta{n} is the Arabic page number. This means that I~needed to
+define a new location with the form:
+\begin{verbatim}
+\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
+  \string\Numberstringnum\space\glsopenbrace"
+  "arabic-numbers" :sep "\glsclosebrace"}
+\end{verbatim}
+and if I'd used the \cs{linkpagenumber} command from the previous
+example, it would need \emph{three} arguments (the first being
+\cs{protect}):
+\begin{verbatim}
+\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
+\end{verbatim}
 
-\begin{definition}[\DescribeMacro{\glossentry}]
-\cs{glossentry}\marg{label}\marg{number list}
-\end{definition}
-This macro indicates what to do for each top-level (level~0) glossary entry.
-The entry label is given by \meta{label} and the associated
-\gls{numberlist} is given by \meta{number list}. You can redefine
-\ics{glossentry} to use commands like \ics{glossentryname}\marg{label},
-\ics{glossentrydesc}\marg{label} and \ics{glossentrysymbol}\marg{label} 
-to display the name, description and symbol fields, or to access
-other fields, use commands like \ics{glsentryuseri}\marg{label}.
-(See \sectionref{sec:glsnolink} for further details.) You can also
-use the following commands:
+The internal definition of \cs{Numberstring} has since changed
+so that it now expands to \verb|\Numberstringnum |\marg{n}
+(no \cs{protect}). This means that the location class definition
+must be changed to:
+\begin{verbatim}
+\GlsAddXdyLocation{Numberstring}{% no \protect now!
+  :sep "\string\Numberstringnum\space\glsopenbrace"
+  "arabic-numbers" :sep "\glsclosebrace"}
+\end{verbatim}
+and \cs{linkpagenumber} goes back to only two arguments:
+\begin{verbatim}
+\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
+\end{verbatim}
+The other change is that \cs{Numberstring} uses
+\begin{alltt}
+\cs{the}\cs{value}\marg{counter}
+\end{alltt}
+instead of
+\begin{alltt}
+\cs{expandafter}\cs{the}\cs{csname} c@\meta{counter}\cs{endcsname}
+\end{alltt}
+so it hides \cs{c@page} from the location escaping mechanism 
+(see \sectionref{sec:locationsyntax}). This means that the page
+number may be incorrect if the indexing occurs during the output
+routine.
 
-\begin{definition}[\DescribeMacro{\glsentryitem}]
-\cs{glsentryitem}\marg{label}
-\end{definition}
-This macro will increment and display the associated counter for the
-main (level~0) entries if the \pkgopt{entrycounter} or
-\pkgopt{counterwithin} package options have been used. This macro
-is typically called by \cs{glossentry} before \cs{glstarget}. 
-The format of the counter is controlled by the macro
-\begin{definition}[\DescribeMacro{\glsentrycounterlabel}]
-\cs{glsentrycounterlabel}
-\end{definition}
+A more recent change to \sty{fmtcount} (v3.03) now puts three
+instances of \cs{expandafter} before \verb|\the\value| which
+no longer hides \cs{c@page} from the location escaping mechanism, so
+the page numbers should once more be correct. Further changes
+to the \sty{fmtcount} package may cause a problem again.
 
-Each time you use a glossary entry it creates a hyperlink (if
-hyperlinks are enabled) to the relevant line in the glossary.
-Your new glossary style must therefore redefine
-\cs{glossentry} to set the appropriate target. This
-is done using
-\begin{definition}[\DescribeMacro{\glstarget}]
-\cs{glstarget}\marg{label}\marg{text}
-\end{definition}
-where \meta{label} is the entry's label. Note that you
-don't need to worry about whether the \sty{hyperref} package has
-been loaded, as \cs{glstarget} won't create a target if
-\cs{hypertarget} hasn't been defined.
+\begin{important}
+When dealing with custom formats where the internal definitions
+are outside of your control and liable to change, it's best
+to provide a wrapper command.
+\end{important}
 
-For example, the \glostyle{list} style defines \cs{glossentry} as follows:
+Instead of directly using \cs{Numberstring} in the definition of
+\cs{thepage}, I can provide a custom command in the same form
+as the earlier \cs{tally} command:
 \begin{verbatim}
-  \renewcommand*{\glossentry}[2]{%
-    \item[\glsentryitem{##1}%
-          \glstarget{##1}{\glossentryname{##1}}]
-       \glossentrydesc{##1}\glspostdescription\space ##2}
+\newcommand{\customfmt}[1]{\customfmtnum{\arabic{#1}}}
+\newrobustcmd{\customfmtnum}[1]{\Numberstringnum{#1}}
+\end{verbatim}
+This ensures that the location will always be written to
+the indexing file in the form:
+\begin{alltt}
+:locref "\glsopenbrace\glsclosebrace\glsopenbrace\string\\customfmtnum \marg{n}\glsclosebrace"
+\end{alltt}
+So the location class can be defined as:
+\begin{verbatim}
+\GlsAddXdyLocation{customfmt}{
+ :sep "\string\customfmtnum\space\glsopenbrace"
+ "arabic-numbers" 
+ :sep "\glsclosebrace"}
 \end{verbatim}
 
-Note also that \meta{number list} will always be of the form
-\begin{definition}
-\ics{glossaryentrynumbers}\{\cs{relax}\\
-\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}\}
-\end{definition}
-where \meta{number(s)}
-may contain \ics{delimN} (to delimit individual numbers) and/or
-\ics{delimR} (to indicate a range of numbers). There may be 
-multiple occurrences of 
-\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}, but note
-that the entire number list is enclosed within the argument
-of \ics{glossaryentrynumbers}. The user can redefine this to change
-the way the entire number list is formatted, regardless of 
-the glossary style. However the most common use of
-\ics{glossaryentrynumbers} is to provide a means of suppressing the
-number list altogether. (In fact, the \pkgopt{nonumberlist} option 
-redefines \ics{glossaryentrynumbers} to ignore its argument.)
-Therefore, when you define a new glossary style, you don't need
-to worry about whether the user has specified the 
-\pkgopt{nonumberlist} package option.
+The sample file
+\samplefile{xdy3} illustrates this.
+\end{example}
+
+In the \gls{numberlist}, the locations are sorted according to the list
+of provided location classes. The default ordering is:
+\texttt{roman-page-numbers} (i, ii, \ldots), \texttt{arabic-page-numbers}
+(1, 2, \ldots), \texttt{arabic-section-numbers} (for example, 1.1 if the
+compositor is a full stop or 1-1 if the compositor is a
+hyphen\footnote{see \ics{glsSetCompositor} described in
+\sectionref{sec:setup}}), \texttt{alpha-page-numbers} (a, b, \ldots),
+\texttt{Roman-page-numbers} (I, II, \ldots), \texttt{Alpha-page-numbers}
+(A, B, \ldots), \texttt{Appendix-page-numbers} (for example, A.1 if the Alpha
+compositor is a full stop or A-1 if the Alpha compositor is a
+hyphen\footnote{see \ics{glsSetAlphaCompositor} described in
+\sectionref{sec:setup}}), user defined location names (as specified
+by \ics{GlsAddXdyLocation} in the order in which they were defined),
+and finally \texttt{see} (cross-referenced entries).\footnote{With
+\gls{glossaries-extra} \texttt{seealso} is appended to the end of
+the list.} This ordering can be changed using:
 
-\begin{definition}[\DescribeMacro{\subglossentry}]
-\cs{subglossentry}\marg{level}\marg{label}\marg{number list}
+\begin{definition}[\DescribeMacro\GlsSetXdyLocationClassOrder]
+\cs{GlsSetXdyLocationClassOrder}\marg{location names}
 \end{definition}
-This is used to display sub-entries.
-The first argument, \meta{level}, indicates the sub-entry level.
-This must be an integer from 1 (first sub-level) onwards. The
-remaining arguments are analogous to those for
-\ics{glossentry} described above.
+where each location name is delimited by double quote marks and
+separated by white space. For example:
+\begin{verbatim}
+\GlsSetXdyLocationClassOrder{
+  "arabic-page-numbers"
+  "arabic-section-numbers"
+  "roman-page-numbers"
+  "Roman-page-numbers"
+  "alpha-page-numbers"
+  "Alpha-page-numbers"
+  "Appendix-page-numbers"
+  "see"
+}
+\end{verbatim}
+(Remember to add \verb|"seealso"| if you're using
+\gls{glossaries-extra}.)
 
-\begin{definition}[\DescribeMacro{\glssubentryitem}]
-\cs{glssubentryitem}\marg{label}
-\end{definition}
-This macro will increment and display the associated counter for the
-level~1 entries if the \pkgopt{subentrycounter} package option has
-been used. This macro is typically called by \cs{subglossentry}
-before \ics{glstarget}. The format of the counter is controlled by
-the macro
-\begin{definition}[\DescribeMacro{\glssubentrycounterlabel}]
-\cs{glssubentrycounterlabel}
-\end{definition}
+\begin{important}
+Note that \cs{GlsSetXdyLocationClassOrder} has no effect if 
+\ics{noist} is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyLocationClassOrder} must be used before 
+\ics{makeglossaries}.
+\end{important}
 
-Note that \ics{printglossary} (which \ics{printglossaries} calls)
-sets
-\begin{definition}[\DescribeMacro{\currentglossary}]
-\cs{currentglossary}
-\end{definition}
-to the current glossary label, so it's possible to create a glossary
-style that varies according to the glossary type.
+If a \gls{numberlist} consists of a sequence of consecutive 
+numbers, the range will be concatenated. The 
+number of consecutive locations that causes a range formation 
+defaults to 2, but can be changed using:
 
-For further details of these commands, see \ifpdf
-section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary}
-in the documented code (\texttt{glossaries-code.pdf}).
+\begin{definition}[\DescribeMacro\GlsSetXdyMinRangeLength]
+\cs{GlsSetXdyMinRangeLength}\marg{n}
+\end{definition}
+For example:
+\begin{verbatim}
+\GlsSetXdyMinRangeLength{3}
+\end{verbatim}
+The argument may also be the keyword \texttt{none}, to indicate that
+there should be no range formations. See the \gls{xindy}
+manual for further details on range formations.
 
-\begin{example}{Creating a completely new style}{sec:exnewstyle}
+\begin{important}
+Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist}
+is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyMinRangeLength} must be used before 
+\ics{makeglossaries}.
+\end{important}
+See also \sectionref{sec:ranges}.
 
-If you want a completely new style, you will need to redefine all
-of the commands and the environment listed above. 
+\section{Glossary Groups}
+\label{sec:groups}
 
-For example, suppose you want each entry to start with a bullet point.
-This means that the glossary should be placed in the \env{itemize}
-environment, so \env{theglossary} should start and end that
-environment. Let's also suppose that you don't want anything between
-the glossary groups (so \ics{glsgroupheading} and \ics{glsgroupskip}
-should do nothing) and suppose you don't want anything to appear
-immediately after \verb|\begin{theglossary}| (so \ics{glossaryheader}
-should do nothing). In addition, let's suppose the symbol should
-appear in brackets after the name, followed by the description and
-last of all the \gls{numberlist} should appear within square brackets
-at the end. Then you can create this new glossary style, called, say,
-\texttt{mylist}, as follows:
+The glossary is divided into groups according to the first
+letter of the sort key. The \styfmt{glossaries} package also adds
+a number group by default, unless you suppress it in the
+\pkgopt{xindy} package option. For example:
 \begin{verbatim}
- \newglossarystyle{mylist}{%
- % put the glossary in the itemize environment:
- \renewenvironment{theglossary}%
-   {\begin{itemize}}{\end{itemize}}%
- % have nothing after \begin{theglossary}:
- \renewcommand*{\glossaryheader}{}%
- % have nothing between glossary groups:
- \renewcommand*{\glsgroupheading}[1]{}%
- \renewcommand*{\glsgroupskip}{}%
- % set how each entry should appear:
- \renewcommand*{\glossentry}[2]{%
- \item % bullet point
- \glstarget{##1}{\glossentryname{##1}}% the entry name
- \space (\glossentrysymbol{##1})% the symbol in brackets
- \space \glossentrydesc{##1}% the description
- \space [##2]% the number list in square brackets
- }%
- % set how sub-entries appear:
- \renewcommand*{\subglossentry}[3]{%
-   \glossentry{##2}{##3}}%
- }
+\usepackage[xindy={glsnumbers=false}]{glossaries}
 \end{verbatim}
-Note that this style creates a flat glossary, where sub-entries
-are displayed in exactly the same way as the top level entries.
-It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so
-it won't be affected by the \pkgopt{entrycounter},
-\pkgopt{counterwithin} or \pkgopt{subentrycounter} package options.
-
-Variations:
-\begin{itemize}
-\item You might want the entry name to be capitalised, in
-which case use \ics{Glossentryname} instead of \ics{glossentryname}.
-
-\item You might want to check if the symbol hasn't been set and omit
-the parentheses if the symbol is absent. In this case you can use
-\ics{ifglshassymbol} (see \sectionref{sec:utilities}):
+Any entry that doesn't go in one of the letter groups or the
+number group is placed in the default group. If you want \gls{xindy}
+to sort the number group numerically (rather than by a string sort)
+then you need to use \gls{xindy}['s] \texttt{numeric-sort} module:
 \begin{verbatim}
- \renewcommand*{\glossentry}[2]{%
- \item % bullet point
- \glstarget{##1}{\glossentryname{##1}}% the entry name
- \ifglshassymbol{##1}% check if symbol exists
- {%
-   \space (\glossentrysymbol{##1})% the symbol in brackets
- }%
- {}% no symbol so do nothing
- \space \glossentrydesc{##1}% the description
- \space [##2]% the number list in square brackets
- }%
+\GlsAddXdyStyle{numeric-sort}
 \end{verbatim}
-\end{itemize}
-\end{example}
 
-\begin{example}{Creating a new glossary style based on an
-existing style}{sec:exadaptstyle}
+If you don't use \texttt{glsnumbers=false}, the default behaviour is to locate
+the number group before the \qt{A} letter group. If you are not using a
+Roman alphabet, you need to change this using:
 
-If you want to define a new style that is a slightly modified
-version of an existing style, you can use \ics{setglossarystyle}
-within the second argument of \ics{newglossarystyle} followed by
-whatever alterations you require. For example, suppose you want 
-a style like the \glostyle{list} style but you don't want the extra
-vertical space created by \ics{indexspace} between groups, then you
-can create a new glossary style called, say, \texttt{mylist} as
-follows:
-\begin{verbatim}
-\newglossarystyle{mylist}{%
-\setglossarystyle{list}% base this style on the list style
-\renewcommand{\glsgroupskip}{}% make nothing happen 
-                              % between groups
-}
-\end{verbatim} 
-(In this case, you can actually achieve the same effect using the
-\glostyle{list} style in combination with the package option
-\pkgopt{nogroupskip}.)
-\end{example}
 
-\begin{example}{Example: creating a glossary style that uses the
-\texorpdfstring{\gloskey{user1}}{user1}, \ldots, 
-\texorpdfstring{\gloskey{user6}}{user6} keys}{sec:exuserstyle}
+\begin{definition}[\DescribeMacro\GlsSetXdyFirstLetterAfterDigits]
+\cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter}
+\end{definition}
+where \meta{letter} is the first letter of your alphabet. Take care
+if you're using \sty{inputenc} as non-ASCII characters are actually
+active characters that expand. (This isn't a problem with the native
+\gls{UTF-8} engines and \sty{fontspec}.) The starred form will sanitize
+the argument to prevent expansion.
+Alternatively you can use:
 
-Suppose each entry not only has an associated symbol,
-but also units (stored in \gloskey{user1}) and dimension
-(stored in \gloskey{user2}). Then you can define a glossary style
-that displays each entry in a \env{longtable} as follows:
+
+\begin{definition}[\DescribeMacro\GlsSetXdyNumberGroupOrder]
+\cs{GlsSetXdyNumberGroupOrder}\marg{relative location}
+\end{definition}
+to change the default
+\begin{alltt}
+:before \cs{string}"\meta{letter}\cs{string}"
+\end{alltt}
+to \meta{relative location}. For example:
 \begin{verbatim}
-\newglossarystyle{long6col}{%
- % put the glossary in a longtable environment:
- \renewenvironment{theglossary}%
-  {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}%
-  {\end{longtable}}%
- % Set the table's header:
- \renewcommand*{\glossaryheader}{%
-  \bfseries Term & \bfseries Description & \bfseries Symbol &
-  \bfseries Units & \bfseries Dimensions & \bfseries Page List
-  \\\endhead}%
- % No heading between groups:
-  \renewcommand*{\glsgroupheading}[1]{}%
- % Main (level 0) entries displayed in a row optionally numbered:
-  \renewcommand*{\glossentry}[2]{%
-    \glsentryitem{##1}% Entry number if required
-    \glstarget{##1}{\glossentryname{##1}}% Name
-    & \glossentrydesc{##1}% Description
-    & \glossentrysymbol{##1}% Symbol
-    & \glsentryuseri{##1}% Units
-    & \glsentryuserii{##1}% Dimensions
-    & ##2% Page list
-    \tabularnewline % end of row
-  }%
- % Similarly for sub-entries (no sub-entry numbers):
- \renewcommand*{\subglossentry}[3]{%
-    % ignoring first argument (sub-level)
-    \glstarget{##2}{\glossentryname{##2}}% Name
-    & \glossentrydesc{##2}% Description
-    & \glossentrysymbol{##2}% Symbol
-    & \glsentryuseri{##2}% Units
-    & \glsentryuserii{##2}% Dimensions
-    & ##3% Page list
-    \tabularnewline % end of row
-  }%
- % Nothing between groups:
- \renewcommand*{\glsgroupskip}{}%
-}
+\GlsSetXdyNumberGroupOrder{:after \string"Z\string"}
 \end{verbatim}
-\end{example}
+will put the number group after the \qt{Z} letter group.
+Again take care of active characters. There's a starred version
+that sanitizes the argument (so don't use \cs{string} in it).
+\begin{alltt}
+\cs{GlsSetXdyNumberGroupOrder}*\{:after "\"O"\}
+\end{alltt}
+
+\begin{important}
+Note that these commands have no effect if 
+\ics{noist} is used or if \ics{makeglossaries} is omitted.
+\cs{GlsSetXdyFirstLetterAfterDigits} must be used before 
+\ics{makeglossaries}.\par
+\end{important}
+
 
 \chapter{Utilities}
 \label{sec:utilities}
@@ -13375,6 +13785,12 @@ option). This command doesn't have an optional argument. If you want
 to explicitly say which lists to iterate over, just use the optional
 argument of \cs{forallglossaries}.
 
+\begin{xtr}
+The \gls{glossaries-extra}
+package provides an analogous command
+\ics*{forallabbreviationlists}.
+\end{xtr}
+
 \begin{definition}[\DescribeMacro{\forglsentries}]
 \cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body}
 \end{definition}
@@ -13474,7 +13890,14 @@ part}}
 \end{definition}
 This checks if the glossary entry given by \meta{label} has any
 sub-entries. If it does, \meta{true part} is performed, otherwise
-\meta{false part}.
+\meta{false part}. This uses an inefficient method since this
+information isn't stored.
+
+\begin{bib2gls}
+If you use \gls{bib2gls}, a more efficient method is to use the
+\resourceopt{save-child-count} resource option and test the value of
+the \field{childcount} field.
+\end{bib2gls}
 
 \begin{definition}[\DescribeMacro{\ifglshasparent}]
 \cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false
@@ -14314,7 +14737,7 @@ The \gls{glossaries-extra} package and \gls{bib2gls}
 provide some additional sample files. There are also examples in the
 \gallery{}{Dickimaw Books Gallery}.
 
-If you prefer to use UTF-8 aware engines (\texttt{xelatex} or
+If you prefer to use \gls{UTF-8} aware engines (\texttt{xelatex} or
 \texttt{lualatex}) remember that you'll need to switch from
 \styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where
 appropriate.
@@ -18272,7 +18695,7 @@ also the earlier \samplefile{Sec}.
 \exitem{utf8} This is another example
 that uses \gls{xindy}. Unlike \gls{makeindex},
 \gls{xindy} can cope with \glspl{nonlatinchar}. This
-document uses UTF-8 encoding. To create the document do:
+document uses \gls{UTF-8} encoding. To create the document do:
 \begin{prompt}
 pdflatex sampleutf8
 makeglossaries sampleutf8
@@ -19214,10 +19637,10 @@ If you have any problems, please first consult the
 \urlfootref{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ}. If that
 doesn't help, try posting your query to somewhere like the
 \texttt{comp.text.tex} newsgroup, the 
-\urlfootref{http://www.latex-community.org/}{\LaTeX\ Community Forum} or 
-\urlfootref{http://tex.stackexchange.com/}{\TeX\ on StackExchange}. 
+\urlfootref{https://latex.org/forum/}{\LaTeX\ Community Forum} or 
+\urlfootref{https://tex.stackexchange.com/}{\TeX\ on StackExchange}. 
 Bug reports can be submitted via 
-\urlfootref{http://www.dickimaw-books.com/bug-report.html}{my package bug report form}. 
+\urlfootref{https://www.dickimaw-books.com/bug-report.html}{my package bug report form}. 
 
 \PrintIndex
 
-- 
cgit v1.2.3

