summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-02-15 03:01:17 +0000
committerNorbert Preining <norbert@preining.info>2020-02-15 03:01:17 +0000
commit6e362e815ea119b3f6db97b21c10fee3279b5c6b (patch)
tree536b6a92aa0abbc06d83b0b03850caeebf82d65e /macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
parentdc072b1cb0427be056e747cdbfd6b7a4f1e02e56 (diff)
CTAN sync 202002150301
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex2526
1 files changed, 1471 insertions, 1055 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
index 674b704722..28bd4c59a5 100644
--- a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
+++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
@@ -1,4 +1,4 @@
-\documentclass[report,inlinetitle,widecs]{nlctdoc}
+\documentclass[report,inlinetitle,noprint]{nlctdoc}
\makeatletter
\@ifpackageloaded{tex4ht}
@@ -225,13 +225,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.41:
+ \title{glossaries-extra.sty v1.42:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2019-04-09}
+ \date{2020-02-13}
\maketitle
\begin{abstract}
@@ -241,7 +241,7 @@ Some of the features provided by this package are only available
with \styfmt{glossaries} version 4.19 (or above).
This document assumes familiarity with the \styfmt{glossaries} package.
-The file \texttt{example-glossaries-xr.tex} contains dummy
+The file \nolinkurl{example-glossaries-xr.tex} contains dummy
entries with cross-references that may be used for creating
minimal working examples for testing the \styfmt{glossaries-extra}
package. (The base \styfmt{glossaries} package provides additional files,
@@ -611,9 +611,17 @@ missing. (With \gls{bib2gls} you can instead redefine
location prefixes with \texttt{loc-prefix} which will only
apply if the entry has a \gls{numberlist}.)
-\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp}
+\item[{\pkgoptdef{prefix}}] Load the \sty{glossaries-prefix}
package (if not already loaded).
+\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp}
+package (if not already loaded).
+
+\begin{important}
+The \sty{glossaries-accsupp} package is still experimental and so
+accessibility features are liable to change.
+\end{important}
+
If you want to define styles that can interface with the
accessibility support provided by \sty{glossaries-accsupp} use
the \cs{glsaccess\meta{xxx}} type of commands instead of
@@ -1009,7 +1017,9 @@ file or files.
be cancelled. If used,
it will automatically create a new glossary with the label
\texttt{abbreviations} and redefines \cs{glsxtrabbrvtype} to this
-label. In addition, it defines a shortcut command
+label. (The file extensions are \filetype{glg-abr},
+\filetype{gls-abr} and \filetype{glo-abr}.)
+In addition, this option defines a shortcut command
\begin{definition}[\DescribeMacro\printabbreviations]
\cs{printabbreviations}\oarg{options}
\end{definition}
@@ -1180,6 +1190,8 @@ after \ics{makenoidxglossaries}.
\chapter{Modifications to Existing Commands and Styles}
\label{sec:modifications}
+\section{Defining Entries}
+
The \styfmt{glossaries} package provides \ics{nopostdesc}
which may be used in the \gloskey{description} to suppress
the post-description hook. The \styfmt{glossaries-extra} package
@@ -1202,95 +1214,10 @@ These commands have no effect outside of the glossary (except with
standalone entries that use \cs{glsxtractivatenopost} and
\cs{glspostdescription}, see \sectionref{sec:glossentry}).
-The \styfmt{glossaries} package provides
-\begin{definition}[\DescribeMacro\glsseeitemformat]
-\cs{glsseeitemformat}\marg{label}
-\end{definition}
-to format items in a cross-reference list (identified with the
-\gloskey{see} key or \cs{glssee}). This was originally defined to
-use \cs{glsentryname}\marg{label} since it makes more sense for the
-cross-reference to match the way the term appears in the glossary.
-Unfortunately this caused a problem when the \gloskey{name} field
-was sanitized, which used to be the default setting, so
-\styfmt{glossaries} v3.0 changed the default definition of this
-command to use \cs{glsentrytext} instead. Since the \gloskey{name}
-and \gloskey{text} field are quite often the same, this change
-usually doesn't have a noticeable effect. However, now that the
-\gloskey{name} field is no longer sanitized (following the redesign
-of \styfmt{glossaries} v4.0) it makes more sense to restore this
-command to its original behaviour, but to take account of
-abbreviations \styfmt{glossaries-extra} redefines this as:
-\begin{verbatim}
-\renewcommand*{\glsseeitemformat}[1]{%
- \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}%
-}
-\end{verbatim}
-If you want to restore the \styfmt{glossaries} v3.0+ definition just do:
-\begin{verbatim}
-\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}}
-\end{verbatim}
-The \sty{glossaries-extra} package provides \ics{glsxtrhiername}
-and its case-changing variants that may be used within
-the definition of \cs{glsseeitemformat} if required. These
-display the hierarchy for sub-entries rather than just the name,
-which may be more helpful in cross-references. See
-\sectionref{sec:see} for further details.
-
The commands used by \styfmt{glossaries} to automatically produce an
error if an entry is undefined (such as \ics{glsdoifexists}) are
changed to take the \pkgopt{undefaction} option into account.
-The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
-version that doesn't automatically switch off the hyperlinks.
-This starred version may be used with the \catattr{targeturl}
-attribute to create a link to an external URL. (See
-\sectionref{sec:categories} for further details.)
-As from v1.12 both the starred and unstarred version check
-that the glossary doesn't already exist. (The \styfmt{glossaries}
-package omits this check.)
-
-You can now provide an ignored glossary with:
-\begin{definition}[\DescribeMacro\provideignoredglossary]
-\cs{provideignoredglossary}\marg{type}
-\end{definition}
-which will only define the glossary if it doesn't already exist.
-This also has a starred version that doesn't automatically switch
-off hyperlinks.
-
-The individual glossary displaying commands \ics{printglossary},
-\ics{printnoidxglossary} and \cs{printunsrtglossary} have two extra
-keys:
-
-\begin{itemize}
-\item \gloskey[printglossary]{target}. This is a boolean key which can
-be used to switch off the automatic hypertarget for each entry.
-Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so
-any cross-references within the glossary won't be affected. This is
-a way of avoiding duplicate target warnings if a glossary needs to
-be displayed multiple times.
-\item
-\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way
-of avoiding duplicate target names is to set a prefix
-used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect
-any hyperlinks (such as those created with \cs{gls}).
-\item
-\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do
-actually want to locally change \cs{glolinkprefix}, you can use
-the \gloskey{prefix} key instead. You need to use the matching
-\gloskey[glslink]{prefix} key in commands like \cs{gls}.
-
-\item
-\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels
-the glossary with \texttt{\cs{label}\marg{label}} and also
-defines \cs{@currentlabelname} to the glossary's TOC title
-(to provide text for \cs{nameref}). You can also set the
-label before the glossary using:
-\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel]
-\cs{glsxtrsetglossarylabel}\marg{label}
-\end{definition}
-but take care of duplicate labels if it's not scoped.
-\end{itemize}
-
The \cs{newglossaryentry} command has three new keys:
\begin{itemize}
\item \gloskey{category}, which sets the category label for the given
@@ -1303,11 +1230,14 @@ entry. See \sectionref{sec:alias} for further details.
allows for separate \qt{see} and \qt{see also} treatment.
See \sectionref{sec:see} for further details.
\end{itemize}
-The test file \texttt{example-glossaries-xr.tex} contains
+This apply to all entry defining commands (such as
+\cs{newabbreviation}).
+
+The test file \nolinkurl{example-glossaries-xr.tex} contains
dummy entries with a mixture of \gloskey{see}, \gloskey{alias}
and \gloskey{seealso} keys for use with minimal working examples.
-There are also \texttt{example-glossaries-*.bib} files that
-correspond to each \texttt{example-glossaries-*.tex} file
+There are also \nolinkurl{example-glossaries-*.bib} files that
+correspond to each \nolinkurl{example-glossaries-*.tex} file
for testing \gls{bib2gls}.
The \cs{longnewglossaryentry} command now has a starred version
@@ -1444,6 +1374,7 @@ equivalent to:
\cs{GlsXtrAutoAddOnFormat} is not applied to \cs{glsadd}
as it could cause an infinite loop.
\end{important}
+
The \styfmt{glossaries-extra} package provides extra keys for
commands like \cs{gls} and \cs{glstext}:
\begin{description}
@@ -1491,8 +1422,8 @@ which is defined as:
}
\end{verbatim}
This sets the conditional
-\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore]
-\cs{ifglsxtrinitwrgloss}
+\begin{definition}
+\ics{ifglsxtrinitwrgloss}
\end{definition}
which is used to determine where to perform the indexing.
@@ -1555,6 +1486,77 @@ hyperlink location (see below).
\end{description}
+You can set the default options used by \ics{glslink}, \ics{gls}
+etc with:
+\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts]
+\cs{GlsXtrSetDefaultGlsOpts}\marg{options}
+\end{definition}
+For example, if you mostly don't want to index entries then
+you can do:
+\begin{verbatim}
+\GlsXtrSetDefaultGlsOpts{noindex}
+\end{verbatim}
+and then use, for example, \verb|\gls[noindex=false]{sample}|
+when you actually want the location added to the \gls{numberlist}.
+These defaults may be overridden by other settings (such as
+category attributes) in addition to any settings passed in the
+option argument of commands like \cs{glslink} and \cs{gls}.
+
+Note that if you don't want \emph{any} indexing, just omit
+\cs{makeglossaries} and \cs{printglossaries} (or analogous
+commands). If you want to adjust the default for
+\gloskey[glslink]{wrgloss}, it's better to do this by redefining
+\ics{glsxtrinitwrgloss} instead.
+
+\begin{important}
+\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}.
+\end{important}
+
+If you want to change the default value of \gloskey[glsadd]{format},
+you can instead use:
+\begin{definition}[\GlsXtrSetDefaultNumberFormat]
+\cs{GlsXtrSetDefaultNumberFormat}\marg{format}
+\end{definition}
+This has the advantage of also working for \cs{glsadd}.
+For example, if you want all locations in the back matter to appear
+in italic (unless explicitly overridden):
+\begin{verbatim}
+\backmatter
+\GlsXtrSetDefaultNumberFormat{hyperit}
+\end{verbatim}
+
+Commands like \ics{gls} have star (\texttt{*}) and plus
+(\texttt{+}) modifiers as a short cut for \texttt{hyper=false}
+and \texttt{hyper=true}. The \styfmt{glossaries-extra} package
+provides a way to add a third modifier, if required, using
+\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier]
+\cs{GlsXtrSetAltModifier}\marg{char}\marg{options}
+\end{definition}
+where \meta{char} is the character used as the modifier and
+\meta{options} is the default set of options (which may be
+overridden). Note that \meta{char} must be a single character
+(not a UTF-8 character, unless you are using \XeLaTeX\ or
+\LuaLaTeX).
+
+\begin{important}
+When choosing the character \meta{char} take care of any
+changes in category code.
+\end{important}
+
+Example:
+\begin{verbatim}
+\GlsXtrSetAltModifier{!}{noindex}
+\end{verbatim}
+This means that \verb|\gls!{sample}| will be equivalent to
+\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers.
+For example, if you want to do
+\begin{verbatim}
+\gls[noindex,hyper=false]{sample}
+\end{verbatim}
+you can use \verb|\gls*[noindex]{sample}| or
+\verb|\gls![hyper=false]{sample}| but you can't combine the
+\texttt{*} and \texttt{!} modifiers.
+
There is a new hook that's used each time indexing information is
written to the external glossary files:
\begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook]
@@ -1813,7 +1815,44 @@ sub-entries. For example:
\renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}}
\end{verbatim}
-The command:
+The \styfmt{glossaries} package provides
+\begin{definition}[\DescribeMacro\glsseeitemformat]
+\cs{glsseeitemformat}\marg{label}
+\end{definition}
+to format items in a cross-reference list (identified with the
+\gloskey{see} key or \cs{glssee}). This was originally defined to
+use \cs{glsentryname}\marg{label} since it makes more sense for the
+cross-reference to match the way the term appears in the glossary.
+Unfortunately this caused a problem when the \gloskey{name} field
+was sanitized, which used to be the default setting, so
+\styfmt{glossaries} v3.0 changed the default definition of this
+command to use \cs{glsentrytext} instead. Since the \gloskey{name}
+and \gloskey{text} field are quite often the same, this change
+usually doesn't have a noticeable effect. However, now that the
+\gloskey{name} field is no longer sanitized (following the redesign
+of \styfmt{glossaries} v4.0) it makes more sense to restore this
+command to its original behaviour, but to take account of
+abbreviations \styfmt{glossaries-extra} redefines this as:
+\begin{verbatim}
+\renewcommand*{\glsseeitemformat}[1]{%
+ \ifglshasshort{\glslabel}{\glsfmttext{#1}}{\glsfmtname{#1}}%
+}
+\end{verbatim}
+(Note that as from \styfmt{glossaries-extra} version 1.42, this now
+uses \cs{glsfmttext} and \cs{glsfmtname} instead of just referencing
+the \gloskey{text} and \gloskey{name} fields. This helps to ensure
+that any formatting is correctly applied.)
+
+If you want to restore the \styfmt{glossaries} v3.0+ definition just do:
+\begin{verbatim}
+\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}}
+\end{verbatim}
+
+The \sty{glossaries-extra} package provides \ics{glsxtrhiername}
+and its case-changing variants that may be used within
+the definition of \cs{glsseeitemformat} if required. These
+display the hierarchy for sub-entries rather than just the name,
+which may be more helpful in cross-references.
\begin{definition}[\DescribeMacro\glsxtrhiername]
\cs{glsxtrhiername}\marg{label}
\end{definition}
@@ -1824,8 +1863,8 @@ performs a recursive action:
\cs{glsxtrhiernamesep} then:
\item If the entry given by \meta{label} is an abbreviation
(that is, it has the \gloskey{short} field set) then
-the short form is displayed (using \cs{glsaccessshort})
-otherwise the name is displayed (using \cs{glsaccessname}).
+the short form is displayed (using \cs{glsfmtshort})
+otherwise the name is displayed (using \cs{glsfmtname}).
\end{enumerate}
The first step above is skipped if the entry doesn't have a parent.
Each level is separated by:
@@ -1840,27 +1879,27 @@ There are some case-changing variants:
\cs{Glsxtrhiername}\marg{label}
\end{definition}
The top-level has the first letter changed to upper case
-(either \cs{Glsaccessshort} or \cs{Glsaccessname}). There's
+(either \cs{Glsfmtshort} or \cs{Glsfmtname}). There's
no case-change for sub-entries.
\begin{definition}[\DescribeMacro\GlsXtrhiername]
\cs{GlsXtrhiername}\marg{label}
\end{definition}
All levels have the first letter changed to upper case
-(either \cs{Glsaccessshort} or \cs{Glsaccessname}).
+(either \cs{Glsfmtshort} or \cs{Glsfmtname}).
\begin{definition}[\DescribeMacro\GLSxtrhiername]
\cs{GLSxtrhiername}\marg{label}
\end{definition}
The top-level is converted to upper case
-(either \cs{GLSaccessshort} or \cs{GLSaccessname}). There's
+(either \cs{GLSfmtshort} or \cs{GLSfmtname}). There's
no case-change for sub-entries.
\begin{definition}[\DescribeMacro\GLSXTRhiername]
\cs{GLSXTRhiername}\marg{label}
\end{definition}
All levels are converted to upper case
-(either \cs{GLSaccessshort} or \cs{GLSaccessname}).
+(either \cs{GLSfmtshort} or \cs{GLSfmtname}).
Suppose you want to suppress the \gls*{numberlist}
using \pkgopt{nonumberlist}. This will automatically prevent the
@@ -1912,6 +1951,13 @@ For example:
}
\end{verbatim}
+The \gloskey{alias} key only contains a single label not a list, but
+if you want to ensure consistent formatting with \cs{glsxtrusesee}
+and \cs{glsxtruseseealso} you can use (from v1.42):
+\begin{definition}[\DescribeMacro\glsxtrusealias]
+\cs{glsxtrusealias}\marg{label}
+\end{definition}
+
The actual unformatted comma-separated list \meta{xr-list}
stored in the \gloskey{seealso} field can be accessed with:
\begin{definition}[\DescribeMacro\glsxtrseealsolabels]
@@ -1946,6 +1992,21 @@ unless the \pkgopt{xindy} option is used with \sty{glossaries}
v4.30+, in which case a distinct \texttt{seealso} cross-reference
class is used instead.
+The command that produces this \qt{see also} text is
+\begin{definition}[\DescribeMacro\seealsoname]
+\cs{seealsoname}
+\end{definition}
+If \ics{alsoname} (provided by language packages) is defined then
+\cs{seealsoname} will simply be defined to \cs{alsoname} otherwise
+it will be defined to \texttt{see also}.
+
+The language-sensitive \cs{alsoname} is used by general indexing
+packages, such as \sty{makeidx}, so if you redefine \cs{alsoname}
+the change will apply to normal indexes as well as glossaries. If
+you only want to change the text produced by the \gloskey{seealso}
+key without affecting general indexing (with \cs{index}) then
+redefine \cs{seealsoname} instead.
+
\section{Entry Display Style Modifications}
\label{sec:entryfmtmods}
@@ -1959,8 +2020,9 @@ depends on the command used (such as \cs{gls}) and the entry format.
The default entry format (\ics{glsentryfmt}) used in the
\gls{linktext} by commands like \ics{gls}, \ics{glsxtrfull},
\ics{glsxtrshort} and \ics{glsxtrlong} (but not commands like
-\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by \styfmt{glossaries-extra} to test for
-regular entries, which are determined as follows:
+\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by
+\styfmt{glossaries-extra} to test for regular entries, which are
+determined as follows:
\begin{itemize}
\item If an entry is assigned to a category that has the
@@ -2178,141 +2240,6 @@ The \abbrstyle{short-postfootnote} abbreviation style uses the
post-\gls{linktext} hook to
place the footnote after trailing punctuation characters.
-You can set the default options used by \ics{glslink}, \ics{gls}
-etc with:
-\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts]
-\cs{GlsXtrSetDefaultGlsOpts}\marg{options}
-\end{definition}
-For example, if you mostly don't want to index entries then
-you can do:
-\begin{verbatim}
-\GlsXtrSetDefaultGlsOpts{noindex}
-\end{verbatim}
-and then use, for example, \verb|\gls[noindex=false]{sample}|
-when you actually want the location added to the \gls{numberlist}.
-These defaults may be overridden by other settings (such as
-category attributes) in addition to any settings passed in the
-option argument of commands like \cs{glslink} and \cs{gls}.
-
-Note that if you don't want \emph{any} indexing, just omit
-\cs{makeglossaries} and \cs{printglossaries} (or analogous
-commands). If you want to adjust the default for
-\gloskey[glslink]{wrgloss}, it's better to do this by redefining
-\ics{glsxtrinitwrgloss} instead.
-
-\begin{important}
-\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}.
-\end{important}
-
-If you want to change the default value of \gloskey[glsadd]{format},
-you can instead use:
-\begin{definition}[\GlsXtrSetDefaultNumberFormat]
-\cs{GlsXtrSetDefaultNumberFormat}\marg{format}
-\end{definition}
-This has the advantage of also working for \cs{glsadd}.
-For example, if you want all locations in the back matter to appear
-in italic (unless explicitly overridden):
-\begin{verbatim}
-\backmatter
-\GlsXtrSetDefaultNumberFormat{hyperit}
-\end{verbatim}
-
-Commands like \ics{gls} have star (\texttt{*}) and plus
-(\texttt{+}) modifiers as a short cut for \texttt{hyper=false}
-and \texttt{hyper=true}. The \styfmt{glossaries-extra} package
-provides a way to add a third modifier, if required, using
-\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier]
-\cs{GlsXtrSetAltModifier}\marg{char}\marg{options}
-\end{definition}
-where \meta{char} is the character used as the modifier and
-\meta{options} is the default set of options (which may be
-overridden). Note that \meta{char} must be a single character
-(not a UTF-8 character, unless you are using \XeLaTeX\ or
-\LuaLaTeX).
-
-\begin{important}
-When choosing the character \meta{char} take care of any
-changes in category code.
-\end{important}
-
-Example:
-\begin{verbatim}
-\GlsXtrSetAltModifier{!}{noindex}
-\end{verbatim}
-This means that \verb|\gls!{sample}| will be equivalent to
-\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers.
-For example, if you want to do
-\begin{verbatim}
-\gls[noindex,hyper=false]{sample}
-\end{verbatim}
-you can use \verb|\gls*[noindex]{sample}| or
-\verb|\gls![hyper=false]{sample}| but you can't combine the
-\texttt{*} and \texttt{!} modifiers.
-
-\Glspl{locationlist} displayed with \cs{printnoidxglossary}
-internally use
-\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
-\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
-\end{definition}
-This command is provided by \styfmt{glossaries}, but is modified by
-\styfmt{glossaries-extra} to check for the start and end range
-formation identifiers \verb|(| and \verb|)| which are discarded to
-obtain the actual control sequence name that forms the location
-formatting command.
-
-If the range identifiers aren't present, this just uses
-\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc]
-\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
-\end{definition}
-otherwise it uses
-\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc]
-\cs{glsxtrdisplaystartloc}\marg{format}\marg{location}
-\end{definition}
-for the start of a range (where the identifier has been stripped
-from \meta{format}) or
-\begin{definition}[\DescribeMacro\glsxtrdisplayendloc]
-\cs{glsxtrdisplayendloc}\marg{format}\marg{location}
-\end{definition}
-for the end of a range (where the identifier has been stripped
-from \meta{format}).
-
-By default the start range command saves the format in
-\begin{definition}[\DescribeMacro\glsxtrlocrangefmt]
-\cs{glsxtrlocrangefmt}
-\end{definition}
-and does
-\begin{display}
-\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
-\end{display}
-(If the format is empty, it will be replaced with
-\texttt{glsnumberformat}.)
-
-The end command checks that the format matches the start of the
-range, does
-\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook]
-\cs{glsxtrdisplayendlochook}\marg{format}\marg{location}
-\end{definition}
-(which does nothing by default), followed by
-\begin{display}
-\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
-\end{display}
-and then sets \cs{glsxtrlocrangefmt} to empty.
-
-This means that the list
-\begin{verbatim}
-\glsnoidxdisplayloc{}{page}{(textbf}{1},
-\glsnoidxdisplayloc{}{page}{textbf}{1},
-\glsnoidxdisplayloc{}{page}{)textbf}{1}.
-\end{verbatim}
-doesn't display any differently from
-\begin{verbatim}
-\glsnoidxdisplayloc{}{page}{textbf}{1},
-\glsnoidxdisplayloc{}{page}{textbf}{1},
-\glsnoidxdisplayloc{}{page}{textbf}{1}.
-\end{verbatim}
-but it does make it easier to define your own custom list handler
-that can accommodate the ranges.
-
\section{Entry Counting Modifications}
\label{sec:entrycountmods}
@@ -2457,6 +2384,12 @@ where \meta{cs} is a control sequence that takes a single argument
(which is the entry label). This is best used with the starred
version \cs{GlsXtrStartUnsetBuffering*} to avoid duplicates.
+You can discard the buffer and restore \cs{glsunset} to its normal
+behaviour with (new to v1.42):
+\begin{definition}[\DescribeMacro\GlsXtrDiscardUnsetBuffering]
+\cs{GlsXtrDiscardUnsetBuffering}
+\end{definition}
+
\begin{important}
Note that since the change in the first use flag now doesn't
occur until \cs{GlsXtrStopUnsetBuffering}, multiple references
@@ -2995,7 +2928,16 @@ The simplest way to update a document that uses
\begin{verbatim}
\setabbreviationstyle[acronym]{long-short}
\end{verbatim}
-before you define any entries.
+before you define any entries. If you have used commands like
+\ics{acrshort}, \ics{acrlong} and \ics{acrfull}, you need to
+substitute them with \ics{glsxtrshort}, \ics{glsxtrlong} and
+\ics{glsxtrfull}. (This includes plural and case-changing forms.)
+Your text editor's search and replace function should help with
+this. If you have used the \pkgopt{shortcuts} package option then
+use \pkgopt[ac]{shortcuts} in order to continue using the shortcut
+commands like \ics{ac}. With this setting, \ics{acs} will use
+\ics{glsxtrshort} instead of \ics{acrshort} etc.
+
For example, the following document using just \styfmt{glossaries}
\begin{verbatim}
\documentclass{article}
@@ -3129,6 +3071,812 @@ is redefined to use the subsequent use abbreviation font command
\ics{glsabbrvfont}. This will be reset if you use
\cs{RestoreAcronyms}.
+\section{Glossaries}
+
+The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
+version that doesn't automatically switch off the hyperlinks.
+This starred version may be used with the \catattr{targeturl}
+attribute to create a link to an external URL. (See
+\sectionref{sec:categories} for further details.)
+As from v1.12 both the starred and unstarred version check
+that the glossary doesn't already exist. (The \styfmt{glossaries}
+package omits this check.)
+
+You can now provide an ignored glossary with:
+\begin{definition}[\DescribeMacro\provideignoredglossary]
+\cs{provideignoredglossary}\marg{type}
+\end{definition}
+which will only define the glossary if it doesn't already exist.
+This also has a starred version that doesn't automatically switch
+off hyperlinks.
+
+The individual glossary displaying commands \ics{printglossary},
+\ics{printnoidxglossary} and \cs{printunsrtglossary} have extra
+keys:
+
+\begin{itemize}
+\item \gloskey[printglossary]{target}. This is a boolean key which can
+be used to switch off the automatic hypertarget for each entry.
+Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so
+any cross-references within the glossary won't be affected. This is
+a way of avoiding duplicate target warnings if a glossary needs to
+be displayed multiple times.
+\item
+\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way
+of avoiding duplicate target names is to set a prefix
+used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect
+any hyperlinks (such as those created with \cs{gls}).
+\item
+\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do
+actually want to locally change \cs{glolinkprefix}, you can use
+the \gloskey{prefix} key instead. You need to use the matching
+\gloskey[glslink]{prefix} key in commands like \cs{gls}.
+
+\item
+\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels
+the glossary with \texttt{\cs{label}\marg{label}} and also
+defines \cs{@currentlabelname} to the glossary's TOC title
+(to provide text for \cs{nameref}). You can also set the
+label before the glossary using:
+\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel]
+\cs{glsxtrsetglossarylabel}\marg{label}
+\end{definition}
+but take care of duplicate labels if it's not scoped.
+\end{itemize}
+
+\subsection{Glossary Style Modifications}
+\label{sec:glosstylemods}
+
+The \sty{glossaries-extra-stylemods} package (more conveniently
+loaded through the \styfmt{glossaries-extra}
+\pkgopt{stylemods} option) modifies some of the predefined
+styles that are provided with the \styfmt{glossaries} package.
+These modifications are described in more detail in
+\sectionref{sec:stylemods}.
+
+The \sty{glossaries} package tries to determine the group
+title from its label by first checking if
+\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist,
+then the title is assumed to be the same as the label.
+For example, when typesetting the \qt{A} letter group,
+\sty{glossaries} first checks if \cs{Agroupname} exists.
+This could potentially cause conflict with another package
+that may have some other meaning for \cs{Agroupname}, so
+\sty{glossaries-extra} first checks for the existence
+of the internal command \cs{glsxtr@grouptitle@}\meta{label}
+which shouldn't clash with another package. You can set the
+group title using
+\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle]
+\cs{glsxtrsetgrouptitle}\marg{label}\marg{title}
+\end{definition}
+For example:
+\begin{verbatim}
+\glsxtrsetgrouptitle{A}{A (a)}
+\end{verbatim}
+This uses a global assignment. If you need to scope the change
+you can use
+\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle]
+\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title}
+\end{definition}
+
+\subsubsection{Style Hooks}
+\label{sec:stylehooks}
+
+The commands \ics{glossentryname} and \ics{glossentrydesc} are
+modified to take into account the \catattr{glossname},
+\category{glossnamefont}, \catattr{glossdesc} and \catattr{glossdescfont}
+attributes (see \sectionref{sec:categories}). This means you can
+make simple font or case-changing modifications to the name and description
+without defining a new glossary style.
+
+(New to version 1.42.)
+The command \ics{glossentrysymbol} is modified to take into account
+the \catattr{glosssymbolfont}. Note that, unlike the above, there's
+no corresponding attribute to change the case as it's usually not
+appropriate to change the case of a symbol (and for some symbols,
+such as pictographs, there's no concept of case). If
+\ics{texorpdfstring} has been defined \ics{glossentrysymbol} will
+be defined to do:
+\begin{alltt}
+\ics{texorpdfstring}\marg{\TeX\ code}\marg{PDF}
+\end{alltt}
+The \meta{\TeX\ code} part is robust and deals with the actual
+typesetting of the symbol. The \meta{PDF} part is simply:
+\begin{definition}[\DescribeMacro\glsentrypdfsymbol]
+\cs{glsentrypdfsymbol}\marg{label}
+\end{definition}
+which is defined to just do \cs{glsentrysymbol}\marg{label}. The
+chances are that the code in the \gloskey{symbol} key won't be valid
+in the PDF bookmarks, so you can redefine \cs{glsentrypdfsymbol} to
+use a more appropriate field. (If you do redefine this command,
+remember that it needs to fully expand.)
+
+For example, if you are using \sty{glossaries-accsupp}, you could
+use the \gloskey{symbolaccess} field:
+\begin{verbatim}
+\renewcommand{\glsentrypdfsymbol}[1]{\glsentrysymbolaccess{#1}}
+\end{verbatim}
+Alternatively, if you are using \gls{bib2gls} you can use the \TeX\
+parser library to interpret a copy of the \gloskey{symbol} field and
+use that. For example, with the resource options:
+\begin{verbatim}
+ replicate-fields={symbol=user1},
+ interpret-fields={user1}
+\end{verbatim}
+This stores the interpreted value of the symbol in the
+\gloskey{user1} field, so you can then do:
+\begin{verbatim}
+\renewcommand{\glsentrypdfsymbol}[1]{\glsentryuseri{#1}}
+\end{verbatim}
+(You may need \XeLaTeX\ or \LuaLaTeX\ with this method.) This allows
+\cs{glossentrysymbol} to be used in a section heading with
+standalone definitions.
+
+If you want to adapt a style to use another field instead
+of \gloskey{name}, you can use
+\begin{definition}[\DescribeMacro\glossentrynameother]
+\cs{glossentrynameother}\marg{label}\marg{field}
+\end{definition}
+This behaves just like \cs{glossentryname} (that is, it obeys
+\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name
+hook) but it uses the given \meta{field} instead of \gloskey{name}.
+The \meta{field} argument must be the internal field name
+(for example \texttt{desc} rather than \texttt{description}).
+See the key to field mappings table in the \styfmt{glossaries}
+user manual.
+
+There is a hook after \ics{glossentryname} and
+\ics{Glossentryname}:
+\begin{definition}[\DescribeMacro\glsxtrpostnamehook]
+\cs{glsxtrpostnamehook}\marg{label}
+\end{definition}
+By default this checks the \catattr{indexname} attribute.
+If the attribute exists for the category to which the label belongs,
+then the name is automatically indexed using
+\begin{definition}
+\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}}
+\end{definition}
+See \sectionref{sec:autoindex} for further details.
+
+\begin{sloppypar}
+As from version 1.04, the post-name hook \cs{glsxtrpostnamehook}
+will also use \cs{glsxtrpostname}\meta{category} if it exists.
+You can use \ics{glscurrententrylabel} to obtain the entry label
+with the definition of this command. For example, suppose you are
+using a glossary style the doesn't display the symbol, you can
+insert the symbol after the name for a particular category, say,
+the \qt{symbol} category:
+\end{sloppypar}
+\begin{verbatim}
+\newcommand*{\glsxtrpostnamesymbol}{\space
+ (\glsentrysymbol{\glscurrententrylabel})}
+\end{verbatim}
+For convenience, as from v1.31, you can use
+\begin{definition}[\DescribeMacro\glsdefpostname]
+\cs{glsdefpostname}\marg{category}\marg{definition}
+\end{definition}
+This is simply a shortcut for:
+\begin{alltt}
+\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition}
+\end{alltt}
+Note that it doesn't check if the command has already been defined.
+
+As from version 1.25, the post-name hook also does
+\begin{definition}[\DescribeMacro\glsextrapostnamehook]
+\cs{glsextrapostnamehook}\marg{label}
+\end{definition}
+(before \cs{glsxtrpostname}\meta{category})
+to allow for additional non-category related code. This does nothing
+by default.
+
+The post-description code used within the glossary is modified so
+that it also does
+\begin{definition}[\DescribeMacro\glsxtrpostdescription]
+\cs{glsxtrpostdescription}
+\end{definition}
+This occurs before the original \cs{glspostdescription}, so if the
+\pkgopt[false]{nopostdot} option is used, it will be inserted before
+the terminating full stop.
+
+This new command will do \cs{glsxtrpostdesc\meta{category}}
+if it exists, where \meta{category} is the category label associated
+with the current entry. For example \cs{glsxtrpostdescgeneral}
+for entries with the category set to \category{general}
+or \cs{glsxtrpostdescacronym} for entries with the category set to
+\category{acronym}.
+For convenience, as from v1.31, you can use
+\begin{definition}[\DescribeMacro\glsdefpostdesc]
+\cs{glsdefpostdesc}\marg{category}\marg{definition}
+\end{definition}
+This is simply a shortcut for:
+\begin{alltt}
+\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition}
+\end{alltt}
+Note that it doesn't check if the command has already been defined.
+
+Since both \cs{glossentry} and \cs{subglossentry} set
+\begin{definition}[\DescribeMacro\glscurrententrylabel]
+\cs{glscurrententrylabel}
+\end{definition}
+to the label for the current entry, you can use this within the
+definition of these post-description hooks if you need to reference
+the label.
+
+For example, suppose you want to insert the plural form in brackets
+after the description in the glossary, but only for entries in the
+\category{general} category, then you could do:
+\begin{verbatim}
+\renewcommand{\glsxtrpostdescgeneral}{\space
+ (plural: \glsentryplural{\glscurrententrylabel})}
+\end{verbatim}
+This means you don't have to define a custom glossary style, which
+you may find more complicated. (It also allows more flexibility if
+you decide to change the underlying glossary style.)
+
+\begin{important}
+This feature can't be used for glossary styles that ignore
+\cs{glspostdescription} or if you redefine
+\cs{glspostdescription} without including \cs{glsxtrpostdescription}.
+(For example, if you redefine \cs{glspostdescription} to do
+nothing instead of using the \pkgopt{nopostdot} option to suppress
+the terminating full stop.) See \sectionref{sec:stylemods} to patch
+the predefined styles provided by \styfmt{glossaries} that are missing
+\cs{glspostdescription}.
+\end{important}
+
+\subsubsection{Number List}
+\label{sec:glosstylenumlist}
+
+The \gls{numberlist} is now placed inside the argument of
+\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList]
+\cs{GlsXtrFormatLocationList}\marg{number list}
+\end{definition}
+This is internally used by \cs{glossaryentrynumbers}. The
+\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it
+doesn't display the \gls{numberlist}, but it still saves the
+\gls{numberlist} in case it's required.
+
+\begin{important}
+If you want to suppress the \gls{numberlist} always use the
+\pkgopt{nonumberlist} option instead of redefining
+\cs{glossaryentrynumbers} to do nothing.
+\end{important}
+
+For example, to change the font for the entire
+\gls{numberlist} redefine \cs{GlsXtrFormatLocationList} as
+appropriate. Don't modify \cs{glossaryentrynumbers}.
+
+Sometimes users like to insert \qt{page} or \qt{pages} in front of
+the \gls{numberlist}. This is quite fiddly to do with the base
+\styfmt{glossaries} package, but \styfmt{glossaries-extra}
+provides a way of doing this. First you need to enable this
+option and specify the text to display using:
+\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag]
+\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages}
+\end{definition}
+where \meta{page} is the text to display if the \gls{numberlist} only
+contains a single location and \meta{pages} is the text to display
+otherwise. For example:
+\begin{verbatim}
+\GlsXtrEnablePreLocationTag{Page: }{Pages: }
+\end{verbatim}
+An extra run is required when using this command.
+
+\begin{important}
+Use \texttt{glsignore} not \texttt{@gobble} as the format if you
+want to suppress the page number (and only index the entry once).
+\end{important}
+
+See the accompanying sample file \texttt{sample-pages.tex}.
+
+Note that \gls{bib2gls} can be instructed to insert
+a prefix at the start of non-empty location lists, which
+can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}.
+
+\Glspl{locationlist} displayed with \cs{printnoidxglossary}
+internally use
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+This command is provided by \styfmt{glossaries}, but is modified by
+\styfmt{glossaries-extra} to check for the start and end range
+formation identifiers \verb|(| and \verb|)| which are discarded to
+obtain the actual control sequence name that forms the location
+formatting command.
+
+If the range identifiers aren't present, this just uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc]
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{definition}
+otherwise it uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc]
+\cs{glsxtrdisplaystartloc}\marg{format}\marg{location}
+\end{definition}
+for the start of a range (where the identifier has been stripped
+from \meta{format}) or
+\begin{definition}[\DescribeMacro\glsxtrdisplayendloc]
+\cs{glsxtrdisplayendloc}\marg{format}\marg{location}
+\end{definition}
+for the end of a range (where the identifier has been stripped
+from \meta{format}).
+
+By default the start range command saves the format in
+\begin{definition}[\DescribeMacro\glsxtrlocrangefmt]
+\cs{glsxtrlocrangefmt}
+\end{definition}
+and does
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+(If the format is empty, it will be replaced with
+\texttt{glsnumberformat}.)
+
+The end command checks that the format matches the start of the
+range, does
+\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook]
+\cs{glsxtrdisplayendlochook}\marg{format}\marg{location}
+\end{definition}
+(which does nothing by default), followed by
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+and then sets \cs{glsxtrlocrangefmt} to empty.
+
+This means that the list
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{(textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{)textbf}{1}.
+\end{verbatim}
+doesn't display any differently from
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1}.
+\end{verbatim}
+but it does make it easier to define your own custom list handler
+that can accommodate the ranges.
+
+\subsubsection{The \styfmt{glossaries-extra-stylemods} Package}
+\label{sec:stylemods}
+
+As from v1.02, \styfmt{glossaries-extra} now includes the package
+\sty{glossaries-extra-stylemods} that will redefine the predefined
+styles to include the post-description hook (for those that are
+missing it). You will need to make sure the styles have already
+been defined before loading \styfmt{glossaries-extra}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage{glossary-longragged}
+\usepackage{glossaries-extra-stylemods}
+\end{verbatim}
+Alternatively you can load
+\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by
+passing \meta{name} as a package option to
+\sty{glossaries-extra-stylemods}. For example:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\usepackage[longragged]{glossaries-extra-stylemods}
+\end{verbatim}
+Another option is to use the \pkgopt{stylemods} key when you
+load \styfmt{glossaries-extra}. You can omit a value if you only want to use
+the predefined styles that are automatically loaded by
+\styfmt{glossaries} (for example, the \glostyle{long3col} style):
+\begin{verbatim}
+\usepackage[style=long3col,stylemods]{glossaries-extra}
+\end{verbatim}
+Or the value of \pkgopt{stylemods} may be a comma-separated list
+of the style package identifiers. For example:
+\begin{verbatim}
+\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
+\end{verbatim}
+Remember to group the value if it contains any commas:
+\begin{verbatim}
+\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
+\end{verbatim}
+
+Note that the \glostyle{inline} style is dealt with slightly
+differently. The original definition provided by the
+\sty{glossary-inline} package uses \cs{glspostdescription} at the
+end of the glossary (not after each entry description) within the
+definition of \cs{glspostinline}. The style modification changes
+this so that \cs{glspostinline} just does a full stop followed by
+space factor adjustment, and the description
+\cs{glsinlinedescformat} and sub-entry description formats
+\cs{glsinlinesubdescformat} are redefined to include
+\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means
+that the modified \glostyle{inline} style isn't affected by the
+\pkgopt{nopostdot} option, but the post-description category hook
+can still be used.
+
+The \env{tabular}-like styles, such as \glostyle{long} are
+adjusted so that the \ics{ifglsnogroupskip} conditional (set with
+\pkgopt{nogroupskip}) is moved outside of the definition of
+\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete
+\cs{iftrue}} error with \cs{printunsrtglossary} and
+\cs{printnoidxglossary}. This means that if you want to change this
+conditional using \cs{setupglossaries} or using the
+\gloskey[printglossary]{nogroupskip} option in \cs{printglossary},
+\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also
+reset the glossary style.
+
+As from version 1.21, the hard-coded \cs{space} before the
+\gls{numberlist} in many of the predefined styles is replaced
+with
+\begin{definition}[\DescribeMacro\glsxtrprelocation]
+\cs{glsxtrprelocation}
+\end{definition}
+This just defaults to \cs{space} but may be redefined as required.
+For example:
+\begin{verbatim}
+\renewcommand{\glsxtrprelocation}{\dotfill}
+\end{verbatim}
+
+The \glostyle{list} styles use
+\begin{definition}[\DescribeMacro\glslistprelocation]
+\cs{glslistprelocation}
+\end{definition}
+(which defaults to \cs{glsxtrprelocation}) for top-level items and
+\begin{definition}[\DescribeMacro\glslistchildprelocation]
+\cs{glslistchildprelocation}
+\end{definition}
+(which defaults to \cs{glslistprelocation}) for child items.
+
+As from v1.31, the description (including the post-description hook)
+is governed by:
+\begin{definition}[\DescribeMacro\glslistdesc]
+\cs{glslistdesc}\marg{label}
+\end{definition}
+for the \glostyle{list} and \glostyle{altlist} styles (but not the
+\glostyle{listdotted} variations).
+
+For just the \glostyle{list} style and its letter group variations
+(not the \glostyle{altlist} or \glostyle{listdotted} variations) the
+\gls{numberlist} for child entries is followed by
+\begin{definition}[\DescribeMacro\glslistchildpostlocation]
+\cs{glslistchildpostlocation}
+\end{definition}
+which defaults to a full stop.
+
+The default value of \ics{glslistdottedwidth} is changed so that
+it's set at the start of the document (if it hasn't been changed in
+the preamble). This should take into account situations where
+\cs{hsize} isn't set until the start of the document.
+
+The separator between groups (if not \pkgopt{nogroupskip}) is now
+given by:
+\begin{definition}[\DescribeMacro\glslistgroupskip]
+\cs{glslistgroupskip}
+\end{definition}
+This defaults to \cs{indexspace} with penalties to deter page
+breaks.
+This command isn't used if \pkgopt{nogroupskip} is set.
+
+The \sty{glossary-tree} package introduced new commands in
+v4.22, \ics{glstreegroupheaderfmt}
+and \ics{glstreenavigationfmt}, which are used to format
+the letter group headings and the navigation elements for the
+appropriate styles. These two new commands are defined in terms of
+\ics{glstreenamefmt} since that was the command originally used
+for the group headings and navigation. This now allows these
+different elements to be defined independently, but the most common
+redefinition is for \cs{glstreenamefmt} to remove the bold in the
+name. If the bold is still required for the group heading and navigation
+elements, then both other commands also need redefining. To simplify
+matters, if \cs{glstreenamefmt} has been defined, as from v1.31
+\sty{glossaries-extra-stylemods} defines:
+\begin{definition}[\DescribeMacro\glstreedefaultnamefmt]
+\cs{glstreedefaultnamefmt}\marg{text}
+\end{definition}
+which simply does \cs{textbf}\marg{text} and redefines
+\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
+\cs{glstreenavigationfmt} all in terms of
+\cs{glstreedefaultnamefmt}.
+
+This means that if you want to change
+all three to use a particular style you only need to redefine
+\cs{glstreedefaultnamefmt}, but if you only want to redefine
+\cs{glstreenamefmt} without affecting the other two commands, then
+you now can.
+
+The separator between groups without headers is given by:
+\begin{definition}[\DescribeMacro\glstreegroupskip]
+\cs{glstreegroupskip}
+\end{definition}
+This defaults to just \ics{indexspace} without penalties. This
+command isn't used if \pkgopt{nogroupskip} is set. (The penalties
+introduced in v1.41 were moved to \cs{glstreeheadergroupskip} in
+v1.42 as they are inappropriate when there's no header.)
+
+The separator between groups with headers is now given by (as from v1.42):
+\begin{definition}[\DescribeMacro\glstreeheadergroupskip]
+\cs{glstreegroupheaderskip}
+\end{definition}
+This defaults to \cs{glstreegroupskip} with penalties to deter page
+breaks after the group heading.
+
+The styles that display the group titles now use:
+\begin{definition}[\DescribeMacro\glstreePreHeader]
+\cs{glstreePreHeader}\marg{label}\marg{title}
+\end{definition}
+where \meta{label} is the group label and \meta{title} is the group
+title. This does nothing by default
+and is inserted before the group title. You can redefine it to add
+the group title to the PDF bookmarks. For example, if the
+glossary title uses \cs{chapter} then:
+\begin{verbatim}
+\renewcommand{\glstreePreHeader}[2]{%
+ \pdfbookmark[1]{#2}{\currentglossary.#1}%
+}
+\end{verbatim}
+will insert section-level bookmarks. The use of \cs{currentglossary}
+helps to provide unique bookmark labels in the event of multiple
+glossaries.
+
+The \glostyle{index}-like and \glostyle{tree}-like styles
+insert the pre-\gls{numberlist} space with
+\begin{definition}[\DescribeMacro\glstreeprelocation]
+\cs{glstreeprelocation}
+\end{definition}
+(which defaults to \cs{glsxtrprelocation}) for top-level items and
+\begin{definition}[\DescribeMacro\glstreechildprelocation]
+\cs{glstreechildprelocation}
+\end{definition}
+(which defaults to \cs{glstreeprelocation}) for child items.
+
+As from version 1.31, the \styfmt{glossaries-extra-stylemods}
+package also provides:
+\begin{definition}[\DescribeMacro\glstreenonamedesc]
+\cs{glstreenonamedesc}\marg{label}
+\end{definition}
+which is used by the \glostyle{treenoname} styles to display the
+pre-description separator, the description and the post-description
+hook. Similarly for the symbol:
+\begin{definition}[\DescribeMacro\glstreenonamesymbol]
+\cs{glstreenonamesymbol}\marg{label}
+\end{definition}
+The above are just used for top-level entries. Child entries don't
+have the name or symbol displayed for the \glostyle{treenoname}
+styles, so there's only a command for the child description:
+\begin{definition}[\DescribeMacro\glstreenonamechilddesc]
+\cs{glstreenonamechilddesc}\marg{label}
+\end{definition}
+
+For the \glostyle{tree} styles (but not the \glostyle{treenoname} or
+\glostyle{alttree} styles), the description is displayed using:
+\begin{definition}[\DescribeMacro\glstreedesc]
+\cs{glstreedesc}\marg{label}
+\end{definition}
+and the symbol with:
+\begin{definition}[\DescribeMacro\glstreesymbol]
+\cs{glstreesymbol}\marg{label}
+\end{definition}
+Again the above two commands are just for top-level entries. The
+child entries use:
+\begin{definition}[\DescribeMacro\glstreechilddesc]
+\cs{glstreechilddesc}\marg{label}
+\end{definition}
+for the description and
+\begin{definition}[\DescribeMacro\glstreechildsymbol]
+\cs{glstreechildsymbol}\marg{label}
+\end{definition}
+for the symbol.
+As from version 1.41, there are now wrapper commands for
+\cs{glstreedesc} and \cs{glstreechilddesc} that check for
+the description and symbol to determine what separator to use
+before the page list. These are:
+\begin{definition}[\DescribeMacro\glstreeDescLoc]
+\cs{glstreeDescLoc}\marg{label}\marg{location}
+\end{definition}
+for top-level entries and
+\begin{definition}[\DescribeMacro\glstreeChildDescLoc]
+\cs{glstreeChildDescLoc}\marg{label}\marg{location}
+\end{definition}
+for sub-entries.
+
+If either the symbol or description is present these will use
+\cs{glstreeprelocation} or \cs{glstreechildprelocation},
+respectively. Otherwise, both will use (from v1.42):
+\begin{definition}[\DescribeMacro\glstreeNoDescSymbolPreLocation]
+\cs{glstreeNoDescSymbolPreLocation}
+\end{definition}
+The default is a space. This means that you could have, say, a
+comma followed by a space for terms that are simply an alias, but
+just have a space for terms that have a description that ends with a
+full stop (or that just have a symbol without a description) where
+the comma would be inappropriate.
+
+Note that version 1.42 has corrected an error that was introduced to
+v1.41 that caused the name to run into the location list if there
+was no symbol and no description.
+
+As from version 1.05, the \styfmt{glossaries-extra-stylemods}
+package provides some additional commands for use with the
+\glostyle{alttree} style to make it easier to modify.
+These commands are only defined if the
+\sty{glossary-tree} package has already been loaded, which is
+typically the case unless the \pkgopt{notree} option has been used
+when loading \styfmt{glossaries}.
+
+\begin{definition}[\DescribeMacro\gglssetwidest]
+\cs{gglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+(New to version 1.21.)
+This is like \cs{glssetwidest} (provided by \sty{glossary-tree})
+but performs a global assignment.
+
+\begin{definition}[\DescribeMacro\eglssetwidest]
+\cs{eglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+This is like \cs{glssetwidest}
+but performs a protected expansion on \meta{name}. This has
+a localised effect. For a global setting, use
+\begin{definition}[\DescribeMacro\xglssetwidest]
+\cs{xglssetwidest}\oarg{level}\marg{name}
+\end{definition}
+The following only set the value if \meta{name} is wider than the
+current value (new to version 1.23). Local update:
+\begin{definition}[\DescribeMacro\glsupdatewidest]
+\cs{glsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update:
+\begin{definition}[\DescribeMacro\gglsupdatewidest]
+\cs{gglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Locale update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\eglsupdatewidest]
+\cs{eglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\xglsupdatewidest]
+\cs{xglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+
+
+The widest entry value can later be retrieved using
+\begin{definition}[\DescribeMacro\glsgetwidestname]
+\cs{glsgetwidestname}
+\end{definition}
+for the top-level entries and
+\begin{definition}[\DescribeMacro\glsgetwidestsubname]
+\cs{glsgetwidestsubname}\marg{level}
+\end{definition}
+for sub-entries, where \meta{level} is the level number.
+
+Note that if you are using \gls{bib2gls}, you can use the
+resource option \texttt{set-widest} which will try to determine the
+widest name of all the selected entries. This isn't guaranteed
+to work as it may depend on fonts or commands that \gls{bib2gls}
+can't replicate, but it should be suitable for names that just
+consist of text, and can be more efficient than iterating over all
+the defined entries using \TeX.
+
+The command \cs{glsfindwidesttoplevelname} provided by
+\sty{glossary-tree} has a CamelCase synonym:
+\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName]
+\cs{glsFindWidestTopLevelName}\oarg{glossary list}
+\end{definition}
+Similar commands are also provided:
+\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName]
+\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list}
+\end{definition}
+This has an additional check that the entry has been used.
+Naturally this is only useful if the glossaries that use
+the \glostyle{alttree} style occur at the end of the document.
+This command should be placed just before the start of the glossary.
+(Alternatively, place it at the end of the document and save
+the value in the auxiliary file for the next run.)
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName]
+\cs{glsFindWidestUsedAnyName}\oarg{glossary list}
+\end{definition}
+This is like the previous command but if doesn't check the
+\gloskey{parent} key. This is useful if all levels should have the
+same width for the name.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyName]
+\cs{glsFindWidestAnyName}\oarg{glossary list}
+\end{definition}
+This is like the previous command but doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo]
+\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list}
+\end{definition}
+This is like \cs{glsFindWidestUsedTopLevelName} but also sets
+the first two sub-levels as well. Any entry that has a
+great-grandparent is ignored.
+
+\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo]
+\cs{glsFindWidestLevelTwo}\oarg{glossary list}
+\end{definition}
+This is like the previous command but doesn't check if the entry has
+been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol]
+\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyName} but also measures the
+symbol. The length of the widest symbol is stored in
+\meta{register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol]
+\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register}
+\end{definition}
+This is like the previous command but it doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation]
+\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary
+list}\marg{symbol register}\marg{location register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyNameSymbol} but also
+measures the \gls{numberlist}. This requires
+\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual).
+The length of the widest symbol is stored in \meta{symbol register}
+and the length of the widest \gls*{numberlist} is stored in
+\meta{location register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation]
+\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary
+list}\marg{symbol register}\marg{location register}
+\end{definition}
+This is like the previous command but it doesn't check if the entry
+has been used.
+
+\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation]
+\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't
+measure the symbol. The length of the widest \gls{numberlist}
+is stored in \meta{register}.
+
+\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation]
+\cs{glsFindWidestAnyNameLocation}\oarg{glossary
+list}\marg{register}
+\end{definition}
+This is like the previous command but doesn't check if the entry has
+been used.
+
+The layout of the symbol, description and \gls{numberlist}
+is governed by
+\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation]
+\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list}
+\end{definition}
+for top-level entries and
+\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation]
+\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list}
+\end{definition}
+for sub-entries.
+
+There is now a user level command that performs the initialisation
+for the \glostyle{alttree} style:
+\begin{definition}[\DescribeMacro\glsxtralttreeInit]
+\cs{glsxtralttreeInit}
+\end{definition}
+
+The paragraph indent for subsequent paragraphs in multi-paragraph
+descriptions is provided by the length
+\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent]
+\cs{glsxtrAltTreeIndent}
+\end{definition}
+
+For additional commands that are available with the
+\glostyle{alttree} style, see the documented code
+(\nolinkurl{glossaries-extra-code.pdf}). See also
+the accompanying sample files \nolinkurl{sample-alttree.tex},
+\nolinkurl{sample-alttree-sym.tex} and
+\nolinkurl{sample-alttree-marginpar.tex}.
+
+\chapter{New Glossary Styles}
+
+The \styfmt{glossaries-extra} package comes with some new styles.
+The associated style package needs to be loaded. This can be done
+with \cs{usepackage} but it's simpler to use the \pkgopt{stylemods}
+option.
+
\section{\styfmt{glossary-bookindex} package}
\label{sec:bookindex}
@@ -4093,624 +4841,6 @@ Finally the location list is displayed using:
\end{definition}
which just does \meta{location} by default.
-\section{Glossary Style Modifications}
-\label{sec:glosstylemods}
-
-The \sty{glossaries-extra-stylemods} package (more conveniently
-loaded through the \styfmt{glossaries-extra}
-\pkgopt{stylemods} option) modifies some of the predefined
-styles that are provided with the \styfmt{glossaries} package.
-These modifications are described in more detail in
-\sectionref{sec:stylemods}.
-
-The \sty{glossaries} package tries to determine the group
-title from its label by first checking if
-\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist,
-then the title is assumed to be the same as the label.
-For example, when typesetting the \qt{A} letter group,
-\sty{glossaries} first checks if \cs{Agroupname} exists.
-This could potentially cause conflict with another package
-that may have some other meaning for \cs{Agroupname}, so
-\sty{glossaries-extra} first checks for the existence
-of the internal command \cs{glsxtr@grouptitle@}\meta{label}
-which shouldn't clash with another package. You can set the
-group title using
-\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle]
-\cs{glsxtrsetgrouptitle}\marg{label}\marg{title}
-\end{definition}
-For example:
-\begin{verbatim}
-\glsxtrsetgrouptitle{A}{A (a)}
-\end{verbatim}
-This uses a global assignment. If you need to scope the change
-you can use
-\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle]
-\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title}
-\end{definition}
-
-\subsection{Style Hooks}
-\label{sec:stylehooks}
-
-The commands \ics{glossentryname} and \ics{glossentrydesc} are
-modified to take into account the \catattr{glossname},
-\catattr{glossdesc} and \catattr{glossdescfont} attributes (see \sectionref{sec:categories}).
-This means you can make simple case-changing modifications to
-the name and description without defining a new glossary style.
-
-If you want to adapt a style to use another field instead
-of \gloskey{name}, you can use
-\begin{definition}[\DescribeMacro\glossentrynameother]
-\cs{glossentrynameother}\marg{label}\marg{field}
-\end{definition}
-This behaves just like \cs{glossentryname} (that is, it obeys
-\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name
-hook) but it uses the given \meta{field} instead of \gloskey{name}.
-The \meta{field} argument must be the internal field name
-(for example \texttt{desc} rather than \texttt{description}).
-See the key to field mappings table in the \styfmt{glossaries}
-user manual.
-
-There is a hook after \ics{glossentryname} and
-\ics{Glossentryname}:
-\begin{definition}[\DescribeMacro\glsxtrpostnamehook]
-\cs{glsxtrpostnamehook}\marg{label}
-\end{definition}
-By default this checks the \catattr{indexname} attribute.
-If the attribute exists for the category to which the label belongs,
-then the name is automatically indexed using
-\begin{definition}
-\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}}
-\end{definition}
-See \sectionref{sec:autoindex} for further details.
-
-\begin{sloppypar}
-As from version 1.04, the post-name hook \cs{glsxtrpostnamehook}
-will also use \cs{glsxtrpostname}\meta{category} if it exists.
-You can use \ics{glscurrententrylabel} to obtain the entry label
-with the definition of this command. For example, suppose you are
-using a glossary style the doesn't display the symbol, you can
-insert the symbol after the name for a particular category, say,
-the \qt{symbol} category:
-\end{sloppypar}
-\begin{verbatim}
-\newcommand*{\glsxtrpostnamesymbol}{\space
- (\glsentrysymbol{\glscurrententrylabel})}
-\end{verbatim}
-For convenience, as from v1.31, you can use
-\begin{definition}[\DescribeMacro\glsdefpostname]
-\cs{glsdefpostname}\marg{category}\marg{definition}
-\end{definition}
-This is simply a shortcut for:
-\begin{alltt}
-\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition}
-\end{alltt}
-Note that it doesn't check if the command has already been defined.
-
-As from version 1.25, the post-name hook also does
-\begin{definition}[\DescribeMacro\glsextrapostnamehook]
-\cs{glsextrapostnamehook}\marg{label}
-\end{definition}
-(before \cs{glsxtrpostname}\meta{category})
-to allow for additional non-category related code. This does nothing
-by default.
-
-The post-description code used within the glossary is modified so
-that it also does
-\begin{definition}[\DescribeMacro\glsxtrpostdescription]
-\cs{glsxtrpostdescription}
-\end{definition}
-This occurs before the original \cs{glspostdescription}, so if the
-\pkgopt[false]{nopostdot} option is used, it will be inserted before
-the terminating full stop.
-
-This new command will do \cs{glsxtrpostdesc\meta{category}}
-if it exists, where \meta{category} is the category label associated
-with the current entry. For example \cs{glsxtrpostdescgeneral}
-for entries with the category set to \category{general}
-or \cs{glsxtrpostdescacronym} for entries with the category set to
-\category{acronym}.
-For convenience, as from v1.31, you can use
-\begin{definition}[\DescribeMacro\glsdefpostdesc]
-\cs{glsdefpostdesc}\marg{category}\marg{definition}
-\end{definition}
-This is simply a shortcut for:
-\begin{alltt}
-\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition}
-\end{alltt}
-Note that it doesn't check if the command has already been defined.
-
-Since both \cs{glossentry} and \cs{subglossentry} set
-\begin{definition}[\DescribeMacro\glscurrententrylabel]
-\cs{glscurrententrylabel}
-\end{definition}
-to the label for the current entry, you can use this within the
-definition of these post-description hooks if you need to reference
-the label.
-
-For example, suppose you want to insert the plural form in brackets
-after the description in the glossary, but only for entries in the
-\category{general} category, then you could do:
-\begin{verbatim}
-\renewcommand{\glsxtrpostdescgeneral}{\space
- (plural: \glsentryplural{\glscurrententrylabel})}
-\end{verbatim}
-This means you don't have to define a custom glossary style, which
-you may find more complicated. (It also allows more flexibility if
-you decide to change the underlying glossary style.)
-
-\begin{important}
-This feature can't be used for glossary styles that ignore
-\cs{glspostdescription} or if you redefine
-\cs{glspostdescription} without including \cs{glsxtrpostdescription}.
-(For example, if you redefine \cs{glspostdescription} to do
-nothing instead of using the \pkgopt{nopostdot} option to suppress
-the terminating full stop.) See \sectionref{sec:stylemods} to patch
-the predefined styles provided by \styfmt{glossaries} that are missing
-\cs{glspostdescription}.
-\end{important}
-
-\subsection{Number List}
-\label{sec:glosstylenumlist}
-
-The \gls{numberlist} is now placed inside the argument of
-\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList]
-\cs{GlsXtrFormatLocationList}\marg{number list}
-\end{definition}
-This is internally used by \cs{glossaryentrynumbers}. The
-\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it
-doesn't display the \gls{numberlist}, but it still saves the
-\gls{numberlist} in case it's required.
-
-\begin{important}
-If you want to suppress the \gls{numberlist} always use the
-\pkgopt{nonumberlist} option instead of redefining
-\cs{glossaryentrynumbers} to do nothing.
-\end{important}
-
-If you want to, for example, change the font for the entire
-\gls{numberlist} then redefine \cs{GlsXtrFormatLocationList} as
-appropriate. Don't modify \cs{glossaryentrynumbers}.
-
-Sometimes users like to insert \qt{page} or \qt{pages} in front of
-the \gls{numberlist}. This is quite fiddly to do with the base
-\styfmt{glossaries} package, but \styfmt{glossaries-extra}
-provides a way of doing this. First you need to enable this
-option and specify the text to display using:
-\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag]
-\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages}
-\end{definition}
-where \meta{page} is the text to display if the \gls{numberlist} only
-contains a single location and \meta{pages} is the text to display
-otherwise. For example:
-\begin{verbatim}
-\GlsXtrEnablePreLocationTag{Page: }{Pages: }
-\end{verbatim}
-An extra run is required when using this command.
-
-\begin{important}
-Use \texttt{glsignore} not \texttt{@gobble} as the format if you
-want to suppress the page number (and only index the entry once).
-\end{important}
-
-See the accompanying sample file \texttt{sample-pages.tex}.
-
-Note that \gls{bib2gls} can be instructed to insert
-a prefix at the start of non-empty location lists, which
-can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}.
-
-\subsection{The \styfmt{glossaries-extra-stylemods} Package}
-\label{sec:stylemods}
-
-As from v1.02, \styfmt{glossaries-extra} now includes the package
-\sty{glossaries-extra-stylemods} that will redefine the predefined
-styles to include the post-description hook (for those that are
-missing it). You will need to make sure the styles have already
-been defined before loading \styfmt{glossaries-extra}. For example:
-\begin{verbatim}
-\usepackage{glossaries-extra}
-\usepackage{glossary-longragged}
-\usepackage{glossaries-extra-stylemods}
-\end{verbatim}
-Alternatively you can load
-\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by
-passing \meta{name} as a package option to
-\sty{glossaries-extra-stylemods}. For example:
-\begin{verbatim}
-\usepackage{glossaries-extra}
-\usepackage[longragged]{glossaries-extra-stylemods}
-\end{verbatim}
-Another option is to use the \pkgopt{stylemods} key when you
-load \styfmt{glossaries-extra}. You can omit a value if you only want to use
-the predefined styles that are automatically loaded by
-\styfmt{glossaries} (for example, the \glostyle{long3col} style):
-\begin{verbatim}
-\usepackage[style=long3col,stylemods]{glossaries-extra}
-\end{verbatim}
-Or the value of \pkgopt{stylemods} may be a comma-separated list
-of the style package identifiers. For example:
-\begin{verbatim}
-\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
-\end{verbatim}
-Remember to group the value if it contains any commas:
-\begin{verbatim}
-\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
-\end{verbatim}
-
-Note that the \glostyle{inline} style is dealt with slightly
-differently. The original definition provided by the
-\sty{glossary-inline} package uses \cs{glspostdescription} at the
-end of the glossary (not after each entry description) within the
-definition of \cs{glspostinline}. The style modification changes
-this so that \cs{glspostinline} just does a full stop followed by
-space factor adjustment, and the description
-\cs{glsinlinedescformat} and sub-entry description formats
-\cs{glsinlinesubdescformat} are redefined to include
-\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means
-that the modified \glostyle{inline} style isn't affected by the
-\pkgopt{nopostdot} option, but the post-description category hook
-can still be used.
-
-The \env{tabular}-like styles, such as \glostyle{long} are
-adjusted so that the \ics{ifglsnogroupskip} conditional (set with
-\pkgopt{nogroupskip}) is moved outside of the definition of
-\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete
-\cs{iftrue}} error with \cs{printunsrtglossary} and
-\cs{printnoidxglossary}. This means that if you want to change this
-conditional using \cs{setupglossaries} or using the
-\gloskey[printglossary]{nogroupskip} option in \cs{printglossary},
-\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also
-reset the glossary style.
-
-As from version 1.21, the hard-coded \cs{space} before the
-\gls{numberlist} in many of the predefined styles is replaced
-with
-\begin{definition}[\DescribeMacro\glsxtrprelocation]
-\cs{glsxtrprelocation}
-\end{definition}
-This just defaults to \cs{space} but may be redefined as required.
-For example:
-\begin{verbatim}
-\renewcommand{\glsxtrprelocation}{\dotfill}
-\end{verbatim}
-
-The \glostyle{list} styles use
-\begin{definition}[\DescribeMacro\glslistprelocation]
-\cs{glslistprelocation}
-\end{definition}
-(which defaults to \cs{glsxtrprelocation}) for top-level items and
-\begin{definition}[\DescribeMacro\glslistchildprelocation]
-\cs{glslistchildprelocation}
-\end{definition}
-(which defaults to \cs{glslistprelocation}) for child items.
-
-As from v1.31, the description (including the post-description hook)
-is governed by:
-\begin{definition}[\DescribeMacro\glslistdesc]
-\cs{glslistdesc}\marg{label}
-\end{definition}
-for the \glostyle{list} and \glostyle{altlist} styles (but not the
-\glostyle{listdotted} variations).
-
-For just the \glostyle{list} style and its letter group variations
-(not the \glostyle{altlist} or \glostyle{listdotted} variations) the
-\gls{numberlist} for child entries is followed by
-\begin{definition}[\DescribeMacro\glslistchildpostlocation]
-\cs{glslistchildpostlocation}
-\end{definition}
-which defaults to a full stop.
-
-The default value of \ics{glslistdottedwidth} is changed so that
-it's set at the start of the document (if it hasn't been changed in
-the preamble). This should take into account situations where
-\cs{hsize} isn't set until the start of the document.
-
-The separator between groups (if not \pkgopt{nogroupskip}) is now
-given by:
-\begin{definition}[\DescribeMacro\glslistgroupskip]
-\cs{glslistgroupskip}
-\end{definition}
-This defaults to \cs{indexspace} with penalties to deter page
-breaks.
-This command isn't used if \pkgopt{nogroupskip} is set.
-
-The \sty{glossary-tree} package introduced two new commands in
-\sty{glossaries} version 4.22, \ics{glstreegroupheaderfmt}
-and \ics{glstreenavigationfmt}, which are used to format
-the letter group headings and the navigation elements for the
-appropriate styles. These two new commands are defined in terms of
-\ics{glstreenamefmt} since that was the command originally used
-for the group headings and navigation. This now allows these
-different elements to be defined independently, but the most common
-redefinition is for \cs{glstreenamefmt} to remove the bold in the
-name. If the bold is still required for the group heading and navigation
-elements, then both other commands also need redefining. To simplify
-matters, if \cs{glstreenamefmt} has been defined, as from v1.31
-\sty{glossaries-extra-stylemods} defines:
-\begin{definition}[\DescribeMacro\glstreedefaultnamefmt]
-\cs{glstreedefaultnamefmt}\marg{text}
-\end{definition}
-which simply does \cs{textbf}\marg{text} and redefines
-\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and
-\cs{glstreenavigationfmt} all in terms of
-\cs{glstreedefaultnamefmt}. This means that if you want to change
-all three to use a particular style you only need to redefine
-\cs{glstreedefaultnamefmt}, but if you only want to redefine
-\cs{glstreenamefmt} without affecting the other two commands, then
-you now can.
-
-The separator between groups (if not \pkgopt{nogroupskip}) is now
-given by:
-\begin{definition}[\DescribeMacro\glstreegroupskip]
-\cs{glstreegroupskip}
-\end{definition}
-This defaults to \cs{indexspace} with penalties to deter page
-breaks.
-This command isn't used if \pkgopt{nogroupskip} is set (except for
-the styles that display the group titles).
-
-The styles that display the group titles now use:
-\begin{definition}[\DescribeMacro\glstreePreHeader]
-\cs{glstreePreHeader}\marg{label}\marg{title}
-\end{definition}
-where \meta{label} is the group label and \meta{title} is the group
-title. This does nothing by default
-and is inserted before the group title. You can redefine it to add
-the group title to the PDF bookmarks. For example, if the
-glossary title uses \cs{chapter} then:
-\begin{verbatim}
-\renewcommand{\glstreePreHeader}[2]{%
- \pdfbookmark[1]{#2}{\currentglossary.#1}%
-}
-\end{verbatim}
-will insert section-level bookmarks. The use of \cs{currentglossary}
-helps to provide unique bookmark labels in the event of multiple
-glossaries.
-
-The \glostyle{index}-like and \glostyle{tree}-like styles
-insert the pre-\gls{numberlist} space with
-\begin{definition}[\DescribeMacro\glstreeprelocation]
-\cs{glstreeprelocation}
-\end{definition}
-(which defaults to \cs{glsxtrprelocation}) for top-level items and
-\begin{definition}[\DescribeMacro\glstreechildprelocation]
-\cs{glstreechildprelocation}
-\end{definition}
-(which defaults to \cs{glstreeprelocation}) for child items.
-
-As from version 1.31, the \styfmt{glossaries-extra-stylemods}
-package also provides:
-\begin{definition}[\DescribeMacro\glstreenonamedesc]
-\cs{glstreenonamedesc}\marg{label}
-\end{definition}
-which is used by the \glostyle{treenoname} styles to display the
-pre-description separator, the description and the post-description
-hook. Similarly for the symbol:
-\begin{definition}[\DescribeMacro\glstreenonamesymbol]
-\cs{glstreenonamesymbol}\marg{label}
-\end{definition}
-The above are just used for top-level entries. Child entries don't
-have the name or symbol displayed for the \glostyle{treenoname}
-styles, so there's only a command for the child description:
-\begin{definition}[\DescribeMacro\glstreenonamechilddesc]
-\cs{glstreenonamechilddesc}\marg{label}
-\end{definition}
-
-For the \glostyle{tree} styles (but not the \glostyle{treenoname} or
-\glostyle{alttree} styles), the description is displayed using:
-\begin{definition}[\DescribeMacro\glstreedesc]
-\cs{glstreedesc}\marg{label}
-\end{definition}
-and the symbol with:
-\begin{definition}[\DescribeMacro\glstreesymbol]
-\cs{glstreesymbol}\marg{label}
-\end{definition}
-Again the above two commands are just for top-level entries. The
-child entries use:
-\begin{definition}[\DescribeMacro\glstreechilddesc]
-\cs{glstreechilddesc}\marg{label}
-\end{definition}
-for the description and
-\begin{definition}[\DescribeMacro\glstreechildsymbol]
-\cs{glstreechildsymbol}\marg{label}
-\end{definition}
-for the symbol.
-
-As from version 1.41, there are now wrapper commands for
-\cs{glstreedesc} and \cs{glstreechilddesc} that check for
-the description and symbol to determine whether or not to insert a
-space (\cs{glstreeprelocation} or \cs{glstreechildprelocation})
-before the page list. These are:
-\begin{definition}[\DescribeMacro\glstreeDescLoc]
-\cs{glstreeDescLoc}\marg{label}\marg{location}
-\end{definition}
-for top-level entries and
-\begin{definition}[\DescribeMacro\glstreeChildDescLoc]
-\cs{glstreeChildDescLoc}\marg{label}\marg{location}
-\end{definition}
-for sub-entries. This prevents a spurious space for terms that don't
-have a symbol or description but do have a location list (for
-example, aliases).
-
-As from version 1.05, the \styfmt{glossaries-extra-stylemods}
-package provides some additional commands for use with the
-\glostyle{alttree} style to make it easier to modify.
-These commands are only defined if the
-\sty{glossary-tree} package has already been loaded, which is
-typically the case unless the \pkgopt{notree} option has been used
-when loading \styfmt{glossaries}.
-
-\begin{definition}[\DescribeMacro\gglssetwidest]
-\cs{gglssetwidest}\oarg{level}\marg{name}
-\end{definition}
-(New to version 1.21.)
-This is like \cs{glssetwidest} (provided by \sty{glossary-tree})
-but performs a global assignment.
-
-\begin{definition}[\DescribeMacro\eglssetwidest]
-\cs{eglssetwidest}\oarg{level}\marg{name}
-\end{definition}
-This is like \cs{glssetwidest}
-but performs a protected expansion on \meta{name}. This has
-a localised effect. For a global setting, use
-\begin{definition}[\DescribeMacro\xglssetwidest]
-\cs{xglssetwidest}\oarg{level}\marg{name}
-\end{definition}
-The following only set the value if \meta{name} is wider than the
-current value (new to version 1.23). Local update:
-\begin{definition}[\DescribeMacro\glsupdatewidest]
-\cs{glsupdatewidest}\oarg{level}\marg{name}
-\end{definition}
-Global update:
-\begin{definition}[\DescribeMacro\gglsupdatewidest]
-\cs{gglsupdatewidest}\oarg{level}\marg{name}
-\end{definition}
-Locale update (expands \meta{name}):
-\begin{definition}[\DescribeMacro\eglsupdatewidest]
-\cs{eglsupdatewidest}\oarg{level}\marg{name}
-\end{definition}
-Global update (expands \meta{name}):
-\begin{definition}[\DescribeMacro\xglsupdatewidest]
-\cs{xglsupdatewidest}\oarg{level}\marg{name}
-\end{definition}
-
-
-The widest entry value can later be retrieved using
-\begin{definition}[\DescribeMacro\glsgetwidestname]
-\cs{glsgetwidestname}
-\end{definition}
-for the top-level entries and
-\begin{definition}[\DescribeMacro\glsgetwidestsubname]
-\cs{glsgetwidestsubname}\marg{level}
-\end{definition}
-for sub-entries, where \meta{level} is the level number.
-
-Note that if you are using \gls{bib2gls}, you can use the
-resource option \texttt{set-widest} which will try to determine the
-widest name of all the selected entries. This isn't guaranteed
-to work as it may depend on fonts or commands that \gls{bib2gls}
-can't replicate, but it should be suitable for names that just
-consist of text, and can be more efficient than iterating over all
-the defined entries using \TeX.
-
-The command \cs{glsfindwidesttoplevelname} provided by
-\sty{glossary-tree} has a CamelCase synonym:
-\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName]
-\cs{glsFindWidestTopLevelName}\oarg{glossary list}
-\end{definition}
-Similar commands are also provided:
-\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName]
-\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list}
-\end{definition}
-This has an additional check that the entry has been used.
-Naturally this is only useful if the glossaries that use
-the \glostyle{alttree} style occur at the end of the document.
-This command should be placed just before the start of the glossary.
-(Alternatively, place it at the end of the document and save
-the value in the auxiliary file for the next run.)
-
-\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName]
-\cs{glsFindWidestUsedAnyName}\oarg{glossary list}
-\end{definition}
-This is like the previous command but if doesn't check the
-\gloskey{parent} key. This is useful if all levels should have the
-same width for the name.
-
-\begin{definition}[\DescribeMacro\glsFindWidestAnyName]
-\cs{glsFindWidestAnyName}\oarg{glossary list}
-\end{definition}
-This is like the previous command but doesn't check if the entry
-has been used.
-
-\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo]
-\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list}
-\end{definition}
-This is like \cs{glsFindWidestUsedTopLevelName} but also sets
-the first two sub-levels as well. Any entry that has a
-great-grandparent is ignored.
-
-\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo]
-\cs{glsFindWidestLevelTwo}\oarg{glossary list}
-\end{definition}
-This is like the previous command but doesn't check if the entry has
-been used.
-
-\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol]
-\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary
-list}\marg{register}
-\end{definition}
-This is like \cs{glsFindWidestUsedAnyName} but also measures the
-symbol. The length of the widest symbol is stored in
-\meta{register}.
-
-\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol]
-\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register}
-\end{definition}
-This is like the previous command but it doesn't check if the entry
-has been used.
-
-\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation]
-\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary
-list}\marg{symbol register}\marg{location register}
-\end{definition}
-This is like \cs{glsFindWidestUsedAnyNameSymbol} but also
-measures the \gls{numberlist}. This requires
-\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual).
-The length of the widest symbol is stored in \meta{symbol register}
-and the length of the widest \gls*{numberlist} is stored in
-\meta{location register}.
-
-\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation]
-\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary
-list}\marg{symbol register}\marg{location register}
-\end{definition}
-This is like the previous command but it doesn't check if the entry
-has been used.
-
-\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation]
-\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary
-list}\marg{register}
-\end{definition}
-This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't
-measure the symbol. The length of the widest \gls{numberlist}
-is stored in \meta{register}.
-
-\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation]
-\cs{glsFindWidestAnyNameLocation}\oarg{glossary
-list}\marg{register}
-\end{definition}
-This is like the previous command but doesn't check if the entry has
-been used.
-
-The layout of the symbol, description and \gls{numberlist}
-is governed by
-\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation]
-\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list}
-\end{definition}
-for top-level entries and
-\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation]
-\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list}
-\end{definition}
-for sub-entries.
-
-There is now a user level command that performs the initialisation
-for the \glostyle{alttree} style:
-\begin{definition}[\DescribeMacro\glsxtralttreeInit]
-\cs{glsxtralttreeInit}
-\end{definition}
-
-The paragraph indent for subsequent paragraphs in multi-paragraph
-descriptions is provided by the length
-\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent]
-\cs{glsxtrAltTreeIndent}
-\end{definition}
-
-For additional commands that are available with the
-\glostyle{alttree} style, see the documented code
-(\texttt{glossaries-extra-code.pdf}). For examples, see
-the accompanying sample files \texttt{sample-alttree.tex},
-\texttt{sample-alttree-sym.tex} and
-\texttt{sample-alttree-marginpar.tex}.
-
\chapter{Abbreviations}
\label{sec:abbreviations}
@@ -4722,17 +4852,50 @@ package modifies the underlying formatting used by
abbreviations can have their formatting dealt with by the style. You
therefore need to select an abbreviation style that ensures that
\cs{gls} (and its variants) displays the desired output.
+See the file
+\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf}{sample-abbr-styles.pdf}
+for samples of all provided abbreviation styles.
\begin{important}
-Don't use commands like \cs{glstext} or \cs{glsfirst} with
+Don't use \ics{glsfirst}, \ics{Glsfirst} or \ics{GLSfirst} with
abbreviations as they aren't flexible enough to handle some
-abbreviation styles and unexpected results may occur. Use commands
-like \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or
+abbreviation styles and unexpected results may occur. (To a lesser
+degree, this also applies to \ics{glstext} etc.) Use commands
+like \cs{glsfmttext}, \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or
captions instead of \cs{gls}. If you don't want the full form to
show on first use of \cs{gls} use one of the \qt{nolong} or
\qt{noshort} styles.
\end{important}
+This lack of flexibility in \cs{glsfirst} can be demonstrated with
+the following document:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+\setabbreviationstyle{footnote}
+\newabbreviation{ex}{EX}{Example}
+
+\begin{document}
+Compare \gls{ex}['s] with \glsfirst{ex}['s].
+\end{document}
+\end{verbatim}
+The \gls{firstuse} \cs{gls} has the footnote marker after the
+inserted material \qt{EX's\textsuperscript{1}} but \cs{glsfirst} has
+it before the inserted material \qt{EX\textsuperscript{1}'s} which
+is inappropriate. Note that if the style is changed to
+\abbrstyle{postfootnote}, the footnote marker appears after the
+inserted material as \ics{footnote} is in the post-link hook.
+
+There are some instances where \cs{glstext} can be useful. It's used
+internally by \ics{glsfmttext}, which in turn is used by
+\ics{glsseelistformat} if the entry has a short form. If
+\cs{glsfmtshort} is used, this enforces the short form, but if
+\cs{glsfmttext} is used, then the long form will be used for the
+\qt{noshort} styles, which is more appropriate. In this particular
+situation, there's no need to worry about inserted material as the
+final optional argument isn't supported by \cs{glsfmttext}.
+
Abbreviations include acronyms (words formed from initial letters,
such as \qt{laser}),
initialisms (initial letters of a phrase, such as \qt{html}, that
@@ -4826,6 +4989,17 @@ use by the long form:
\cs{glsuselongfont}\marg{text}\marg{category}
\end{definition}
+You can't use the acronym commands provided by the base package with
+the new abbreviations provided by the \styfmt{glossaries-extra}
+package. The style commands that replace \cs{setacronymstyle},
+\cs{acrshort} etc are described in \sectionref{sec:abbrstyle}.
+The \pkgopt{acronymlists} package option and associated commands
+aren't supported. The \ics{forallacronyms} command, which iterates
+over all acronym lists, should be replaced with:
+\begin{definition}[\DescribeMacro\forallabbreviationlists]
+\cs{forallabbreviationlists}\marg{cs}\marg{body}
+\end{definition}
+
\section{Tagging Initials}
\label{sec:tagging}
@@ -4866,7 +5040,7 @@ You can later set this attribute for other categories (see
\sectionref{sec:categories}) but this must be done before the
glossary is displayed.
-The accompanying sample file \texttt{sample-mixtures.tex}
+The accompanying sample file \nolinkurl{sample-mixtures.tex}
uses initial tagging for both the \category{acronym} and
\category{abbreviation} categories:
\begin{verbatim}
@@ -5047,7 +5221,7 @@ entry was defined. If you have mixed styles, you'll need to use
\label{sec:abbrshortcuts}
The abbreviation shortcut commands can be enabled using
-the package option \pkgopt[abbreviation]{shortcuts}
+the \pkgopt[abbreviations]{shortcuts} package option
(or \pkgopt[abbr]{shortcuts}) or \pkgopt[ac]{shortcuts}.
(You can use both settings at the same time.)
The provided shortcut commands listed in
@@ -5120,7 +5294,7 @@ In both cases, the \gls{firstuse} of \ics{gls} may not match the
text produced by \ics{glsfirst} (and likewise for the plural
and case-changing versions).
-The sample file \texttt{sample-abbr-styles.tex} demonstrates all
+The sample file \nolinkurl{sample-abbr-styles.tex} demonstrates all
predefined styles described here.
\begin{important}
@@ -5131,6 +5305,15 @@ recommend that you at least use the \sty{fontenc} package with the
\pkgoptfmt{T1} option or something similar.
\end{important}
+Many of the styles have helper commands in the form
+\cs{glsxtr...name} and \cs{glsxtr...sort} that are expanded within the
+\gloskey{name} and \gloskey{sort} fields when the abbreviation is defined.
+These commands may use the helper token registers available within
+\cs{newabbreviation}, such as \ics{glsshorttok}. The contents of a
+register can be accessed with \ics{the}\meta{register}. It's essential that
+these expand when the abbreviation is defined so don't hide them behind no-expandable content if you
+redefine these helper commands.
+
The parenthetical styles, such as \abbrstyle{long-short},
use
\begin{definition}[\DescribeMacro\glsxtrparen]
@@ -6059,7 +6242,7 @@ marker may be, if the \sty{hyperref} package is used).
The inline full form uses the \meta{short}
(\meta{long}) style. The \gloskey{name} is set to the short form.
The \gloskey{description} is set to the long form. The
-\gloskey{name} key is obtained by expanding
+\gloskey{name} key is obtained by expanding:
\begin{definition}[\DescribeMacro\glsxtrfootnotename]
\cs{glsxtrfootnotename}
\end{definition}
@@ -6126,6 +6309,44 @@ use \ics{glsabbrvemfont}.
1.04, but original name retained as a deprecated synonym for
backward-compatibility.)
+\item[\abbrstyledef{short-footnote-desc}]
+(New to v1.42.)
+This is similar to \abbrstyle{short-footnote}, but the
+\gloskey{description} must be supplied by the user.
+The \gloskey{name} field is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrfootnotedescname]
+\cs{glsxtrfootnotedescname}
+\end{definition}
+which defaults to \meta{short} followed by \meta{long} in
+parentheses, and the \gloskey{sort} field is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrfootnotedescsort]
+\cs{glsxtrfootnotedescsort}
+\end{definition}
+which defaults to just the short form. (Similarly for other
+\texttt{short}\meta{modifier}\texttt{-[post]footnote}\texttt{-desc}
+styles, unless indicated otherwise.)
+
+Any redefinition of these commands must come before the abbreviations
+are defined as it expands on definition. Make sure you protect
+any commands that shouldn't be expanded. The long form can be
+referenced with \cs{the}\cs{glslongtok} and the short form
+can be referenced with \cs{the}\cs{glsshorttok}.
+
+\item[\abbrstyledef{footnote-desc}]
+A synonym for \abbrstyle{short-footnote-desc}.
+
+\item[\abbrstyledef{short-sc-footnote-desc}]
+Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{short-sm-footnote-desc}]
+Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{short-em-footnote-desc}]
+Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
\item[\abbrstyledef{short-postfootnote}]
This is similar to the \abbrstyle{short-footnote} style but doesn't modify
the category attribute. Instead it changes \postlinkcat\ to
@@ -6165,6 +6386,28 @@ use \ics{glsabbrvemfont}.
1.04, but original name retained as a deprecated synonym for
backward-compatibility.)
+\item[\abbrstyledef{short-postfootnote-desc}]
+(New to v1.42.)
+This is similar to \abbrstyle{short-postfootnote}, but the
+\gloskey{description} must be supplied by the user. The
+\gloskey{name} and \gloskey{sort} are set as for
+\abbrstyle{short-footnote-desc}.
+
+\item[\abbrstyledef{postfootnote-desc}]
+A synonym for \abbrstyle{short-postfootnote-desc}.
+
+\item[\abbrstyledef{short-sc-postfootnote-desc}]
+Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvscfont}.
+
+\item[\abbrstyledef{short-sm-postfootnote-desc}]
+Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvsmfont}.
+
+\item[\abbrstyledef{short-em-postfootnote-desc}]
+Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to
+use \ics{glsabbrvemfont}.
+
\item[\abbrstyledef{short-postlong-user}]
This style was introduced in version 1.12. It's like the
\abbrstyle{short-long-user} style but defers the parenthetical
@@ -6771,7 +7014,7 @@ use the more generic \cs{glsabbrvfont} etc which makes them easier
to adapt than the modified styles.
For further details, see the \qt{Abbreviations} section in the documented code
-(\texttt{glossaries-extra-code.pdf}).
+(\nolinkurl{glossaries-extra-code.pdf}).
\chapter{Entries in Sectioning Titles, Headers, Captions and Contents}
\label{sec:headtitle}
@@ -6800,6 +7043,8 @@ in the table of contents.
Similar problems can also occur with captions (except for the page
header and bookmark issues).
+\section{Simplistic Approach}
+
To get around all these problems, the \styfmt{glossaries} user manual
recommends using the expandable non-hyperlink commands, such as
\ics{glsentrytext} (for regular entries) or \ics{glsentryshort}
@@ -6859,14 +7104,22 @@ the argument of sectioning commands. You can still use them even
if the mark commands have been reverted, but only where they don't
conflict with the page style.
-The commands listed below all use \ics{texorpdfstring} if
-\sty{hyperref} has been loaded so that the expandable non-formatted
-version is added to the PDF bookmarks. Note that since the commands
-that convert the first letter to upper case aren't expandable, the
-non-case-changing version is used for the bookmarks.
+\section{New Commands Designed for Chapter/Section Headings}
+
+The commands listed below are designed for use in chapter or section
+headings. There are still limitations, but they provide a better
+solution. They all use \ics{texorpdfstring} if \sty{hyperref} has
+been loaded so that the expandable non-formatted version is added to
+the PDF bookmarks. Note that since the commands that convert the
+first letter to upper case aren't expandable, the non-case-changing
+version is used for the bookmarks. If the required field contains
+non-expandable (robust or fragile) commands that cause a problem for
+the bookmarks then \ics{texorpdfstring} will be needed as
+appropriate in that field. (Take care if the field has its value
+expanded before being assigned.)
These commands essentially behave as though you have used
-\cs{glsxtrshort} (or equivalent) with the options
+\cs{glsxtrshort}, \cs{glstext} etc with the options
\gloskey[glslink]{noindex} and \gloskey[glslink]{hyper\eq false}.
The text produced won't be converted to upper case in the page
headings by default. If you want the text converted to upper case
@@ -6908,6 +7161,18 @@ First letter upper case plural short form:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps singular short form:
+\begin{definition}[\DescribeMacro\GLSfmtshort]
+\cs{GLSfmtshort}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+All caps plural short form:
+\begin{definition}[\DescribeMacro\Glsfmtshortpl]
+\cs{Glsfmtshortpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
Display the long form:
\begin{definition}[\DescribeMacro\glsfmtlong]
\cs{glsfmtlong}\marg{label}
@@ -6930,9 +7195,32 @@ First letter upper case plural long form:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps singular long form:
+\begin{definition}[\DescribeMacro\GLSfmtlong]
+\cs{GLSfmtlong}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+All caps plural long form:
+\begin{definition}[\DescribeMacro\GLSfmtlongpl]
+\cs{GLSfmtlongpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
There are similar commands for the full form, but note that these
use the \emph{inline} full form, which may be different from the
-full form used by \cs{gls}.
+full form used by \cs{gls}. The PDF version has to be a simple
+fully expandable command, so one of two commands that are unrelated to the style
+is used instead:
+\begin{definition}[\DescribeMacro\glspdffmtfull]
+\cs{glspdffmtfull}\marg{label}
+\end{definition}
+for the singular form or:
+\begin{definition}[\DescribeMacro\glspdffmtfullpl]
+\cs{glspdffmtfullpl}\marg{label}
+\end{definition}
+for the full form. These simply do the long form followed by the
+short form in parentheses.
Display the full form:
\begin{definition}[\DescribeMacro\glsfmtfull]
@@ -6956,6 +7244,18 @@ First letter upper case plural full form:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps singular full form:
+\begin{definition}[\DescribeMacro\GLSfmtfull]
+\cs{GLSfmtfull}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
+All caps plural full form:
+\begin{definition}[\DescribeMacro\GLSfmtfullpl]
+\cs{GLSfmtfullpl}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
There are also equivalent commands for the value of the
\gloskey{text} field:
\begin{definition}[\DescribeMacro\glsfmttext]
@@ -6968,14 +7268,24 @@ First letter converted to upper case:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps:
+\begin{definition}[\DescribeMacro\GLSfmttext]
+\cs{GLSfmttext}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
The plural equivalents:
\begin{definition}[\DescribeMacro\glsfmtplural]
\cs{glsfmtplural}\marg{label}
\end{definition}
-and
+First letter upper case:
\begin{definition}[\DescribeMacro\Glsfmtplural]
\cs{Glsfmtplural}\marg{label}
\end{definition}
+and all caps:
+\begin{definition}[\DescribeMacro\GLSfmtplural]
+\cs{GLSfmtplural}\marg{label}
+\end{definition}
Likewise for the value of the
\gloskey{name} field:
@@ -6989,6 +7299,12 @@ First letter converted to upper case:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps:
+\begin{definition}[\DescribeMacro\GLSfmtname]
+\cs{GLSfmtname}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
Similarly for the value of the
\gloskey{first} field:
\begin{definition}[\DescribeMacro\glsfmtfirst]
@@ -7001,14 +7317,24 @@ First letter converted to upper case:
\end{definition}
(No case-change applied to PDF bookmarks.)
+All caps:
+\begin{definition}[\DescribeMacro\GLSfmtfirst]
+\cs{GLSfmtfirst}\marg{label}
+\end{definition}
+(No case-change applied to PDF bookmarks.)
+
The plural equivalents:
\begin{definition}[\DescribeMacro\glsfmtfirstpl]
\cs{glsfmtfirstpl}\marg{label}
\end{definition}
-and
+First letter upper case:
\begin{definition}[\DescribeMacro\Glsfmtfirstpl]
\cs{Glsfmtfirstpl}\marg{label}
\end{definition}
+and all caps:
+\begin{definition}[\DescribeMacro\GLSfmtfirstpl]
+\cs{GLSfmtfirstpl}\marg{label}
+\end{definition}
\chapter{Categories}
\label{sec:categories}
@@ -7254,61 +7580,6 @@ overridden. \emph{This setting is incompatible with \catattr{aposplural}.} This
defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
\cs{newabbreviation}.)
-\item[\catattrdef{accessinsertdots}] If this attribute is set to
-\qt{true} and the \sty{glossaries-accsupp} package has been loaded
-(with the \pkgopt{accsupp} option), then this behaves like
-\catattr{insertdots} but for the \gloskey{shortaccess} field instead
-of the \gloskey{short} field. This can be used to assist the
-screen reader for initialisms that should be read out letter by
-letter rather than as a word. For example:
-\begin{verbatim}
-\glssetcategoryattribute{initialism}{accessinsertdots}{true}
-
-\newabbreviation[category=initialism]{pi}{PI}{Private Investigator}
-\end{verbatim}
-This setting will be overridden by an explicit use of
-the \gloskey{shortaccess} key in the optional argument
-of \cs{newabbreviation} (or \cs{newacronym}). This attribute is only applicable to entries
-defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
-\cs{newabbreviation}.)
-
-\item[\catattrdef{nameshortaccess}] If this attribute is set to
-\qt{true}, the \gloskey{access} field (used for the \gloskey{name}
-field's accessibility support) is set to the \gloskey{shortaccess}
-value. This attribute has no effect if there's no accessibility
-support or if the \gloskey{shortaccess} field hasn't been assigned
-or if the \gloskey{access} field is used explicitly. This attribute is only applicable to entries
-defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
-\cs{newabbreviation}.)
-
-\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess}
-but applies to the \gloskey{textaccess} field (for use with
-regular abbreviations).
-
-\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess}
-but applies to the \gloskey{firstaccess} field (for use with
-regular abbreviations).
-
-\item[\catattrdef{accessaposplural}] This boolean attribute overrides
-\catattr{aposplural} for the \gloskey{shortpluralaccess} key.
-Has no effect if there's no accessibility support or if
-the \gloskey{shortaccess} key hasn't been set or if the
-\gloskey{shortpluralaccess} key is explicitly set. If
-the \catattr{aposplural} is set and this attribute isn't set
-and the \gloskey{shortaccess} key is set, then the
-\catattr{aposplural} setting governs the default
-\gloskey{shortpluralaccess} setting. If you want
-\catattr{aposplural} but don't want it applied to the accessibility
-support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries
-defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
-\cs{newabbreviation}.)
-
-\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides
-\catattr{noshortplural} for the \gloskey{shortpluralaccess} key.
-The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries
-defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
-\cs{newabbreviation}.)
-
\item[\catattrdef{headuc}] If this attribute is set to \qt{true},
commands like \ics{glsfmtshort} will use the upper case version
in the page headers.
@@ -7408,6 +7679,10 @@ Remember that glossary styles may additionally apply a font change,
such as the list styles which put the name in the optional argument
of \cs{item}.
+\item[\catattrdef{glosssymbolfont}] (New to version 1.42.)
+This is similar to \catattr{glossnamefont} and
+\catattr{glossdescfont} but is used by \ics{glossentrysymbol}.
+
\item[\catattrdef{textformat}] (New to version 1.21.)
Commands like \cs{gls} and \cs{glstext} have the link text
encapsulated in the argument of \cs{glstextformat} by default. If
@@ -7498,6 +7773,70 @@ external sources and doesn't require this attribute.
\end{description}
+If a term is defined using \ics{newabbreviation} and accessibility
+support has been supplied via the \pkgopt{accsupp} package option
+then the following attributes are also available. If
+\gloskey{shortaccess} isn't set its value will be obtained from:
+\begin{definition}[\DescribeMacro\glsdefaultshortaccess]
+\cs{glsdefaultshortaccess}\marg{short}\marg{long}
+\end{definition}
+This is defined by \sty{glossaries-accsupp} to just do \meta{long}
+but \sty{glossaries-extra} redefines it to do \meta{long}
+(\meta{short}). The \catattr{accessinsertdots},
+\catattr{accessaposplural} and \catattr{accessnoshortplural}
+attributes below refer to the \meta{short} form that's passed to
+this command.
+
+The following attributes are only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}). They have no effect if the \pkgopt{accsupp}
+package option hasn't been used.
+
+\begin{description}
+\item[\catattrdef{accessinsertdots}] If this attribute is set to
+\qt{true} and the \sty{glossaries-accsupp} package has been loaded
+(with the \pkgopt{accsupp} option), then this behaves like
+\catattr{insertdots} but for the \meta{short} part used in the \gloskey{shortaccess} field instead
+of the \gloskey{short} field.
+This setting will be overridden by an explicit use of
+the \gloskey{shortaccess} key in the optional argument
+of \cs{newabbreviation} (or \cs{newacronym}).
+
+\item[\catattrdef{accessaposplural}] This boolean attribute overrides
+\catattr{aposplural} for the \gloskey{shortpluralaccess} key.
+Has no effect if there's no accessibility support or if
+the \gloskey{shortaccess} key hasn't been set or if the
+\gloskey{shortpluralaccess} key is explicitly set. If
+the \catattr{aposplural} is set and this attribute isn't set
+and the \gloskey{shortaccess} key is set, then the
+\catattr{aposplural} setting governs the default
+\gloskey{shortpluralaccess} setting. If you want
+\catattr{aposplural} but don't want it applied to the accessibility
+support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides
+\catattr{noshortplural} for the \gloskey{shortpluralaccess} key.
+The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries
+defined using \cs{newabbreviation} (or \cs{newacronym} if it's using
+\cs{newabbreviation}.)
+
+\item[\catattrdef{nameshortaccess}] If this attribute is set to
+\qt{true}, the \gloskey{access} field (used for the \gloskey{name}
+field's accessibility support) automatically assigned if it's not
+provided.
+
+\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess}
+but applies to the \gloskey{textaccess} field automatically assigned if it's not
+provided.
+
+\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess}
+but applies to the \gloskey{firstaccess} field automatically assigned if it's not
+provided.
+
+\end{description}
+
An attribute can be set using:
\begin{definition}[\DescribeMacro\glssetcategoryattribute]
\cs{glssetcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value}
@@ -8374,120 +8713,6 @@ Set the escape (quote) character to \meta{char}.
\end{definition}
Set the encap character to \meta{char}.
-\chapter{On-the-Fly Document Definitions}
-\label{sec:onthefly}
-
-\begin{important}
-The commands described here may superficially look like
-\meta{word}\cs{index}\marg{word}, but they behave rather
-differently. If you want to use \cs{index} then just use
-\cs{index}.
-\end{important}
-
-The \styfmt{glossaries} package advises against defining entries
-in the \env{document} environment. As mentioned in
-\sectionref{sec:pkgopts} above, this ability is disabled by
-default with \styfmt{glossaries-extra} but can be enabled using
-the \pkgopt{docdefs} package options.
-
-Although this can be problematic, the \styfmt{glossaries-extra}
-package provides a way of defining and using entries within
-the \env{document} environment without the tricks used with the
-\pkgopt{docdefs} option. \emph{There are limitations with this
-approach, so take care with it.} This function is disabled by
-default, but can be enabled using the preamble-only command:
-\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly]
-\cs{GlsXtrEnableOnTheFly}
-\end{definition}
-When used, this defines the commands described below.
-
-\begin{important}
-The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr}
-and \cs{Glsxtrpl} can't be used after the glossaries have been
-displayed (through \ics{printglossary} etc). It's best not to mix
-these commands with the standard glossary commands, such
-as \cs{gls} or there may be unexpected results.
-\end{important}
-
-\begin{definition}[\DescribeMacro\glsxtr]
-\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
-\end{definition}
-If an entry with the label \meta{label} has already been defined,
-this just does \cs{gls}\oarg{gls-options}\marg{label}. If
-\meta{label} hasn't been defined, this will define the entry
-using:
-\begin{alltt}
-\cs{newglossaryentry}\marg{label}\{name=\marg{label},
- category=\cs{glsxtrcat},
- description=\{\cs{nopostdesc}\},
- \meta{dfn-options}\}
-\end{alltt}
-
-\begin{important}
-The \meta{label} must contain any non-expandable commands, such as
-formatting commands or problematic characters.
-If the term requires any of these, they must be omitted from the
-\meta{label} and placed in the \gloskey{name} key must be provided
-in the optional argument \meta{dfn-options}.
-\end{important}
-
-The second optional argument \meta{dfn-options} should be empty
-if the entry has already been defined, since it's too late for
-them. If it's not empty, a~warning will be generated with
-\begin{definition}[\DescribeMacro\GlsXtrWarning]
-\cs{GlsXtrWarning}\marg{dfn-options}\marg{label}
-\end{definition}
-
-For example, this warning will be generated on the second instance
-of \cs{glsxtr} below:
-\begin{verbatim}
-\glsxtr[][plural=geese]{goose}
-% ... later
-\glsxtr[][plural=geese]{goose}
-\end{verbatim}
-
-If you are considering doing something like:
-\begin{verbatim}
-\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}}
-\renewcommand*{\GlsXtrWarning}[2]{}
-% ... later
-\goose\ some more text here
-\end{verbatim}
-then don't bother. It's simpler and less problematic to just
-define the entries in the preamble with \ics{newglossaryentry}
-and then use \cs{gls} in the document.
-
-There are plural and case-changing alternatives to \cs{glsxtr}:
-\begin{definition}[\DescribeMacro\glsxtrpl]
-\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
-\end{definition}
-This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}.
-
-\begin{definition}[\DescribeMacro\Glsxtr]
-\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
-\end{definition}
-This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}.
-
-\begin{definition}[\DescribeMacro\Glsxtrpl]
-\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
-\end{definition}
-This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}.
-
-If you use UTF-8 and don't want the inconvenient of needing
-to use an ASCII-only label, then it's better to use
-\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX).
-If you really desperately want to use UTF-8 entry labels without
-switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred
-version of \cs{GlsXtrEnableOnTheFly} that allows you to
-use UTF-8 characters in \meta{label}, but it's experimental and
-may not work in some cases.
-
-\begin{important}
-If you use the starred version of \cs{GlsXtrEnableOnTheFly}
-don't use any commands in the \meta{label}, even if they expand
-to just text.
-\end{important}
-
\chapter{\appfmt{bib2gls}: Managing Reference Databases}
\label{sec:bib2gls}
@@ -8922,6 +9147,11 @@ the associated glossary: \ics{printunsrtabbreviations},
\ics{printunsrtacronyms}, \ics{printunsrtsymbols},
\ics{printunsrtnumbers} and \ics{printunsrtindex}.
+The \pkgopt{savenumberlist} package option doesn't have any effect
+with \gls{bib2gls}. The location lists are saved by default, so
+\sty{glossaries-extra-bib2gls} patches \ics{glsentrynumberlist} and
+\ics{glsdisplaynumberlist} to work with the \gloskey{location} field
+
\begin{definition}[\DescribeMacro\glsxtrprovidecommand]
\cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition}
\end{definition}
@@ -10612,10 +10842,15 @@ you can use
\begin{definition}[\DescribeMacro\glsxtrentryfmt]
\cs{glsxtrentryfmt}\marg{label}\marg{text}
\end{definition}
-This uses \cs{texorpdfstring} and will simply expand to \meta{text}
+If \sty{hyperref} is used, this uses \cs{texorpdfstring} and will expand to
+\begin{definition}[\DescribeMacro\glsxtrpdfentryfmt]
+\cs{glsxtrpdfentryfmt}\marg{label}\marg{text}
+\end{definition}
within the PDF bookmarks, but in the document it will do
\meta{cs}\marg{text} if a control sequence name has been provided
-or just \meta{text} otherwise.
+or just \meta{text} otherwise. The PDF bookmark version simply does
+\meta{text}. It may be redefined, but remember that it needs to
+expand fully.
The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to
add new keys. This command will cause an error if the key has
@@ -10801,6 +11036,30 @@ use:
Again, version 1.39 introduced a starred form of these commands,
which use the starred form of \cs{glsxtrifhasfield}.
+As from v1.42, you can test if the field value is contained in a
+comma-separated list with:
+\begin{definition}[\DescribeMacro\GlsXtrIfFieldValueInCsvList]
+\cs{GlsXtrIfFieldValueInCsvList}\marg{label}\marg{field}\marg{list}\marg{true}\marg{false}
+\end{definition}
+The unstarred version uses the unstarred form of
+\cs{glsxtrifhasfield} (which adds grouping so \meta{true} and
+\meta{false} will be localised). The starred version uses
+\cs{glsxtrifhasfield*}. If the field value (without expansion) is
+contained in \meta{list} then \meta{true} is done otherwise
+\meta{false} is done. If the field hasn't been set \meta{false} is
+done. This internally uses \cs{DTLifinlist} provided by
+\sty{datatool-base} which performs a one level expansion on
+\meta{list}. See the \sty{datatool} documentation for further
+details.
+
+This command is intended for fields that contain a label. For
+example, to test if the category is one of a set of labels:
+\begin{verbatim}
+\GlsXtrIfFieldValueInCsvList{examplelabel}{category}%
+ {abbreviation,acronym}% set of labels
+ {true part}{false part}
+\end{verbatim}
+
As from v1.31, if a field represents a numeric (integer) value, you
can use the following two numeric tests. If the field is set, it must
expand to an integer. You may use \cs{glscurrentfieldvalue}
@@ -10883,7 +11142,36 @@ or
\cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler}
\end{definition}
that internally use \cs{dolistcsloop} and \cs{forlistloop},
-respectively.
+respectively. You can use \ics{listbreak} to break out of the loop
+(see the \sty{etoolbox} manual for further details).
+
+For fields that contain comma-separated lists use
+\cs{glsxtrforcsvfield} instead.
+
+New to v1.42:
+\begin{definition}[\DescribeMacro\glsxtrfieldformatlist]
+\cs{glsxtrfieldformatlist}\marg{label}\marg{field}
+\end{definition}
+Like \sty{datatool-base}'s \ics{DTLformatlist}, this iterates over
+an (\sty{etoolbox}) internal list and formats each item. Uses all
+the same helper commands as \cs{DTLformatlist} (the same list handler
+macro is used). Unlike the \sty{datatool-base} command, this command
+has no starred version. Grouping is automatically applied.
+
+For example, with \gls{bib2gls}['s] \texttt{save-child-count}
+resource option:
+\begin{verbatim}
+\newcommand*{\listchildren}[1]{%
+ \GlsXtrIfFieldNonZero{childcount}{#1}%
+ {child count: \glscurrentfieldvalue; children:
+ \let\DTLlistformatitem\glsfmtname
+ \glsxtrfieldformatlist{#1}{childlist}%
+ }%
+ {no children}%
+}
+\end{verbatim}
+For fields that contain a comma-separated list use \cs{glsxtrfieldformatcsvlist}
+instead.
There are also commands that use \cs{ifinlistcs}:
\begin{definition}[\DescribeMacro\glsxtrfieldifinlist]
@@ -10920,6 +11208,13 @@ which is just a synonym for \cs{@endfortrue}.
The loop is performed within the true part of \cs{glsxtrifhasfield}
so scoping is automatically applied.
+New to v1.42:
+\begin{definition}[\DescribeMacro\glsxtrfieldformatcsvlist]
+\cs{glsxtrfieldformatcsvlist}\marg{label}\marg{field}
+\end{definition}
+Like \cs{glsxtrfieldformatcsvlist} but for fields that contain
+comma-separated lists.
+
As from version 1.32, if the field given by
\begin{definition}[\DescribeMacro\GlsXtrForeignTextField]
\cs{GlsXtrForeignTextField}
@@ -11572,6 +11867,120 @@ The value of the \gloskey{alias} field can be accessed using
\cs{glsxtralias}\marg{label}
\end{definition}
+\chapter{On-the-Fly Document Definitions}
+\label{sec:onthefly}
+
+\begin{important}
+The commands described here may superficially look like
+\meta{word}\cs{index}\marg{word}, but they behave rather
+differently. If you want to use \cs{index} then just use
+\cs{index}.
+\end{important}
+
+The \styfmt{glossaries} package advises against defining entries
+in the \env{document} environment. As mentioned in
+\sectionref{sec:pkgopts} above, this ability is disabled by
+default with \styfmt{glossaries-extra} but can be enabled using
+the \pkgopt{docdefs} package options.
+
+Although this can be problematic, the \styfmt{glossaries-extra}
+package provides a way of defining and using entries within
+the \env{document} environment without the tricks used with the
+\pkgopt{docdefs} option. \emph{There are limitations with this
+approach, so take care with it.} This function is disabled by
+default, but can be enabled using the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly]
+\cs{GlsXtrEnableOnTheFly}
+\end{definition}
+When used, this defines the commands described below.
+
+\begin{important}
+The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr}
+and \cs{Glsxtrpl} can't be used after the glossaries have been
+displayed (through \ics{printglossary} etc). It's best not to mix
+these commands with the standard glossary commands, such
+as \cs{gls} or there may be unexpected results.
+\end{important}
+
+\begin{definition}[\DescribeMacro\glsxtr]
+\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+If an entry with the label \meta{label} has already been defined,
+this just does \cs{gls}\oarg{gls-options}\marg{label}. If
+\meta{label} hasn't been defined, this will define the entry
+using:
+\begin{alltt}
+\cs{newglossaryentry}\marg{label}\{name=\marg{label},
+ category=\cs{glsxtrcat},
+ description=\{\cs{nopostdesc}\},
+ \meta{dfn-options}\}
+\end{alltt}
+
+\begin{important}
+The \meta{label} must contain any non-expandable commands, such as
+formatting commands or problematic characters.
+If the term requires any of these, they must be omitted from the
+\meta{label} and placed in the \gloskey{name} key must be provided
+in the optional argument \meta{dfn-options}.
+\end{important}
+
+The second optional argument \meta{dfn-options} should be empty
+if the entry has already been defined, since it's too late for
+them. If it's not empty, a~warning will be generated with
+\begin{definition}[\DescribeMacro\GlsXtrWarning]
+\cs{GlsXtrWarning}\marg{dfn-options}\marg{label}
+\end{definition}
+
+For example, this warning will be generated on the second instance
+of \cs{glsxtr} below:
+\begin{verbatim}
+\glsxtr[][plural=geese]{goose}
+% ... later
+\glsxtr[][plural=geese]{goose}
+\end{verbatim}
+
+If you are considering doing something like:
+\begin{verbatim}
+\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}}
+\renewcommand*{\GlsXtrWarning}[2]{}
+% ... later
+\goose\ some more text here
+\end{verbatim}
+then don't bother. It's simpler and less problematic to just
+define the entries in the preamble with \ics{newglossaryentry}
+and then use \cs{gls} in the document.
+
+There are plural and case-changing alternatives to \cs{glsxtr}:
+\begin{definition}[\DescribeMacro\glsxtrpl]
+\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\Glsxtr]
+\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\Glsxtrpl]
+\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label}
+\end{definition}
+This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}.
+
+If you use UTF-8 and don't want the inconvenient of needing
+to use an ASCII-only label, then it's better to use
+\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX).
+If you really desperately want to use UTF-8 entry labels without
+switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred
+version of \cs{GlsXtrEnableOnTheFly} that allows you to
+use UTF-8 characters in \meta{label}, but it's experimental and
+may not work in some cases.
+
+\begin{important}
+If you use the starred version of \cs{GlsXtrEnableOnTheFly}
+don't use any commands in the \meta{label}, even if they expand
+to just text.
+\end{important}
+
\chapter{Supplemental Packages}
\label{sec:supplemental}
@@ -11611,6 +12020,11 @@ Next use: \pgls{svm}.
\section{Accessibility Support}
\label{sec:accsupp}
+\begin{important}
+The \sty{glossaries-accsupp} package is still experimental and so
+accessibility features are liable to change.
+\end{important}
+
The \sty{glossaries-accsupp} package needs to be loaded before
\styfmt{glossaries-extra} or through the \pkgopt{accsupp} package
option:
@@ -11621,7 +12035,9 @@ If you don't load \sty{glossaries-accsupp} or you load
\sty{glossaries-accsupp} after \styfmt{glossaries-extra}
the new \cs{glsaccess}\meta{xxx} commands described below will
simply be equivalent to the corresponding \cs{glsentry}\meta{xxx}
-commands.
+commands. Other accessibility features, such as the attributes used
+by \ics{newabbreviation} also won't work if \sty{glossaries-accsupp}
+is loaded too late.
The following \cs{glsaccess}\meta{xxx} commands add accessibility information wrapped around
the corresponding \cs{glsentry}\meta{xxx} commands. There is
@@ -11978,7 +12394,7 @@ shouldn't appear in the final draft of your document.
The \styfmt{glossaries-extra} package has the facility to load
language modules (whose filename is in the form
-\texttt{glossariesxtr-}\meta{language}\texttt{.ldf}) if they exist,
+\texttt{glossariesxtr\dhyphen}\meta{language}\texttt{.ldf}) if they exist,
but won't warn if they don't. If \sty{glossaries-extra-bib2gls} is
loaded via the \pkgopt{record} package option then the check for
language resource files will additionally search for an associated
@@ -11991,9 +12407,9 @@ dialect file.
If you want to write your own language module, you just need to
create a file called
-\texttt{glossariesxtr-}\meta{lang}\texttt{.ldf}, where \meta{lang}
+\texttt{glossariesxtr\dhyphen}\meta{lang}\texttt{.ldf}, where \meta{lang}
identifies the language or dialect (see the \sty{tracklang}
-package). For example, \texttt{glossariesxtr-french.ldf}.
+package). For example, \nolinkurl{glossariesxtr-french.ldf}.
The simplest code for this file is:
\begin{verbatim}
@@ -12107,8 +12523,6 @@ This produces the following text in English:
\cs{GlsXtrNoGlsWarningBuildInfo}
\end{definition}
This is advice on how to generate the glossary files.
-See the documented code (\texttt{glossaries-extra-code.pdf})
-for further details.
\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningAutoMake]
\cs{GlsXtrNoGlsWarningAutoMake}\marg{label}
@@ -12117,7 +12531,9 @@ This is the message produced when the \pkgopt{automake} option
is used, but the document needs a rerun or the shell escape
setting doesn't permit the execution of the external application.
This command also generates a warning in the transcript file.
-See the documented code for further details.
+
+See the documented code (\nolinkurl{glossaries-extra-code.pdf})
+for further details.
\printglossaries
\PrintIndex