summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex2710
1 files changed, 2590 insertions, 120 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
index 5f47addf84..44d5314dad 100644
--- a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
+++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
@@ -17,6 +17,7 @@
\makeatother
\usepackage{alltt}
+\usepackage[normalem]{ulem}
\usepackage{hologo}
\usepackage[colorlinks,
hyperindex=false,
@@ -28,6 +29,20 @@ package},
\makeglossaries
+\makeatletter
+\@nlctdoc@if@usingtexht
+ {
+ \newcommand{\headingsty}[1]{#1}
+ \newcommand{\headingcs}[1]{#1}
+ \newcommand{\headingapp}[1]{#1}
+ }
+ {
+ \newcommand{\headingsty}[1]{\styfmt{#1}}
+ \newcommand{\headingcs}[1]{\cs{#1}}
+ \newcommand{\headingapp}[1]{\appfmt{#1}}
+ }
+\makeatother
+
\GlsXtrEnableEntryUnitCounting{general}{0}{page}
\renewcommand*{\glsxtrifcounttrigger}[3]{#3}
@@ -225,13 +240,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.47:
+ \title{glossaries-extra.sty v1.48:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2021-11-04}
+ \date{2021-11-22}
\maketitle
\begin{abstract}
@@ -587,6 +602,29 @@ file for \gls{makeindex} or \gls{xindy}.
The \pkgopt[all]{debug} option implements both \pkgopt[showtargets]{debug}
and \pkgopt[showwrgloss]{debug}.
+\item[{\pkgoptdef{showtargets}}] This implements
+\pkgopt[showtargets]{debug} and can also adjust the way the targets
+are shown. By default, any links that occur in \TeX's \qt{outer}
+mode are placed in the margin according to \ics{glsshowtargetouter}
+(provided by the base \styfmt{glossaries} package). This can lead to
+the \qt{too many floats} error if there are multiple instances of
+commands like \cs{gls} in a single line. This option provides a way
+of changing this to an in-line annotation. Available values:
+\begin{description}
+\item[\optfmt{left}] A marker is placed to the left of the
+link/target and a marginal note is used in outer mode;
+\item[\optfmt{right}] A marker is placed to the right of the
+link/target and a marginal note is used in outer mode;
+\item[\optfmt{innerleft}] A marker and annotation are placed to the left of the
+link/target in all modes;
+\item[\optfmt{innerright}] A marker and annotation are placed to the
+right of the link/target in all modes;
+\item[\optfmt{annoteleft}] Markers are placed on either side of the
+link/target and the annotation is on the left;
+\item[\optfmt{annoteright}] Markers are placed on either side of the
+link/target and the annotation is on the right.
+\end{description}
+
\item[{\pkgoptdef{postdot}}] (New to version 1.12.)
This option is just a shortcut for \pkgopt[false]{nopostdot}.
@@ -988,74 +1026,75 @@ See the \gls{bib2gls} documentation for the
\cs{newglossaryentry}. It was originally a boolean option,
but as from version 1.06, it can now take one of the following values (if
the value is omitted, \pkgoptfmt{true} is assumed):
-\begin{itemize}
-\item[{\pkgopt[false]{docdef}}] \ics{newglossaryentry} is not
-permitted in the \env{document} environment (default).
-
-\item[{\pkgopt[true]{docdef}}] \cs{newglossaryentry} behaves as it
-does in the base \styfmt{glossaries} package. That is, where
-its use is permitted in the \env{document} environment, it
-uses the \texttt{.glsdefs} temporary file to store the entry
-definitions so that on the next \LaTeX\ run the entries are
-defined at the beginning of the \env{document} environment.
-This allows the entry information to be referenced in the glossary,
-even if the glossary occurs before \cs{newglossaryentry}.
-(For example, when the glossary is displayed in the front matter.)
-This method of saving the definitions for the next \LaTeX\ run
-has drawbacks that are detailed in the \styfmt{glossaries} user
-manual.
-
-Remember that if \cs{newglossaryentry} wouldn't be allowed
-in the \env{document} environment with the
-base \styfmt{glossaries} package, then it still won't
-be allowed with \pkgopt[true]{docdefs}.
-If your glossaries occur at the end of the document, consider using
-\pkgopt[restricted]{docdef} instead.
-
-\item[{\pkgopt[restricted]{docdef}}] (new to version 1.06)
-\ics{newglossaryentry} is permitted in the \env{document}
-environment without using the \texttt{.glsdefs} file. This means
-that all entries must be defined before the glossary is displayed,
-but it avoids the complications associated with saving the
-entry details in a temporary file. You will still need to take
-care about any changes made to characters that are required
-by the \meta{key}=\meta{value} mechanism (that is, the comma and
-equal sign) and any \gls{makeindex} or \gls{xindy} character that
-occurs in the \gloskey{sort} key or label. If any of those
-characters are made active in the document, then it can cause
-problems with the entry definition. This option will allow
-\cs{newglossaryentry} to be used in the document with
-\cs{makenoidxglossaries}, but note that \cs{longnewglossaryentry}
-remains a preamble-only command.
-
-With this option, if an entry appears in the glossary before
-it has been defined, an error will occur (or a warning if
-the \pkgopt[warn]{undefaction} option is used.) If you edit your
-document and either remove an entry or change its label, you may
-need to delete the document's temporary files (such as the
-\texttt{.aux} and \texttt{.gls} files).
-
-\item[{\pkgopt[atom]{docdef}}] (new to version 1.34)
-This option behaves like \pkgopt[restricted]{docdef} but creates the
-\texttt{.glsdefs} file for
-\href{https://atom.io/packages/autocomplete-glossaries}{atom's
-autocomplete support}. This file isn't input by
-\styfmt{glossaries-extra} and so associated problems with the use of
-this file are avoided, but it allows the autocomplete support to
-find the labels in the file. As with \pkgopt[restricted]{docdef},
-entries may be defined in the preamble or anywhere in the document,
-but they may only be referenced after they have been defined.
-Entries must be defined before the associated glossary is displayed.
-
-If you need a list of all entry labels for the use of an editor or
-helper script you may also want to consider the package options
-\pkgopt{writeglslabels} and \pkgopt{writeglslabelnames} provided by
-the base \sty{glossaries} package. Note that with these options
-and \pkgopt[atom]{docdef}, only the entry labels visible to \LaTeX\ can
-be saved. So if you are using \gls{bib2gls} you will only get the
-labels of the entries that are selected by \gls{bib2gls}.
-\end{itemize}
+ \begin{itemize}
+ \item {\pkgopt[false]{docdef}}: \ics{newglossaryentry} is not
+ permitted in the \env{document} environment (default).
+
+ \item {\pkgopt[true]{docdef}}: \cs{newglossaryentry} behaves as it
+ does in the base \styfmt{glossaries} package. That is, where
+ its use is permitted in the \env{document} environment, it
+ uses the \texttt{.glsdefs} temporary file to store the entry
+ definitions so that on the next \LaTeX\ run the entries are
+ defined at the beginning of the \env{document} environment.
+ This allows the entry information to be referenced in the glossary,
+ even if the glossary occurs before \cs{newglossaryentry}.
+ (For example, when the glossary is displayed in the front matter.)
+ This method of saving the definitions for the next \LaTeX\ run
+ has drawbacks that are detailed in the \styfmt{glossaries} user
+ manual.
+
+ Remember that if \cs{newglossaryentry} wouldn't be allowed
+ in the \env{document} environment with the
+ base \styfmt{glossaries} package, then it still won't
+ be allowed with \pkgopt[true]{docdefs}.
+ If your glossaries occur at the end of the document, consider using
+ \pkgopt[restricted]{docdef} instead.
+
+ \item {\pkgopt[restricted]{docdef}}: (new to version 1.06)
+ \ics{newglossaryentry} is permitted in the \env{document}
+ environment without using the \texttt{.glsdefs} file. This means
+ that all entries must be defined before the glossary is displayed,
+ but it avoids the complications associated with saving the
+ entry details in a temporary file. You will still need to take
+ care about any changes made to characters that are required
+ by the \meta{key}=\meta{value} mechanism (that is, the comma and
+ equal sign) and any \gls{makeindex} or \gls{xindy} character that
+ occurs in the \gloskey{sort} key or label. If any of those
+ characters are made active in the document, then it can cause
+ problems with the entry definition. This option will allow
+ \cs{newglossaryentry} to be used in the document with
+ \cs{makenoidxglossaries}, but note that \cs{longnewglossaryentry}
+ remains a preamble-only command.
+
+ With this option, if an entry appears in the glossary before
+ it has been defined, an error will occur (or a warning if
+ the \pkgopt[warn]{undefaction} option is used.) If you edit your
+ document and either remove an entry or change its label, you may
+ need to delete the document's temporary files (such as the
+ \texttt{.aux} and \texttt{.gls} files).
+
+ \item {\pkgopt[atom]{docdef}}: (new to version 1.34)
+ This option behaves like \pkgopt[restricted]{docdef} but creates the
+ \texttt{.glsdefs} file for
+ \href{https://atom.io/packages/autocomplete-glossaries}{atom's
+ autocomplete support}. This file isn't input by
+ \styfmt{glossaries-extra} and so associated problems with the use of
+ this file are avoided, but it allows the autocomplete support to
+ find the labels in the file. As with \pkgopt[restricted]{docdef},
+ entries may be defined in the preamble or anywhere in the document,
+ but they may only be referenced after they have been defined.
+ Entries must be defined before the associated glossary is displayed.
+
+ If you need a list of all entry labels for the use of an editor or
+ helper script you may also want to consider the package options
+ \pkgopt{writeglslabels} and \pkgopt{writeglslabelnames} provided by
+ the base \sty{glossaries} package. Note that with these options
+ and \pkgopt[atom]{docdef}, only the entry labels visible to \LaTeX\ can
+ be saved. So if you are using \gls{bib2gls} you will only get the
+ labels of the entries that are selected by \gls{bib2gls}.
+
+ \end{itemize}
The \styfmt{glossaries} package allows
\cs{newglossaryentry} within the \env{document} environment (when
@@ -1206,50 +1245,52 @@ which uses \ics{printunsrtglossary}.
\item[{\pkgoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package
option of the same name, this option isn't boolean but has multiple
values:
-\begin{itemize}
-\item \pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}):
-set the shortcuts provided by the \styfmt{glossaries} package for
-acronyms (such as \cs{ac}). Note that the short and long forms don't
-use \cs{glsxtrshort} and \cs{glsxtrlong} but use the original
-\cs{acrshort} and \cs{acrlong}, which don't recognise multiple
-abbreviation styles. The better option with \styfmt{glossaries-extra}
-is \pkgopt[ac]{shortcuts}.
-
-\item \pkgopt[ac]{shortcuts}:
-set the shortcuts provided by the \styfmt{glossaries} package for
-acronyms (such as \cs{ac}) but uses the \styfmt{glossaries-extra}
-interface (such as \cs{glsxtrshort} rather than \cs{acrshort}).
-In this case \cs{ac} is defined as \cs{cgls} rather than
-\cs{gls}.
-
-\item \pkgopt[abbreviations]{shortcuts} (or
-\pkgopt[abbr]{shortcuts}):
-set the abbreviation shortcuts provided by \styfmt{glossaries-extra}. (See
-\sectionref{sec:abbrshortcuts}.) These settings don't switch on the
-acronym shortcuts provided by the \styfmt{glossaries} package.
-
-\item \pkgopt[other]{shortcuts}: set the \qt{other}
-shortcut commands, but not the shortcut commands for abbreviations
-or the acronym shortcuts provided by \styfmt{glossaries}.
-The \qt{other} shortcuts are:
-\begin{itemize}
-\item \ics{newentry} equivalent to \ics{newglossaryentry}
-\item \ics{newsym} equivalent to \ics{glsxtrnewsymbol} (see the
-\pkgopt{symbols} option).
-\item \ics{newnum} equivalent to \ics{glsxtrnewnumber} (see the
-\pkgopt{numbers} option).
-\end{itemize}
-
-\item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}):
-implements \pkgopt[ac]{shortcuts}, \pkgopt[abbreviations]{shortcuts}
-and \pkgopt[other]{shortcuts}.
+ \begin{itemize}
+ \item \pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}):
+ set the shortcuts provided by the \styfmt{glossaries} package for
+ acronyms (such as \cs{ac}). Note that the short and long forms don't
+ use \cs{glsxtrshort} and \cs{glsxtrlong} but use the original
+ \cs{acrshort} and \cs{acrlong}, which don't recognise multiple
+ abbreviation styles. The better option with \styfmt{glossaries-extra}
+ is \pkgopt[ac]{shortcuts}.
+
+ \item \pkgopt[ac]{shortcuts}:
+ set the shortcuts provided by the \styfmt{glossaries} package for
+ acronyms (such as \cs{ac}) but uses the \styfmt{glossaries-extra}
+ interface (such as \cs{glsxtrshort} rather than \cs{acrshort}).
+ In this case \cs{ac} is defined as \cs{cgls} rather than
+ \cs{gls}.
+
+ \item \pkgopt[abbreviations]{shortcuts} (or
+ \pkgopt[abbr]{shortcuts}):
+ set the abbreviation shortcuts provided by \styfmt{glossaries-extra}. (See
+ \sectionref{sec:abbrshortcuts}.) These settings don't switch on the
+ acronym shortcuts provided by the \styfmt{glossaries} package.
+
+ \item \pkgopt[other]{shortcuts}: set the \qt{other}
+ shortcut commands, but not the shortcut commands for abbreviations
+ or the acronym shortcuts provided by \styfmt{glossaries}.
+ The \qt{other} shortcuts are:
+ \begin{itemize}
+ \item \ics{newentry} equivalent to \ics{newglossaryentry}
+ \item \ics{newsym} equivalent to \ics{glsxtrnewsymbol} (see the
+ \pkgopt{symbols} option).
+ \item \ics{newnum} equivalent to \ics{glsxtrnewnumber} (see the
+ \pkgopt{numbers} option).
+ \end{itemize}
+
+ \item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}):
+ implements \pkgopt[ac]{shortcuts}, \pkgopt[abbreviations]{shortcuts}
+ and \pkgopt[other]{shortcuts}.
+
+ \item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}):
+ don't define any of the shortcut commands (default).
-\item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}):
-don't define any of the shortcut commands (default).
-\end{itemize}
+ \end{itemize}
Note that multiple invocations of the \pkgopt{shortcuts} option
\emph{within the same option list} will override each other.
+
\end{description}
After the \styfmt{glossaries-extra} package has been loaded, you can
@@ -1265,6 +1306,7 @@ after \ics{makenoidxglossaries}.
\label{sec:modifications}
\section{Defining Entries}
+\label{sec:definingentries}
The \styfmt{glossaries} package provides \ics{nopostdesc}
which may be used in the \gloskey{description} to suppress
@@ -2536,6 +2578,7 @@ complex formatting or if the field value contains problematic
content.
\section{Plurals}
+\label{sec:plurals}
Some languages, such as English, have a general rule that plurals
are formed from the singular with a suffix appended. This isn't
@@ -2755,6 +2798,7 @@ they may be directed to the SHTML entry in the glossary.
For these reasons it's better to use the simple expandable commands like
\ics{glsentrytext} or \ics{glsentryshort} in the definition
of other entries (although that doesn't fix the first problem).
+
Alternatively use something like:
\begin{verbatim}
\newacronym
@@ -2787,7 +2831,11 @@ This will pick up the font style setting of the outer entry (shtml,
in the above case). This isn't a problem in the above example as all
the abbreviations use the same style.
-However if you're really determined to use
+If the term can simply be treated as a series of previously defined
+entries, then consider using multi-entries (or compound sets). See
+\sectionref{sec:multientries} for further details.
+
+However, if you're really determined to use
\ics{gls} in a field that may be included within
some \gls{linktext}, \styfmt{glossaries-extra} patches internals
used by the linking commands so that if \cs{gls} (or plural or
@@ -3158,6 +3206,7 @@ is redefined to use the subsequent use abbreviation font command
\cs{RestoreAcronyms}.
\section{Glossaries}
+\label{sec:glossaries}
The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred
version that doesn't automatically switch off the hyperlinks.
@@ -3192,6 +3241,12 @@ be displayed multiple times.
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}).
+\begin{important}
+This doesn't include the navigation hyper group targets in styles such as
+\glostyle{listhypergroup}. The link name for these is given by
+\ics{glsnavhyperlinkname}.
+\end{important}
+
\item
\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do
actually want to locally change \cs{glolinkprefix}, you can use
@@ -3560,7 +3615,7 @@ doesn't display any differently from
but it does make it easier to define your own custom list handler
that can accommodate the ranges.
-\subsection{The \styfmt{glossaries-extra-stylemods} Package}
+\subsection{The \headingsty{glossaries-extra-stylemods} Package}
\label{sec:stylemods}
As from v1.02, \styfmt{glossaries-extra} now includes the package
@@ -4042,13 +4097,14 @@ the accompanying sample files \nolinkurl{sample-alttree.tex},
\nolinkurl{sample-alttree-marginpar.tex}.
\chapter{New Glossary Styles}
+\label{sec:newglossarystyles}
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}
+\section{\headingsty{glossary-bookindex} package}
\label{sec:bookindex}
As from v1.21, \styfmt{glossaries-extra} has a new supplementary
@@ -4343,7 +4399,7 @@ to show the first and last entry for the current page with:
\rfoot{\glsxtrbookindexlastmark}%
\end{verbatim}
-\section{\styfmt{glossary-longextra} package}
+\section{\headingsty{glossary-longextra} package}
\label{sec:longextra}
As from version 1.37, the \styfmt{glossaries-extra} package comes
@@ -4834,7 +4890,7 @@ and
\end{description}
-\section{\styfmt{glossary-topic} package}
+\section{\headingsty{glossary-topic} package}
\label{sec:topic}
As from version 1.40, the \styfmt{glossaries-extra} package comes
@@ -5684,6 +5740,41 @@ for the first use long form, and
\end{definition}
for the short plural suffix.
+The \qt{short-sc-only} styles, such as
+\abbrstyle{long-only-short-sc-only}:
+\begin{definition}[\DescribeMacro\glsabbrvsconlyfont]
+\cs{glsabbrvsconlyfont}\marg{text}
+\end{definition}
+for the short form (which uses \ics{glsabbrvscfont}), and
+\begin{definition}[\DescribeMacro\glsfirstabbrvsconlyfont]
+\cs{glsfirstabbrvsconlyfont}\marg{text}
+\end{definition}
+which uses \ics{glsabbrvsconlyfont}.
+The short plural suffix is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrsconlysuffix]
+\cs{glsxtrsconlysuffix}
+\end{definition}
+This uses \ics{glsxtrscsuffix}. For other font types, use the
+one of \qt{short-only} styles and redefine \cs{glsabbrvonlyfont} as
+required. (The smallcaps style is a special case as its plural suffix is
+awkward.)
+
+The \qt{postshort-sc-user} styles, such as
+\abbrstyle{long-postshort-sc-user}:
+\begin{definition}[\DescribeMacro\glsabbrvscuserfont]
+\cs{glsabbrvscuserfont}\marg{text}
+\end{definition}
+for the short form (which uses \ics{glsabbrvscfont}), and
+\begin{definition}[\DescribeMacro\glsfirstabbrvscuserfont]
+\cs{glsfirstabbrvscuserfont}\marg{text}
+\end{definition}
+which uses \ics{glsabbrvscuserfont}.
+The short plural suffix is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrscusersuffix]
+\cs{glsxtrscusersuffix}
+\end{definition}
+This uses \ics{glsxtrscsuffix}.
+
Note that by default inserted material (provided in the final
optional argument of commands like \cs{gls}), is placed outside the
font command in the predefined styles. To move it inside, use:
@@ -6124,20 +6215,48 @@ any commands that shouldn't be expanded. The long form can be
referenced with \cs{the}\cs{glslongtok} and the short form
can be referenced with \cs{the}\cs{glsshorttok}.
+\item[\abbrstyledef{long-only-short-sc-only}]
+
+New to version 1.48, this is like \abbrstyle{long-only-short-only} but
+uses smallcaps for the short form. The name is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrsconlyname]
+\cs{glsxtrsconlyname}
+\end{definition}
+
\item[\abbrstyledef{long-only-short-only-desc}]
New to version 1.17, this style is like
\abbrstyle{long-only-short-only} but the user must supply the
-description. The \gloskey{name}
-field is obtained from
+description. The \gloskey{name} field is obtained from
\begin{definition}[\DescribeMacro\glsxtronlydescname]
\cs{glsxtronlydescname}
\end{definition}
-Any redefinition of this command must come before the abbreviations
+The sort value is obtained from:
+\begin{definition}[\DescribeMacro\glsxtronlydescsort]
+\cs{glsxtronlydescsort}
+\end{definition}
+
+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{long-only-short-sc-only-desc}]
+New to version 1.48, this style is like
+\abbrstyle{long-only-short-only-desc} but it uses smallcaps for the
+short form. The name is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrsconlydescname]
+\cs{glsxtrsconlydescname}
+\end{definition}
+This defaults to \cs{glsxtronlydescname}.
+
+The sort value is obtained from:
+\begin{definition}[\DescribeMacro\glsxtrsconlydescsort]
+\cs{glsxtrsconlydescsort}
+\end{definition}
+This defaults to \cs{glsxtronlydescsort}.
+
\item[\abbrstyledef{long-em-noshort-em-noreg}]
New to version 1.17, this style is like
\abbrstyle{long-em-noshort-em} but
@@ -6615,6 +6734,14 @@ This style was introduced in version 1.12. It's like the above
must be specified. The \gloskey{name} is obtained from
\cs{glsxtrlongshortuserdescname}.
+\item[\abbrstyledef{long-postshort-sc-user}]
+This style (new to v1.48) is like \abbrstyle{long-postshort-user}
+but uses smallcaps for the short form.
+
+\item[\abbrstyledef{long-postshort-sc-user-desc}]
+This style (new to v1.48) is like \abbrstyle{long-postshort-user-desc}
+but uses smallcaps for the short form.
+
\item[\abbrstyledef{long-hyphen-short-hyphen}]
This style (new to v1.17) is designed to work with the \catattr{markwords}
category attribute. The full form is formatted using
@@ -7224,6 +7351,7 @@ Similar problems can also occur with captions (except for the page
header and bookmark issues).
\section{Simplistic Approach}
+\label{sec:simplisticapproach}
To get around all these problems, the \styfmt{glossaries} user manual
recommends using the expandable non-hyperlink commands, such as
@@ -7285,6 +7413,7 @@ if the mark commands have been reverted, but only where they don't
conflict with the page style.
\section{New Commands Designed for Chapter/Section Headings}
+\label{sec:headingcommands}
The commands listed below are designed for use in chapter or section
headings. There are still limitations, but they provide a better
@@ -7516,6 +7645,2306 @@ and all caps:
\cs{GLSfmtfirstpl}\marg{label}
\end{definition}
+\chapter{Multi (or Compound) Entries}
+\label{sec:multientries}
+
+Nested entries (where the entry definition references other entries)
+are discussed in \sectionref{sec:nested}. This chapter deals with
+occasions where a term or phrase may consist of multiple sub-terms
+that are independently defined. (Examples in
+\sectionref{sec:exskipfirstsuffix} and
+\sectionref{sec:exskippostlink} provide workarounds for nested
+entries.)
+
+For example, the names of bacteria, such as \emph{Clostridium
+botulinum} and \emph{Clostridium perfringens}, are made up of the
+genus (for example, \emph{Clostridium}) and the species
+(for example, \emph{botulinum} or \emph{perfringens}). The genus is
+often abbreviated after \gls{firstuse}. For example, \emph{C.
+botulinum}. However, if the name is defined as a single term
+consisting of both the genus and species then it's not possible to
+apply the abbreviation when a different species with the same genus
+is used.
+
+Consider the following document:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries-extra}
+\setabbreviationstyle{long-only-short-only}
+\newabbreviation{cbot}{C. botulinum}{Clostridium botulinum}
+\newabbreviation{cperf}{C. perfringens}{Clostridium perfringens}
+\begin{document}
+\gls{cbot}, \gls{cbot}, \gls{cperf}.
+\end{document}
+\end{verbatim}
+The result is:
+\begin{display}
+Clostridium botulinum, C. botulinum, Clostridium perfringens.
+\end{display}
+However, it should more typically be:
+\begin{display}
+Clostridium botulinum, C. botulinum, C. perfringens.
+\end{display}
+In this case, the genus should actually be a separate definition:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries-extra}
+\setabbreviationstyle{long-only-short-only}
+\newabbreviation{clostridium}{C.}{Clostridium}
+\newglossaryentry{botulinum}{name={botulinum},description={}}
+\newglossaryentry{perfringens}{name=perfringens,description={}}
+\begin{document}
+\gls{clostridium} \gls{botulinum},
+\gls{clostridium} \gls{botulinum},
+\gls{clostridium} \gls{perfringens}.
+\end{document}
+\end{verbatim}
+This is quite awkward to write. This chapter describes how to
+provide a shortcut for this kind of construct. Each term should be
+defined as normal (as in the above example), and a \qt{multi-entry}
+label is then defined with the list of labels of the entries that
+need to be referenced. This is done with the command:
+\begin{definition}[\DescribeMacro\multiglossaryentry]
+\cs{multiglossaryentry}\oarg{options}\marg{multi-label}\oarg{main
+label}\marg{label list}
+\end{definition}
+where \meta{multi-label} is the new label and \meta{label list} is
+the list of labels (corresponding to entries that have already been
+defined).
+
+The \meta{main label} may be omitted, in which case the
+main label will be assumed to be the final element in \meta{label
+list}. If \meta{main label} is present, it must
+also be listed in \meta{label list}. This is described in more
+detail in \sectionref{sec:mglsmain}.
+
+The \meta{options} are a comma-separated list of options to override
+the current settings and are described in \sectionref{sec:multiglsoptions}.
+
+The earlier example can now be modified to include the following:
+\begin{verbatim}
+\multiglossaryentry{cbot}{clostridium,botulinum}
+\multiglossaryentry{cperf}{clostridium,perfringens}
+\end{verbatim}
+These commands must come after the definitions of \texttt{clostridium},
+\texttt{botulinum} and \texttt{perfringens}.
+
+Once defined, a multi-entry set can be referenced using commands like:
+\begin{definition}[\DescribeMacro\mgls]
+\cs{mgls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This command essentially does \cs{gls}\marg{label} for each item in
+the \meta{label list} (with separators, see
+\sectionref{sec:mglssep}). If the final optional argument
+\meta{insert} is provided, it will be applied to the final
+(non-skipped) element in the list. So the document body in the
+above example, can be rewritten as:
+\begin{verbatim}
+\mgls{cbot}, \mgls{cbot}, \mgls{cperf}.
+\end{verbatim}
+
+There are some variants of \cs{mgls} listed in \sectionref{sec:mglslike}.
+The available \meta{options} are listed in \sectionref{sec:mglsopts}. They are
+applied after the \cs{multiglossaryentry} options and will override
+settings for the individual entries.
+
+\begin{important}
+You can't use \meta{multi-label} in commands like \cs{gls}
+as this label represents a set of entry labels not a single entry.
+\end{important}
+
+The \cs{multiglossaryentry} command will generate an error if the label has already
+been defined as a multi-entry. To do nothing if a multi-entry already exists,
+use:
+\begin{definition}[\DescribeMacro\providemultiglossaryentry]
+\cs{providemultiglossaryentry}\oarg{options}\marg{multi-label}\oarg{main
+label}\marg{label list}
+\end{definition}
+Notes and associated commands applying to \cs{multiglossaryentry}
+also apply to \cs{providemultiglossaryentry} unless otherwise
+stated.
+
+\begin{important}
+\cs{multiglossaryentry} may be placed anywhere after the \meta{label
+list} entries have been defined. A multi-entry label can't be
+referenced (with commands like \cs{mgls}) before it has been defined.
+\end{important}
+
+There is limited support for \pkgopt[true]{docdef}. The multi-entry
+definition can be picked up from the \filetype{aux} file on the next
+run to allow cross-references in any glossaries that occur at the
+start of the document. Any changes made with commands like
+\cs{mglsSetMain} won't be carried over to the next run.
+
+By default \cs{multiglossaryentry} will be localised to the current scope.
+If you want to globally define a multi-entry you need to first
+switch on global definitions with:
+\begin{definition}[\DescribeMacro\multiglossaryentryglobaltrue]
+\cs{multiglossaryentryglobaltrue}
+\end{definition}
+To switch back to local definitions use:
+\begin{definition}[\DescribeMacro\multiglossaryentryglobalfalse]
+\cs{multiglossaryentryglobalfalse}
+\end{definition}
+
+If you want to change the multi-entry options (locally) you can use:
+\begin{definition}[\DescribeMacro\mglsSetOptions]
+\cs{mglsSetOptions}\marg{multi-label}\marg{new-options}
+\end{definition}
+This removes the original options. If you want to (locally) append to the
+existing options, use:
+\begin{definition}[\DescribeMacro\mglsSetOptions]
+\cs{mglsAddOptions}\marg{multi-label}\marg{new-options}
+\end{definition}
+
+Note that \cs{multiglossaryentry} doesn't make any adjustments to
+the component entries. You will need to use the \gloskey{parent} key
+when you define the entries if you want a hierarchical structure in
+your glossary. (See the example in \sectionref{sec:mglsexhier}.)
+
+If you don't want the other elements in the glossary, you can
+suppress the indexing with \optfmt{indexothers=false}
+(\sectionref{sec:multiglsoptionsindexing}) or put them in an ignored
+glossary. For example:
+\begin{verbatim}
+\newignoredglossary{common}
+\newabbreviation[type=common]{clostridium}{C.}{Clostridium}
+\end{verbatim}
+
+The \meta{multi-label} can't be used in commands like \cs{gls} since
+the label refers to a set of entry labels not to an individual
+entry. Similarly, an individual entry label can't be used in
+commands like \cs{mgls}. It is possible (although potentially
+confusing) to use the same label for a multi-entry as for an
+individual entry (see the example in
+\sectionref{sec:exskippostlink}). Context will determine which is
+meant, except in the case of the cross-referencing fields
+(\gloskey{see}, \gloskey{seealso} and \gloskey{alias}) where the
+cross-referenced label will first be tested if it's a known
+multi-entry label.
+
+If you don't want to have to keep track of which labels refer to
+multi-entries and which refer to individual entries you can use:
+\begin{definition}[\DescribeMacro\GlsXtrMglsOrGls]
+\cs{GlsXtrMglsOrGls}\marg{mgls cs}\marg{gls
+cs}\meta{modifier}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+where \meta{mgls cs} is the \cs{mgls}-like command to use if
+\meta{label} has been defined as a multi-entry and \meta{gls cs} is
+the \cs{gls}-like command to use otherwise. The \meta{modifier} may
+be omitted, otherwise it is the modifier that may be used with
+\cs{mgls} or \cs{gls} (\texttt{*}, \texttt{+} or the character
+identified with \ics{GlsXtrSetAltModifier}). The modifier and remaining
+options are passed to the relevant command (\meta{mgls cs} or
+\meta{gls cs}).
+
+You may prefer to define your own shortcut commands for common
+combinations. For example:
+\begin{verbatim}
+\newcommand{\ac}{\GlsXtrMglsOrGls{\mgls}{\gls}}
+\newcommand{\acpl}{\GlsXtrMglsOrGls{\mglsmainpl}{\glspl}}
+\newcommand{\Ac}{\GlsXtrMglsOrGls{\Mgls}{\Gls}}
+\newcommand{\Acpl}{\GlsXtrMglsOrGls{\Mglsmainpl}{\Glspl}}
+\end{verbatim}
+
+\section{Examples}
+\label{sec:mglsexamples}
+
+\subsection{Example: Hierarchical}
+\label{sec:mglsexhier}
+
+Bacteria names are represented by the genus (for example,
+Clostridium) followed by the species (for example, botulinum).
+This example has the genus as a parent of the species.
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra}
+
+\makeglossaries
+
+\newcommand{\latinname}[1]{\emph{#1}}
+\glssetcategoriesattributes
+ {genus,species}{textformat,glossnamefont}{latinname}
+
+\setabbreviationstyle[genus]{long-only-short-only-desc}
+\newabbreviation
+ [category=genus,description={}]
+ {clostridium}{C.}{Clostridium}
+
+\newglossaryentry{botulinum}{name=botulinum,category=species,
+ description={},parent=clostridium}
+\newglossaryentry{perfringens}{name=perfringens,category=species,
+ description={},parent=clostridium}
+\newglossaryentry{tetani}{name=tetani,category=species,
+ description={},parent=clostridium}
+
+\multiglossaryentry{cbot}{clostridium,botulinum}
+\multiglossaryentry{cperf}{clostridium,perfringens}
+\multiglossaryentry{ctet}{clostridium,tetani}
+
+\multiglossaryentrysetup{indexothers=false,hyper=allmain}
+
+\begin{document}
+First use:
+\mgls{cbot}, \mgls{cperf}, \mgls{ctet}.
+
+Next use:
+\mgls{cbot}, \mgls{cperf}, \mgls{ctet}.
+\printglossaries
+\end{document}
+\end{verbatim}
+This suppresses the indexing of the non-main elements (in this case,
+the genus). However the genus is included in the glossary (without a
+\gls{numberlist}) because it's the parent of the species (which are
+indexed).
+
+The \optfmt{hyper=allmain} option makes the entire content of each
+\cs{mgls} a hyperlink to the main entry in the glossary. The
+resulting document text (before the glossary) is:
+\begin{quote}
+First use:
+\emph{Clostridium botulinum}, \emph{C. perfringens}, \emph{C. tetani}.
+
+Next use:
+\emph{C. botulinum}, \emph{C. perfringens}, \emph{C. tetani}.
+\end{quote}
+
+\subsection{Example: Suffix}
+\label{sec:mglsexsuffix}
+
+This example has a minor modification to the previous one. In this
+case the multi-entries are defined with a suffix:
+\begin{verbatim}
+\multiglossaryentry[firstsuffix=botulism]{cbot}{clostridium,botulinum}
+\multiglossaryentry[firstsuffix={gas gangrene}]{cperf}{clostridium,perfringens}
+\multiglossaryentry[firstsuffix=tetanus]{ctet}{clostridium,tetani}
+\end{verbatim}
+The rest of the document is as in \sectionref{sec:mglsexhier}.
+The document text is now:
+\begin{quote}
+First use:
+\emph{Clostridium botulinum} (botulism), \emph{C. perfringens} (gas
+gangrene), \emph{C. tetani} (tetanus).
+
+Next use:
+\emph{C. botulinum}, \emph{C. perfringens}, \emph{C. tetani}.
+\end{quote}
+
+\subsection{Example: Category Suffix}
+\label{sec:mglsexcatsuffix}
+
+This is an alternative to the previous example. Instead of storing
+the extra information in the \optfmt{firstsuffix} key, the
+information is stored in the \gloskey{user1} key of the last
+element (the species). A category suffix is used to look up the
+field and append it.
+\begin{verbatim}
+\newglossaryentry{botulinum}{name=botulinum,category=species,
+ user1={botulism},
+ description={},parent=clostridium}
+\newglossaryentry{perfringens}{name=perfringens,category=species,
+ user1={gas gangrene},
+ description={},parent=clostridium}
+\newglossaryentry{tetani}{name=tetani,category=species,
+ user1={tetanus},
+ description={},parent=clostridium}
+
+\mglsdefcategorysuffix{bacteria}{%
+ \mglsisfirstuse
+ {\glsxtrifhasfield{useri}{\mglslastelementlabel}{ (\glscurrentfieldvalue)}{}}%
+ {}%
+}
+
+\multiglossaryentry[category=bacteria]{cbot}{clostridium,botulinum}
+\multiglossaryentry[category=bacteria]{cperf}{clostridium,perfringens}
+\multiglossaryentry[category=bacteria]{ctet}{clostridium,tetani}
+\end{verbatim}
+The result is the same as the previous example.
+
+\subsection{Example: Separators}
+\label{sec:mglsexsep}
+
+The first example (\sectionref{sec:mglsexhier}) can be modified so
+that the species are also abbreviations. In this case, the
+separators are modified to suppress the space (\cs{relax}) if both the genus and
+species are abbreviated, or to use a non-breaking space \verb|~| between
+the genus short form (shown on subsequent use) and the species long
+form (shown on first use). If the genus is showing the long form
+(first use) then a normal space is used.
+
+Note that the separator attributes apply to the category of the
+element before the separator (not to the multi-entry category).
+\begin{verbatim}
+\glssetcategoryattribute{genus}{combinedfirstsepfirst}{\space}
+\glssetcategoryattribute{genus}{combinedfirstsep}{\space}
+\glssetcategoryattribute{genus}{combinedsepfirst}{~}
+\glssetcategoryattribute{genus}{combinedsep}{\relax}
+
+\setabbreviationstyle[species]{long-only-short-only-desc}
+
+\newabbreviation[category=species,
+ description={},parent=clostridium]{botulinum}{bot.}{botulinum}
+\newabbreviation[category=species,
+ description={},parent=clostridium]{perfringens}{per.}{perfringens}
+\newabbreviation[,category=species,
+ description={},parent=clostridium]{tetani}{tet.}{tetani}
+\end{verbatim}
+This will cause a double dot at the end of the second sentence,
+which can be suppressed using the \catattr{discardperiod} and
+\catattr{retainfirstuseperiod} attributes.
+\begin{verbatim}
+\glssetcategoriesattributes{species}{discardperiod,retainfirstuseperiod}{true}
+\end{verbatim}
+This works because the final element's post-link hook is transferred
+to the multi-entry post-link hook, which can detect the sentence
+terminating period. If the post-link hook settings are changed, for
+example, to \optfmt{postlinks=all,mpostlink=false} then the feature
+won't work as the final element's post-link hook can't detect the
+period (because \cs{gls} is embedded too deeply inside the internal
+workings of \cs{mgls}).
+
+The result is:
+\begin{quote}
+First use: Clostridium botulinum, C.~perfringens, C.~tetani.
+
+Next use: C.bot., C.per., C.tet.
+\end{quote}
+
+\subsection{Example: Skipping Elements (Fragment Element)}
+\label{sec:exskipfirstsuffix}
+
+This example is an alternative way of dealing with nested links
+(see \sectionref{sec:nested}).
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[stylemods,style=long]{glossaries-extra}
+
+\makeglossaries
+
+\setabbreviationstyle{long-short-sc}
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+
+\setabbreviationstyle[combinedabbrv]{long-only-short-sc-only}
+\newabbreviation
+ [category=combinedabbrv,
+ description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}]
+ {shtml-frag}{shtml}{enabled}
+
+\glssetcategoryattribute{combinedabbrv}{multioptions}
+ {usedskipothers,firstsuffix={\glsxtrshort{\mglslastmainlabel}}}
+
+\multiglossaryentry
+ [category={combinedabbrv}]
+ {shtml}[shtml-frag]{ssi,shtml-frag,html}
+
+\begin{document}
+Individual elements first use: \gls{ssi} and \gls{html}.
+
+Individual elements next use: \gls{ssi} and \gls{html}.
+
+Multi-entry first use: \mgls{shtml}.
+
+Multi-entry next use: \mgls{shtml}.
+
+Resetting all\glsresetall\mglsreset{shtml}:
+
+Multi-entry first use: \mgls{shtml}.
+
+Multi-entry next use: \mgls{shtml}.
+
+Individual elements: \gls{ssi} and \gls{html}.
+\printglossaries
+\end{document}
+\end{verbatim}
+This uses the \catattr{multioptions} attribute to skip \qt{other}
+elements on subsequent use. The problematic abbreviation (SHTML) is
+defined as a fragment that simply expands to \qt{enabled} on first
+use. Note that the description has to be supplied for the glossary.
+
+The above produces (underlining added to mark the hyperlinks):
+\begin{quote}
+Individual elements first use: \uline{server-side includes (\textsc{ssi})} and
+\uline{hypertext markup language (\textsc{html})}.
+
+Individual elements next use: \uline{\textsc{ssi}} and
+\uline{\textsc{html}}.
+
+Multi-entry first use: \uline{\textsc{ssi}} \uline{enabled}
+\uline{\textsc{html}} (\uline{\textsc{shtml}}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Resetting all:
+
+Multi-entry first use: \uline{server-side includes (\textsc{ssi})}
+\uline{enabled} \uline{hypertext markup language (\textsc{html})}
+(\uline{\textsc{shtml}}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Individual elements: \uline{\textsc{ssi}} and \uline{\textsc{html}}.
+\end{quote}
+The key difference here from the example using \cs{glsps} at the end
+of \sectionref{sec:nested} is that the individual elements hyperlink
+to their respective entries in the glossary on first use of \cs{mgls}.
+
+The problem is that with the \pkgopt{colorlinks} package option,
+it's not obvious where the hyperlinks start and end. The suffix (\textsc{shtml})
+will hyperlink to the \qt{shtml} entry in the glossary, so the
+\qt{enabled} hyperlink is redundant. The simplest fix for this is to
+add \optfmt{hyper=notmainfirst} to the option list, which will prevent
+\qt{enabled} from being a hyperlink.
+
+Another problem occurs where \cs{mgls} is used before the individual elements are
+used, which leads to their full expansion with a confusing amount of
+parentheses. A simple solution is to use the option
+\optfmt{mglsopts=unsetothers}, which will unset the other (not-main)
+elements first. This can be localised with \optfmt{presetlocal} but
+\cs{gls} will then unset the \gls{firstuseflag} globally, which
+means that the other elements won't show the full form when they are
+first used on their on after \cs{mgls}. This can be switched to a
+local unset with \optfmt{others={local}}.
+
+The complete set of options are now:
+\begin{verbatim}
+\glssetcategoryattribute{combinedabbrv}{multioptions}
+ {%
+ hyper=notmainfirst,
+ mglsopts={presetlocal,unsetothers,others={local}},
+ usedskipothers,
+ firstsuffix={\glsxtrshort{\mglslastmainlabel}}
+ }
+\end{verbatim}
+This now produces (underlining added to mark the hyperlinks):
+\begin{quote}
+Individual elements first use: \uline{server-side includes (\textsc{ssi})} and
+\uline{hypertext markup language (\textsc{html})}.
+
+Individual elements next use: \uline{\textsc{ssi}} and
+\uline{\textsc{html}}.
+
+Multi-entry first use: \uline{\textsc{ssi}} \uline{enabled}
+\uline{\textsc{html}} (\uline{\textsc{shtml}}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Resetting all:
+
+Multi-entry first use: \uline{\textsc{ssi}}
+\uline{enabled} \uline{\textsc{html}}
+(\uline{\textsc{shtml}}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Individual elements: \uline{server-side includes (\textsc{ssi})}
+and \uline{hypertext markup language (\textsc{html})}.
+\end{quote}
+This method still has two main drawbacks: the description must be
+added manually and the long form can't be accessed with
+\cs{glsxtrlong}. The next example provides an alternative approach.
+
+\subsection{Example: Skipping Elements (Prefix and Post-Link Hooks)}
+\label{sec:exskippostlink}
+
+This is a modified version of the previous example. In this case,
+the main element isn't a fragment and also happens to have the same
+label as the multi-entry set. (\verb|\mgls{shtml}| references the
+multi-entry label and \verb|\gls{shtml}| references the individual
+entry.)
+
+In this case, the nested parts are marked up with custom commands:
+\begin{verbatim}
+\newrobustcmd{\combinedpre}[1]{\glsps{#1}}
+\newrobustcmd{\combinedpost}[1]{\glsps{#1}}
+
+\newabbreviation{shtml}{shtml}
+{{}\combinedpre{ssi} enabled \combinedpost{html}}
+\end{verbatim}
+This means that it's no longer necessary to manually insert the
+description and the long form can be accessed as usual with
+\cs{glsxtrshort}\verb|{shtml}|. Note that it is necessary to define
+the custom commands robustly otherwise they will need to be
+protected against premature expansion:
+\begin{verbatim}
+\newcommand{\combinedpre}[1]{\glsps{#1}}
+\newcommand{\combinedpost}[1]{\glsps{#1}}
+
+\newabbreviation{shtml}{shtml}
+{{}\protect\combinedpre{ssi} enabled \protect\combinedpost{html}}
+\end{verbatim}
+In both cases, an initial empty group is added to guard
+against any first letter uppercase commands, such as \cs{Glsxtrlong}.
+
+The abbreviations all use the \abbrstyle{long-postshort-sc-user}
+style, which places the short form in the post-link hook on
+\gls{firstuse}. The \cs{gls} post-link hook for the main element
+can be transferred to the \cs{mgls} post-link using:
+\begin{verbatim}
+mpostlinkelement=main
+\end{verbatim}
+All elements have their individual post-link hooks suppressed by default.
+As in the previous example, the other elements can be skipped on
+subsequent use:
+\begin{verbatim}
+usedskipothers
+\end{verbatim}
+Within \cs{mgls}, the nested content needs to be suppressed, which
+can be done by redefining the custom commands. This can be done in
+the multi-entry prefix. Since the entire content of \cs{mgls} (except for the
+final multi-entry post-link hook) occurs inside a group, this
+redefinition will be localised.
+
+The complete document is as follows:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[stylemods,style=long]{glossaries-extra}
+
+\makeglossaries
+
+\setabbreviationstyle{long-postshort-sc-user}
+
+\newabbreviation{ssi}{ssi}{server-side includes}
+\newabbreviation{html}{html}{hypertext markup language}
+
+\newrobustcmd{\combinedpre}[1]{\glsps{#1}}
+\newrobustcmd{\combinedpost}[1]{\glsps{#1}}
+
+\newabbreviation{shtml}{shtml}
+{{}\combinedpre{ssi} enabled \combinedpost{html}}
+
+\glssetcategoryattribute{combinedabbrv}{multioptions}
+ {%
+ mpostlinkelement=main,
+ usedskipothers
+ }
+
+\multiglossaryentry
+ [category={combinedabbrv}]
+ {shtml}[shtml]{ssi,shtml,html}
+
+\mglsdefcategoryprefix{combinedabbrv}{%
+ \renewcommand{\combinedpre}[1]{\ignorespaces}%
+ \renewcommand{\combinedpost}[1]{\unskip}%
+}
+
+\begin{document}
+Individual elements first use: \gls{ssi} and \gls{html}.
+
+Individual elements next use: \gls{ssi} and \gls{html}.
+
+Multi-entry first use: \mgls{shtml}.
+
+Multi-entry next use: \mgls{shtml}.
+
+Individual entry first use: \gls{shtml}.
+
+Resetting all\glsresetall\mglsresetall:
+
+Multi-entry first use: \mgls{shtml}.
+
+Multi-entry next use: \mgls{shtml}.
+
+Individual elements: \gls{ssi} and \gls{html}.
+
+Resetting all\glsresetall\mglsresetall:
+
+Individual entry first use: \gls{shtml}.
+
+Multi-entry first use: \mgls{shtml}. (Wrong!)
+
+\printglossaries
+\end{document}
+\end{verbatim}
+This now produces (underlining added to mark the hyperlinks):
+\begin{quote}
+Individual elements first use: \uline{server-side includes}
+(\textsc{ssi}) and \uline{hypertext markup language} (\textsc{html}).
+
+Individual elements next use: \uline{\textsc{ssi}} and
+\uline{\textsc{html}}.
+
+Multi-entry first use: \uline{\textsc{ssi}} \uline{enabled}
+\uline{\textsc{html}} (\textsc{shtml}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Individual entry first use: \uline{\textsc{shtml}}.
+
+Resetting all:
+
+Multi-entry first use: \uline{server-side includes} \uline{enabled}
+\uline{hypertext markup language} (\textsc{shtml}).
+
+Multi-entry next use: \uline{\textsc{shtml}}.
+
+Individual elements: \uline{\textsc{ssi}} and \uline{\textsc{html}}.
+
+Resetting all:
+
+Individual entry first use: \uline{\textsc{ssi}} \uline{enabled}
+\uline{\textsc{html}} (\textsc{shtml}).
+
+Multi-entry first use: \uline{server-side includes}
+\uline{\textsc{shtml}} \uline{hypertext markup language}. (Wrong!)
+\end{quote}
+Note the last two paragraphs, which highlights what happens if
+\verb|\gls{shtml}| is used before \verb|\mgls{shtml}| when neither
+of the other elements (\texttt{ssi} and \texttt{html}) have been
+used. The final instance of \cs{mgls} has produced the wrong result.
+This is because it's the first use of the multi-entry \texttt{shtml} but
+not the first use of the individual entry \texttt{shtml}.
+
+One way around this is to modify the prefix to ensure that the main
+element's \gls{firstuseflag} matches the multi-entry's first use
+flag:
+\begin{verbatim}
+\mglsdefcategoryprefix{combinedabbrv}{%
+ \renewcommand{\combinedpre}[1]{\ignorespaces}%
+ \renewcommand{\combinedpost}[1]{\unskip}%
+ \mglsisfirstuse
+ {\glslocalreset{\mglscurrentmainlabel}}%
+ {\glslocalunset{\mglscurrentmainlabel}}%
+}
+\end{verbatim}
+
+The \pkgopt[annoteleft]{showtargets} option can be used to mark up
+the links with the targets. For example, the first instance of
+\verb|\mgls{shtml}| will show as:
+\begin{quote}
+\newcommand{\markup}[2]{%
+{\glsshowtargetfont[#1]}%
+\glsxtrshowtargetsymbolleft#2\glsxtrshowtargetsymbolright}%
+Multi-entry first use: \markup{glo:ssi}{\textsc{ssi}}
+\markup{glo:shtml}{enabled}
+\markup{glo:html}{\textsc{html}} (\textsc{shtml}).
+\end{quote}
+Each entry has an individual hyperlink to its own glossary item,
+which may be confusing. This can be made clearer by suppressing the
+main element link on first use with:
+\begin{verbatim}
+hyper=notmainfirst
+\end{verbatim}
+(as in the previous example), and adjusting the abbreviation style
+so that the parenthetical content in the post-link hook has a
+hyperlink:
+\begin{verbatim}
+\renewcommand*{\glsxtruserparen}[2]{%
+ \glsxtrfullsep{#2}%
+ \glsxtrparen
+ {\glshyperlink[#1]{#2}%
+ \ifglshasfield{\glsxtruserfield}{#2}{, \glscurrentfieldvalue}{}%
+ }%
+}
+\end{verbatim}
+
+The remaining problem is how to deal with the possibility that
+\verb|\mgls{shtml}| may come before the \gls{firstuse} of the other
+elements. For example:
+\begin{verbatim}
+Multi-entry first use: \mgls{shtml}.
+
+Individual elements: \gls{ssi} and \gls{html}.
+\end{verbatim}
+This leads to:
+\begin{quote}
+Multi-entry first use: server-side includes enabled hypertext markup
+language (\textsc{shtml}).
+
+Individual elements: \textsc{ssi} and \textsc{html}.
+\end{quote}
+This means that the abbreviations \textsc{ssi} and \textsc{html}
+aren't explained in the document text. One way around this is to
+only locally unset the other element \glspl{firstuseflag}:
+\begin{verbatim}
+\glssetcategoryattribute{combinedabbrv}{multioptions}
+ {%
+ hyper=notmainfirst,
+ mpostlinkelement=main,
+ usedskipothers,
+ mglsopts={others={local}}
+ }
+\end{verbatim}
+With the above setting, the following:
+\begin{verbatim}
+\glsresetall\mglsresetall
+
+Multi-entry first use: \mgls{shtml}.
+
+Multi-entry next use: \mgls{shtml}.
+
+Individual elements: \gls{ssi} and \gls{html}.
+\end{verbatim}
+will now produce:
+\begin{quote}
+Multi-entry first use: server-side includes enabled hypertext markup
+language (\textsc{shtml}).
+
+Multi-entry next use: \textsc{shtml}.
+
+Individual elements: server-side includes (\textsc{ssi}) and
+hypertext markup language (\textsc{html}).
+\end{quote}
+
+\section{Main and Other Elements}
+\label{sec:mglsmain}
+
+The list of labels provided in the final argument of
+\cs{multiglossaryentry} consists of a main element and all the other
+elements. If the main element isn't identified in the optional
+argument, it's assumed to be the final element in the list.
+
+The main element allows you to determine which target to use if you
+want the entire content of \cs{mgls} to be a single hyperlink. You
+can also use the settings described in \sectionref{sec:multiglsoptions}
+to only index the main element.
+
+You can change the main element using:
+\begin{definition}[\DescribeMacro\mglsSetMain]
+\cs{mglsSetMain}\marg{multi-label}\marg{new-main-label}
+\end{definition}
+The new main label provided in the second argument must be in the
+list corresponding to \meta{multi-label}. This change is locally
+applied to the current scope. Note that if you are using
+\gls{bib2gls}, this change in the document can't be detected.
+
+The main element can also be used to identify which element should
+be displayed in the plural with \cs{mglsmainpl}. For example:
+\begin{verbatim}
+\newglossaryentry{great}{name={great},description={}}
+\newglossaryentry{little}{name={little},description={}}
+\newglossaryentry{grebe}{name={grebe},description={}}
+
+\multiglossaryentry{greatgrebe}{great,grebe}
+\multiglossaryentry{littlegrebe}{little,grebe}
+\end{verbatim}
+In the above, two multi-entries are defined: \texttt{greatgrebe} and
+\texttt{littlegrebe}. In both cases the main element is
+\texttt{grebe} (the last element). Using \cs{mglspl} will show the
+plural for all elements, but using \cs{mglsmainpl} will only use the
+plural for the main element (grebe). For example:
+\begin{verbatim}
+Plural all: \mglspl{greatgrebe}, \mglspl{littlegrebe}.
+Plural main: \mglsmainpl{greatgrebe}, \mglsmainpl{littlegrebe}.
+\end{verbatim}
+produces:
+\begin{display}
+Plural all: greats grebes, littles grebes.
+Plural main: great grebes, little grebes.
+\end{display}
+
+\section{Prefixes and Suffixes}
+\label{sec:mglsfixes}
+
+A multi-entry may have associated prefixes and suffixes. These are
+scoped and are placed outside of the hyperlinks and encapsulating
+commands. They are not affected by case-changing commands, such as
+\cs{Mgls}.
+If you want a prefix to obey case-changing, use the \cs{mpgls}-like
+commands instead (\sectionref{sec:mpgls}).
+
+The prefix is inserted with:
+\begin{definition}[\DescribeMacro\mglsprefix]
+\cs{mglsprefix}
+\end{definition}
+The default definition is:
+\begin{verbatim}
+\newcommand*{\mglsprefix}{%
+ \ifdefempty\mglscurrentcategory
+ {\mglscurrentprefix}%
+ {%
+ \mglshascategoryprefix{\mglscurrentcategory}%
+ {\mglsusecategoryprefix{\mglscurrentcategory}}%
+ {\mglscurrentprefix}%
+ }%
+}
+\end{verbatim}
+This will insert the current prefix unless there is prefix command
+associated with the current category.
+
+The suffix is inserted with:
+\begin{definition}[\DescribeMacro\mglssuffix]
+\cs{mglssuffix}
+\end{definition}
+The command is defined as follows:
+\begin{verbatim}
+\newcommand*{\mglssuffix}{%
+ \ifdefempty\mglscurrentcategory
+ {\ifdefempty{\mglscurrentsuffix}{}{\space(\mglscurrentsuffix)}}%
+ {%
+ \mglshascategorysuffix{\mglscurrentcategory}%
+ {\mglsusecategorysuffix{\mglscurrentcategory}}%
+ {\ifdefempty{\mglscurrentsuffix}{}{\space(\mglscurrentsuffix)}}%
+ }%
+}
+\end{verbatim}
+If there is a suffix associated with the current category, that will
+be used, otherwise if the current suffix isn't empty this
+inserts a space followed by the current suffix in parentheses.
+You can access the label of the last (non-skipped) element with
+\ics{mglslastelementlabel}.
+
+Note that in both cases the category corresponds to the multi-entry
+category (see \sectionref{sec:multiglscategory}).
+
+To define a category-dependent prefix, use:
+\begin{definition}[\DescribeMacro\mglsdefcategoryprefix]
+\cs{mglsdefcategoryprefix}\marg{category}\marg{definition}
+\end{definition}
+You can reference the current prefix with \cs{mglscurrentprefix}.
+
+To define a category-dependent suffix, use:
+\begin{definition}[\DescribeMacro\mglsdefcategorysuffix]
+\cs{mglsdefcategorysuffix}\marg{category}\marg{definition}
+\end{definition}
+You can reference the current suffix with \cs{mglscurrentsuffix}.
+
+The default definition of \cs{mglsprefix} tests if there is a
+category prefix using:
+\begin{definition}[\DescribeMacro\mglshascategoryprefix]
+\cs{glshascategoryprefix}\marg{category}\marg{true}\marg{false}
+\end{definition}
+The category prefix is used with:
+\begin{definition}[\DescribeMacro\mglsusecategoryprefix]
+\cs{glsusecategoryprefix}\marg{category}
+\end{definition}
+
+The default definition of \cs{mglssuffix} tests if there is a
+category suffix using:
+\begin{definition}[\DescribeMacro\mglshascategorysuffix]
+\cs{glshascategorysuffix}\marg{category}\marg{true}\marg{false}
+\end{definition}
+The category suffix is used with:
+\begin{definition}[\DescribeMacro\mglsusecategorysuffix]
+\cs{glsusecategorysuffix}\marg{category}
+\end{definition}
+
+The current prefix \cs{mglscurrentprefix} and \cs{mglscurrentsuffix}
+are obtained as follows:
+\begin{itemize}
+\item if this is the first use of the multi-entry
+(\sectionref{sec:mglsfirstuse}) then the \meta{prefix} is set to the
+value of the \optfmt{firstprefix} option and the \meta{suffix} is
+set to the value of the \optfmt{firstsuffix} option;
+\item otherwise the \meta{prefix} is set to the
+value of the \optfmt{usedprefix} option and the \meta{suffix} is
+set to the value of the \optfmt{usedsuffix} option.
+\end{itemize}
+
+\begin{important}
+The prefix and suffix (if set) are placed outside of the hyperlink
+and text formatting encapsulator. They are not affected by
+case-changing commands such as \cs{Mgls} or \cs{MGLS}.
+\end{important}
+
+For example:
+\begin{verbatim}
+\setabbreviationstyle{long-only-short-only}
+\newabbreviation{clostridium}{C.}{Clostridium}
+\newglossaryentry{botulinum}{name=botulinum,description={}}
+
+\multiglossaryentry[firstsuffix=botulism]
+ {cbot}{clostridium,botulinum}
+\end{verbatim}
+On first use, this produces (assuming the \qt{clostridum} element
+hasn't been used previously):
+\begin{quote}
+Clostridium botulinum (botulism).
+\end{quote}
+On subsequent use, this produces:
+\begin{quote}
+C. botulinum.
+\end{quote}
+
+\section{Separators}
+\label{sec:mglssep}
+
+The separators between each instance of \cs{gls} are given by the
+following commands, which all take two arguments. The first argument
+is the label of the previous element. The second argument is the
+label of the following element.
+\begin{definition}[\DescribeMacro\glscombinedsep]
+\cs{glscombinedsep}\marg{prev label}\marg{next label}
+\end{definition}
+This is inserted between two entries that have both been marked as used.
+The default definition is:
+\begin{verbatim}
+\newcommand*{\glscombinedsep}[2]{%
+ \glshasattribute{#1}{combinedsep}%
+ {\glsgetattribute{#1}{combinedsep}}%
+ { }%
+}
+\end{verbatim}
+This will use the \catattr{combinedsep} attribute for the
+\meta{prev label}'s category, if set. Otherwise this just does a
+space. Note that this ignores the second argument.
+
+\begin{definition}[\DescribeMacro\glscombinedfirstsep]
+\cs{glscombinedfirstsep}\marg{prev label}\marg{next label}
+\end{definition}
+This is inserted between two entries where only the next entry has
+been marked as used. The default definition is:
+\begin{verbatim}
+\newcommand*{\glscombinedfirstsep}[2]{%
+ \glshasattribute{#1}{combinedfirstsep}%
+ {\glsgetattribute{#1}{combinedfirstsep}}%
+ {\glscombinedsep{#1}{#2}}%
+}
+\end{verbatim}
+This will use the \catattr{combinedfirstsep} attribute for
+\meta{prev label}'s category, if set. If that attribute isn't set,
+\cs{glscombinedsep} is used.
+
+\begin{definition}[\DescribeMacro\glscombinedsepfirst]
+\cs{glscombinedsepfirst}\marg{prev label}\marg{next label}
+\end{definition}
+This is inserted between two entries where only the previous entry has
+been marked as used. The default definition is:
+\begin{verbatim}
+\newcommand*{\glscombinedsepfirst}[2]{%
+ \glshasattribute{#1}{combinedsepfirst}%
+ {\glsgetattribute{#1}{combinedsepfirst}}%
+ {\glscombinedsep{#1}{#2}}%
+}
+\end{verbatim}
+This will use the \catattr{combinedsepfirst} attribute for
+\meta{prev label}'s category, if set. If that attribute isn't set,
+\cs{glscombinedsep} is used.
+
+\begin{definition}[\DescribeMacro\glscombinedfirstsepfirst]
+\cs{glscombinedfirstsepfirst}\marg{prev label}\marg{next label}
+\end{definition}
+This is inserted between two entries where both have
+been marked as used. The default definition is:
+\begin{verbatim}
+\newcommand*{\glscombinedfirstsepfirst}[2]{%
+ \glshasattribute{#1}{combinedfirstsepfirst}%
+ {\glsgetattribute{#1}{combinedfirstsepfirst}}%
+ {\glscombinedsep{#1}{#2}}%
+}
+\end{verbatim}
+This will use the \catattr{combinedfirstsepfirst} attribute for
+\meta{prev label}'s category, if set. If that attribute isn't set,
+\cs{glscombinedsep} is used.
+
+These commands may be redefined as required.
+For example, to have no space between two elements that have both
+been marked as used and are both abbreviations (disregarding
+category attributes):
+\begin{verbatim}
+\renewcommand*{\glscombinedfirstsepfirst}[2]{%
+ \ifglshasshort{#1}{\ifglshasshort{#2}{}{\space}}{\space}%
+}
+\end{verbatim}
+
+There are some commands for redefining the above separators to
+common combinations.
+
+\begin{definition}[\DescribeMacro\glssetcombinedsepabbrvnbsp]
+\cs{glssetcombinedsepabbrvnbsp}
+\end{definition}
+This does the following:
+\begin{verbatim}
+\renewcommand*{\glscombinedsep}[2]{%
+ \glshasattribute{#1}{combinedsep}%
+ {\glsgetattribute{#1}{combinedsep}}%
+ {\ifhasshort{#1}{~}{ }}%
+}%
+\renewcommand*{\glscombinedsepfirst}[2]{%
+ \glshasattribute{##1}{combinedsepfirst}%
+ {\glsgetattribute{##1}{combinedsepfirst}}%
+ {\ifhasshort{#1}{~}{ }}%
+}%
+\renewcommand*{\glscombinedfirstsep}[2]{%
+ \glshasattribute{#1}{combinedfirstsep}%
+ {\glsgetattribute{#1}{combinedfirstsep}}%
+ { }%
+}%
+\renewcommand*{\glscombinedfirstsepfirst}[2]{%
+ \glshasattribute{##1}{combinedfirstsepfirst}%
+ {\glsgetattribute{##1}{combinedfirstsepfirst}}%
+ { }%
+}%
+\end{verbatim}
+This uses a non-breakable space \verb|~| following an abbreviation
+(that has already been marked as used). Note that if the associated
+attributes are set the commands will behave according to the
+attribute.
+
+\begin{definition}[\DescribeMacro\glssetcombinedsepabbrvnone]
+\cs{glssetcombinedsepabbrvnone}
+\end{definition}
+This does the following:
+\begin{verbatim}
+\renewcommand*{\glscombinedsep}[2]{%
+ \glshasattribute{#1}{combinedsep}%
+ {\glsgetattribute{#1}{combinedsep}}%
+ {\ifhasshort{#1}{}{\ifhasshort{#2}{}{ }}}%
+}%
+\renewcommand*{\glscombinedsepfirst}[2]{%
+ \glshasattribute{#1}{combinedsepfirst}%
+ {\glsgetattribute{#1}{combinedsepfirst}}%
+ {\ifhasshort{#1}{}{ }}%
+}%
+\renewcommand*{\glscombinedfirstsep}[2]{%
+ \glshasattribute{##1}{combinedfirstsep}%
+ {\glsgetattribute{##1}{combinedfirstsep}}%
+ {\ifhasshort{##2}{}{ }}%
+}%
+\renewcommand*{\glscombinedfirstsepfirst}[2]{%
+ \glshasattribute{##1}{combinedfirstsepfirst}%
+ {\glsgetattribute{##1}{combinedfirstsepfirst}}%
+ { }%
+}%
+\end{verbatim}
+This does nothing if either element are abbreviations that have already been
+used. Note that if the associated attributes are set the commands
+will behave according to the attribute.
+
+\begin{definition}[\DescribeMacro\glssetcombinedsepnarrow]
+\cs{glssetcombinedsepnarrow}\marg{width}\marg{narrow sep}
+\end{definition}
+This is rather more complicated as it measures a field value and
+uses \meta{narrow sep} if the width is less than \meta{width}.
+The field value is determined as follows:
+\begin{itemize}
+\item on \gls{firstuse} the
+\gloskey{long} field is used if it is set otherwise the
+\gloskey{first} field is used;
+
+\item otherwise the
+\gloskey{short} field is used if it is set otherwise the
+\gloskey{text} field is used;
+\end{itemize}
+
+Note that this doesn't take into account fonts, hooks, abbreviation
+styles or plural forms (e.g.\ \cs{mglspl}) or other field references
+(e.g.\ \cs{mglsname}). If the associated attributes are set the commands
+will behave according to the attribute.
+
+\section{\headingcs{mgls} Element Hooks}
+\label{sec:mglselementhooks}
+
+The \cs{mgls}-like commands use the following hooks:
+\begin{definition}[\DescribeMacro\mglselementprehook]
+\cs{mglselementprehook}
+\end{definition}
+This is done before each (non-skipped) element. (Default does nothing.)
+\begin{definition}[\DescribeMacro\mglselementposthook]
+\cs{mglselementposthook}
+\end{definition}
+This is done after each (non-skipped) element. (Default does nothing.)
+Note that this is different from the normal entry post-link hook
+\ics{glspostlinkhook}. If the individual entry post-link hook is enabled (see the
+\optfmt{postlinks} key in \sectionref{sec:multiglsoptions}), this will go before
+\cs{mglselementposthook}.
+
+The definitions of the following commands are scoped within the
+\cs{mgls}-like commands so they can't be accessed elsewhere
+(including in the post-link hook, see
+\sectionref{sec:mglspostlinkhook}). They
+may be used in the above hooks or in the separator commands (described in
+\sectionref{sec:mglssep}) or in the command used to encapsulate the
+entire content. They can also be used in the post-link hook (see
+\sectionref{sec:entryfmtmods}) to determine if an entry is being
+used within a \cs{mgls}-like command.
+
+The multi-entry label is stored in:
+\begin{definition}[\DescribeMacro\mglscurrentmultilabel]
+\cs{mglscurrentmultilabel}
+\end{definition}
+
+The label of the main element:
+\begin{definition}[\DescribeMacro\mglscurrentmainlabel]
+\cs{mglscurrentmainlabel}
+\end{definition}
+
+The complete comma-separated list of elements:
+\begin{definition}[\DescribeMacro\mglscurrentlist]
+\cs{mglscurrentlist}
+\end{definition}
+
+Multi-entry options:
+\begin{definition}[\DescribeMacro\mglscurrentoptions]
+\cs{mglscurrentoptions}
+\end{definition}
+These are the options that were used when defining the multi-entry. This
+doesn't include options set with \cs{multiglossaryentrysetup}
+or those passed to \cs{mgls} (or whichever variant is being used).
+
+The current multi-entry category in effect is stored in:
+\begin{definition}[\DescribeMacro\mglscurrentcategory]
+\cs{mglscurrentcategory}
+\end{definition}
+
+The calling command control sequence name (e.g.\ \qt{mgls} or \qt{mglspl})
+can be obtained with:
+\begin{definition}[\DescribeMacro\glsxtrcurrentmglscsname]
+\cs{glsxtrcurrentmglscsname}
+\end{definition}
+
+To test if the current multi-entry is the first use:
+\begin{definition}[\DescribeMacro\mglsisfirstuse]
+\cs{mglsisfirstuse}\marg{true}\marg{false}
+\end{definition}
+This does \meta{true} if this is the first use otherwise it does
+\meta{false}. Note that this
+applies to the multi-entry first use flag not the
+\glspl{firstuseflag} of the individual elements.
+
+At each iteration of the loop over the element list, the following
+commands are set, which can be accessed in hooks such as
+\cs{mglselementprehook} or in hooks used by the underlying \cs{gls}
+etc commands. For example, if \cs{mglscurrentlabel} is defined then
+\cs{gls} is being used inside \cs{mgls}.
+
+The current element label:
+\begin{definition}[\DescribeMacro\mglscurrentlabel]
+\cs{mglscurrentlabel}
+\end{definition}
+
+This is a count register that is set to the element index:
+\begin{definition}[\DescribeMacro\mglselementindex]
+\cs{mglselementindex}
+\end{definition}
+
+The current multi-entry prefix:
+\begin{definition}[\DescribeMacro\mglscurrentprefix]
+\cs{mglscurrentprefix}
+\end{definition}
+
+The current multi-entry suffix:
+\begin{definition}[\DescribeMacro\mglscurrentsuffix]
+\cs{mglscurrentsuffix}
+\end{definition}
+
+\begin{definition}[\DescribeMacro\mglsiflast]
+\cs{mglsiflast}\marg{true}\marg{false}
+\end{definition}
+If this is the last iteration, does \meta{true} otherwise does
+\meta{false}. This takes the skip options into account, so the last
+iteration may not necessarily be when the element index is equal to
+the total number of elements.
+
+\section{Post-Link Hook}
+\label{sec:mglspostlinkhook}
+
+There is a hook that occurs at the end the \cs{mgls}-like commands
+according to the \optfmt{mpostlink} setting (see
+\sectionref{sec:multiglsoptions}). The hook used depends on the
+\optfmt{mpostlinkelement} option.
+These hooks can't access the commands described in \sectionref{sec:mglselementhooks}
+as the hook occurs outside of the scope in which they are defined.
+
+The \optfmt{mpostlinkelement=custom} option uses:
+\begin{definition}[\DescribeMacro\mglscustompostlinkhook]
+\cs{mglscustompostlinkhook}
+\end{definition}
+This does nothing by default.
+
+The \optfmt{mpostlinkelement=last} option uses:
+\begin{definition}[\DescribeMacro\mglslastelementpostlinkhook]
+\cs{mglslastelementpostlinkhook}
+\end{definition}
+which emulates the post-link hook of the last element.
+
+The \optfmt{mpostlinkelement=main} option uses:
+\begin{definition}[\DescribeMacro\mglslastmainpostlinkhook]
+\cs{mglslastmainpostlinkhook}
+\end{definition}
+which emulates the post-link hook of the main element.
+
+The default settings
+\optfmt{postlinks=none,mpostlink=true,mpostlinkelementlast} will
+suppress the individual element post-link hooks
+(\ics{glspostlinkhook}) and do the multi-entry post-link hook for
+the last element (\cs{mglslastelementpostlinkhook}).
+
+If you have the final element's post-link hook enabled and the
+multi-entry post-link hook enabled (for example,
+\optfmt{postlinks=all, mpostlink=true, mpostlinkelement=last}), the
+final element's post-link hook will be done twice. Similarly for the
+main element with
+\optfmt{postlinks=all, mpostlink=true, mpostlinkelement=main}.
+
+The following commands are available for use in these hooks and may
+also be used in \ics{mglssuffix}.
+
+The multi-entry label:
+\begin{definition}[\DescribeMacro\mglslastmultilabel]
+\cs{mglslastmultilabel}
+\end{definition}
+
+The multi-entry category (\sectionref{sec:multiglscategory}):
+\begin{definition}[\DescribeMacro\mglslastcategory]
+\cs{mglslastcategory}
+\end{definition}
+This will be empty if no category was assigned.
+
+\begin{definition}[\DescribeMacro\mglswasfirstuse]
+\cs{mglswasfirstuse}\marg{true}\marg{false}
+\end{definition}
+If that was the first use of the multi-entry (\sectionref{sec:mglsfirstuse})
+this does \meta{true} otherwise it does \meta{false}.
+
+\subsection{Last Element}
+\label{sec:mglspostlinkhooklastelement}
+The following commands relate to the last element.
+
+The label of the last non-skipped element:
+\begin{definition}[\DescribeMacro\mglslastelementlabel]
+\cs{mglslastelementlabel}
+\end{definition}
+If all elements were skipped or if the multi-entry wasn't defined,
+this will be empty.
+
+Test if the last element was skipped:
+\begin{definition}[\DescribeMacro\mglsiflastelementskipped]
+\cs{mglsiflastelementskipped}\marg{true}\marg{false}
+\end{definition}
+If the last element was skipped this does \meta{true} otherwise it
+does \meta{false}.
+If all elements were skipped or if the multi-entry wasn't defined,
+this will do \meta{true}.
+
+Test if the last element was its first use:
+\begin{definition}[\DescribeMacro\mglsiflastelementwasfirstuse]
+\cs{mglsiflastelementwasfirstuse}\marg{true}\marg{false}
+\end{definition}
+If the last non-skipped element was used for the first time this
+does \meta{true} otherwise it does \meta{false}. (Corresponds to
+\cs{glsxtrifwasfirstuse}.)
+If all elements were skipped or if the multi-entry wasn't defined,
+this will do \meta{true}.
+
+Test if the last element was plural:
+\begin{definition}[\DescribeMacro\mglsiflastelementwasplural]
+\cs{mglsiflastelementwasplural}\marg{true}\marg{false}
+\end{definition}
+If the last non-skipped element had the plural form displayed, this
+does \meta{true} otherwise it does \meta{false}. (Corresponds to
+\cs{glsifplural}.)
+If all elements were skipped or if the multi-entry wasn't defined,
+this will do \meta{false}.
+
+Test if the last element was had any case-changing applied:
+\begin{definition}[\DescribeMacro\mglsiflastelementcapscase]
+\cs{mglsiflastelementcapscase}\marg{no-change}\marg{firstuc}\marg{all caps}
+\end{definition}
+Corresponds to \cs{glscapscase} of the last non-skipped element.
+If all elements were skipped or if the multi-entry wasn't defined,
+this will do \meta{no-change}.
+
+\subsection{Main Element}
+\label{sec:mglspostlinkhookmainelement}
+The following commands relate to the main element.
+
+The label of the main element from the multi-entry that was just
+referenced:
+\begin{definition}[\DescribeMacro\mglslastmainlabel]
+\cs{mglslastmainlabel}
+\end{definition}
+If the main element was skipped or if the multi-entry
+wasn't defined, this will be empty. If this is the same as
+\cs{mglslastelementlabel} then the main element was the last
+element.
+
+Test if the main element was skipped:
+\begin{definition}[\DescribeMacro\mglsiflastmainskipped]
+\cs{mglsiflastmainskipped}\marg{true}\marg{false}
+\end{definition}
+If the main element from the multi-entry that was just referenced
+was skipped this does \meta{true} otherwise it does \meta{false}.
+If the multi-entry wasn't defined, this will do \meta{true}.
+
+Test if the main element was its first use:
+\begin{definition}[\DescribeMacro\mglsiflastmainwasfirstuse]
+\cs{mglsiflastmainwasfirstuse}\marg{true}\marg{false}
+\end{definition}
+If the main element was used for the first time this
+does \meta{true} otherwise it does \meta{false}. (Corresponds to
+\cs{glsxtrifwasfirstuse}.)
+If the main element was skipped or if the multi-entry wasn't defined,
+this will do \meta{true}.
+
+Test if the main element was plural:
+\begin{definition}[\DescribeMacro\mglsiflastmainwasplural]
+\cs{mglsiflastmainwasplural}\marg{true}\marg{false}
+\end{definition}
+If the main element from the multi-entry that was just referenced
+had its plural form displayed this does \meta{true} otherwise it
+does \meta{false}. (Corresponds to \cs{glsifplural}.) If the main
+element was skipped or if the multi-entry wasn't defined, this will
+do \meta{false}.
+
+Test if the main element was had any case-changing applied:
+\begin{definition}[\DescribeMacro\mglsiflastmaincapscase]
+\cs{mglsiflastmaincapscase}\marg{no-change}\marg{firstuc}\marg{all caps}
+\end{definition}
+Corresponds to \cs{glscapscase} of the main element from the
+multi-entry that was just referenced. If the main element was
+skipped or if the multi-entry wasn't defined, this will do
+\meta{no-change}.
+
+\section{Multi-Entry First Use}
+\label{sec:mglsfirstuse}
+
+Each multi-entry set has an associated first use flag. This is
+independent of the \gls{firstuseflag} associated with the individual
+entries that make up the set. As with the \cs{gls}-like commands,
+\cs{mgls} unsets this flag. Unlike the \cs{glstext}-like commands, all
+the commands described in \sectionref{sec:mglslike} (including
+commands like \cs{mglsname}) unset this flag, even if the elements
+use commands like \cs{glsname} that don't unset the entry's
+\gls{firstuseflag}.
+
+You can determine whether or not a multi-entry set has been
+marked as used with:
+\begin{definition}[\DescribeMacro\ifmglsused]
+\cs{ifmglsused}\marg{multi-label}\marg{true}\marg{false}
+\end{definition}
+You can (globally) unset the flag (mark the set as having been referenced)
+with:
+\begin{definition}[\DescribeMacro\mglsunset]
+\cs{mglsunset}\marg{multi-label}
+\end{definition}
+or reset it with:
+\begin{definition}[\DescribeMacro\mglsreset]
+\cs{mglsreset}\marg{multi-label}
+\end{definition}
+There are also local versions of these commands:
+\begin{definition}[\DescribeMacro\mglslocalunset]
+\cs{mglslocalunset}\marg{multi-label}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\mglslocalreset]
+\cs{mglslocalreset}\marg{multi-label}
+\end{definition}
+
+To unset all multi-entries:
+\begin{definition}[\DescribeMacro\mglsunsetall]
+\cs{mglsunsetall}
+\end{definition}
+To reset all multi-entries:
+\begin{definition}[\DescribeMacro\mglsresetall]
+\cs{mglsresetall}
+\end{definition}
+
+Note that unsetting or resetting any of the individual element
+\glspl{firstuseflag} doesn't affect the multi-entry flag.
+Similarly, unsetting or resetting the multi-entry flag doesn't
+affect the \glspl{firstuseflag} of the individual elements.
+
+\section{Multi-Entry Category}
+\label{sec:multiglscategory}
+
+A multi-entry set may have an associated category set using the
+\optfmt{category} key described in \sectionref{sec:multiglsoptions}.
+This isn't set by default, but if it is set the category may have
+attributes set in the usual way. The multi-entry category is
+independent of the individual entry categories. The following
+attribute is recognised by commands like \cs{mgls}:
+
+\begin{description}
+
+\item[\catattrdef{multioptions}] default options to apply to any
+multi-entry set with the given category. These can be overridden
+by the first optional argument of \cs{multiglossaryentry} or by the
+\optfmt{setup} key in the first optional argument of commands like
+\cs{mgls}.
+
+\end{description}
+
+Note that you can't access the category or its attributes via the
+multi-entry label (for example, with \cs{glshasattribute}). If you
+need to access the current multi-entry's category within any of the
+\cs{mgls}-like hooks (\sectionref{sec:mglselementhooks}), you can
+obtain the category with \cs{mglscurrentcategory} and use commands
+like \cs{glshascategoryattribute}.
+
+\section{Multi-Entry Settings}
+\label{sec:multiglsoptions}
+
+The settings that govern all multi-entries can be set using:
+\begin{definition}[\DescribeMacro\multiglossaryentrysetup]
+\cs{multiglossaryentrysetup}\marg{options}
+\end{definition}
+The \meta{options} are the same as for \cs{multiglossaryentry}.
+Options may also be set according to the multi-entry category
+attribute \catattr{multioptions}.
+
+Whenever the \cs{mgls}-like commands are used, options are applied in the
+following order:
+\begin{enumerate}
+\item general options identified by \cs{multiglossaryentrysetup};
+
+\item the category key is assigned if it's in the general options,
+\cs{multiglossaryentry} or \optfmt{setup} key;
+
+\item \catattr{multioptions} category attribute (if set);
+
+\item any options provided in the first optional argument of
+\cs{multiglossaryentry};
+
+\item any options provided in the \optfmt{setup} key in the first
+optional argument of the \cs{mgls}-like command.
+\end{enumerate}
+
+These options are described below.
+
+\subsection{Indexing}
+\label{sec:multiglsoptionsindexing}
+
+\begin{description}
+\item[\optfmt{indexmain}] This setting may take one of the following
+values:
+ \begin{description}
+ \item[\optfmt{false}] don't index the main entry;
+ \item[\optfmt{true}] index the main entry;
+ \item[\optfmt{first}] only index the main entry if it's the first
+use (of the main entry).
+ \end{description}
+ The default is \optfmt{true}.
+
+\item[\optfmt{indexothers}] This setting may take one of the following
+values:
+ \begin{description}
+ \item[\optfmt{false}] don't index the other entries;
+ \item[\optfmt{true}] index the other entries;
+ \item[\optfmt{first}] only index the other entries if
+it's the first use (of the non-main entry).
+ \end{description}
+ The default is \optfmt{first}.
+\end{description}
+
+\subsection{Location Formats (Encaps)}
+\label{sec:multiglsoptionsencap}
+
+\begin{description}
+\item[\optfmt{encapmain}] This setting value should be the value to
+ pass to \gloskey[glslink]{format} for the main entry. (The location
+ encapsulator.) The default is \texttt{glsnumberformat}.
+
+\item[\optfmt{encapothers}] This setting value should be the value to
+ pass to \gloskey[glslink]{format} for the other (not main) entries. (The location
+ encapsulator.) The default is \texttt{glsnumberformat}.
+\end{description}
+
+\subsection{Post-Link Hooks}
+\label{sec:multiglsoptionspostlink}
+
+\begin{description}
+\item[\optfmt{postlinks}] This setting determines whether or not to
+enable the individual element's post-link hook
+(\ics{glspostlinkhook}). The value may be one of:
+\begin{description}
+\item[\optfmt{none}] suppress the post-link hook for all elements;
+\item[\optfmt{all}] don't suppress the post-link hook for all elements;
+\item[\optfmt{notlast}] only suppress the post-link hook for the
+last element;
+\item[\optfmt{mainnotlast}] suppress the post-link hook for all
+\qt{other} (not main) elements and for the last element (so only the
+main element will have its post-link hook as long as it's not the
+last element);
+\item[\optfmt{mainonly}] suppress the post-link hook for all
+\qt{other} (not main) elements;
+\item[\optfmt{othernotlast}] suppress the post-link hook for the
+main element and for the last element (so only the other elements
+will have their post-link hook as long as the element isn't the last
+one);
+\item[\optfmt{otheronly}] suppress the post-link hook for the main element.
+\end{description}
+The default is \optfmt{postlinks=none}.
+
+\item[\optfmt{mpostlink}] This setting determines whether or not to
+enable the multi-entry post-link hook
+(\sectionref{sec:mglspostlinkhook}). The value may be one of:
+ \begin{description}
+ \item[\optfmt{false}] suppress the multi-entry post-link hook;
+ \item[\optfmt{true}] enable the multi-entry post-link hook;
+ \item[\optfmt{firstonly}] enable the multi-entry post-link hook
+ only for the first use of the multi-entry;
+ \item[\optfmt{usedonly}] enable the multi-entry post-link hook
+ only for the subsequent (not first) use of the multi-entry.
+ \end{description}
+The default is \optfmt{mpostlink=true}. If the value is omitted,
+\optfmt{true} is assumed.
+
+\item[\optfmt{mpostlinkelement}] This setting indicates which
+post-link hook should be used if the multi-entry post-link hook has
+been enabled. Allowed values:
+ \begin{description}
+ \item[\optfmt{last}] use \ics{mglslastelementpostlinkhook} (that
+is, use the post-link hook for the last element);
+ \item[\optfmt{main}] use \ics{mglslastmainpostlinkhook} (that
+is, use the post-link hook for the main element);
+ \item[\optfmt{custom}] use \ics{mglslastcustompostlinkhook}.
+ \end{description}
+\end{description}
+Note that some combinations may cause a repeated hook.
+
+\subsection{Prefixes and Suffixes}
+\label{sec:multiglsoptionsfixes}
+
+See \sectionref{sec:mglsfixes} for more information on prefixes and
+suffixes. Note that the prefixes and suffixes are not affected by
+case-changing commands such as \cs{Mgls} or \cs{MGLS}.
+If you want a prefix to obey case-changing, use the \cs{mpgls}-like
+commands instead (\sectionref{sec:mpgls}).
+
+\begin{description}
+
+\item[firstprefix] The prefix to use on first use of the
+multi-entry.
+
+\item[usedprefix] The prefix to use on subsequent use of the
+multi-entry.
+
+\item[firstsuffix] The suffix to use on first use of the
+multi-entry.
+
+\item[usedsuffix] The suffix to use on subsequent use of the
+multi-entry.
+\end{description}
+
+\subsection{Skipping Elements}
+\label{sec:multiglsoptionsskip}
+
+\begin{description}
+
+\item[\optfmt{firstskipmain}] This is a boolean setting. If
+\optfmt{true}, the main element will be omitted on (multi-entry) first use.
+
+\item[\optfmt{firstskipothers}] This is a boolean setting. If
+\optfmt{true}, the other (non-main) elements will be omitted on
+(multi-entry) first use.
+
+\item[\optfmt{usedskipmain}] This is a boolean setting. If
+\optfmt{true}, the main element will be omitted on (multi-entry) subsequent use.
+
+\item[\optfmt{usedskipothers}] This is a boolean setting. If
+\optfmt{true}, the other (non-main) elements will be omitted on
+(multi-entry) subsequent use.
+
+\end{description}
+The skip options apply to the multi-entry first use flag not the
+individual element first use. See \sectionref{sec:mglsfirstuse}.
+
+Note that it is technically possible to set the skip options so that
+both the main and the other elements are skipped. However, by
+default, this will generate a warning and only the final optional
+argument (the \meta{insert}) will be displayed. There won't be a
+loop over all elements so the commands set at each iteration, such
+as \cs{mglscurrentlabel}, won't be defined.
+
+The warning and the
+insertion of the \meta{insert} is done by:
+\begin{definition}[\DescribeMacro\glsxtrmglsWarnAllSkipped]
+\cs{glsxtrmglsWarnAllSkipped}\marg{message}\marg{insert}\marg{cs}
+\end{definition}
+where \meta{message} is the warning message and \meta{cs} is the
+control sequence that encapsulates the entire content (including
+hyperlink and the \optfmt{textformat} setting, if enabled).
+
+If, for some particular reason, you want this scenario, you can
+redefine this command to omit the warning.
+
+\subsection{General}
+\label{sec:multiglsoptionsgeneral}
+
+\begin{description}
+\item[\optfmt{hyper}] This setting may take one of the following
+values:
+ \begin{description}
+ \item[\optfmt{none}] no hyperlinks;
+ \item[\optfmt{allmain}] encapsulate the entire content with
+ a single hyperlink to the main entry's target;
+ \item[\optfmt{mainonly}] only hyperlink the main entry;
+ \item[\optfmt{individual}] hyperlink each entry individually;
+ \item[\optfmt{otheronly}] only hyperlink the other entries;
+ \item[\optfmt{notmainfirst}] don't hyperlink the main entry on
+ multi-entry first use;
+ \item[\optfmt{nototherfirst}] don't hyperlink the other entries on
+ multi-entry first use;
+ \item[\optfmt{notfirst}] don't hyperlink any entries on
+ multi-entry first use.
+ \end{description}
+ The default is \optfmt{individual}.
+
+\item[\optfmt{textformat}] This setting value should be the control
+sequence name (without the leading backslash) of the command used to
+encapsulate the entire content. The default is \texttt{@firstofone}.
+
+\item[\optfmt{category}] The category to apply to the
+multi-entry. This is independent of the categories of each of the elements.
+The default is no category. See \sectionref{sec:multiglscategory}.
+
+\item[\optfmt{mglsopts}] Default options to pass to \cs{mgls}.
+Note that \optfmt{setup} can't be used within this value.
+
+\end{description}
+
+\section{\headingcs{mgls} Options}
+\label{sec:mglsopts}
+
+The \meta{options} for \cs{mgls} (and similar commands) are listed below.
+Any additional options provided will be appended to the \optfmt{all}
+value. For example:
+\begin{verbatim}
+\mgls[counter=chapter]{cbot}
+\end{verbatim}
+is equivalent to:
+\begin{verbatim}
+\mgls[all={counter=chapter}]{cbot}
+\end{verbatim}
+Whereas:
+\begin{verbatim}
+\mgls[counter=chapter,all={counter=section}]{cbot}
+\end{verbatim}
+is treated as:
+\begin{verbatim}
+\mgls[all={counter=section,counter=chapter}]{cbot}
+\end{verbatim}
+which has the same effect as:
+\begin{verbatim}
+\mgls[all={counter=chapter}]{cbot}
+\end{verbatim}
+(The descriptions below reference \cs{gls} which is used internally
+by \cs{mgls}. Replace this with \cs{glspl} etc as applicable for the
+variants, such as \cs{mglspl}.)
+
+\begin{description}
+\item[\optfmt{setup}] The value should be a list of any options that
+can be passed to \cs{multiglossaryentrysetup}. These options will
+override any conflicting options that were supplied to \cs{multiglossaryentry}
+or \cs{multiglossaryentrysetup}. Note that \optfmt{mgls} can't be
+used within this value.
+
+\item[\optfmt{all}] The value should be a list of any options that
+can be passed to \cs{gls}. These options will be passed to each
+instance of \cs{gls} and will override any conflicting setting in
+\optfmt{setup}.
+
+\item[\optfmt{main}] The value should be a list of any options that
+can be passed to \cs{gls}. These options will be passed to the
+instance of \cs{gls} used for the main label and will override any
+conflicting setting in \optfmt{all}.
+
+\item[\optfmt{others}] The value should be a list of any options that
+can be passed to \cs{gls}. These options will be passed to each
+instance of \cs{gls} used for the other (not main) labels and will
+override any conflicting setting in \optfmt{all}.
+
+\item[\optfmt{hyper}] a boolean option to determine whether or not
+to use hyperlinks (if supported). This may cause a conflict with
+other options, but is essentially provided to allow the starred
+version of \cs{mgls} to switch off all hyperlinks.
+
+\item[\optfmt{multiunset}] This only applies to the multi-entry
+first use flag, described in \sectionref{sec:mglsfirstuse}, not the
+\glspl{firstuseflag} of the elements. The value may be one of:
+\begin{description}
+\item \optfmt{global} globally unset the flag (default);
+\item \optfmt{local} locally unset the flag;
+\item \optfmt{none} don't unset the flag.
+\end{description}
+
+\item[\optfmt{presetlocal}] a boolean option that governs whether or
+not the following options should have a local or global effect.
+The default is \optfmt{presetlocal=false} (global).
+
+\item[\optfmt{resetall}] a boolean option to determine whether or not
+to reset all entries in \meta{label list} \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+
+\item[\optfmt{resetmain}] a boolean option to determine whether or not
+to reset the main entry \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+
+\item[\optfmt{resetothers}] a boolean option to determine whether or not
+to reset the other (not main) entries \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+
+\item[\optfmt{unsetall}] a boolean option to determine whether or not
+to unset all entries in \meta{label list} \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+
+\item[\optfmt{unsetmain}] a boolean option to determine whether or not
+to unset the main entry \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+
+\item[\optfmt{unsetothers}] a boolean option to determine whether or not
+to unset the other (not main) entries \emph{before} using \cs{gls}.
+This option refers to the individual entry's \gls{firstuseflag} not
+the multi-set flag.
+\end{description}
+The \optfmt{reset\ldots} options all use:
+\begin{definition}[\DescribeMacro\mglselementreset]
+\cs{mglselementreset}\marg{label}
+\end{definition}
+The \optfmt{unset\ldots} options all use:
+\begin{definition}[\DescribeMacro\mglselementunset]
+\cs{mglselementunset}\marg{label}
+\end{definition}
+These take the \optfmt{presetlocal} into account.
+
+An alternative way of resetting the other elements is to use:
+\begin{definition}[\DescribeMacro\mglsunsetothers]
+\cs{mglsunsetothers}\marg{multi-label}
+\end{definition}
+or for a local reset:
+\begin{definition}[\DescribeMacro\mglslocalunsetothers]
+\cs{mglslocalunsetothers}\marg{multi-label}
+\end{definition}
+
+\section{Variants of \headingcs{mgls}}
+\label{sec:mglslike}
+
+The commands listed in this section all behave like \cs{mgls}. These
+(including \cs{mgls} itself) are collectively referred to as the
+\cs{mgls}-like commands. All commands unset the multi-entry first
+use flag (unless the \optfmt{multiunset=none} option is applied). Only
+those commands that use the \cs{gls}-like commands (such as \cs{gls}
+or \cs{glspl}) will unset the individual entry \gls{firstuseflag}.
+
+\subsection{\headingcs{gls}-like}
+\label{sec:mglsbasic}
+
+\begin{definition}[\DescribeMacro\mglspl]
+\cs{mglspl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{glspl} instead of \cs{gls} for each entry.
+
+\begin{definition}[\DescribeMacro\mglsmainpl]
+\cs{mglsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{glspl} instead of \cs{gls} for the main entry and
+\cs{gls} for all the other entries.
+
+\begin{definition}[\DescribeMacro\Mgls]
+\cs{Mgls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Gls} for the first entry and \cs{gls} for the other
+entries.
+
+\begin{definition}[\DescribeMacro\MGls]
+\cs{MGls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Gls} for all entries.
+
+\begin{definition}[\DescribeMacro\Mglspl]
+\cs{Mglspl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Glspl} for the first entry and \cs{glspl} for the other
+entries.
+
+\begin{definition}[\DescribeMacro\Mglsmainpl]
+\cs{Mglsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+The first entry starts with an upper case. The plural form is used
+for the main entry.
+
+\begin{definition}[\DescribeMacro\MGlspl]
+\cs{MGlspl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Glspl} for all entries.
+
+\begin{definition}[\DescribeMacro\MGlsmainpl]
+\cs{MGlsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Glspl} for the main entry and \cs{Gls} for all other entries.
+
+\begin{definition}[\DescribeMacro\MGLS]
+\cs{MGLS}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{GLS} instead of \cs{gls} for each entry.
+
+\begin{definition}[\DescribeMacro\MGLSpl]
+\cs{MGLSpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{GLSpl} instead of \cs{gls} for each entry.
+
+\begin{definition}[\DescribeMacro\MGLSmainpl]
+\cs{MGLSmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses all caps for all entries and \cs{GLSpl} for the main
+entry.
+
+\subsection{Abbreviations}
+\label{sec:mglsabbrv}
+
+\begin{definition}[\DescribeMacro\mglsshort]
+\cs{mglsshort}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This will use \cs{glsxtrshort} for any entries that have the
+\gloskey{short} key set and will use \cs{glstext} otherwise.
+
+\begin{definition}[\DescribeMacro\mglslong]
+\cs{mglslong}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This will use \cs{glsxtrlong} for any entries that have the
+\gloskey{long} key set and will use \cs{glstext} otherwise.
+
+\begin{definition}[\DescribeMacro\mglsfull]
+\cs{mglsfull}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This will use \cs{glsxtrfull} for any entries that have the
+\gloskey{short} key set and will use \cs{glsfirst} otherwise.
+
+\begin{definition}[\DescribeMacro\Mglsshort]
+\cs{Mglsshort}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As \cs{mglsshort} but with an initial capital on the first entry.
+
+\begin{definition}[\DescribeMacro\Mglslong]
+\cs{Mglslong}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As \cs{mglslong} but with an initial capital on the first entry.
+
+\begin{definition}[\DescribeMacro\Mglsfull]
+\cs{Mglsfull}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As \cs{mglsfull} but with an initial capital on the first entry.
+
+\subsection{Other Fields}
+\label{sec:mglsotherfields}
+
+\begin{definition}[\DescribeMacro\mglsname]
+\cs{mglsname}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{glsname} instead of \cs{gls} for each entry.
+
+\begin{definition}[\DescribeMacro\MGlsname]
+\cs{MGlsname}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Glsname} instead of \cs{gls} for each entry.
+
+\begin{definition}[\DescribeMacro\Mglsname]
+\cs{Mglsname}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{Glsname} instead of \cs{gls} for the first entry and
+\cs{glsname} for all the other entries.
+
+\begin{definition}[\DescribeMacro\mglssymbol]
+\cs{mglssymbol}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{glssymbol} if the \gloskey{symbol} key has been set
+otherwise it uses \cs{gls} for each element.
+
+\begin{definition}[\DescribeMacro\MGlssymbol]
+\cs{MGlssymbol}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+This uses \cs{glssymbol} if the \gloskey{symbol} key has been set
+otherwise it uses \cs{Gls} for each element. (Note that no case
+change is applied to the symbol as this usually isn't appropriate.)
+
+\begin{definition}[\DescribeMacro\Mglssymbol]
+\cs{Mglssymbol}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As above, but \cs{Gls} is only used for the first element (if it
+doesn't have the \gloskey{symbol} key set).
+
+\begin{definition}[\DescribeMacro\mglsusefield]
+\cs{mglsusefield}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Use \texttt{\cs{glsdisp}\marg{label}\glsopenbrace\meta{field
+value}\meta{insert}\glsclosebrace} if the field given by:
+\begin{definition}[\DescribeMacro\mglsfield]
+\cs{mglsfield}
+\end{definition}
+exists, otherwise use \cs{gls}. By default, this is \texttt{useri}
+(corresponding to the \gloskey{user1} key). If you redefine
+\cs{mglsfield}, you will need to use the internal name.
+
+\begin{definition}[\DescribeMacro\Mglsusefield]
+\cs{Mglsusefield}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As \cs{mglsusefield} but the first element starts with an initial
+uppercase.
+
+\begin{definition}[\DescribeMacro\MGlsusefield]
+\cs{MGlsusefield}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+As \cs{mglsusefield} but each element starts with an initial
+uppercase.
+
+You can use the pre-element hook \cs{mglselementprehook} to locally
+redefine \cs{mglsfirst}. Examples:
+\begin{enumerate}
+\item if the multi-category is \qt{sample} then use the
+\gloskey{user2} field otherwise use the \gloskey{user1} field:
+\begin{verbatim}
+\renewcommand{\mglselementprehook}{%
+ \ifdefstring{\mglscurrentcategory}{sample}%
+ {\renewcommand{\mglsfield}{userii}}%
+ {\renewcommand{\mglsfield}{useri}}%
+}
+\end{verbatim}
+
+\item if the element's category is \qt{sample} then use the
+\gloskey{user2} field otherwise use the \gloskey{user1} field:
+\begin{verbatim}
+\renewcommand{\mglselementprehook}{%
+ \glsifcategory{\mglscurrentlabel}{sample}%
+ {\renewcommand{\mglsfield}{userii}}%
+ {\renewcommand{\mglsfield}{useri}}%
+}
+\end{verbatim}
+
+\item if either the multi-entry's category or the element's category
+has the custom attribute \qt{mglsfield} set then use it otherwise use
+the \gloskey{user1} field:
+\begin{verbatim}
+\renewcommand{\mglselementprehook}{%
+ \glshascategoryattribute{\mglscurrentcategory}{mglsfield}%
+ {\renewcommand{\mglsfield}{\glsgetcategoryattribute{\mglscurrentcategory}{mglsfield}}}%
+ {%
+ \glshasattribute{\mglscurrentlabel}{mglsfield}%
+ {\renewcommand{\mglsfield}{\glsgetattribute{\mglscurrentlabel}{mglsfield}}}%
+ {\renewcommand{\mglsfield}{useri}}%
+ }%
+}
+\end{verbatim}
+\end{enumerate}
+
+\subsection{Support for \headingsty{glossaries-prefix} (\headingcs{pgls})}
+\label{sec:mpgls}
+
+If you load the \sty{glossaries-prefix} package (either after
+\styfmt{glossaries-extra}) or with the \pkgopt{prefix} package
+option, then the following commands will use one of the
+\cs{pgls}-like commands provided by that package. (See the
+\styfmt{glossaries} user manual for further details.)
+
+If the \styfmt{glossaries-prefix} package hasn't been loaded then
+\cs{gls} (or analogous case-changing variant) will be used instead
+and a warning is issued. The warning can be removed by redefining
+the following to do nothing:
+\begin{definition}[\DescribeMacro\mpglsWarning]
+\cs{mpglsWarning}
+\end{definition}
+
+\begin{definition}[\DescribeMacro\mpgls]
+\cs{mpgls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{pgls} for the first element and \cs{gls} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\mpglspl]
+\cs{mpglspl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{pglspl} for the first element and \cs{glspl} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\mpglsmainpl]
+\cs{mpglsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Only uses the plural form for the main element. The first element
+uses the prefixing command (\cs{pgls} or \cs{pglspl}, depending on
+whether the first element is the main element).
+
+\begin{definition}[\DescribeMacro\Mpgls]
+\cs{Mpgls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{Pgls} for the first element and \cs{gls} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\Mpglsmainpl]
+\cs{Mpglsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Only uses the plural form for the main element. The first element
+uses the first-letter uppercase prefixing command
+(\cs{Pgls} or \cs{Pglspl}, depending on whether the first element is
+the main element).
+
+\begin{definition}[\DescribeMacro\MPGls]
+\cs{MPGls}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{Pgls} for the first element and \cs{Gls} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\MPGlspl]
+\cs{MPGlspl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{Pglspl} for the first element and \cs{Glspl} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\MPGlsmainpl]
+\cs{MPGlsmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Only uses the plural form for the main element. The first element
+uses the prefixing command (\cs{Pgls} or \cs{Pglspl}, depending on
+whether the first element is the main element). All elements are
+converted to first letter uppercase.
+
+\begin{definition}[\DescribeMacro\MPGLS]
+\cs{MPGLS}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{PGLS} for the first element and \cs{GLS} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\MPGLSpl]
+\cs{MPGLSpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Uses \cs{PGLSpl} for the first element and \cs{GLSpl} for the remaining
+elements.
+
+\begin{definition}[\DescribeMacro\MPGLSmainpl]
+\cs{MPGLSmainpl}\oarg{options}\marg{multi-label}\oarg{insert}
+\end{definition}
+Only uses the plural form for the main element. All elements are
+converted to uppercase. The first element uses the prefixing command
+(\cs{PGLS} or \cs{PGLSpl}, depending on whether the first element is
+the main element).
+
+\section{Cross-References}
+\label{sec:msee}
+
+Multi-entry labels may be used in the cross-referencing keys
+\gloskey{see} and \gloskey{seealso}. The formatting command will
+use:
+\begin{definition}[\DescribeMacro\mglsseefirstitem]
+\cs{mglsseefirstitem}\marg{label}
+\end{definition}
+for the first item in the list (if it's a multi-entry) and
+\begin{definition}[\DescribeMacro\mglsseeitem]
+\cs{mglsseeitem}\marg{label}
+\end{definition}
+for any subsequent items that are multi-entries. The default
+definition of \cs{mglsseeitem} is:
+\begin{verbatim}
+\newcommand*{\mglsseeitem}[1]{%
+ \mglsname[all={noindex},setup={hyper=allmain}]{#1}%
+}
+\end{verbatim}
+This switches off indexing, sets the hyperlink to encompass the
+entire multi-entry content and uses the \gloskey{name} field.
+The default definition of \cs{mglsseefirstitem} is simply
+\cs{mglsseeitem}.
+
+For example, to use the \gloskey{short} or \gloskey{text} fields:
+\begin{verbatim}
+\renewcommand*{\mglsseeitem}[1]{%
+ \mglsshort[all={noindex},setup={hyper=allmain}]{#1}%
+}
+\end{verbatim}
+
+A multi-entry label may also be used in the \gloskey{alias} key. The
+hyperlink target will be the target for the main entry. For example:
+\begin{verbatim}
+\multiglossaryentry{cbot}{clostridium,botulinum}
+\newglossaryentry{botox}{name=botox,description={},alias={cbot}}
+\end{verbatim}
+In this case \verb|\gls{botox}| will hyperlink to the
+\texttt{botulinum} target.
+
+\begin{important}
+Any multi-entries used in the cross-referencing keys must be defined
+before the glossary is displayed. There is some support for
+\pkgopt[true]{docdef} but not for the other \pkgopt{docdef} settings.
+\end{important}
+
+\section{Additional Commands}
+\label{sec:multiextras}
+
+You can test if a label represents a multi-entry using:
+\begin{definition}[\DescribeMacro\glsxtrifmulti]
+\cs{glsxtrifmulti}\marg{label}\marg{true}\marg{false}
+\end{definition}
+The following command will expand to the main entry label for
+the given multi-entry label:
+\begin{definition}[\DescribeMacro\glsxtrmultimain]
+\cs{glsxtrmultimain}\marg{multi-label}
+\end{definition}
+This will expand to nothing if the supplied \meta{multi-label}
+hasn't been defined as a multi-entry. Similarly, for the complete
+label list:
+\begin{definition}[\DescribeMacro\glsxtrmultilist]
+\cs{glsxtrmultilist}\marg{multi-label}
+\end{definition}
+
+To iterate over all the list of all elements:
+\begin{definition}[\DescribeMacro\mglsforelements]
+\cs{mglsforelements}\marg{multi-label}\marg{cs}\marg{body}
+\end{definition}
+This defines \meta{cs} to the current element label on each
+iteration of the loop, which can be used to reference the label in
+\meta{body}. This internally uses \cs{@for} (patched by the
+\sty{xfor} package).
+
+There is a similar command that skips the main element:
+\begin{definition}[\DescribeMacro\mglsforotherelements]
+\cs{mglsforotherelements}\marg{multi-label}\marg{cs}\marg{body}
+\end{definition}
+
+The total number of elements can be obtained with:
+\begin{definition}[\DescribeMacro\glsxtrmultitotalelements]
+\cs{glsxtrmultitotalelements}\marg{multi-label}
+\end{definition}
+This expands to the number, if \meta{multi-label} is defined,
+otherwise expands to nothing.
+
+The index of the main element can be obtained with:
+\begin{definition}[\DescribeMacro\glsxtrmultimainindex]
+\cs{glsxtrmultimainindex}\marg{multi-label}
+\end{definition}
+This expands to the index, if \meta{multi-label} is defined,
+otherwise expands to nothing. Indexing starts from 1 for the first
+element. The index of the final non-main element can be obtained
+with:
+\begin{definition}[\DescribeMacro\glsxtrmultilastotherindex]
+\cs{glsxtrmultilastotherindex}\marg{multi-label}
+\end{definition}
+
+The \cs{multiglossaryentry} command will write the label information
+to the \filetype{aux} file using:
+\begin{definition}[\DescribeMacro\writemultiglossentry]
+\cs{writemultiglossentry}\marg{options}\marg{multi-label}\marg{main-label}\marg{list}
+\end{definition}
+This is will write the following line to the \filetype{aux} file:
+\begin{definition}
+\cs{@glsxtr@multientry}\marg{options}\marg{multi-label}\marg{main-label}\marg{list}
+\end{definition}
+This is provided to support \pkgopt[true]{docdef} and also
+for the benefit of any tools that require the
+information (such as \gls{bib2gls} or autocompletion tools).
+If it's not required and causes too much clutter, it can
+be disabled by redefining \cs{writemultiglossentry} to do nothing.
+
+\section{\headingapp{bib2gls}}
+\label{sec:mbib2gls}
+
+In the \gls{bib2gls} v2.9+ user manual, these multi-entry sets are
+referred to as \qt{compound entries} or \qt{compound sets} to
+differentiate them from \gls{bib2gls}['s] multi-entry types (such as
+\texttt{@dualentry}).
+
+Each instance of one of the \cs{mgls}-like commands is written to
+the \filetype{aux} file and so can be picked up by \gls{bib2gls}
+(at least version 2.9). The resource options can be used to
+determine whether or not to consider the other (non-main) elements
+to be dependent on the main element.
+
+With \gls{bib2gls}, you can either define the compound entries in
+the document with \cs{multiglossaryentry} (or
+\cs{providemultiglossaryentry}) or you can use the \texttt{@compoundset}
+entry type in a \filetype{bib} file. Whichever method you use,
+remember that the entries that form the elements of the set must be
+defined first. See the \gls{bib2gls} manual (v2.9+) for further details.
+
+You can use the resource option \optfmt{compound-adjust-name}
+to replace the \gloskey{name} field of the main entry to:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustedname]
+\cs{glsxtrmultientryadjustedname}\marg{sublist1}\marg{name}\marg{sublist2}\marg{label}
+\end{definition}
+where \meta{label} is the label identifying the compound set,
+\meta{name} was the value of the \gloskey{name} before adjustment,
+\meta{sublist1} is the sub-list of other element labels
+before the main element (empty if the main element is the first
+element in the list), and \meta{sublist2} is the sub-list of
+other elements after the main element (empty if the main label is
+the final element).
+
+This command is defined in \sty{glossaries-extra-bib2gls}, which is
+automatically loaded with \pkgopt[only]{record} and
+\pkgopt[nameref]{record}. Case-changing versions of this command are
+also available. First letter uppercase:
+\begin{definition}[\DescribeMacro\Glsxtrmultientryadjustedname]
+\cs{Glsxtrmultientryadjustedname}\marg{sublist1}\marg{name}\marg{sublist2}\marg{label}
+\end{definition}
+Title case:
+\begin{definition}[\DescribeMacro\GlsXtrmultientryadjustedname]
+\cs{GlsXtrmultientryadjustedname}\marg{sublist1}\marg{name}\marg{sublist2}\marg{label}
+\end{definition}
+All uppercase:
+\begin{definition}[\DescribeMacro\GLSxtrmultientryadjustedname]
+\cs{GLSxtrmultientryadjustedname}\marg{sublist1}\marg{name}\marg{sublist2}\marg{label}
+\end{definition}
+
+Note that this command doesn't take the prefix or suffix into
+account (see \sectionref{sec:mglsfixes}).
+
+The separator between each element in the sub-lists is produced
+with:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustednamesep]
+\cs{glsxtrmultientryadjustednamesep}\marg{pre label}\marg{post label}
+\end{definition}
+The default definition just uses \cs{glscombinedfirstsepfirst}.
+
+The separator between the last element of \meta{sublist1} and the
+main element is produced with:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustednamepresep]
+\cs{glsxtrmultientryadjustednamepresep}\marg{pre label}\marg{post label}
+\end{definition}
+Similarly for the separator between the main element and the first
+element of \meta{sublist2}:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustednamepostsep]
+\cs{glsxtrmultientryadjustednamepostsep}\marg{pre label}\marg{post label}
+\end{definition}
+These both default to \cs{glsxtrmultientryadjustednamesep}.
+
+The \meta{name} is encapsulated with:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustednamefmt]
+\cs{glsxtrmultientryadjustednamefmt}\marg{text}
+\end{definition}
+This just does its argument by default.
+If \meta{sublist1} is empty for the first letter upper case
+version, then \meta{name} is encapsulated with:
+\begin{definition}[\DescribeMacro\Glsxtrmultientryadjustednamefmt]
+\cs{Glsxtrmultientryadjustednamefmt}\marg{text}
+\end{definition}
+This does \ics{makefirstuc}\marg{text} by default.
+For the title case version, the name is encapsulated with:
+\begin{definition}[\DescribeMacro\GlsXtrmultientryadjustednamefmt]
+\cs{GlsXtrmultientryadjustednamefmt}\marg{text}
+\end{definition}
+This uses \cs{glscapitalisewords} (provided by \styfmt{glossaries}
+v4.48+) if defined or \cs{capitalisewords} otherwise.
+The all uppercase version uses:
+\begin{definition}[\DescribeMacro\GLSxtrmultientryadjustednamefmt]
+\cs{GLSxtrmultientryadjustednamefmt}\marg{text}
+\end{definition}
+This uses \cs{mfirstucMakeUppercase} by default.
+
+Each element label in the sub-lists is encapsulated with:
+\begin{definition}[\DescribeMacro\glsxtrmultientryadjustednameother]
+\cs{glsxtrmultientryadjustednameother}\marg{label}
+\end{definition}
+This does \cs{glsentryname}\marg{label} by default.
+For the first letter uppercase version (where
+\meta{sublist1} isn't empty), then the element label is encapsulated
+with:
+\begin{definition}[\DescribeMacro\Glsxtrmultientryadjustednameother]
+\cs{Glsxtrmultientryadjustednameother}\marg{label}
+\end{definition}
+This does \cs{Glsentryname}\marg{label} by default.
+The title case version uses:
+\begin{definition}[\DescribeMacro\GlsXtrmultientryadjustednameother]
+\cs{GlsXtrmultientryadjustednameother}\marg{label}
+\end{definition}
+This does \ics{glsentrytitlecase}\marg{label}\verb|{name}| by
+default.
+The all uppercase version uses:
+\begin{definition}[\DescribeMacro\GLSxtrmultientryadjustednameother]
+\cs{GLSxtrmultientryadjustednameother}\marg{label}
+\end{definition}
+This is defined as:
+\begin{verbatim}
+\newcommand*{\GLSxtrmultientryadjustednameother}[1]{%
+ \mfirstucMakeUppercase{\glsentryname{#1}}}
+\end{verbatim}
+
\chapter{Categories}
\label{sec:categories}
@@ -7533,6 +9962,8 @@ are displayed in the text or glossary. Note that an entry's category
is independent of the glossary type. Be careful not to confuse
\gloskey{category} with \gloskey{type}.
+For multi-entry categories, see \sectionref{sec:multiglscategory}.
+
The default category assumed by
\cs{newglossaryentry} is labelled \category{general}. Abbreviations
defined with \cs{newabbreviation} have the category set to
@@ -8019,6 +10450,18 @@ provided.
but applies to the \gloskey{firstaccess} field automatically assigned if it's not
provided.
+\item[\catattrdef{combinedfirstsep}] The separator to use for
+\ics{glscombinefirstsep}.
+
+\item[\catattrdef{combinedfirstsepfirst}] The separator to use for
+\ics{glscombinedfirstsepfirst}.
+
+\item[\catattrdef{combinedsepfirst}] The separator to use for
+\ics{glscombinesepfirst}.
+
+\item[\catattrdef{combinedsep}] The separator to use for
+\ics{glscombinedsep}.
+
\end{description}
An attribute can be set using:
@@ -8027,13 +10470,37 @@ An attribute can be set using:
\end{definition}
where \meta{category-label} is the category label,
\meta{attribute-label} is the attribute label and \meta{value} is
-the new value for the attribute.
+the new value for the attribute. \emph{This will be localised to the
+current scope.} If you want a global definition use the following
+command instead.
+
+If you want to apply the same attribute to multiple categories then
+use:
+\begin{definition}[\DescribeMacro\glssetcategoriesattribute]
+\cs{glssetcategoriesattribute}\marg{category-label list}\marg{attribute-label}\marg{value}
+\end{definition}
+\emph{This has a global effect.}
+
+If you also want to set multiple attributes to the same value, then
+you can use:
+\begin{definition}[\DescribeMacro\glssetcategoriesattributes]
+\cs{glssetcategoriesattributes}\marg{category-label list}\marg{attribute-label list}\marg{value}
+\end{definition}
+\emph{This has a global effect.}
+
+For example:
+\begin{verbatim}
+\newcommand{\latinname}[1]{\emph{#1}}
+\glssetcategoriesattributes{genus,species}{textformat,glossnamefont}{latinname}
+\end{verbatim}
There is a shortcut version to set the \catattr{regular} attribute
to \qt{true}:
\begin{definition}[\DescribeMacro\glssetregularcategory]
\cs{glssetregularcategory}\marg{category-label}
\end{definition}
+This internally uses \cs{glssetcategoryattribute} so it has a local
+effect.
If you need to lookup the category label for a particular entry, you
can use the shortcut command:
@@ -8903,7 +11370,7 @@ Set the escape (quote) character to \meta{char}.
\end{definition}
Set the encap character to \meta{char}.
-\chapter{\appfmt{bib2gls}: Managing Reference Databases}
+\chapter{\headingapp{bib2gls}: Managing Reference Databases}
\label{sec:bib2gls}
There is a new command line application called
@@ -9072,6 +11539,7 @@ reads the file to allow for any internal commands stored in the
location field.
\section{Selection}
+\label{sec:bib2glsselection}
The default behaviour is for \gls{bib2gls} to select all entries
that have a record in the \texttt{.aux} file, and any dependent
@@ -9112,6 +11580,7 @@ have any records will have an empty location list.
See the \gls{bib2gls} user manual for more details of this option.
\section{Sorting and Displaying the Glossary}
+\label{sec:bib2glssortprint}
There are many sorting options provided by \gls{bib2gls}.
The default is to sort according to the system locale.
@@ -9311,7 +11780,7 @@ the above needs to be written as:
\}]
\end{alltt}
-\section{The \styfmt{glossaries-extra-bib2gls} package}
+\section{The \headingsty{glossaries-extra-bib2gls} package}
\label{sec:bib2glssty}
The package option \pkgopt[only]{record} (or simply \pkgopt{record})
@@ -10297,6 +12766,7 @@ The nabla symbol ($\nabla$).
\section{Supplementary Commands}
+\label{sec:bib2glssupplementarycommands}
These commands are provided by \styfmt{glossaries-extra}
for use with \gls{bib2gls}.