summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-02-05 23:22:17 +0000
committerKarl Berry <karl@freefriends.org>2017-02-05 23:22:17 +0000
commit17efbb93c3c280ebec43438b10c53601758ef11e (patch)
treea113323608fcf1d4538b75835d3d28b8b6bae6be /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parent9cb0c9d7ad125c5b287bfc285ebf1bf94749494a (diff)
glossaries-extra (4feb17)
git-svn-id: svn://tug.org/texlive/trunk@43152 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex1224
1 files changed, 1100 insertions, 124 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
index b531dedd609..78dd9913911 100644
--- a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
@@ -71,6 +71,17 @@ called \texttt{makeglossaries-lite} (without the \texttt{.lua}
extension) to the actual \texttt{makeglossaries-lite.lua} script.}
}
+\newglossaryentry{bib2gls}{%
+name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},%
+sort={bib2gls},%
+text={\appfmt{bib2gls}\iapp{bib2gls}},%
+description={A command line Java application that selects
+entries from a .bib file and converts them to glossary
+definitions. At the time of writing, this application
+is still under development. Further details at:
+\url{https://github.com/nlct/bib2gls}.}%
+}
+
\newglossaryentry{numberlist}{%
name={number list},%
description={A list of \glspl{entrylocation} (also
@@ -155,13 +166,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.11:
+ \title{glossaries-extra.sty v1.12:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-01-19}
+ \date{2017-02-03}
\maketitle
\begin{abstract}
@@ -477,14 +488,12 @@ over a glossary list. This includes \ics{forglsentries} and
\ics{glsaddall}.
\end{important}
-\item[{\pkgopt{record}}] (New to v1.08.) This is a \meta{key}=\meta{value}
+\item[{\pkgopt{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value}
option, which has three allowed values: \pkgoptfmt{off} (default),
\pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted
\pkgoptfmt{only} is assumed. The option is provided for the benefit
-of any post-processing applications that need to know information
-about the entries used in the document, such as
-\href{https://github.com/nlct/bib2gls}{bib2gls}.\footnote{Still
-under development at the time of writing this.}
+of \gls{bib2gls} (see \sectionref{sec:bib2gls}).
+
The option may only be set in the preamble.
The \pkgopt[off]{record} option switches off the recording, as per
@@ -499,94 +508,11 @@ or \cs{makenoidxglossaries} has been used) whereas
With the recording on, any of the commands that would typically
index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd})
will add a \cs{glsxtr@record} entry to the \texttt{.aux} file.
-The post-processing application can then read these lines to find
+\gls{bib2gls} can then read these lines to find
out which entries have been used. (Remember that commands like
\cs{glsentryname} don't index, so any use of these commands won't
add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux}
-file.)
-
-There are new commands that are intended for use with the
-recording function:
-\begin{definition}[\DescribeMacro\glsxtrresourcefile]
-\cs{glsxtrresourcefile}\oarg{options}\marg{filename}
-\end{definition}
-(Don't include the file extension in \meta{filename}.)
-There's a shortcut version that sets \meta{filename} \cs{jobname}:
-\begin{definition}[\DescribeMacro\GlsXtrLoadResources]
-\cs{GlsXtrLoadResources}\oarg{options}
-\end{definition}
-(Only one instance of \cs{GlsXtrLoadResources} is permitted
-per document. Use \cs{glsxtrresourcefile} for any additional
-resources.)
-
-This writes the line
-\begin{alltt}
-\cs{glsxtr@resource}\marg{options}\marg{filename}
-\end{alltt}
-to the \texttt{.aux} file and will input
-\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed
-\meta{filename}\texttt{.tex} but that's potentially dangerous if,
-for example, \meta{filename} happens to be the same as \cs{jobname}.
-The \texttt{.glstex} extension was enforced by version 1.11.} The post-processor may use this information
-to create the required file. (This is why the \pkgopt{record}
-option automatically switches on \pkgopt[warn]{undefaction},
-to allow the document to compile before the post-processor
-has created the \texttt{.glstex} file.)
-
-The options aren't processed by
-\styfmt{glossaries-extra} (other than simply writing \meta{options}
-to the \texttt{.aux} file). The post-processor determines the
-allowed options. As from v1.11, this command also writes other
-information to the \texttt{.aux} file for the benefit of the
-post-processor, including the list of valid keys allowed by
-\cs{newglossaryentry} so make sure you add any custom keys
-before using \cs{glsxtrresourcefile} or \cs{GlsXtrLoadResources}
-if the post-processor needs that information.
-
-\begin{definition}[\DescribeMacro\printunsrtglossary]
-\cs{printunsrtglossary}\oarg{options}
-\end{definition}
-This behaves like \cs{printnoidxglossary} but never sorts the
-entries and always lists all the defined entries for the given
-glossary (and doesn't require \cs{makenoidxglossaries}).
-
-\begin{important}
-You may use this command without the \pkgopt{record} option
-or \cs{glsxtrresourcefile} if you're happy to have a complete
-unsorted list without \glspl{numberlist}. However this requires
-all entries to have been defined before use, so if you've used the
-\pkgopt{docdefs} package option with definitions after the glossary,
-you'll need a second \LaTeX\ run to pick up the definitions from the
-\texttt{.glsdefs} file.
-\end{important}
-
-The optional argument is as for \cs{printnoidxglossary} (except for
-the \gloskey[printnoidxglossary]{sort} key, which isn't available).
-The \gls{numberlist} will need setting by the post-processor
-by adding the \gloskey{loclist} or \gloskey{location} field to the entry definitions,
-otherwise the \gls*{numberlist} will be empty. (If both the
-\gloskey{loclist} and \gloskey{location} fields are set, the
-\gloskey{location} field will be used in the glossary.)
-
-The \gloskey{location} field should contain the relevant commands to
-format the \gls{numberlist}. There's no specific syntax for this
-field, it just needs to contain valid \LaTeX\ commands.
-
-The \gloskey{loclist} field should be a list separated by
-\verb"|" (as per \sty{etoolbox}'s internal lists) where each
-location in the list is in the format
-\begin{definition}
-\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
-\end{definition}
-(see the \styfmt{glossaries} manual for information about that
-command).
-
-All glossaries may be displayed in the order of their definition
-using:
-\begin{definition}[\DescribeMacro\printunsrtglossaries]
-\cs{printunsrtglossaries}
-\end{definition}
-which is analogous to \cs{printnoidxglossaries}.
+file.) See \sectionref{sec:bib2gls} for further details.
\item[{\pkgopt{docdef}}] This option governs the use of
\cs{newglossaryentry}. It was originally a boolean option,
@@ -668,9 +594,14 @@ the end of the document. Note that this necessarily adds to
the overall document build time, especially if you have defined
a large number of entries, so this defaults to \pkgoptfmt{false},
but it will be automatically switched on if you use the \gloskey{see} key in any
-entries. To force it off, even if you use the \gloskey{see}, you
+entries. To force it off, even if you use the \gloskey{see} key, you
need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}.
+Note that \gls{bib2gls} can automatically find dependent
+entries when it parses the \texttt{.bib} source file.
+The \pkgopt{record} option automatically implements
+\pkgopt[false]{indexcrossrefs}.
+
\item[{\pkgopt{abbreviations}}] This option has no value and can't
be cancelled. If used,
it will automatically create a new glossary with the label
@@ -797,12 +728,81 @@ version that doesn't automatically switch off the hyperlinks.
This starred version may be used with the \catattr{targeturl}
attribute to create a link to an external URL. (See
\sectionref{sec:categories} for further details.)
-
-The \cs{newglossaryentry} command has a new key called
-\gloskey{category}, which sets the category label for the given
+As from v1.12 both the starred and unstarred version check
+that the glossary doesn't already exist. (The \styfmt{glossaries}
+package omits this check.)
+
+You can now provide an ignored glossary with:
+\begin{definition}[\DescribeMacro\provideignoredglossary]
+\cs{provideignoredglossary}\marg{type}
+\end{definition}
+which will only define the glossary if it doesn't already exist.
+This also has a starred version that doesn't automatically switch
+off hyperlinks.
+
+The individual glossary displaying commands \ics{printglossary},
+\ics{printnoidxglossary} and \cs{printunsrtglossary} have an extra
+key \gloskey[printglossary]{target}. This is a boolean key which can
+be used to switch off the automatic hypertarget for each entry.
+Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so
+any cross-references within the glossary won't be affected. This is
+a way of avoiding duplicate target warnings if a glossary needs to
+be displayed multiple times.
+
+The \cs{newglossaryentry} command has two new keys:
+\begin{itemize}
+\item \gloskey{category}, which sets the category label for the given
entry. By default this is \texttt{general}. See
\sectionref{sec:categories} for further information about
categories.
+\item \gloskey{alias}, which allows an entry to be alias to another
+entry. See \sectionref{sec:alias} for further details.
+\end{itemize}
+
+The \cs{longnewglossaryentry} command now has a starred version
+(as from v1.12) that doesn't automatically insert
+\begin{verbatim}
+\leavevmode\unskip\nopostdesc
+\end{verbatim}
+at the end of the description field.
+\begin{definition}[\DescribeMacro\longnewglossaryentry]
+\cs{longnewglossaryentry}*\marg{label}\marg{options}\marg{description}
+\end{definition}
+The \gloskey{descriptionplural} key is left unset unless explicitly
+set in \meta{options}.
+
+The unstarred version no longer hard-codes the above code (which
+removes trailing space and suppresses the post-description hook) but instead
+uses:
+\begin{definition}[\DescribeMacro\glsxtrpostlongdescription]
+\cs{glsxtrpostlongdescription}
+\end{definition}
+This can be redefined to allow the post-description hook to work
+but retain the \cs{unskip} part if required.
+For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip}
+\end{verbatim}
+This will discarded unwanted trailing space at the end of the description
+but won't suppress the post-description hook.
+
+The unstarred version also alters the base \sty{glossaries} package's
+treatment of the \gloskey{descriptionplural} key. Since a
+plural description doesn't make much sense for multi-paragraph
+descriptions, the default behaviour with
+\sty{glossaries-extra}'s
+\cs{longnewglossaryentry} is to simply leave the plural description
+unset unless explicitly set using the \gloskey{descriptionplural}
+key. The \styfmt{glossaries.sty} version of this command sets the description's
+plural form to the same as the singular.\footnote{The
+\gloskey{descriptionplural} key is a
+throwback to the base package's original acronym mechanism before the introduction of
+the \gloskey{long} and \gloskey{short} keys, where the long form was
+stored in the \gloskey{description} field and the short form was stored in the
+\gloskey{symbol} field.}
+
+Note that this modified unstarred version doesn't append
+\cs{glsxtrpostlongdescription} to the description's plural form.
The \ics{newterm} command (defined through the \pkgopt{index} package
option) is modified so that the category defaults to \category{index}.
@@ -1178,6 +1178,71 @@ you can use \verb|\gls*[noindex]{sample}| or
\verb|\gls![hyper=false]{sample}| but you can't combine the
\texttt{*} and \texttt{!} modifiers.
+\Glspl{locationlist} displayed with \cs{printnoidxglossary}
+internally use
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+This command is provided by \styfmt{glossaries}, but is modified by
+\styfmt{glossaries-extra} to check for the start and end range
+formation identifiers \verb|(| and \verb|)| which are discarded to
+obtain the actual control sequence name that forms the location
+formatting command.
+
+If the range identifiers aren't present, this just uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc]
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{definition}
+otherwise it uses
+\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc]
+\cs{glsxtrdisplaystartloc}\marg{format}\marg{location}
+\end{definition}
+for the start of a range (where the identifier has been stripped
+from \meta{format}) or
+\begin{definition}[\DescribeMacro\glsxtrdisplayendloc]
+\cs{glsxtrdisplayendloc}\marg{format}\marg{location}
+\end{definition}
+for the end of a range (where the identifier has been stripped
+from \meta{format}).
+
+By default the start range command saves the format in
+\begin{definition}[\DescribeMacro\glsxtrlocrangefmt]
+\cs{glsxtrlocrangefmt}
+\end{definition}
+and does
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+(If the format is empty, it will be replaced with
+\texttt{glsnumberformat}.)
+
+The end command checks that the format matches the start of the
+range, does
+\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook]
+\cs{glsxtrdisplayendlochook}\marg{format}\marg{location}
+\end{definition}
+(which does nothing by default), followed by
+\begin{display}
+\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location}
+\end{display}
+and then sets \cs{glsxtrlocrangefmt} to empty.
+
+This means that the list
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{(textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{)textbf}{1}.
+\end{verbatim}
+doesn't display any differently from
+\begin{verbatim}
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1},
+\glsnoidxdisplayloc{}{page}{textbf}{1}.
+\end{verbatim}
+but it does make it easier to define your own custom list handler
+that can accommodate the ranges.
+
+
\section{Entry Counting Modifications}
\label{sec:entrycountmods}
@@ -1203,6 +1268,92 @@ other categories will be unchanged.
Further information about entry counting, including the
new per-unit feature, is described in \sectionref{sec:entrycount}.
+\section{Plurals}
+
+Some languages, such as English, have a general rule that plurals
+are formed from the singular with a suffix appended. This isn't
+an absolute rule. There are plenty of exceptions (for example,
+geese, children, churches, elves, fairies, sheep). The
+\sty{glossaries} package allows the \gloskey{plural} key to be
+optional when defining entries. In some cases a plural may not make
+any sense (for example, the term is a symbol) and in some cases
+the plural may be identical to the singular.
+
+To make life easier for languages where the majority of plurals can
+simply be formed by appending a suffix to the singular, the
+\sty{glossaries} package sets lets the \gloskey{plural} field default
+to the value of the \gloskey{text} field with \ics{glspluralsuffix}
+appended. This command is defined to be just the letter \qt{s}.
+This means that the majority of terms don't need to have the
+\gloskey{plural} supplied as well, and you only need to use it for the
+exceptions.
+
+For languages that don't have this general rule, the \gloskey{plural}
+field will always need to be supplied, where needed.
+
+There are other plural fields, such as \gloskey{firstplural},
+\gloskey{longplural} and \gloskey{shortplural}. Again, if you are using
+a language that doesn't have a simple suffix rule, you'll have to
+supply the plural forms if you need them (and if a plural makes
+sense in the context).
+
+If these fields are omitted, the \sty{glossaries} package follows
+these rules:
+\begin{itemize}
+\item If \gloskey{firstplural} is missing, then \cs{glspluralsuffix}
+is appended to the \gloskey{first} field, if that field has been
+supplied. If the \gloskey{first} field hasn't been supplied but the
+\gloskey{plural} field has been supplied, then the \gloskey{firstplural}
+field defaults to the \gloskey{plural} field. If the \gloskey{plural}
+field hasn't been supplied, then both the \gloskey{plural} and
+\gloskey{firstplural} fields default to the \gloskey{text} field (or
+\gloskey{name}, if no \gloskey{text} field) with \cs{glspluralsuffix}
+appended.
+
+\item If the \gloskey{longplural} field is missing, then
+\cs{glspluralsuffix} is appended to the \gloskey{long} field, if the
+\gloskey{long} field has been supplied.
+
+\item If the \gloskey{shortplural} field is missing then, \emph{with
+the base \sty{glossaries} acronym mechanism}, \ics{acrpluralsuffix}
+is appended to the \gloskey{short} field.
+
+\end{itemize}
+
+This \emph{last case is changed} with \styfmt{glossaries-extra}.
+With this extension package, the \gloskey{shortplural} field
+defaults to the \gloskey{short} field with \ics{abbrvpluralsuffix}
+appended unless overridden by category attributes. This
+suffix command is set by the abbreviation styles. This means that
+every time an abbreviation style is implemented,
+\cs{abbrvpluralsuffix} is redefined. In most cases its redefined to
+use
+\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix]
+\cs{glsxtrabbrvpluralsuffix}
+\end{definition}
+which defaults to just \cs{glspluralsuffix}. Some of the
+abbreviation styles have their own command for the plural suffix,
+such as \cs{glsxtrscsuffix} which is defined as:
+\begin{verbatim}
+\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}}
+\end{verbatim}
+So if you want to completely strip all the plural suffixes used for
+abbreviations then you need to redefine \cs{glsxtrabbrvpluralsuffix}
+\emph{not} \cs{abbrvpluralsuffix}, which changes with the style. Redefining
+\cs{acrpluralsuffix} will have no affect, since it's not used by the
+new abbreviation mechanism.
+
+If you require a mixture (for example, in a multilingual document),
+there are two attributes that affect the short plural suffix
+formation. The first is \catattr{aposplural} which uses the suffix
+\begin{verbatim}
+'\abbrvpluralsuffix
+\end{verbatim}
+That is, an apostrophe followed by \cs{abbrvpluralsuffix} is
+appended. The second attribute is \catattr{noshortplural} which
+suppresses the suffix and simply sets \gloskey{shortplural} to the
+same as \gloskey{short}.
+
\section{Nested Links}
\label{sec:nested}
@@ -1868,6 +2019,10 @@ want to suppress the page number (and only index the entry once).
See the accompanying sample file \texttt{sample-pages.tex}.
+Note that \gls{bib2gls} can be instructed to insert
+a prefix at the start of non-empty location lists, which
+can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}.
+
\subsection{The \styfmt{glossaries-extra-stylemods} Package}
\label{sec:stylemods}
@@ -3186,6 +3341,30 @@ use \ics{glsxtremfont}.
1.04, but original name retained as a deprecated synonym for
backward-compatibility.)
+\item[\abbrstyle{short-postlong-user}]
+This style was introduced in version 1.12. It's like the
+\abbrstyle{short-long-user} style but defers the parenthetical
+material to after the link-text. This means that you don't have such
+a long hyperlink (which can cause problems for the DVI \LaTeX\ format)
+and it also means that the user supplied material can include a
+hyperlink to another location.
+
+\item[\abbrstyle{short-postlong-user-desc}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{short-postlong-user} style but the \gloskey{description}
+must be specified.
+
+\item[\abbrstyle{long-postshort-user}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{short-postlong-user} style but the long form is shown
+first and the short form is in the parenthetical material (as for
+\abbrstyle{long-short-user}) style.
+
+\item[\abbrstyle{long-postshort-user-desc}]
+This style was introduced in version 1.12. It's like the above
+\abbrstyle{long-postshort-user} style but the \gloskey{description}
+must be specified.
+
\end{description}
\section{Defining New Abbreviation Styles}
@@ -4745,6 +4924,265 @@ don't use any commands in the \meta{label}, even if they expand
to just text.
\end{important}
+\chapter{bib2gls: Managing Reference Databases}
+\label{sec:bib2gls}
+
+There is a new command line application under development called
+\gls{bib2gls}, which works in much the same way as \appfmt{bibtex}.
+Instead of storing all your entry definitions in a \texttt{.tex} and
+loading them using \cs{input} or \cs{loadglsentries}, the entries
+can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can
+selectively write the appropriate commands to a \texttt{.glstex}
+file which is loaded using \cs{glsxtrresourcefile} (or
+\cs{GlsXtrLoadResources}).
+
+This means that you can use a reference managing system, such as
+JabRef, to maintain the database and it reduces the \TeX\ overhead
+by only defining the entries that are actually required in the
+document. If you currently have a \texttt{.tex} file that contains
+hundreds of definitions, but you only use a dozen or so in your
+document, then the build time is needlessly slowed by the unrequired
+definitions that occur when the file is input.
+
+Although \gls{bib2gls} isn't ready yet, there have been some new
+commands and options added to \styfmt{glossaries-extra} to help
+assist the integration of \gls{bib2gls} into the document build
+process.
+
+An example of the contents of \texttt{.bib} file that stores
+glossary entries that can be extracted with \gls{bib2gls}:
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal},
+ see={[see also]{duck,goose}}
+}
+
+@entry{duck,
+ name={duck},
+ description = {a waterbird with short legs}
+}
+
+@entry{goose,
+ name="goose",
+ plural="geese",
+ description={a waterbird with a long neck}
+}
+\end{verbatim}
+
+The follow provides some abbreviations:
+\begin{verbatim}
+@string{ssi={server-side includes}}
+@string{html={hypertext markup language}}
+
+@abbreviation{shtml,
+ short="shtml",
+ long= ssi # " enabled " # html,
+ description={a combination of \gls{html} and \gls{ssi}}
+}
+
+@abbreviation{html,
+ short ="html",
+ long = html,
+ description={a markup language for creating web pages}
+}
+
+@abbreviation{ssi,
+ short="ssi",
+ long = ssi,
+ description={a simple interpreted server-side scripting language}
+}
+\end{verbatim}
+
+Here are some symbols:
+\begin{verbatim}
+preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"}
+
+@symbol{M,
+ name={$\mtx{M}$},
+ text={\mtx{M}},
+ description={a matrix}
+}
+
+@symbol{v,
+ name={$\vec{v}$},
+ text={\vec{v}},
+ description={a vector}
+}
+
+@symbol{S,
+ name={$\mathcal{S}$},
+ text={\mathcal{S}},
+ description={a set}
+}
+\end{verbatim}
+
+To ensure that \gls{bib2gls} can find out which entries have been
+used in the document, you need the \pkgopt{record} package. Option:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+If this option's value is omitted (as above), the normal indexing
+will be switched off, since \gls{bib2gls} can also sort the entries and
+collate the locations.
+
+If you still want to use an indexing application (for example, you
+need a custom \gls{xindy} rule), then just use
+\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries}
+and \cs{printglossary} (or \cs{printglossaries}), but instruct
+\gls{bib2gls} to omit sorting to save time.
+
+The \texttt{.glstex} file created by \cs{bib2gls} is loaded using:
+\begin{definition}[\DescribeMacro\glsxtrresourcefile]
+\cs{glsxtrresourcefile}\oarg{options}\marg{filename}
+\end{definition}
+(Don't include the file extension in \meta{filename}.)
+There's a shortcut version that sets \meta{filename} \cs{jobname}:
+\begin{definition}[\DescribeMacro\GlsXtrLoadResources]
+\cs{GlsXtrLoadResources}\oarg{options}
+\end{definition}
+On the first use, this command is a shortcut for
+\begin{alltt}
+\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}\}
+\end{alltt}
+On subsequent use,\footnote{Version 1.11 only allowed one use
+of \cs{GlsXtrLoadResources} per document.}\ this command is a shortcut for
+\begin{alltt}
+\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}-\meta{n}\}
+\end{alltt}
+where \meta{n} is the current value of
+\begin{definition}
+\cs{glsxtrresourcecount}
+\end{definition}
+which is incremented at the end of \cs{GlsXtrLoadResources}.
+Any advisory notes regarding \cs{glsxtrresourcefile} also
+apply to \cs{GlsXtrLoadResources}.
+
+The \cs{glsxtrresourcefile} command writes the line
+\begin{alltt}
+\cs{glsxtr@resource}\marg{options}\marg{filename}
+\end{alltt}
+to the \texttt{.aux} file and will input
+\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed
+\meta{filename}\texttt{.tex} but that's potentially dangerous if,
+for example, \meta{filename} happens to be the same as \cs{jobname}.
+The \texttt{.glstex} extension was enforced by version 1.11.}
+
+The options are ignored by \styfmt{glossaries-extra} but are picked
+up by \gls{bib2gls} and are used to supply various information, such
+as the name of the \texttt{.bib} files and any changes to the
+default behaviour.
+
+Since the \texttt{.glstex} won't exist on the first \LaTeX\ run, the
+\pkgopt{record} package option additionally switches on
+\pkgopt[warn]{undefaction}. Any use of commands like \cs{gls} or
+\cs{glstext} will produce ?? in the document, since they are
+undefined at this point. Once \gls{bib2gls} has created the
+\texttt{.glstex} file the references should be resolved.
+
+Note that as from v1.12, \cs{glsxtrresourcefile} temporarily
+switches the category code of \texttt{@} to 11 (letter) while it
+reads the file to allow for any internal commands stored in the
+location field.
+
+Since the \texttt{.glstex} file only defines those references used
+within the document and the definitions have been written in the
+order corresponding to \gls{bib2gls} sorted list, the glossaries can
+simply be displayed using \cs{printunsrtglossary} (or
+\cs{printunsrtglossaries}), described in \sectionref{sec:printunsrt}.
+
+Suppose the \texttt{.bib} examples shown above have been stored in
+the files \texttt{terms.bib}, \texttt{abbrvs.bib} and
+\texttt{symbols.bib} which may either be in the current directory or
+on \TeX's path. Then the document might look like:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources[src={terms,abbrvs,symbols}]
+
+\begin{document}
+\gls{bird}
+
+\gls{shtml}
+
+\gls{M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+The document build process (assuming the document is called
+\texttt{mydoc}) is:
+\begin{verbatim}
+pdflatex mydoc
+bib2gls mydoc
+pdflatex mydoc
+\end{verbatim}
+This creates a single glossary containing the entries:
+\texttt{bird}, \texttt{duck}, \texttt{goose},
+\texttt{html}, \texttt{M}, \texttt{shtml} and \texttt{ssi} (in that
+order). The \texttt{bird}, \texttt{shtml} and \texttt{M} entries
+were added because \gls{bib2gls} detected (from the \texttt{.aux}
+file) that they had been used in the document. The other entries
+were added because \gls{bib2gls} detected (from the \texttt{.bib}
+files) that they are referenced by the used entries. In the case of
+\texttt{duck} and \texttt{goose}, they are in the \gloskey{see}
+field for \texttt{bird}. In the case of \texttt{ssi} and
+\texttt{html}, they are referenced in the \gloskey{description}
+field of \texttt{shtml}. These cross-referenced entries won't have a
+location list when the glossary is first displayed, but depending on
+how they are referenced, they may pick up a location list on the
+next document build.
+
+The entries can be separated into different glossaries with
+different sort methods:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record,abbreviations,symbols]{glossaries-extra}
+
+\setabbreviationstyle{long-short-desc}
+
+\GlsXtrLoadResources[src={terms},sort={en-GB},type=main]
+
+\glsxtrresourcefile
+ [src={abbrvs},sort={letter-nocase},type=abbreviations]
+ {\jobname-abr}
+
+\glsxtrresourcefile
+ [src={symbols},sort={use},type={symbols}]
+ {\jobname-sym}
+
+\begin{document}
+\gls{bird}
+
+\gls{shtml}
+
+\gls{M}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+(By default, entries are sorted according to the operating system's
+locale. If this doesn't match the document language, you need to
+set this in the option list, for example \verb|sort=de-CH-1996|
+for Swiss German using the new orthography.)
+
+Note that \cs{glsaddall} doesn't work in this case as it has to
+iterate over the glossary lists, which will be empty on the first
+run and on subsequent runs will only contain those entries that have
+been selected by \gls{bib2gls}. Instead, if you want to add all
+entries to the glossary, you need to tell \gls{bib2gls} this in the
+options list:
+\begin{verbatim}
+\GlsXtrLoadResources[src={terms},selection={all}]
+\end{verbatim}
+
+The \gls{bib2gls} user manual will contain more detail.
+
\chapter{Miscellaneous New Commands}
\label{sec:miscnew}
@@ -4758,39 +5196,571 @@ package provides a supplementary command
that works in the same way except that it uses \ics{pageref}
instead of \ics{ref}.
-As mentioned in the description for the \pkgopt{record} package
-option described in \sectionref{sec:pkgopts}, there's a new way of
-printing a glossary without sorting or indexing:
-\begin{definition}
-\ics{printunsrtglossary}\oarg{options}
+You can copy an entry to another glossary using
+\begin{definition}[\DescribeMacro\glsxtrcopytoglossary]
+\cs{glsxtrcopytoglossary}\marg{entry-label}\marg{glossary-type}
+\end{definition}
+This appends \meta{entry-label} to the end of the internal
+list for the glossary given by \meta{glossary-type}.
+Be careful if you use the \sty{hyperref} package as this
+may cause duplicate hypertargets. You will need to change
+\cs{glolinkprefix} to another value or disable hyperlinks
+when you display the duplicate. Alternatively, use the new
+\gloskey[printglossary]{target} key to switch off the targets:
+\begin{verbatim}
+\printunsrtglossary[target=false]
+\end{verbatim}
+
+The \styfmt{glossaries} package allows you to set preamble code
+for a given glossary type using \cs{setglossarypreamble}. This
+overrides any previous setting. With \styfmt{glossaries-extra}
+(as from v1.12) you can instead append to the preamble
+using
+\begin{definition}[\DescribeMacro\apptoglossarypreamble]
+\cs{apptoglossarypreamble}\oarg{type}\marg{code}
\end{definition}
-To iterate over all glossaries:
-\begin{definition}
-\ics{printunsrtglossaries}
+or prepend using
+\begin{definition}[\DescribeMacro\pretoglossarypreamble]
+\cs{pretoglossarypreamble}\oarg{type}\marg{code}
\end{definition}
-However, you can also uses these commands together with a
-post-processor that works with the \pkgopt{record} package option and
-\begin{definition}
-\ics{glsxtrresourcefile}\oarg{options}{filename}
+\section{Entry Fields}
+\label{sec:fields}
+
+A field may now be used to store the name of a text-block command
+that takes a single argument. The field is given by
+\begin{definition}[\DescribeMacro\GlsXtrFmtField]
+\cs{GlsXtrFmtField}
+\end{definition}
+The default value is \texttt{\GlsXtrFmtField}. Note that the
+value must be the control sequence name \emph{without the initial
+backslash}.
+
+For example:
+\begin{verbatim}
+\newcommand*{\mtx}[1]{\boldsymbol{#1}}
+\newcommand*{\mtxinv}[1]{\mtx{#1}\sp{-1}}
+
+\newglossaryentry{matrix}{%
+ name={matrix},
+ symbol={\ensuremath{\mtx{M}}},
+ plural={matrices},
+ user1={mtx},
+ description={rectangular array of values}
+}
+
+\newglossaryentry{identitymatrix}{%
+ name={identity matrix},
+ symbol={\ensuremath{\mtx{I}}},
+ plural={identity matrices},
+ description={a diagonal matrix with all diagonal elements equal to
+1 and all other elements equal to 0}
+}
+
+\newglossaryentry{matrixinv}{%
+ name={matrix inverse},
+ symbol={\ensuremath{\mtxinv{M}}},
+ user1={mtxinv},
+ description={a square \gls{matrix} such that
+ $\mtx{M}\mtxinv{M}=\glssymbol{identitymatrix}$}
+}
+\end{verbatim}
+
+There are two commands provided that allow you to apply the
+command to an argument:
+\begin{definition}[\DescribeMacro\glsxtrfmt]
+\cs{glsxtrfmt}\oarg{options}\marg{label}\marg{text}
+\end{definition}
+This effectively does
+\begin{alltt}
+\cs{glslink}\oarg{options}\marg{label}\marg{\meta{cs}\marg{text}}
+\end{alltt}
+where \meta{cs} is the command obtained from the control
+sequence name supplied in the provided field. If the field
+hasn't been set, \cs{glsxtrfmt} will simply do \meta{text}.
+The default \meta{options} are given by
+\begin{definition}[\DescribeMacro\GlsXtrFmtDefaultOptions]
+\cs{GlsXtrFmtDefaultOptions}
+\end{definition}
+This is defined as \texttt{\GlsXtrFmtDefaultOptions} but may
+be redefined as appropriate. Note that the replacement text of
+\cs{GlsXtrFmtDefaultOptions} is prepended to the optional
+argument of \cs{glslink}.
+
+For example:
+\begin{verbatim}
+\[
+ \glsxtrfmt{matrix}{A}
+ \glsxtrfmt{matrixinv}{A}
+ =
+ \glssymbol{identitymatrix}
+\]
+\end{verbatim}
+If the default options are set to \texttt{noindex} then
+\cs{glsxtrfmt} won't index, but will create a hyperlink (if
+\sty{hyperref} has been loaded). This can be changed so that
+it also suppresses the hyperlink:
+\begin{verbatim}
+\renewcommand{\GlsXtrFmtDefaultOptions}{hyper=false,noindex}
+\end{verbatim}
+
+Note that \cs{glsxtrfmt} won't work with PDF bookmarks. Instead
+you can use
+\begin{definition}[\DescribeMacro\glsxtrentryfmt]
+\cs{glsxtrentryfmt}\marg{label}\marg{text}
+\end{definition}
+This uses \cs{texorpdfstring} and will simply expand to \meta{text}
+within the PDF bookmarks, but in the document it will do
+\meta{cs}\marg{text} if a control sequence name has been provided
+or just \meta{text} otherwise.
+
+The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to
+add new keys. This command will cause an error if the key has
+already been defined. The \styfmt{glossaries-extra} package provides
+a supplementary command that will only define the key if it doesn't
+already exist:
+\begin{definition}[\DescribeMacro\glsxtrprovidestoragekey]
+\cs{glsxtrprovidestoragekey}\marg{key}\marg{default}\marg{cs}
+\end{definition}
+If the key has already been defined, it will still provide the command given in
+the third argument \meta{cs} (if it hasn't already been defined). Unlike
+\cs{glsaddstoragekey}, \meta{cs} may be left empty if you're happy
+to just use \cs{glsfieldfetch} to fetch the value of this new key.
+
+You can test if a key has been provided with:
+\begin{definition}[\DescribeMacro\glsxtrifkeydefined]
+\cs{glsxtrifkeydefined}\marg{key}\marg{true}\marg{false}
+\end{definition}
+This tests if \meta{key} is available for use in the
+\meta{key}=\value{value} list in the second argument of
+\cs{newglossaryentry} (or the optional argument of
+commands like \cs{newabbreviation}). The corresponding
+field may not have been set for any of the entries if no
+default was provided.
+
+There are now commands provided to set individual fields. Note that
+these only change the specified field, not any related fields. For
+example, changing the value of the \gloskey{text} field won't update
+the \gloskey{plural} field.
+
+\begin{definition}[\DescribeMacro\GlsXtrSetField]
+\cs{GlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+Sets the field given by \meta{field} to \meta{value} for the entry
+given by \meta{label}. No expansion is performed. It's not
+necessary for the field to have been defined as a key. You
+can access the value later with \cs{glsxtrusefield}. Note that
+\cs{glsxtrifkeydefined} only tests if a key has been defined for use
+with commands like \cs{newglossaryentry}. If a field without a
+corresponding key is assigned a value, the key remains undefined.
+This command is robust.
+
+\cs{GlsXtrSetField} uses
+\begin{definition}[\DescribeMacro\glsxtrsetfieldifexists]
+\cs{glsxtrsetfieldifexists}\marg{label}\marg{field}\marg{code}
+\end{definition}
+where \meta{label} is the entry label and \meta{code} is the
+assignment code.
+
+This command just uses \ics{glsdoifexists}\marg{label}\marg{code}
+(ignoring the \meta{field} argument), so by default it causes an
+error if the entry doesn't exist. This can be changed to a warning
+with \pkgopt[warn]{undefaction}. You can redefine
+\cs{glsxtrsetfieldifexists} to simply do \meta{code} if you want to
+skip the existence check. Alternatively you can instead use
+\begin{definition}[\DescribeMacro\glsxtrdeffield]
+\cs{glsxtrdeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text}
+\end{definition}
+This simply uses \sty{etoolbox}'s \cs{csdef} without any checks.
+This command isn't robust. There is also a version that uses
+\cs{csedef} instead:
+\begin{definition}[\DescribeMacro\glsxtredeffield]
+\cs{glsxtredeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text}
+\end{definition}
+
+\begin{definition}[\DescribeMacro\gGlsXtrSetField]
+\cs{gGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{GlsXtrSetField} but globally.
+
+\begin{definition}[\DescribeMacro\eGlsXtrSetField]
+\cs{eGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{GlsXtrSetField} but uses protected expansion.
+
+\begin{definition}[\DescribeMacro\xGlsXtrSetField]
+\cs{xGlsXtrSetField}\marg{label}\marg{field}\marg{value}
+\end{definition}
+As \cs{gGlsXtrSetField} but uses protected expansion.
+
+\begin{definition}[\DescribeMacro\GlsXtrLetField]
+\cs{GlsXtrLetField}\marg{label}\marg{field}\marg{cs}
+\end{definition}
+Sets the field given by \meta{field} to the replacement text of \meta{cs}
+for the entry given by \meta{label} (using \cs{let}).
+
+\begin{definition}[\DescribeMacro\csGlsXtrLetField]
+\cs{csGlsXtrLetField}\marg{label}\marg{field}\marg{cs name}
+\end{definition}
+As \cs{GlsXtrLetField} but the control sequence name is supplied
+instead.
+
+\begin{definition}[\DescribeMacro\GlsXtrLetFieldToField]
+\cs{GlsXtrLetFieldToField}\marg{label-1}\marg{field-1}\marg{label-2}\marg{field-2}
+\end{definition}
+Sets the field given by \meta{field-1} for the entry given by
+\meta{label-1} to the field given by \meta{field-2} for the entry
+given by \meta{label-2}. There's no check for the existence of
+\meta{label-2}, but
+\cs{glsxtrsetfieldifexists}\marg{label-1}\marg{field-1}\marg{code}
+is still used, as for \cs{GlsXtrSetField}.
+
+The \styfmt{glossaries} package provides \ics{glsfieldfetch} which
+can be used to fetch the value of the given field and store it in a
+control sequence. The \styfmt{glossaries-extra} package provides
+another way of accessing the field value:
+\begin{definition}[\DescribeMacro\glsxtrusefield]
+\cs{glsxtrusefield}\marg{entry-label}\marg{field-label}
+\end{definition}
+This works in the same way as commands like \cs{glsentrytext} but
+the field label is specified in the first argument. Note that the
+\meta{field-label} corresponds to the internal field tag, which
+isn't always the same as the key name. See Table~4.1 of the
+\sty{glossaries} manual. No error occurs if the entry or field
+haven't been defined. This command is not robust.
+
+There is also a version that converts the first letter to uppercase
+(analogous to \cs{Glsentrytext}):
+\begin{definition}[\DescribeMacro\Glsxtrusefield]
+\cs{Glsxtrusefield}\marg{entry-label}\marg{field-label}
+\end{definition}
+
+If you want to use a field to store a list that can be used
+as an \sty{etoolbox} internal list, you can use the following
+command that adds an item to the field using \sty{etoolbox}'s
+\cs{listcsadd}:
+\begin{definition}[\DescribeMacro\glsxtrfieldlistadd]
+\cs{glsxtrfieldlistadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+where \meta{label} is the entry's label, \meta{field} is
+the entry's field and \meta{item} is the item to add. There
+are analogous commands that use \cs{listgadd}, \cs{listeadd}
+and \cs{listxadd}:
+\begin{definition}[\DescribeMacro\glsxtrfieldlistgadd]
+\cs{glsxtrfieldlistgadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrfieldlisteadd]
+\cs{glsxtrfieldlisteadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+\begin{definition}[\DescribeMacro\glsxtrfieldlistxadd]
+\cs{glsxtrfieldlistxadd}\marg{label}\marg{field}\marg{item}
+\end{definition}
+You can then iterate over the list using:
+\begin{definition}[\DescribeMacro\glsxtrfielddolistloop]
+\cs{glsxtrfielddolistloop}\marg{label}\marg{field}
\end{definition}
or
-\begin{definition}
-\ics{GlsXtrLoadResources}\oarg{options}
-\end{definition}
-At the time of writing this,
-there is a new post-processor under development called
-\href{https://github.com/nlct/bib2gls}{bib2gls} that can be used in
-this way to fetch glossary entries stored in a \texttt{.bib} file,
-selecting only those referenced in the document. It then creates a
-\texttt{.glstex} file with the relevant definitions defined in the
-order indicated in by \meta{options}. Since the order of definition
-is already in the appropriate order, there's no need for any
-additional sorting by \gls{makeindex} or \gls{xindy}. (It is however
-possible to use \gls{makeindex}\slash\gls{xindy} in combination
-with the post-processor by setting \pkgopt[alsoindex]{record} and using
-\cs{makeglossaries} and \cs{printglossaries} as usual. For example,
-if you require custom \gls{xindy} rules.)
+\begin{definition}[\DescribeMacro\glsxtrfieldforlistloop]
+\cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler}
+\end{definition}
+that internally use \cs{dolistcsloop} and \cs{forlistloop},
+respectively.
+
+There are also commands that use \cs{ifinlistcs}:
+\begin{definition}[\DescribeMacro\glsxtrfieldifinlist]
+\cs{glsxtrfieldifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false}
+\end{definition}
+and \cs{xifinlistcs}
+\begin{definition}[\DescribeMacro\glsxtrfieldxifinlist]
+\cs{glsxtrfieldxifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false}
+\end{definition}
+
+See the \sty{etoolbox}'s user manual for further
+details of these commands, in particular the limitations
+of \cs{ifinlist}.
+
+When using the \pkgopt{record} option, in addition to recording the
+usual location, you can also record the current value
+of another counter at the same time using the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrRecordCounter]
+\cs{GlsXtrRecordCounter}\marg{counter name}
+\end{definition}
+For example:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\GlsXtrRecordCounter{section}
+\end{verbatim}
+Each time an entry is referenced with commands like \cs{gls}
+or \cs{glstext}, the \texttt{.aux} file will not only contain
+the \cs{glsxtr@record} command but also
+\begin{alltt}
+\cs{glsxtr@counterrecord}\marg{label}\{section\}\marg{n}
+\end{alltt}
+where \meta{n} is the current expansion of \cs{thesection}
+and \meta{label} is the entry's label. On the next run, when the
+\texttt{.aux} file is run, this command will do
+\begin{alltt}
+\cs{glsxtrfieldlistgadd}\marg{label}\{record.\meta{counter}\}\marg{n}
+\end{alltt}
+In the above example, if \verb|\gls{bird}| is used in section~1.2
+this would be
+\begin{verbatim}
+\glsxtrfieldlistgadd{bird}{record.section}{1.2}
+\end{verbatim}
+Note that there's no key corresponding to this new
+\texttt{record.section} field, but its value can be
+accessed with \cs{glsxtrfielduse} or the list can be
+iterated over with \cs{glsxtrfielddolistloop} etc.
+
+\section{Display All Entries Without Sorting or Indexing}
+\label{sec:printunsrt}
+
+\begin{definition}[\DescribeMacro\printunsrtglossary]
+\cs{printunsrtglossary}\oarg{options}
+\end{definition}
+This behaves like \cs{printnoidxglossary} but never sorts the
+entries and always lists all the defined entries for the given
+glossary (and doesn't require \cs{makenoidxglossaries}).
+
+There's also a starred form
+\begin{definition}[\DescribeMacro\printunsrtglossary*]
+\cs{printunsrtglossary}*\oarg{options}\marg{code}
+\end{definition}
+which is equivalent to
+\begin{alltt}
+\cs{begingroup}
+ \meta{code}\cs{printunsrtglossary}\oarg{options}\%
+\cs{endgroup}
+\end{alltt}
+Note that unlike \cs{glossarypreamble}, the supplied \meta{code} is
+done before the glossary header.
+
+This means you now have the option to simply list all entries on the
+first \LaTeX\ run without the need for a post-processor, however
+there will be no \gls{numberlist} in this case, as that has to be
+set by a post-processor such as \gls{bib2gls} (see
+\sectionref{sec:bib2gls}).
+
+For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{glossaries-extra}
+
+\newglossaryentry{zebra}{name={zebra},description={stripy animal}}
+\newglossaryentry{ant}{name={ant},description={an insect}}
+
+\begin{document}
+\gls{ant} and \gls{zebra}
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+In the above, zebra will be listed before ant as it was defined
+first.
+
+If you allow document definitions with the \pkgopt{docdefs} option,
+the document will require a second \LaTeX\ run if the entries are
+defined after \cs{printunsrtglossary}.
+
+The optional argument is as for \cs{printnoidxglossary} (except for
+the \gloskey[printnoidxglossary]{sort} key, which isn't available).
+
+All glossaries may be displayed in the order of their definition
+using:
+\begin{definition}[\DescribeMacro\printunsrtglossaries]
+\cs{printunsrtglossaries}
+\end{definition}
+which is analogous to \cs{printnoidxglossaries}. This just
+iterates over all defined glossaries (that aren't on the ignored
+list) and does \cs{printunsrtglossary}[type=\meta{type}].
+
+The \cs{printunsrtglossary} command internally uses
+\begin{definition}[\DescribeMacro\printunsrtglossaryhandler]
+\cs{printunsrtglossaryhandler}\marg{label}
+\end{definition}
+for each item in the list, where \meta{label} is the current label.
+
+By default this just does
+\begin{definition}[\DescribeMacro\glsxtrunsrtdo]
+\cs{glsxtrunsrtdo}\marg{label}
+\end{definition}
+which determines whether to use \cs{glossentry} or
+\cs{subglossentry} and checks the \gloskey{location} and
+\gloskey{loclist} fields for the \gls{numberlist}.
+
+You can redefine the handler if required.
+
+\begin{important}
+If you redefine the handler to exclude entries, you may end
+up with an empty glossary. This could cause a problem for
+the list-based styles.
+\end{important}
+
+For example, if the preamble includes:
+\begin{verbatim}
+\usepackage[record,style=index]{glossaries-extra}
+\GlsXtrRecordCounter{section}
+\end{verbatim}
+then you can print the glossary but first redefine the handler
+to only select entries that include the current section number
+in the \texttt{record.section} field:
+\begin{verbatim}
+\renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+}
+\end{verbatim}
+
+Alternatively you can use the starred form of
+\cs{printunsrtglossary} which will localise the change:
+
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+}
+\end{verbatim}
+
+If you are using the \sty{hyperref} package and want to
+display the same glossary more than once, you can also
+add a temporary redefinition of \cs{glolinkprefix} to
+avoid duplicate hypertarget names. For example:
+
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+ \ifcsundef{theHsection}%
+ {%
+ \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}%
+ }%
+ {%
+ \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}%
+ }%
+}
+\end{verbatim}
+If it's a short summary at the start of a section, you might
+also want to suppress the glossary header and add some vertical
+space afterwards:
+\begin{verbatim}
+\printunsrtglossary*{%
+ \renewcommand{\printunsrtglossaryhandler}[1]{%
+ \glsxtrfieldxifinlist{#1}{record.section}{\thesection}
+ {\glsxtrunsrtdo{#1}}%
+ {}%
+ }%
+ \ifcsundef{theHsection}%
+ {%
+ \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}%
+ }%
+ {%
+ \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}%
+ }%
+ \renewcommand*{\glossarysection}[2][]{}%
+ \appto\glossarypostamble{\glspar\medskip\glspar}%
+}
+\end{verbatim}
+
+There's a shortcut command that does this:
+\begin{definition}[\DescribeMacro\printunsrtglossaryunit]
+\cs{printunsrtglossaryunit}\oarg{options}\marg{counter name}
+\end{definition}
+The above example can simply be replaced with:
+\begin{verbatim}
+\printunsrtglossaryunit{section}
+\end{verbatim}
+
+This shortcut command is actually defined to use \cs{printunsrtglossary*} with
+\begin{definition}[\DescribeMacro\printunsrtglossaryunitsetup]
+\cs{printunsrtglossaryunitsetup}\marg{counter name}
+\end{definition}
+so if you want to just make some minor modifications you can
+do
+\begin{verbatim}
+\printunsrtglossary*{\printunsrtglossaryunitsetup{section}%
+ \renewcommand*{\glossarysection}[2][]{\subsection*{Summary}}%
+}
+\end{verbatim}
+which will start the list with a subsection header with the
+title \qt{Summary} (overriding the glossary's title).
+
+Note that this shortcut command is only available with the
+\pkgopt{record} (or \pkgopt[alsoindex]{record}) package option.
+
+This temporary change in the hypertarget prefix means you
+need to explicitly use \cs{hyperlink} to create a link to it
+as commands like \cs{gls} will try to link to the target
+created with the default definition of \cs{gloslinkprefix}.
+This isn't a problem if you want a primary glossary of all terms
+produced using just \cs{printunsrtglossary} (in the front or back
+matter) which can be the target for all glossary references
+and then just use \cs{printunsrtglossaryunit} for a quick
+summary at the start of a section etc.
+
+\section{Entry Aliases}
+\label{sec:alias}
+
+An entry can be made an alias of another entry using the
+\gloskey{alias} key. The value should be the label of the other
+term. There's no check for the other's existence when the aliased
+entry is defined. This is to allow the possibility of defining the
+other entry after the aliased entry. (For example, when used with
+\gls{bib2gls}.)
+
+If an entry \meta{entry-1} is made an alias of \meta{entry-2} then:
+\begin{itemize}
+\item If the \gloskey{see} field wasn't provided when \meta{entry-1}
+was defined, the \gloskey{alias} key will automatically trigger
+\begin{alltt}
+\cs{glssee}\marg{entry-1}\marg{entry-2}
+\end{alltt}
+\item If the \sty{hyperref} package has been loaded then
+\cs{gls}\marg{entry-1} will link to \meta{entry-2}'s target. (Unless
+the \catattr{targeturl} attribute has been set for \meta{entry-1}'s
+category.)
+\item The \gloskey[glslink]{noindex} setting will automatically be triggered
+when referencing \meta{entry-1} with commands like \cs{gls} or
+\cs{glstext}. This prevents \meta{entry-1} from have a
+\gls{locationlist} (aside from the cross-reference added with
+\cs{glssee}) unless it's been explicitly indexed with \cs{glsadd} or
+if the indexing has been explicitly set using
+\texttt{noindex=false}.
+\end{itemize}
+
+The index suppression trigger is performed by
+\begin{definition}[\DescribeMacro\glsxtrsetaliasnoindex]
+\cs{glsxtrsetaliasnoindex}
+\end{definition}
+This is performed after the default options provided by
+\ics{GlsXtrSetDefaultGlsOpts} have been set.
+
+Within the definition of \cs{glsxtrsetaliasnoindex} you can use
+\begin{definition}[\DescribeMacro\glsxtrindexaliased]
+\cs{glsxtrindexaliased}
+\end{definition}
+to index \meta{entry-2}.
+
+The index suppression command can be redefined to index the main
+term instead. For example:
+\begin{verbatim}
+\renewcommand{\glsxtrsetaliasnoindex}{%
+ \glsxtrindexaliased
+ \setkeys{glslink}{noindex}%
+}
+\end{verbatim}
+
+The value of the \gloskey{alias} field can be accessed using
+\begin{definition}[\DescribeMacro\glsxtralias]
+\cs{glsxtralias}\marg{label}
+\end{definition}
\chapter{Supplemental Packages}
\label{sec:supplemental}
@@ -5105,6 +6075,12 @@ and \cs{printnoidxglossary}.
to allow for entries that should link to an external URL
rather than to an internal glossary.
+\item[sample-fmt.tex] Provides text-block commands associated
+with entries in order to use \cs{glsxtrfmt}.
+
+\item[sample-alias.tex] Uses the \gloskey{alias} key.
+(See \sectionref{sec:alias}.)
+
\item[sample-alttree.tex] Uses the \sty{glossaries-extra-stylemods}
package with the \glostyle{alttree} style (see \sectionref{sec:stylemods}).