summaryrefslogtreecommitdiff
path: root/support/bib2gls/src
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src')
-rw-r--r--support/bib2gls/src/bib2gls.bib134
-rw-r--r--support/bib2gls/src/bib2gls.pod59
-rw-r--r--support/bib2gls/src/bib2gls.tex732
3 files changed, 860 insertions, 65 deletions
diff --git a/support/bib2gls/src/bib2gls.bib b/support/bib2gls/src/bib2gls.bib
index 915cc0d110..cd69e4802c 100644
--- a/support/bib2gls/src/bib2gls.bib
+++ b/support/bib2gls/src/bib2gls.bib
@@ -2658,6 +2658,13 @@ field\dhyphen locale}},
parent={resourceoptions}
}
+@resourceoption{opt.custom-sort-fallbacks,
+ name={\csoptfmt{custom\dhyphen sort\dhyphen fallbacks}},
+ user1={\margm{\keyvallist}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
@resourceoption{opt.entry-sort-fallback,
name={\csoptfmt{entry\dhyphen sort\dhyphen fallback}},
user1={\meta{field}},
@@ -2693,6 +2700,13 @@ field\dhyphen locale}},
parent={resourceoptions}
}
+@resourceoption{opt.field-concat-sep,
+ name={\csoptfmt{field\dhyphen concat\dhyphen sep}},
+ user1={\meta{value}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
@resourceoption{opt.trim-sort,
name={\csoptfmt{trim\dhyphen sort}},
user1={\meta{boolean}},
@@ -5105,6 +5119,11 @@ pages (not available in multi-column or certain other contexts)},
category={environment}
}
+@glsenvironment{env.printunsrtglossarywrap,
+ name={\envfmt{print\-unsrt\-glossary\-wrap}},
+ category={environment}
+}
+
@topic{abbreviationstyles,
name={abbreviation styles},
text={abbreviation style},
@@ -7589,8 +7608,8 @@ long form on \idx{firstuse}. The default definition just uses
package={glossaries},
category={packageoption},
parent={packageoptions},
- description={automatically sets \styopt[true]{entrycounter} and
- indicates the master counter for \counter{glossaryentry}}
+ description={automatically sets the option \styopt[true]{entrycounter}
+ and indicates the master counter for \counter{glossaryentry}}
}
@packageoption{styopt.subentrycounter,
@@ -9351,6 +9370,20 @@ primary formats, if enabled.},
parent={commandlineoptions}
}
+@switch{switch.provide-glossaries,
+ name={\longargfmt{provide\dhyphen glossaries}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+@switch{switch.no-provide-glossaries,
+ name={\longargfmt{no\dhyphen provide\dhyphen glossaries}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
@switch{switch.gls2bib.help,
name={\longargfmt{help}},
symbol={\shortargfmt{h}},
@@ -9922,6 +9955,14 @@ primary formats, if enabled.},
name={\filefmt{constants.bib}}
}
+@samplefile{file.sample-hierarchical.tex,
+ name={\filefmt{sample\dhyphen hierarchical.tex}}
+}
+
+@samplefile{file.sample-nested.tex,
+ name={\filefmt{sample\dhyphen nested.tex}}
+}
+
@samplefile{file.sample-constants.tex,
name={\filefmt{sample\dhyphen constants.tex}}
}
@@ -13157,6 +13198,20 @@ usual delay},
category={command}
}
+@glscommand{printunsrtinnerglossary,
+ name={\csfmt{print\-unsrt\-inner\-glos\-sary}},
+ user1={\oargm{options}\margm{pre code}\margm{post code}},
+ description={similar to \cs{printunsrtglossary} but only contains
+ the code that would typically be placed inside the \env{theglossary}
+ environment. This command should either be placed inside the
+ \env{printunsrtglossarywrap} environment or inside the handler macro
+ used by \cs{printunsrtglossary}. This command is unsuitable for
+ certain glossary styles, particularly tabular-like styles},
+ topics={glossrefs,loop},
+ note={\styfmt{glossaries-extra} v1.44+},
+ category={command}
+}
+
@glscommand{printunsrtglossary*,
name={\csfmt{print\-unsrt\-glos\-sary*}},
user1={\oargm{options}\margm{code}},
@@ -13168,6 +13223,29 @@ usual delay},
category={command}
}
+@glscommand{printunsrtglossaryhandler,
+ name={\csfmt{print\-unsrt\-glos\-sary\-handler}},
+ user1={\margm{label}},
+ description={used by \cs{printunsrtglossary} and
+ \cs{printunsrtinnerglossary} to handler each entry within the
+ loop. By default this simply does \cs{glsxtrunsrtdo}},
+ topics={glossrefs,loop},
+ note={\styfmt{glossaries-extra} v1.12+},
+ category={command}
+}
+
+@glscommand{glsxtrunsrtdo,
+ name={\csfmt{gls\-xtr\-unsrt\-do}},
+ user1={\margm{label}},
+ description={displays the entry given by \meta{label} using
+ \cs{glossentry} or \cs{subglossentry} depending on the entry's
+ hierarchical level (taking \printglossopt{leveloffset} into
+ account)},
+ topics={glossrefs,loop},
+ note={\styfmt{glossaries-extra} v1.12+},
+ category={command}
+}
+
@glscommand{printunsrtglossaries,
name={\csfmt{print\-unsrt\-glos\-saries}},
user1={},
@@ -13367,6 +13445,30 @@ hasn't been defined},
category={commandoption},
}
+@printglossoption{printgloss.groups,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{groups}},
+ user1 = {\margm{boolean}},
+ description = {controls whether or not \cs{printunsrtglossary}
+ (or \cs{printunsrtinnerglossary})
+ should insert letter group markup. There's no visible difference
+ for glossary styles that don't support letter groups (and
+ \styopt{nogroupskip} is in effect) or if there's no group
+ information (for example, \longarg{no-group} has been used)},
+ category={commandoption},
+}
+
+@printglossoption{printgloss.leveloffset,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{level\-offset}},
+ user1 = {\margm{n}},
+ description = {makes the glossary style act as though each entry's
+ hierarchical level is \meta{offset} more than it actually is
+ where \meta{offset} is either \meta{n} or is locally incremented
+ by \meta{n} if \meta{n} starts with \code{++}},
+ category={commandoption},
+}
+
@glscommand{glsxtrsetglossarylabel,
name={\csfmt{gls\-xtr\-set\-glos\-sary\-label}},
user1={\margm{label}},
@@ -14982,13 +15084,24 @@ paragraph break that retains the hanging indent},
@glscommand{ifglossaryexists,
name={\csfmt{if\-glossary\-exists}},
user1={\margm{type}\margm{true}\margm{false}},
- description={tests if the glossary given by \meta{type} exists
- and does \meta{true} if it does exists, otherwise does \meta{false}},
+ description={tests if the glossary identified by \meta{type} exists
+ and does \meta{true} if it does exists, otherwise does
+ \meta{false}. The unstarred form treats ignored glossaries as
+ non-existent},
topics={conditional,glossrefs},
note={\styfmt{glossaries}},
category={command}
}
+@glscommand{ifglossaryexists*,
+ name={\csfmt{if\-glossary\-exists*}},
+ user1={\margm{type}\margm{true}\margm{false}},
+ description={the starred form of \cs{ifglossaryexists} treats ignored glossaries as existing},
+ topics={conditional,glossrefs},
+ note={\styfmt{glossaries} v4.46+ (or \styfmt{glossaries-extra} v1.44+)},
+ category={command}
+}
+
@glscommand{ifignoredglossary,
name={\csfmt{if\-ignored\-glossary}},
user1={\margm{type}\margm{true}\margm{false}},
@@ -15502,7 +15615,18 @@ number is hexadecimal)},
user1={\margm{character}},
description={puts a breve accent over \meta{character}},
note={kernel command\texparserdefnote},
- category={command}
+ category={command},
+ annote={accent}
+}
+
+@command{uhex,
+ name={\csfmt{u}},
+ user1={\meta{hex}},
+ description={identifies a character by its hexadecimal code in the
+ values of some (but not all) resource options},
+ note={\bibgls},
+ category={command},
+ annote={hex code}
}
@command{acute,
diff --git a/support/bib2gls/src/bib2gls.pod b/support/bib2gls/src/bib2gls.pod
index 0740dac928..bf82acc2c2 100644
--- a/support/bib2gls/src/bib2gls.pod
+++ b/support/bib2gls/src/bib2gls.pod
@@ -78,37 +78,37 @@ Don't try interpreting (La)TeX commands.
=item B<--break-space>
-Interpret tilde character and \nobreakspace as a normal space.
+Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space.
=item B<--no-break-space>
-Interpret tilde and \nobreakspace as a non-breaking space (default).
+Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default).
=item B<--cite-as-record>
-Treat B<\citation> as an ignored record.
+Treat C<\citation> as an ignored record.
=item B<--no-cite-as-record>
-Don't check for instances of B<\citation> in the B<.aux> file (default).
+Don't check for instances of C<\citation> in the F<.aux> file (default).
=item B<--warn-non-bib-fields>
-Warn if internal non-bib fields are found in the .bib file.
+Warn if internal non-bib fields are found in the F<.bib> file.
=item B<--no-warn-non-bib-fields>
-Don't warn if internal non-bib fields are found in the .bib file.
+Don't warn if internal non-bib fields are found in the F<.bib> file.
The use of these internal fields can cause unexpected results, so
only use this option if you have taken appropriate precautions.
=item B<--warn-unknown-entry-types>
-Warn if any unknown entry types are found in the .bib file.
+Warn if any unknown entry types are found in the F<.bib> file.
=item B<--no-warn-unknown-entry-types>
-Don't warn if any unknown entry types are found in the .bib file.
+Don't warn if any unknown entry types are found in the F<.bib> file.
=item B<--merge-wrglossary-records>
@@ -121,8 +121,8 @@ Don't merge an entry's B<wrglossary> records.
=item B<--merge-nameref-on> I<rule>
-Rule for merging locations created with the record=nameref package option
-(requires glossaries-extra.sty version 1.37+). The I<rule> may be
+Rule for merging locations created with the B<record=nameref> package option
+(requires F<glossaries-extra.sty> version 1.37+). The I<rule> may be
one of: B<hcounter>, B<href>, B<title> or B<location>.
=item B<--force-cross-resource-refs> or B<-x>
@@ -135,16 +135,16 @@ Don't force cross-resource referencing mode on (default).
=item B<--support-unicode-script>
-Text superscript (\textsuperscript) or subscripts (\textsubscript)
+Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
will use Unicode superscript/subscript characters if available.
-For example, \textsuperscript{2} will be converted to U+00B2
+For example, C<\textsuperscript{2}> will be converted to U+00B2
(superscript two).
=item B<--no-support-unicode-script>
-Text superscript (\textsuperscript) or subscripts (\textsubscript)
+Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
won't be converted to Unicode superscript/subscript characters.
-For example, \textsuperscript{2} will be converted to <sup>2</sup>
+For example, C<\textsuperscript{2}> will be converted to C<E<lt>supE<gt>2E<lt>/supE<gt>>
and the markup will be stripped leaving just the character 2.
=item B<--packages> I<list> (or B<-p> I<list>)
@@ -182,7 +182,7 @@ packages may be used in B<--packages> or B<--ignore-packages>.
=item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>)
Insert an empty group if fields start with certain problematic
-commands to protect against case-changing commands like \Gls.
+commands to protect against case-changing commands like C<\Gls>.
The default is to do this for all fields. To do this for only a
subset of fields, set I<fields> to a comma-separated list of fields
@@ -194,12 +194,12 @@ Switch off the auto-insertion of an empty group for all fields.
=item B<--mfirstuc-math-protection>
-Switch on the auto-insertion of an empty group for math-shift ($).
+Switch on the auto-insertion of an empty group for math-shift (C<$>).
This option will be overridden by B<--no-mfirstuc-protection>.
=item B<--no-mfirstuc-math-protection>
-Switch off the auto-insertion of an empty group for math-shift ($).
+Switch off the auto-insertion of an empty group for math-shift (C<$>).
=item B<--nested-link-check> I<list>|B<none>
@@ -228,11 +228,11 @@ Set location format mappings.
=item B<--group> or B<-g>
-Add 'group' field to entries.
+Add B<group> field to entries.
=item B<--no-group>
-Don't add 'group' field to entries (default).
+Don't add B<group> field to entries (default).
=item B<--record-count> or B<-c>
@@ -278,11 +278,24 @@ This option cancels B<--trim-only-fields> and B<--trim-fields>.
=item B<--expand-fields>
-Don't write B<\glsnoexpandfields> to the B<.glstex> file.
+Don't write C<\glsnoexpandfields> to the F<.glstex> file.
=item B<--no-expand-fields>
-Write B<\glsnoexpandfields> to the B<.glstex> file (default).
+Write C<\glsnoexpandfields> to the F<.glstex> file (default).
+
+=item B<--provide-glossaries>
+
+Write C<\provideignoredglossary*> to the F<.glstex> file to provide
+unknown glossaries.
+
+=item B<--no-provide-glossaries>
+
+Don't write C<\provideignoredglossary*> to the F<.glstex> file to
+provide unknown glossaries except in documented situations
+(B<master>, B<secondary> and B<trigger-type> resource options).
+This setting is the default.
+
=back
@@ -293,7 +306,7 @@ Java 7 or later and a TeX distribution.
=head1 LICENSE
License GPLv3+: GNU GPL version 3 or later
-<http://gnu.org/licenses/gpl.html>
+L<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@@ -314,7 +327,7 @@ The glossaries manual:
=head1 AUTHOR
Nicola L. C. Talbot,
-L<http://www.dickimaw-books.com/>
+L<https://www.dickimaw-books.com/>
=cut
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index f8fa262b5b..7b888ea485 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/support/bib2gls/src/bib2gls.tex
@@ -151,7 +151,7 @@
},
max-loc-diff={2},
see=omit,seealso=omit,alias=omit,
- field-aliases={topics=adoptparents},
+ field-aliases={topics=adoptparents,annote=user2},
replicate-fields={name=nametitle,progeny=unsortedprogeny},
field-case-change={nametitle=title},
interpret-fields={nametitle},
@@ -296,7 +296,7 @@
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
-\newcommand{\stringu}{\idx{cs.string}\idx{u}}
+\newcommand{\stringu}{\idx{cs.string}\idx{uhex}}
\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand*{\metafilefmt}[3]{%
@@ -1080,6 +1080,8 @@
\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}}
+\newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}}
+
\newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}}
\newcommand{\argsection}[2][\section]{%
@@ -1891,22 +1893,29 @@ Although \idxpl{ignoredglossary} can't be used with
\cs{printglossary}, they can be used with \cs{printunsrtglossary},
which is designed to work without any indexing, but you need to
explicitly set the title in the optional argument to override the
-default. The \idxpl{ignoredglossary} still can't be used in
+default. \Idxpl{ignoredglossary} still can't be used in
\cs{printunsrtglossaries}, since they're not included in the list
that this command iterates over.
-So \cs{newignoredglossary} is useful with \bibgls\ if you're happy
-to use \cs{printunsrtglossary} as it reduces the overall number of
-internal control sequences. Since there is now the possibility of
-targets (created within \cs{printunsrtglossary}), it's useful to
+So \cs{newignoredglossary} (or \cs{provideignoredglossary}) is
+useful with \bibgls\ if you're happy to use \cs{printunsrtglossary}
+with the \printglossopt{type} and \printglossopt{title} options as it reduces the overall
+number of internal control sequences. \Idxpl{ignoredglossary} are
+also useful for stand-alone definitions (\ics{glsxtrglossentry}) or
+with \ics{printunsrtinnerglossary} as no title is required in those
+cases (see \exfile{sample-nested.tex} for an example).
+
+Since there is now the possibility of targets (created within \cs{printunsrtglossary} or
+\cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to
have an \idx{ignoredglossary} that doesn't suppress the hyperlinks,
which can be obtained with the starred form \ics{newignoredglossary*}
-provided by \styfmt{glossaries-extra}.
+provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}).
Some resource options, such as \csopt{master}, \csopt{secondary} and
\csopt{trigger-type}, need to ensure that a
required glossary is defined. In this case, \bibgls\ uses
-\ics{provideignoredglossary*} in the \iext{glstex} file. If you
+\ics{provideignoredglossary*} in the \iext{glstex} file
+even if \longarg{no-provide-glossaries} is set. If you
haven't already defined that glossary in the document with \cs{newglossary*},
you'll need to set the title in the optional argument of
\cs{printunsrtglossary} if you don't want the default. The glossary
@@ -1915,6 +1924,27 @@ provided in the \ext{glstex} file) but \cs{printunsrtglossary} will
just give a warning if the type is undefined so it won't interrupt
the document build.
+If you want \bibgls\ to automatically provide unknown glossaries for
+all entries that have the \field{type} field set (unrelated to the
+\csopt{master}, \csopt{secondary} and \csopt{trigger-type} options)
+then use the \longarg{provide-glossaries} switch.
+
+The base \sty{glossaries} package provides a command that can be
+used to test the existence of a glossary:
+\begin{codeenv}
+\ics{ifglossaryexists}\margm{label}\margm{true}\margm{false}
+\end{codeenv}
+The unstarred version considers ignored glossaries as non-existent
+(and so will do \meta{false} for an ignored glossary). As from
+v4.46, this command now has a starred version
+\ics{ifglossaryexists*} that considers ignored glossaries as
+existing (and so will do \meta{true} for an ignored glossary). In
+the event that you have an older version of \sty{glossaries}, the
+\sty{glossaries-extra} package (v1.44+) will provide the starred
+form if it hasn't been defined. (In general, it's best to have
+up-to-date versions of both \sty{glossaries} and
+\sty{glossaries-extra}.)
+
\section{Resource Sets}
\label{sec:resourcesets}
@@ -3785,6 +3815,30 @@ bib2gls --trim-except-fields short --trim-except-fields long myDoc
Don't trim any leading or trailing spaces from field values (but see
the above note about \sty{xkeyval}). This is the default setting.
+\argsection{provide-glossaries}
+
+This setting will make \bibgls\ add the line
+\begin{codeenv}
+\ics{provideignoredglossary*}\margm{type}
+\end{codeenv}
+to the \ext{glstex} file before an entry is defined where that entry
+has the \field{type} field set to an unknown glossary type (\bibgls\
+can detect from the \ext{aux} file all glossaries that have been
+defined with \cs{newglossary} but not those defined with \cs{newignoredglossary}).
+
+This ensures that the glossary exists, but the use of
+\ics{provideignoredglossary} (rather than \cs{newignoredglossary})
+will prevent an error if the glossary has already been defined.
+
+\argsection{no-provide-glossaries}
+
+This setting prevents \bibgls\ from providing unknown glossaries,
+except in a few documented situations (the \csopt{master},
+\csopt{trigger-type} and \csopt{secondary} options). This is the
+default since it's a useful way of detecting misspelt glossary
+labels. It's harder to detect the problem if a misspelt label has
+caused an entry to be added to a hidden glossary.
+
\argsection{record-count}
Switch on record counting. This will ensure that when each entry
@@ -4441,7 +4495,7 @@ For example:
\end{codeenv}
If the \field{sort} field is missing the default is obtained from
-the \field{name} field (unless overridden by
+the \field{name} field (unless overridden by options like
\csopt{entry-sort-fallback}). For hierarchical entries, if the
\field{name} field is omitted it will be obtained from the parent's
\field{name}.
@@ -4465,7 +4519,7 @@ designed specifically for symbols, so in the previous example, the
The required fields are \field{name} or \field{parent}. The
\field{description} field is required if the \field{name} field is
missing. If the \field{sort} field is omitted, the default sort is
-given by the entry label (unless overridden by
+given by the entry label (unless overridden by options like
\csopt{symbol-sort-fallback}). Note that this is different from
\atentry{entry} where the sort defaults to \field{name} if omitted.
@@ -4529,7 +4583,8 @@ entry.) If the name contains any characters that can't be used in
the label, you must use the \field{name} field. If the \field{sort}
field is missing the default is obtained from the \field{name}.
Note that the \atentry{index} entry type is \emph{not} governed by
-\csopt{entry-sort-fallback}. This allows \atentry{index} and
+\csopt{entry-sort-fallback} (but it is governed by
+\csopt{custom-sort-fallbacks}). This allows \atentry{index} and
\atentry{entry} to have different fallbacks if the \field{sort}
field is missing.
@@ -4554,7 +4609,8 @@ field with the plural suffix appended. If the \field{text} field is
missing, it's obtained from the original entry label. If the
\field{sort} field is missing the default is obtained from the
\field{name} field. (As with \atentry{index}, \atentry{indexplural}
-is \emph{not} governed by \csopt{entry-sort-fallback}.)
+is \emph{not} governed by \csopt{entry-sort-fallback}, but it is
+governed by \csopt{custom-sort-fallbacks}.)
All fields are optional. For example:
\begin{codeenv}
\atentry{indexplural}\marg{goose,
@@ -7232,6 +7288,21 @@ setting but parents are added even if they haven't been referenced
in the document. The other dependent entries are omitted if they
haven't been referenced in the document.
+\item \optfmt{deps but not recorded}: this first selects entries as
+though \optfmt{recorded and deps} had been used, but after all
+ancestors and dependencies have been added it then removes all
+entries that have records. This means that you end up with only the
+unrecorded dependencies. (Recorded entries will need to be selected
+in a different resource set.)
+
+\item \optfmt{ancestors but not recorded}: this first selects
+entries as though \optfmt{recorded and ancestors} had been used, but
+after all ancestors have been added it then removes all entries that
+have records. This means that you end up with only the unrecorded
+ancestors. (Recorded entries will need to be selected
+in a different resource set.) See the \exfile{sample-nested.tex}
+example document.
+
\item \optfmt{all}: add all entries found in the \ext{bib} files
supplied in the \csopt{src} option.
\end{itemize}
@@ -8197,7 +8268,8 @@ or \csopt{category} options haven't been used, the corresponding
value will default to \optfmt{master}. The \catattr{targeturl}
and \catattr{targetname} category attributes will automatically be
set, and the glossary type will be provided using
-\code{\ics{provideignoredglossary*}\margm{type}}.
+\code{\ics{provideignoredglossary*}\margm{type}} (even if
+\longarg{no-provide-glossaries} is set).
The above \filefmt{myarticle.tex} can be changed to:
\begin{codeenv}
@@ -9110,6 +9182,7 @@ the keywords allowed by \csopt{type}).
You can define the glossary before loading the resource, but
it's not required as \bibgls\ will write
\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file
+even if \longarg{no-provide-glossaries} is set
(see \sectionref{sec:newglossary}).
\optsection[\subsubsection]{progenitor-type}
@@ -9146,7 +9219,8 @@ missing and it's required for some reason (for example, with
fallback on a different field, then you can use this option to
specify the field. For example,
\csopt[long]{abbreviation-name-fallback}.
-The \meta{field} value must be a known field label.
+The \meta{field} value must be a known field (not an internal field)
+but can't be the \field{sort} field.
\optsection[\subsubsection]{ignore-fields}
@@ -10064,7 +10138,7 @@ contains definitions like:
}
\end{codeenv}
Instead of having a list of terms (glossary), suppose I want to have
-standalone definitions, where the term appears in a section heading.
+stand-alone definitions, where the term appears in a section heading.
I could define a command like this:
\begin{codeenv}
\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
@@ -10232,7 +10306,7 @@ by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
\subsection{Prefix Fields}
-\label{sec:prefixes}
+\label{sec:prefixfields}
If you use the \isty{glossaries-prefix} package, the prefix
set of fields become available (\field{prefix},
@@ -12763,15 +12837,20 @@ list that's the exact reverse of the underlying non-reversed
can affect the order.
\begin{table}[p]
-\caption{Summary of Available Sort Options: No Actual Sorting}
+\caption{Summary of Available Sort Options: No Sort Field}
\label{tab:sortoptionsnosort}
\centering
\begin{tabular}{ll}
\optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline
\optfmt{random} & shuffle entries\tabularnewline
\optfmt{use} & order of use\tabularnewline
-\optfmt{use-reverse} & reverse order of use
+\optfmt{use-reverse} & reverse order of use\tabularnewline
+\optfmt{recordcount}\textsuperscript\textdagger & order of record count\tabularnewline
+\optfmt{recordcount-reverse}\textsuperscript\textdagger & reverse order of record count
\end{tabular}
+\par
+\medskip
+\textsuperscript\textdagger Requires \longarg{record-count} switch.
\end{table}
\begin{table}[p]
@@ -12885,12 +12964,15 @@ sort\tabularnewline
\end{tabular}
\end{table}
-\subsubsection{No Sort}
+\subsubsection{No Sort Field}
-The sort methods listed in \tableref{tab:sortoptionsnosort}
+Most of the sort methods listed in \tableref{tab:sortoptionsnosort}
don't actually perform any sorting. This may cause a problem for
hierarchical entries. In some cases this can lead to detached child
entries or an attempt to define a child entry before its parent.
+The methods listed in this section all ignore the \csopt{sort-field}
+setting and all the various sort fallback settings, except where
+noted below.
\begin{itemize}
\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries.
@@ -12916,8 +12998,103 @@ first use of that term that's used as the sort value.
\item \optfmt{use-reverse}: reverses the order that would be
obtained with \csopt[use]{sort} without reference to hierarchy.
+\item \optfmt{recordcount}: order of record count (starting from 0). This order is
+determined by the total number of records written to the \iext{aux}
+file for each entry. Unlike the above methods, this performs a hierarchical sort.
+If letter groups are enabled with \longarg{group}, this method will assign the entries to
+the \idx{numbergroup}.
+
+This option requires the \longarg{record-count} switch. Although
+that switch makes \bibgls\ write the total record count to the
+\ext{glstex} file in the \field{recordcount} internal field (so that it
+can be accessed in the document), \bibgls\ doesn't actually have a
+field itself that contains the information. So although this option
+behaves much like \csopt[integer]{sort} it's not possible to select
+a field containing the required value. In the event of two or more
+entries having the same record count, the
+\csopt{identical-sort-action} option is used to determine the
+relative ordering between them.
+
+\item \optfmt{recordcount-reverse}: reverse order of record count
+(ending with 0). All the above notes applying to
+\optfmt{recordcount} also apply here.
+
\end{itemize}
+Suppose the file \filefmt{entries.bib} contains
+definitions of a set of symbols that don't have any intuitive
+ordering (for example, they are all pictographs) then there may be
+no point in trying to order them, in which case you can do:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[none]{sort}}
+\end{codeenv}
+Alternatively, you could list them in order of use:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
+\end{codeenv}
+or by frequency of use. For example, starting with entries that
+don't have any records followed by the least used entries (a rarely-used symbol
+may be harder to remember and most likely to be looked up in the glossary):
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount]{sort}}
+\end{codeenv}
+Or starting with the most used entries:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount-reverse]{sort}}
+\end{codeenv}
+It all depends on what's likely to be most useful to the reader.
+
+Consider the following:
+\begin{codeenv}
+\ics{newglossary*}\marg{frequent}\marg{Most Frequently Used Terms}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort},
+ \csopt[recordcount-reverse:frequent]{secondary}
+}
+\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
+ \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
+ \marg{}\comment{}
+ \marg{\ics{printunsrtglossaryskipentry}}\comment{}
+}
+\csfmt{begin}\marg{document}
+\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},\printglossopt[frequent]{type}}\marg{\comment{}
+ \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
+}
+\comment{Main body of the document \ldots}
+\cs{printunsrtglossary}
+\csfmt{end}\marg{document}
+\end{codeenv}
+This has a summary at the start of the document that only contains
+entries that have at least 10 records and is ordered according to
+the total number of records (starting with the most frequently used
+entry). The main glossary at the end of the document is ordered
+according to use and contains all selected entries.
+
+Compare this with the following:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
+\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
+ \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
+ \marg{}\comment{}
+ \marg{\ics{printunsrtglossaryskipentry}}\comment{}
+}
+\csfmt{begin}\marg{document}
+\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},
+ \printglossopt[Most Frequently Used Terms]{title}}\marg{\comment{}
+ \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
+}
+\comment{Main body of the document \ldots}
+\cs{printunsrtglossary}
+\csfmt{end}\marg{document}
+\end{codeenv}
+This again has a summary at the start of the document that only
+contains entries that have at least 10 records but is now ordered
+according to use.
+
+Both examples assume there are no child entries as the filtering can
+cause parent entries to be omitted. Both examples require
+\longarg{record-count} but only the first example sorts according to
+the record count.
+
\subsubsection{Alphabet}
The sort methods listed in \tableref{tab:sortoptionsrule} are for
@@ -12936,7 +13113,7 @@ given by the \idx{IETF} language tag \meta{lang tag}.
\item \optfmt{locale}: equivalent to
\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
-from the \idx{JRE} (which usually matches the
+from the \idx{JRE}['s] default locale (which usually matches the
operating system's locale).
\item \optfmt{locale-reverse}: equivalent to
@@ -13382,7 +13559,7 @@ results in the order:
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
-Remember that the associated settings are reversed
+Remember that the associated settings are reversed as
well. So \csopt[before letter]{letter-number-rule}
results in numbers \emph{after} letters.
@@ -13478,7 +13655,7 @@ decimal sort values.
\item \optfmt{double}: double-precision sort. This is for non-locale
decimal sort values.
-\item \optfmt{float-reverse}: as above but reverses the order.
+\item \optfmt{double-reverse}: as above but reverses the order.
\item \optfmt{numeric}: locale-sensitive numeric sort. Use
\csopt{numeric-locale} to set the locale.
@@ -13638,13 +13815,20 @@ Example:
\begin{codeenv}
\gls{GlsXtrLoadResources}\oarg{
\csopt[entries-terms]{src},\comment{data in entries-terms.bib}
- \csopt[category]{sort-field},\comment{sort by 'category' field}
+ \csopt[symbol]{sort-field},\comment{sort by 'symbol' field}
\csopt[letter-case]{sort}\comment{case-sensitive letter sort}
}
\end{codeenv}
-This sorts the entries according to the \field{category} field using
+This sorts the entries according to the \field{symbol} field using
a case-sensitive letter comparison.
+\begin{important}
+In general it's better to use the default \csopt[sort]{sort-field}
+and adjust the fallbacks instead. The \csopt{sort-field} option is
+provided if you want to use a specific field regardless of the entry
+type.
+\end{important}
+
If an entry is missing a value for \meta{field}, then the value of
the fallback field will be used instead. If \csopt{missing-sort-fallback} is
set, then that's used as the fallback, otherwise it depends on the
@@ -13656,6 +13840,11 @@ setting, the fallback for the \field{sort} field is governed not
only by the entry type but also by some associated settings:
\begin{itemize}
+\item If the entry's original type (before being aliased with
+\csopt{entry-type-aliases}) is identified in
+\csopt{custom-sort-fallbacks}, then if the \field{sort} field is missing
+the value is obtained from the supplied custom mapping.
+
\item If the entry is defined using \atentry{entry} (or a dual form
that acts like \atentry{entry}), then if the \field{sort} field is
missing the value is obtained from the field identified by
@@ -13698,9 +13887,21 @@ follows:
\meta{fallback-field}. If \meta{fallback-field} is
missing, then \bibgls\ will query the entry type's fallback for
\meta{fallback-field} (not for \meta{sort-field}).
+
+The \meta{fallback-field} must be a known field but not an internal
+field. It can't be the \field{sort} field. (Take care not to cause
+an infinite loop if \csopt{sort-field} has been changed.) Unlike the
+other sort fallback options such as \csopt{entry-sort-fallback}, the
+\meta{fallback-field} can't be a keyword (to identify the label) and can't be a
+composite.
+
\item If the entry type has a fallback rule for \meta{sort-field},
then that rule is used. When \csopt[sort]{sort-field} this means:
\begin{itemize}
+\item If the entry's original entry type has been identified in
+\csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the
+designated custom setting.
+
\item If the entry was defined using one of the index types (such as
\atentry{index}), then \bibgls\ will fallback on the \field{name}
field.
@@ -13736,6 +13937,121 @@ separately from primaries, and use
\csopt{secondary-missing-sort-fallback} for \csopt{secondary}
sorting.
+\optsection{custom-sort-fallbacks}
+
+The value should be a \keyvallist\ in the form
+\meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the
+\emph{original} entry type (before being aliased with
+\csopt{entry-type-aliases}). This will override any of the sort fallback
+options listed below for entries whose original entry type matches
+\meta{entrytype}.
+
+The \meta{field} may be a known field but not an internal field. For
+obvious reasons, it can't be the \field{sort} field (since
+\meta{field} is the fallback a missing \field{sort} field). It may also be one of the
+keywords: \optfmt{id} (for the entry's label) or \optfmt{original id}
+(for the entry's original label). The \meta{field} may also be a
+composite in the form \optfmt{\meta{field1}+\meta{field2}+\ldots}
+which indicates that the sort value should be obtained by
+concatenating the values of the given fields, where the separator is
+given by \csopt{field-concat-sep}.
+
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentryfmt{unit}\marg{ohm,
+ \field{name}=\marg{\cs{si}\marg{\csfmt{ohm}}},
+ \field{description}=\marg{electrical resistance}
+}
+\strut
+\atentryfmt{constant}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{the ratio of the length of the circumference
+ of a circle to its diameter},
+ \field{user1}=\marg{3.14159}
+}
+\strut
+\atentry{symbol}\marg{fx,
+ \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
+ \field{description}=\marg{a function of \idx{mshiftchar}x\idx{mshiftchar}}
+}
+\strut
+\atentry{number}\marg{zero,
+ \field{name}=\marg{0},
+ \field{description}=\marg{nothing or no quantity}
+}
+\end{codeenv}
+Then the resource options:
+\begin{codeenv}
+\csopt[\entryfmt{unit}=\entryref{symbol},\entryfmt{constant}=\entryref{number}]{entry-type-aliases},
+\csopt[\entryfmt{unit}=\field{name},\entryfmt{constant}=\field{user1}]{custom-sort-fallbacks}
+\end{codeenv}
+will treat the custom \atentryfmt{unit} and \atentryfmt{constant}
+entries as though they had been defined with \atentry{symbol}
+and \atentry{number}, respectively, but the fallback for the
+\field{sort} field is different: the \code{ohm} entry will use the
+\field{name} field for the sort fallback (because its original entry
+type was \entryfmt{unit}), the \code{pi} entry will use the
+\field{user1} field for the sort fallback (because its original
+entry type was \entryfmt{constant}) and the \code{fx} and
+\code{zero} entries will use the label for the sort fallback (since
+neither \entryfmt{symbol} nor \entryfmt{number} were identified in
+\csopt{custom-sort-fallbacks} so the \csopt{symbol-sort-fallback} is
+used).
+
+If an entry hasn't had its entry type aliased then \meta{entrytype}
+is its actual entry type. For example, consider the following
+definitions:
+\begin{codeenv}
+\atentry{abbreviation}\marg{svm,
+ \field{short}=\marg{SVM},
+ \field{long}=\marg{support vector machine}
+}
+\atentry{acronym}\marg{laser,
+ \field{short}=\marg{laser},
+ \field{long}=\marg{light amplification by stimulated emission of radiation}
+}
+\end{codeenv}
+Then \csopt[short]{abbreviation-sort-fallback} will make both
+entries fallback on the \field{short} field (since
+\csopt{abbreviation-sort-fallback} applies to both \atentry{acronym}
+and \atentry{abbreviation}), but the option:
+\begin{codeenv}
+\csopt[\entryref{abbreviation}=\field{long},\entryref{acronym}=\field{short}]{custom-sort-fallbacks}
+\end{codeenv}
+will make the entry defined with \atentry{abbreviation} fallback on
+the \field{long} field and the entry defined with \atentry{acronym}
+will fallback on the \field{short} field.
+
+Since the default setting is \csopt[short]{abbreviation-sort-fallback}
+this only needs to be:
+\begin{codeenv}
+\csopt[\entryref{abbreviation}=\field{long}]{custom-sort-fallbacks}
+\end{codeenv}
+In this case, the entry defined with \atentry{abbreviation} (\qt{SVM}) will use
+the setting given in \csopt{custom-sort-fallbacks}, but the entry
+defined with \atentry{acronym} (\qt{laser}) will use the setting given by
+\csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't
+been identified in \csopt{custom-sort-fallbacks}.
+
+This option also covers dual entries. For example:
+\begin{codeenv}
+\csopt[
+ \entryref{dualindexnumber}=\field{description},
+ \entryfmt{dualindexnumbersecondary}=\field{user1}
+]{custom-sort-fallbacks}
+\end{codeenv}
+Note that the entry type for the dual is in the form
+\code{\meta{primary entry type}secondary}.
+
+\begin{important}
+The \csopt{custom-sort-fallbacks} setting is only used when \bibgls\
+tries to access the \field{sort} field for an entry (whose original
+entry type has been identified in this setting) and finds that the field
+hasn't been set. This means that this setting has no effect if you
+explicitly set the \field{sort} field or if you change the field
+used for sorting (\csopt{sort-field}).
+\end{important}
+
\optsection{entry-sort-fallback}
The regular entry types (such as \atentry{entry} and
@@ -13744,7 +14060,17 @@ field if the \field{sort} field is missing (assuming
\csopt[sort]{sort-field}). If you prefer to
fallback on a different field, then you can use this option to
specify the field.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
+
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
This setting doesn't affect the index type of entries, such as
\atentry{index} or \atentry{indexplural}. This is useful if your
@@ -13761,7 +14087,7 @@ my file \filefmt{entries.bib} contains:
\strut
\atentry{entry}\marg{glossarylist,
\field{parent}=\marg{glossary},
- \field{description}={list of technical words}
+ \field{description}=\marg{list of technical words}
}
\strut
\atentry{entry}\marg{glosscol,
@@ -13842,9 +14168,19 @@ specify the field. For example,
\csopt[long]{abbreviation-sort-fallback}. Note that if you use
\csopt[name]{sort-field}, then the fallback field will be given by
\csopt{abbreviation-name-fallback} if the \field{name} field is
-omitted. The \meta{field} value must be a known field label.
+omitted.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
+
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\
@@ -13857,14 +14193,23 @@ for sorting (\csopt{sort-field}).
\optsection{symbol-sort-fallback}
The entry types that define symbols (such as \atentry{symbol} and
-\atentry{number}) will, by default, fallback on the label if the
+\atentry{number}) will, by default, fallback on the entry's original label if the
\field{sort} field is missing (assuming the default
\csopt[sort]{sort-field}). If you prefer to fallback on a different
field, then you can use this option to specify the field. For
-example, \csopt[name]{symbol-sort-fallback}. The \meta{field} value
-must be a known field label.
+example, \csopt[name]{symbol-sort-fallback}.
+
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{symbol-sort-fallback} setting is only used when \bibgls\
@@ -13882,7 +14227,17 @@ fallback on the \field{name} if the
\csopt[sort]{sort-field}). If you prefer to fallback on a different
field, then you can use this option to specify the field.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
+
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{bibtexentry-sort-fallback} setting is only used when
@@ -13893,6 +14248,60 @@ explicitly set the \field{sort} field or if you change the field used for
sorting (\csopt{sort-field}).
\end{important}
+\optsection{field-concat-sep}
+
+This option sets the field concatenation separator to \meta{value}.
+The default is a space. An empty value indicates no separator. You
+may use \ics{uhex}\meta{hex} to indicate a character by its hexadecimal
+code. For example, suppose the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{abbreviation}\marg{ac,
+ \field{short}=\marg{AC},
+ \field{long}=\marg{alternating current}
+}
+\atentry{index}\marg{acacia}
+\end{codeenv}
+Then the resource option:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[letter-nocase]{sort},
+ \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
+}
+\end{codeenv}
+will set the \code{ac} sort value to \qt{AC alternating current}.
+That is, the \field{short} value concatenated with the \field{long}
+value using the default space separator. With the
+\optfmt{letter-nocase} sort method, this will put the \code{ac}
+entry before the \code{acacia} entry (because the space character
+comes before \qt{a}).
+
+If the resource options are changed to:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[letter-nocase]{sort},
+ \csopt[\empty]{field-concat-sep},
+ \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
+}
+\end{codeenv}
+This will obtain the sort value for abbreviations from a
+concatenation of the \meta{short} and \meta{long} values without a
+separator. This means that the \code{ac} sort value will be
+\qt{ACalternating current} and so the \code{ac} entry will
+come after the \code{acacia} entry (since \qt{l} comes after \qt{c}).
+
+This setting is only used for the sort fallback options that allow
+field concatenation (such as \csopt{entry-sort-fallback} but not
+\csopt{missing-sort-fallback}).
+
+Note that due to the way that the \keyvallist\ parser trims leading and
+trailing spaces, you can't simply do \csopt[\space]{field-concat-sep}
+to indicate a space character as the value will end up as an empty
+string. You can instead do \csopt[\stringu20]{field-concat-sep} but
+since this is the default value there shouldn't be much need for it.
+
+Remember that the separator may be replaced with a break point
+marker depending on the sort method and \csopt{break-at} setting.
+
\optsection{trim-sort}
If the interpreter is used to determine the sort value, this setting
@@ -15040,7 +15449,8 @@ in the secondary glossary will be the same as for the primary
glossary.
(If the glossary \meta{type} doesn't exist, it will be
-defined with \ics{provideignoredglossary*}\margm{type}.)
+defined with \ics{provideignoredglossary*}\margm{type}
+even if \longarg{no-provide-glossaries} is set.)
Note that if the glossary already exists and contains entries,
the existing entries aren't re-ordered. The new entries are
simply appended to the list.
@@ -19777,6 +20187,251 @@ The \exfile{topics.bib} file contains entries defined using
The contents of \filefmt{topics.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/topics.bib}
+\filesection{sample-hierarchical.tex}
+
+This example uses the \exfile{terms.bib}, \exfile{animals.bib},
+\exfile{minerals.bib} and \exfile{vegetables.bib} files to create a
+hierarchical glossary. These are specified with the resource option:
+\begin{codeenv}
+\csopt[{terms,animals,minerals,vegetables}]{src}
+\end{codeenv}
+The custom \fieldfmt{identifier} field is
+aliased to the \field{parent} field since it conveniently matches
+the labels of the animal, mineral and vegetable entries in the
+\exfile{terms.bib} file:
+\begin{codeenv}
+\csopt[{identifier=parent}]{field-aliases}
+\end{codeenv}
+The default \csopt{selection} setting means that only those terms
+referenced in the document and their dependencies are selected. The
+referenced entries simply have \qt{1} in the \idx{locationlist} as
+it's only a trivial single-paged example.
+
+The dependencies that haven't actually been referenced in the
+document don't have a \idx{locationlist}. (The \qt{seal} entry is a
+dependency, but it's also been referenced in the document, so it has a
+\idx{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow}
+entries are dependencies because they occur in the description of
+some of the referenced entries. Normally this would mean that they
+have no \idx{locationlist} after the first \LaTeX+\bibgls+\LaTeX\
+build but once the glossary has been created the references to those
+dependent entries in the descriptions will create records and so on
+the next \bibgls+\LaTeX\ they will also have \idxpl{locationlist}.
+This would make the complete document build:
+\begin{verbatim}
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+\end{verbatim}
+However, in this example I've decided to ignore any records created
+in the glossary:
+\begin{codeenv}
+\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+This means that the document build is the usual \LaTeX+\bibgls+\LaTeX.
+
+I've used the \glostyle{treegroup} style so I need to invoke
+\bibgls\ with the \longarg{group} switch. This creates letter groups
+for the top-level entries. Note that sub-entries never have letter groups.
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-hierarchical.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-hierarchical.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-hierarchical.pdf}}%
+}
+{\caption{\filefmt{sample-hierarchical.pdf}}}
+{fig:sample-hierarchical.pdf}
+\end{figure}
+
+\filesection{sample-nested.tex}
+
+As discussed in \sectionref{sec:logicaldivisions} there are three
+ways of creating logical divisions when displaying the entries
+through the use of the \field{type}, \field{group} and \field{parent} fields.
+In general, hierarchical glossaries are created with
+the \field{parent} field and an appropriate glossary style (as in
+the previous \exfile{sample-hierarchical.tex} example).
+
+This example creates a hierarchical effect but the entries don't
+actually have a hierarchical structure as none of them have the
+\field{parent} field set. Instead, what were the child entries in
+\exfile{sample-hierarchical.tex} now have the \field{type} field
+set. The hierarchical effect is achieved with
+\ics{printunsrtinnerglossary} (which requires at least
+\sty{glossaries-extra} v1.44).
+
+\begin{important}
+The \ics{printunsrtinnerglossary} command is unsuitable for use
+with tabular-like styles, such as \glostyle{long}, and can be
+problematic with \glostyle{list} styles. However, those styles
+aren't suitable for hierarchical glossaries anyway.
+\end{important}
+
+Normally, hierarchy is achieve through definitions like:
+\begin{codeenv}
+\atentry{index}\marg{animal}
+\atentry{entry}\marg{duck,\field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \field{parent}=\marg{animal}
+}
+\end{codeenv}
+The previous example did this by loading both the \exfile{terms.bib}
+and \exfile{animals.bib} files and aliasing the custom
+\fieldfmt{identifier} field to \field{parent}. In this example, the
+custom field is aliased to \field{type}, which effectively makes the
+definitions behave like:
+\begin{codeenv}
+\atentry{index}\marg{animal}
+\atentry{entry}\marg{duck,\field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \field{type}=\marg{animal}
+}
+\end{codeenv}
+The aim here is for the \code{animal} entry to be placed in the main
+glossary so that it's listed with \cs{printunsrtglossary}. The
+\code{duck} entry is placed in a glossary that has a label
+(\code{animal}) that matches the label of the \qt{parent} entry
+(even though it's technically not a parent). This new glossary
+(\code{animal}) can be automatically defined by invoking \bibgls\
+with the \longarg{provide-glossaries} switch.
+
+This example document defines a custom handler function that
+will do the current entry as normal (with \cs{glsxtrunsrtdo}) but
+will then check for the existence of a glossary that has the same
+label as the current entry. This requires the starred version of
+\ics{ifglossaryexists} to included ignored glossaries in the
+existence check. If the glossary exists, it's then displayed using
+\ics{printunsrtinnerglossary}:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{nestedhandler}}[1]\marg{\comment{}
+ \cs{glsxtrunsrtdo}\marg{\idx{hashchar}1}\comment{}
+ \ics{ifglossaryexists*}\marg{\idx{hashchar}1}\comment{}
+ \marg{\comment{}
+ \cs{printunsrtinnerglossary}\oarg{\printglossopt[\idx{hashchar}1]{type},\printglossopt[++1]{leveloffset},\printglossopt[false]{groups}}
+ \marg{}\marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+The \printglossopt{leveloffset} option is required to achieve a
+hierarchical effect (provided the glossary style supports it) and
+the \printglossopt[false]{groups} option is needed to prevent letter
+groups showing for the nested glossary, which would otherwise create
+a strange effect. (This example uses the \glostyle{treegroup} style,
+which provides a hierarchical glossary with letter groups.)
+
+The \cs{printunsrtglossary} handler macro then needs to be set to
+this custom macro when the main glossary is displayed:
+\begin{codeenv}
+\cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}}
+\end{codeenv}
+The main difficulty comes with ensuring that all the necessary
+entries are selected. Now that the custom \fieldfmt{identifier}
+field has been aliased to \field{type} rather than \field{parent},
+the \code{animal} entry is no longer considered a dependent. The
+\code{duck} entry has been referenced in the document with \cs{gls}
+but the \code{animal} entry hasn't. The previous example ensured
+that the \code{animal} entry was selected because it was a parent of
+a selected entry. If the same resource options are used in this
+example, the main glossary will be empty, which means that the
+nested glossaries won't be displayed either.
+
+One way to ensure that the \code{animal}, \code{mineral} and
+\code{vegetable} entries are selected is to identify the \field{type}
+field as a dependency field:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[{terms,animals,minerals,vegetables}]{src},
+ \csopt[{identifier=type}]{field-aliases},
+ \csopt[{type}]{dependency-fields}
+}
+\end{codeenv}
+This will achieve the same effect as the
+\exfile{sample-hierarchical.tex} document, but it's a far more
+convoluted method. The reason this example document is listed here
+is to demonstrate a sightly modified hierarchical effect that can't
+be achieved through the normal method.
+
+Suppose that, for some strange reason, I want the \qt{animal},
+\qt{mineral} and \qt{vegetable} entries to be listed in a different
+order (say, reverse alphabetical). The other entries (\qt{duck} etc)
+need to be sorted in normal alphabetical order.
+
+The \csopt{sort} option applies the same sort method to all
+hierarchical levels. The sort \emph{value} chosen for particular entries
+can be altered through the use of fallbacks (such as the
+\csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options)
+and a letter comparator may be used to resolve identical sort
+values (\csopt{identical-sort-action}), but the same sort algorithm
+is applied to all entries in the same set (primary, secondary or dual
+within the same resource set). The only way to apply different sort
+methods is to separate the entries into different resource sets (or
+use dual or secondary sorting).
+
+This can be achieved by having one resource set for the main entries
+with one sort method and another resource set for all the other
+entries with a different sort method:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[terms]{src},\csopt[en-reverse]{sort}}
+
+\gls{GlsXtrLoadResources}\oarg{\csopt[animals,minerals,vegetables]{src},\csopt[en]{sort},
+ \csopt[{identifier=type}]{field-aliases},\csopt[{type}]{dependency-fields}
+}
+\end{codeenv}
+This works when cross-resource dependencies are permitted (see
+\sectionref{sec:resourcesets}). In the event that cross-resource
+dependencies aren't permitted, the selection criteria is more
+complicated:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[terms,animals,minerals,vegetables]{src},
+ \csopt[en-reverse]{sort},
+ \csopt[{identifier=parent}]{field-aliases},
+ \csopt[ancestors but not recorded]{selection}
+}
+
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[animals,minerals,vegetables]{src},
+ \csopt[{identifier=type}]{field-aliases},
+ \csopt[{type}]{dependency-fields}
+ \csopt[en]{sort}
+}
+\end{codeenv}
+Fortunately in this example, cross-resource dependencies are
+permitted so the simpler alternative works. (If they're not
+permitted, the \bibgls\ transcript file will contain
+\qt{Cross-resource references can't be supported for resource set
+\meta{filename}}.)
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-nested
+bib2gls --group --provide-glossaries sample-nested
+pdflatex sample-nested
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-nested.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-nested.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-nested.pdf}}%
+}
+{\caption{\filefmt{sample-nested.pdf}}}
+{fig:sample-nested.pdf}
+\end{figure}
+
\filesection{sample-constants.tex}
This example uses the \exfile{constants.bib} file. The aim here
@@ -23145,6 +23800,9 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
}%
}
\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
-\renewcommand*{\bibglspassim}{}
+\glsrenewcommand*{\bibglspassim}{}
+\newcommand{\glsxtrpostnamecommand}{%
+ \glsxtrifhasfield{userii}{\glscurrententrylabel}{ (\glscurrentfieldvalue)}{}%
+}
\printunsrtglossary[type=index]
\end{document}