summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src/bib2gls.tex')
-rw-r--r--support/bib2gls/src/bib2gls.tex2994
1 files changed, 2329 insertions, 665 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index 679fab16ed..652eaf6f92 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/support/bib2gls/src/bib2gls.tex
@@ -11,7 +11,7 @@
\usepackage[autooneside=false]{scrlayer-scrpage}
\usepackage{pifont}
-% Need support for extended characters
+% Need support for less common extended characters
% and need a mono font that supports hyphenation
\usepackage[no-math]{fontspec}
\setmainfont{Linux Libertine O}
@@ -339,7 +339,7 @@ documents}}
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
-\newcommand{\stringu}{\idx{cs.string}\idx{uhex}}
+\newcommand{\stringu}{\idx{cs.string}\gls{uhex}}
\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand*{\metafilefmt}[3]{%
@@ -492,6 +492,12 @@ documents}}
\newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}}
+\newcommand*{\keyval}{%
+ \texorpdfstring
+ {\meta{key}\dequals \meta{value}}%
+ {key=value}%
+}
+
\newcommand*{\keyvallist}{%
\texorpdfstring
{key\dequals value list}%
@@ -1760,7 +1766,7 @@ field. You then need to select an appropriate \idx{glossarystyle}.
If you only want to have a single \ext{bib} file that contains all
your entries and you want to share it across multiple documents then
-the most flexible approach is to use custom fields and entry types
+the most flexible approach is to use custom fields and \glspl{entrytype}
that can be aliased according to the needs of the \glspl{resourceset}.
For example, the file \filefmt{entries.bib}:
@@ -2123,6 +2129,10 @@ the corresponding set of \ext{bib} files:
\item end punctuation is checked according to
\csopt{check-end-punctuation};
+ \item field assignments are made (\csopt{assign-fields}),
+ and any of the above case-change or suffixes required
+ by the destination fields are performed;
+
\item \field{name} adjustment is performed if
\csopt{compound-adjust-name} is set (and the criteria is met);
@@ -2250,6 +2260,107 @@ If the \igls{crossresourceref} mode is enabled then stage~3 and
stage~4 are processed in separate \idxpl{loop}, otherwise they are
processed in the same \idx{loop}.
+\section{\bibgls\ Quarks}
+\label{sec:quarks}
+
+A \bibgls\ \idx{quark} is similar in principle to a \LaTeX3 quark,
+in that it is a token that looks like a control sequence but isn't
+intended to be interpreted as a \LaTeX\ command. Unlike \LaTeX3
+quarks, their name isn't prefixed with \csfmt{q\_} and can
+coincidentally look the same as a \LaTeX\ command. This is
+particularly the case with regular expressions that have escaped
+characters to indicate a literal character. For example, in a
+regular expression a pipe or vertical bar character \idx{regexpor}
+indicates \qt{or}. If you want to match a literal pipe, you need to
+identify this with \cs{quark.pipe}. This is distinct from, but
+visually identical to, the \LaTeX\ command used to create a double
+vertical bar in maths mode.
+
+The resource options provided in \gls{GlsXtrLoadResources} expand as
+they are written to the \ext{aux} file. This allows commands to be
+used within the resource options that expand to a complex option
+that may be required multiple times. For example,
+\ics{GlsXtrBibTeXEntryAliases} or \ics{glsxtrhyphenrules}.
+Unfortunately, this means that quarks must be prevented from
+expansion as they form part of the option syntax and are not
+intended for use in the document.
+
+This means that, unless they happen to coincidentally be robust
+commands, they must be preceded by either \ics{protect} or
+\idx{cs.string}. Since \cs{protect} adds a space afterwards,
+\idx{cs.string} is usually better if the syntax requires that spaces
+after quarks are significant.
+
+This can lead to cumbersome expressions, but it's possible to
+redefine \ics{glsxtrresourceinit} to locally redefine these quarks
+to expand to detokenized forms of themselves. For example:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}}
+\end{codeenv}
+Since there are a number of these quarks, as from v1.51,
+\sty{glossaries-extra-bib2gls} (which is automatically loaded with
+\styopt{record}) provides \ics{GlsXtrResourceInitEscSequences},
+so you can change the above to the following:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
+ \cs{GlsXtrResourceInitEscSequences}
+}
+\end{codeenv}
+
+This will locally define the quarks listed below. Since \cs{glsxtrresourceinit}
+is scoped so that it only has an effect within the protected write,
+this shouldn't interfere with the corresponding commands that are required in
+the document. Note that these quarks should only be used in their
+designated contexts.
+
+\begin{description}
+
+\item[General] \inlinedef{uhex} is recognised in certain resource options
+(such as \csopt{field-concat-sep}) as indicating the Unicode
+character with the given hexadecimal code.
+
+\item[Regular expressions] The following indicate a literal
+character:
+\glsadd{idx.periodchar}\inlinedef{quark.dot}
+\glsadd{idx.backslashchar}\inlinedef{quark.backslash}
+\glsadd{idx.slashchar}\inlinedef{quark.slash}
+\glsadd{idx.pipechar}\inlinedef{quark.pipe}
+\glsadd{idx.ampchar}\inlinedef{quark.amp}
+\glsadd{idx.pluschar}\inlinedef{quark.plus}
+\glsadd{idx.ltchar}\inlinedef{quark.lt}
+\glsadd{idx.gtchar}\inlinedef{quark.gt}
+\glsadd{idx.starchar}\inlinedef{quark.star}
+\glsadd{idx.dollarchar}\inlinedef{quark.dollar}
+\glsadd{idx.circumchar}\inlinedef{quark.circum}
+\glsadd{idx.tildechar}\inlinedef{quark.tilde}
+\glsadd{idx.openparenchar}\inlinedef{quark.openparen}
+\glsadd{idx.closeparenchar}\inlinedef{quark.closeparen}
+\glsadd{idx.opensqchar}\inlinedef{quark.opensq}
+\glsadd{idx.closesqchar}\inlinedef{quark.closesq}
+\glsadd{idx.doublequotechar}\inlinedef{quark.doublequote}
+\glsadd{idx.hyphenchar}\inlinedef{quark.hyphen}
+\glsadd{idx.questionchar}\inlinedef{quark.question}
+\glsadd{idx.colonchar}\inlinedef{quark.colon}
+\glsadd{idx.hashchar}\inlinedef{quark.hash}.
+Note that \idxpl{regex} in resource options are typically
+\gls{anchored}, so there shouldn't be any need to use \idx{regex.circum}
+or \idx{regex.dollar} to denote the start and end.
+
+\item[Field assignments] The following commands may be used in the
+\meta{element-list} syntax of \csopt{assign-fields}:
+\gls{CS}, \gls{MGP}, \gls{LEN}, \gls{TRIM}, \gls{INTERPRET},
+\gls{LC}, \gls{UC}, \gls{FIRSTLC}, \gls{FIRSTUC}, and \gls{TITLE}.
+
+\item[Conditionals] The \meta{condition} part of the \csopt{assign-fields}
+syntax recognises \gls{LEN}, \gls{CAT}, \gls{IN}, \gls{NIN}, \gls{PREFIXOF},
+\gls{NOTPREFIXOF}, \gls{SUFFIXOF}, \gls{NOTSUFFIXOF} and \gls{NULL}.
+\end{description}
+
+Finally, this isn't actually a quark, but \inlinedef{cs} is defined
+to expand to the literal string \csfmt{csname} so you can use it for any
+other escape sequences that aren't covered above. For example,
+\code{\gls{cs}\marg{n}} for a newline \ics{n}.
+
\section{Indexing}
The dual index entries such as \atentry{dualindexentry} (described in
@@ -2354,7 +2465,7 @@ called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a
valid \idx{IETF} language tag.
The appropriate file is searched for in the following order, where
-\meta{locale} is the operating system's locale or the value supplied
+\meta{locale} is the \gls{Java-locale} or the value supplied
by the \longarg{locale} switch:
\begin{enumerate}
\item \meta{lang} exactly matches \meta{locale}.
@@ -2380,13 +2491,31 @@ If there is no match, \bibgls\ will fallback on the English resource file
to translating it. Any volunteers who want to provide other language
resource files would be much appreciated.)
+In addition to the main language file, it's possible to have
+supplementary files that provide text that matches the
+\gls{resource-locale}. These are in files called
+\metafilefmt{bib2gls-extra-}{lang}{.xml}, which has the same format
+as \metafilefmt{bib2gls-}{lang}{.xml}. These supplementary files
+will be loaded automatically if they exist and if you have
+\styfmt{glossaries-extra} v1.51+ (which will save a list of all
+tracked languages for the document).
+
Note that if you use the \csopt[true]{loc-prefix} option, the
-textual labels (\qt{Page} and \qt{Pages} in English) will be taken
-from the resource file. In the event that the loaded resource file
-doesn't match the document language, you will have to manually set
+textual labels (\qt{Page} and \qt{Pages} in English) will be
+first be attempted from the supplementary file with the tags
+\code{tag.\meta{lang}.page} and \code{tag.\meta{lang}.pages}
+(where \meta{lang} is the language code) and then, if not
+found, from the main resource file using the tags \code{tag.page}
+and \code{tag.pages}. In the event that the loaded resource file
+doesn't match the document language and there's no supplementary
+file, you will have to manually set
the correct translation (in English, this would be
\csopt[Page\dcomma Pages]{loc-prefix}). The default definition of
-\gls!{bibglspassim} is also obtained from the resource file.
+\gls!{bibglspassim} is also obtained from the resource file in a
+similar manner.
+
+There are also keys in the resource file to assist case-conversion.
+Currently, there's only support for the Dutch \qt{IJ} case.
\section{Conditional Document Build}
@@ -2570,7 +2699,9 @@ example, UTF-8 characters that occur in any resource options will
need to be detokenized when using \sty{inputenc} to prevent
expansion when they are written to the \ext{aux} file. (In some
options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex}
-syntax to specify a UTF-8 character.)
+syntax to specify a UTF-8 character.) Note that newer \LaTeX\
+kernels have better support for UTF-8 and this issue is less likely
+to occur.
The \longarg{no-interpret} switch will turn off the interpreter, but
the library will still be used to parse the \ext{aux} and \ext{bib}
@@ -2732,16 +2863,16 @@ automatically converts the first letter of the name to
\longarg{mfirstuc-math-protection}.)
None of these entries have a \field{sort} field so the \field{name}
-is used. If the entry type had been \atentry{symbol} instead,
-the fallback would be the entry's label.
-This means that with \atentry{symbol} instead of \atentry{entry}, and the default
-\csopt[sort]{sort-field}, and with
-\csopt[letter-case]{sort}, these entries will be defined in
-the order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since
-this is the case-sensitive letter order of the labels) whereas
-with \csopt[letter-nocase]{sort-field}, the order will be:
-\code{card}, \code{i}, \code{M}, \code{S}, \code{v} (since this
-is the case-insensitive letter order of the labels).
+is used (see \sectionref{sec:fallbacks}). If the \gls{entrytype} had
+been \atentry{symbol} instead, the fallback would be the entry's
+label. This means that with \atentry{symbol} instead of
+\atentry{entry}, and the default \csopt[sort]{sort-field}, and with
+\csopt[letter-case]{sort}, these entries will be defined in the
+order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since
+this is the case-sensitive letter order of the labels) whereas with
+\csopt[letter-nocase]{sort-field}, the order will be: \code{card},
+\code{i}, \code{M}, \code{S}, \code{v} (since this is the
+case-insensitive letter order of the labels).
However, with \atentry{entry}, the fallback field will be taken from
the \field{name} which in the above example contains \TeX\ code, so
@@ -3027,14 +3158,18 @@ Synonym of \longarg{quiet}.
Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag.
This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml}
resource file otherwise \bibgls\ will fallback on English.
-This also sets the default document locale when \csopt[doc]{sort} is
+This also sets the default \gls{document-locale} when the \optfmt{doc}
+keyword (in options such as \csopt[doc]{sort}) is
used and the document doesn't have any language support.
-Note that \csopt[locale]{sort} uses the \idx{JVM}['s] default
-locale and is not governed by this switch.
+Note that the \optfmt{locale} keyword (in options such as \csopt[locale]{sort})
+uses the \gls{Java-locale} and is not governed by this switch.
If a document doesn't have any locale support or has support
for more than one language then it's best to explicitly set
-the required locale in the appropriate \idx{resourceset}.
+the required locale in the appropriate \idx{resourceset} using
+the \csopt{locale} resource option, to specify the default
+\gls{resource-locale}, or set the locale for individual options,
+such as \csopt{sort}.
\argsection{group}
@@ -3120,10 +3255,13 @@ The group label is obtained from \gls!{bibglstimegroup}.
aliasing a field (with \csopt{field-aliases}) or by using the
\csopt[\meta{label}]{group} resource option. You will need to use
\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the
-\meta{label} isn't the same as the title. Remember that the label
-can't contain any active characters, so you can't use non-ASCII
-characters in \meta{label} with \sty{inputenc} (but you can use
-non-ASCII alphanumerics with \sty{fontspec}).
+\meta{label} isn't the same as the title. Remember that with older
+\LaTeX\ kernels, the label can't contain any active characters, so
+you can't use non-ASCII characters in \meta{label} with
+\sty{inputenc} (but you can use non-ASCII alphanumerics with
+\sty{fontspec}). To ensure better support for UTF-8 with \pdfLaTeX, make sure you
+have a recent \TeX\ distribution and up-to-date versions of
+\sty{glossaries} and \sty{glossaries-extra}.
\end{description}
@@ -3417,7 +3555,11 @@ Packages that fall into the first category are:
that might be needed within entry fields. The check for
\isty{fontspec} is to simply determine whether or not UTF-8
characters are allowed in labels (for \csopt{labelify} and
-\csopt{labelify-list}).
+\csopt{labelify-list}). (Now that there is better support for UTF-8
+with \pdfLaTeX, UTF-8 characters will be allowed in labels if the
+detected versions of \isty{glossaries} and \isty{glossaries-extra}
+are new enough, but note that you will also need a relatively new
+\LaTeX\ kernel as well.)
Packages that fall into the second category are:
\isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited),
@@ -3829,7 +3971,7 @@ This will only count records where the format matches the regular
expression \code{.*(bf|it)} (for example, \code{hyperbf} or
\code{hyperit}) or the counter name matches \code{section} or
\code{subsection} (but not \code{subsubsection}, since the
-expressions are anchored).
+expressions are \gls{anchored}).
This syntax doesn't permit the use of the sequence \code{/c/}
appearing in the regular expressions, but both the format and
@@ -3868,7 +4010,7 @@ and \ref{tab:baseinternalfields} with a few exceptions, notably
\field{type} and \field{sort}. Ideally you shouldn't need to use
\field{sort} as there should be an appropriate fallback set up to
use if \field{sort} isn't set, such as the label for symbols or the
-name for terms or the short form for abbreviations.
+name for terms or the short form for abbreviations (see \sectionref{sec:fallbacks}).
This is the default setting and was added as some users were
confused over which fields could be used in the \ext{bib} file.
@@ -3888,12 +4030,12 @@ avoid unexpected results.
\argsection{warn-unknown-entry-types}
-If any unknown entry types are found in the \ext{bib} file, \bibgls\
+If any unknown \glspl{entrytype} are found in the \ext{bib} file, \bibgls\
will issue a warning with this option set (default).
\argsection{no-warn-unknown-entry-types}
-This option will suppress the warning if an unknown entry types are
+This option will suppress the warning if an unknown \glspl{entrytype} are
found in the \ext{bib} file.
\section{Field Options}
@@ -4157,7 +4299,7 @@ Single and double-quote characters (\idx{aposchar} and
\label{sec:bib}
\setsecdepth{1}
-\bibgls\ recognises certain entry types. Any unrecognised types will
+\bibgls\ recognises certain \glspl{entrytype}. Any unrecognised types will
be ignored and a warning will be written to the transcript file.
Entries are defined in the usual \ext{bib} format:
\begin{codeenv*}
@@ -4167,7 +4309,7 @@ Entries are defined in the usual \ext{bib} format:
\meta{field-name-n} = \margm{text}
}
\end{codeenv*}
-where \meta{entry-type} is the entry type (listed below),
+where \meta{entry-type} is the \gls{entrytype} (listed below),
\meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and
\meta{id} is a unique label. The label can't contain any spaces or
commas, and most special characters are forbidden. The hyphen character and
@@ -4257,7 +4399,7 @@ for general comments, but not for the \gls{encoding}.
\section{Fields}
\label{sec:fields}
-Each entry type may have required fields, optional fields and
+Each \gls{entrytype} may have required fields, optional fields and
ignored fields. These are set using a \keyvallist\ within
\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the
\ext{bib} file. Most keys recognised by
@@ -4267,10 +4409,10 @@ shouldn't need to use the \field{sort} field.
If an optional field is missing and \bibgls\ needs to access it for
some reason, \bibgls\ will try to fallback on another value. The
-actual fallback value depends on the entry type. The most common
+actual fallback value depends on the \gls{entrytype}. The most common
fallback is that used if the \field{sort} field is missing, which is
-typically the case. This approach allows different entry types to
-have different fields used for sorting.
+typically the case. This approach allows different \glspl{entrytype} to
+have different fields used for sorting (see \sectionref{sec:fallbacks}).
Predefined fields for use in \ext{bib} files are listed in
Tables~\ref{tab:fields}, \ref{tab:bib2glsfields},
@@ -4280,6 +4422,16 @@ custom keys in your document using \ics{glsaddkey} or
first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\
recognises them as a valid field name.
+\begin{important}
+If you define your own custom keys, ensure that they don't contain
+spaces, commas (\idx{commasep}), equal signs (\idx{equalsassign}) or
+any other character that isn't supported by the \ext{bib} format.
+Additionally, if you want to use \csopt{assign-fields}, ensure
+that you don't use any of the assignment special characters, such as
+plus (\idx{concat-plus}), within any
+field names.
+\end{important}
+
Internal fields that may be assigned within the document (the
\LaTeX\ assignment code having been written by \bibgls\ in the
\iext{glstex} file) are listed in Table~\ref{tab:internalfields}.
@@ -4388,7 +4540,8 @@ but it doesn't add any information to the cross-referencing part of the
within a \ext{bib} file can cause unpredictable
results and is best set through a resource option or by \bibgls.
In general, you shouldn't need to set the \field{sort} field as
- appropriate fallbacks should produce useful sort values.%
+ appropriate fallbacks should produce useful sort values
+ (see \sectionref{sec:fallbacks}).%
]%
{internalfield}%
[Fields Set by \bibgls]%
@@ -4418,6 +4571,45 @@ but it doesn't add any information to the cross-referencing part of the
\clearpage
+\section{String Concatenation}
+\label{sec:bibstringconcat}
+
+The \ext{bib} format allows you to perform string \gls{concatenation}.
+That is, join fragments together to form a single value.
+The \gls{concatenation} operator in \ext{bib} files is
+\idx{stringconcat}.
+For example, if the following string is defined:
+\begin{codeenv}
+\atentry{string}\marg{markuplang=\marg{markup language}}
+\end{codeenv}
+Then values can be obtained by concatenating this string with other
+strings. For example:
+\begin{codeenv}
+\atentry{abbreviation}\marg{xml,
+ \field{short}=\marg{XML},
+ \field{long}=\marg{extensible } \idx{stringconcat} markuplang
+}
+\atentry{abbreviation}\marg{html,
+ \field{short}=\marg{HTML},
+ \field{long}=\marg{hypertext } \idx{stringconcat} markuplang
+}
+\end{codeenv}
+This is equivalent to:
+\begin{codeenv}
+\atentry{abbreviation}\marg{xml,
+ \field{short}=\marg{XML},
+ \field{long}=\marg{extensible markup language}
+}
+\atentry{abbreviation}\marg{html,
+ \field{short}=\marg{HTML},
+ \field{long}=\marg{hypertext markup language}
+}
+\end{codeenv}
+
+Note that some resource options allow string \gls{concatenation} in
+their syntax. That uses a different operator. See
+\sectionref{sec:optstringconcat} for further details.
+
\section{Standard Entry Types}
\label{sec:standardentry}
@@ -4477,7 +4669,7 @@ the resource file is input). In general, it's best to just use
The \TeX\ parser library used by \bibgls\ will parse the contents of
\atentry{preamble} before trying to interpret the field value used
-as a fallback when \field{sort} is omitted (unless
+as a \hyperref[sec:fallbacks]{fallback} when \field{sort} is omitted (unless
\csopt[false]{interpret-preamble} is set in the resource options).
For example:
\begin{codeenv}
@@ -4691,7 +4883,7 @@ but their actual definitions are determined in the \ext{bib} file.
\section{Single Entry Types}
\label{sec:singleentry}
-The entry types described in this section create a single glossary
+The \glspl{entrytype} described in this section create a single glossary
definition per entry (from \styfmt{glossaries-extra}'s point of view).
For example:
\begin{codeenv}
@@ -4715,7 +4907,7 @@ with the entry labels in its internal list in a different order.
This means that the same data can be displayed in two separate lists
without duplicating the resources required by each glossary entry.
-\Sectionref{sec:dualentry} describes \bibgls\ entry types
+\Sectionref{sec:dualentry} describes \bibgls\ \glspl{entrytype}
that create two separate (but related) \styfmt{glossaries-extra}
definitions per \ext{bib} entry.
@@ -4755,17 +4947,18 @@ If the \field{sort} field is missing the default is obtained from
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
-\glsdisp{parententry}{parent's} \field{name}.
+\glsdisp{parententry}{parent's} \field{name}.
+See \sectionref{sec:fallbacks}.
Terms defined using \atentry{entry} will be written to the output
(\ext{glstex}) file using the command \gls!{bibglsnewentry}.
\entrysection{symbol}
-The \atentry{symbol} entry type is much like \atentry{entry}, but it's
+The \atentry{symbol} \gls{entrytype} is much like \atentry{entry}, but it's
designed specifically for symbols, so in the previous example, the
\code{M} and \code{v} terms would be better defined using the
-\atentry{symbol} entry type instead. For example:
+\atentry{symbol} \gls{entrytype} instead. For example:
\begin{codeenv}
\atentry{symbol}\marg{M,
\field{name}=\marg{\cs{ensuremath}\marg{M}},
@@ -4775,17 +4968,18 @@ 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
+missing. If the \field{sort} field is omitted, the default fallback is
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.
+See \sectionref{sec:fallbacks}.
Terms that are defined using \atentry{symbol} will be written to
the output file using the command \gls!{bibglsnewsymbol}.
\entrysection{number}
-The \atentry{number} entry type is like \atentry{symbol}, but it's for
+The \atentry{number} \gls{entrytype} is like \atentry{symbol}, but it's for
numbers. The numbers don't have to be explicit digits and may have a
symbolic representation. There's no real difference between the
behaviour of \atentry{number} and \atentry{symbol} except that terms
@@ -4831,19 +5025,20 @@ glossary format to include the \field{user1} field:
\entrysection{index}
-The \atentry{index} entry type is designed for entries that don't
+The \atentry{index} \gls{entrytype} is designed for entries that don't
have a description. Only the label is required. If \field{name} is
omitted, it's assumed to be the same as the label, even if
\field{parent} is present. (Note this is different to the fallback
behaviour of \atentry{entry}, which fetches the name from the
\gls{parententry}.) 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
+field is missing the default fallback is obtained from the \field{name}.
+Note that the \atentry{index} \gls{entrytype} is \emph{not} governed by
\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.
+See \sectionref{sec:fallbacks}.
Example:
\begin{codeenv}
@@ -4858,8 +5053,8 @@ file using the command \gls!{bibglsnewindex}.
\entrysection{indexplural}
-The \atentry{indexplural} entry type is similar to the
-\atentry{index} entry type except that the \field{name} field, if
+The \atentry{indexplural} \gls{entrytype} is similar to the
+\atentry{index} \gls{entrytype} except that the \field{name} field, if
missing, is obtained from the \field{plural} field. If the
\field{plural} field is missing it's obtained from the \field{text}
field with the plural suffix appended. If the \field{text} field is
@@ -4868,6 +5063,7 @@ missing, it's obtained from the original entry label. If the
\field{name} field. (As with \atentry{index}, \atentry{indexplural}
is \emph{not} governed by \csopt{entry-sort-fallback}, but it is
governed by \csopt{custom-sort-fallbacks}.)
+See \sectionref{sec:fallbacks}.
All fields are optional. For example:
\begin{codeenv}
\atentry{indexplural}\marg{goose,
@@ -4907,7 +5103,7 @@ file using the command \gls!{bibglsnewindexplural}.
\entrysection{abbreviation}
-The \atentry{abbreviation} entry type is designed for abbreviations.
+The \atentry{abbreviation} \gls{entrytype} is designed for abbreviations.
The required fields are \field{short} and \field{long}. If the
\field{sort} key is missing, \bibgls\ will use the field given by
\csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field.
@@ -4920,6 +5116,7 @@ If you use \csopt[name]{sort-field} (rather than the default
the \csopt{abbreviation-sort-fallback} setting, unless you use
\csopt{abbreviation-name-fallback} to change the fallback for the
\field{name} field.
+See \sectionref{sec:fallbacks}.
Note that you must set the abbreviation style before loading the
resource file to ensure that the abbreviations are defined
@@ -5010,21 +5207,22 @@ file using the command \gls!{bibglsnewabbreviation}.
\entrysection{acronym}
-The \atentry{acronym} entry type is like \atentry{abbreviation} except that
+The \atentry{acronym} \gls{entrytype} is like \atentry{abbreviation} except that
the term is written to the output file using the command
\gls!{bibglsnewacronym}.
\entrysection{contributor}
-The \atentry{contributor} entry type is primarily provided for use
-by the \atentry{bibtexentry} type. You may use it explicitly
-if you want, but you need to take care that it doesn't clash with
-\atentry{bibtexentry}. It behaves much like \atentry{index} except that the
-term is written to the \ext{glstex} file using the command
+The \atentry{contributor} \gls{entrytype} is primarily provided for
+use by the \atentry{bibtexentry} type. You may use it explicitly if
+you want, but you need to take care that it doesn't clash with
+\atentry{bibtexentry}. It behaves much like \atentry{index} except
+that the term is written to the \ext{glstex} file using the command
\gls!{bibglsnewcontributor}. There are no required fields. As with
\atentry{index}, if the \field{name} field is missing, the fallback
-value is the entry's label. When this entry type is automatically
-created by \atentry{bibtexentry}, the \field{name} is set to
+value is the entry's label (see \sectionref{sec:fallbacks}). When
+this \gls{entrytype} is automatically created by
+\atentry{bibtexentry}, the \field{name} is set to
\begin{codeenv}
\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}
\end{codeenv}
@@ -5066,7 +5264,7 @@ corresponding \atentry{bibtexentry} then you will end up with a label clash.
\section{Dual Entry Types}
\label{sec:dualentry}
-The entry types described in this section create two separate (but
+The \glspl{entrytype} described in this section create two separate (but
related) \styfmt{glossaries-extra} entry definitions per \ext{bib}
entry. The first of these entries is considered the
\igls{primaryentry}, and the second is the \igls{dualentry}.
@@ -5119,12 +5317,13 @@ that if you only reference the \gls{primaryentry} (using \ics{gls} etc)
then the \gls{dualentry} will still be selected if the \csopt{selection}
setting includes dependencies.
-The creation of the \gls{dualentry} involves mapping or copying fields
-from the \gls{primaryentry}. Each \gls{dualentry} type has a set of mappings.
-If a field in the set of mappings is missing, its fallback value is
-used. Any fields that aren't listed in the mappings are simply copied,
-except for the \field{alias} field, which will never be copied to
-the \gls{dualentry}, nor can it be mapped. The alias will only apply to
+The creation of the \gls{dualentry} involves mapping or copying
+fields from the \gls{primaryentry}. Each \gls{dualentry} type has a
+set of mappings. If a field in the set of mappings is missing, its
+fallback value is used (see \sectionref{sec:fallbacks}). Any fields
+that aren't listed in the mappings are simply copied, except for the
+\field{alias} field, which will never be copied to the
+\gls{dualentry}, nor can it be mapped. The alias will only apply to
the \gls{primaryentry}. The \gls{dualentry} is given the label
\meta{prefix}\meta{id} where \meta{prefix} is set by the
\csopt{dual-prefix} option and \meta{id} is the label supplied in
@@ -5137,7 +5336,7 @@ appended to the end of the \ext{glstex} file. The
\csopt{dual-sort-field} determines what field to use for the sort
value if the dual entries should be sorted separately.
-Take care if you have a mixture of entry types (such as
+Take care if you have a mixture of \glspl{entrytype} (such as
\atentry{dualindexentry}, \atentry{dualindexsymbol}
and \atentry{index}) and you're not
using the default \csopt[combine]{dual-sort}. Remember that the
@@ -5187,7 +5386,7 @@ For example, suppose the file \filefmt{entries.bib} contains:
\cs{gls}\marg{html} document}
}
\end{codeenv}
-This contains a mixture of entry types, including
+This contains a mixture of \glspl{entrytype}, including
\atentry{dualindexabbreviation} (where the \dual\ is the
abbreviation) and \atentry{dualabbreviationentry} (where the
\primary\ is the abbreviation).
@@ -5410,7 +5609,7 @@ A better solution would be to use
\entrysection{dualentry}
-The \atentry{dualentry} entry type is similar to \atentry{entry} but
+The \atentry{dualentry} \gls{entrytype} is similar to \atentry{entry} but
actually defines two entries.
The \gls{dualentry} contains the same information as the \gls{primaryentry}
but some of the fields are swapped around.
@@ -5617,7 +5816,7 @@ with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc.
\entrysection{dualindexabbreviation}
-The \atentry{dualindexabbreviation} entry type is similar to
+The \atentry{dualindexabbreviation} \gls{entrytype} is similar to
\atentry{dualindexentry} and again, by default, the
field mapping is:
\begin{itemize}
@@ -5640,7 +5839,7 @@ However in this case the required fields are \field{short} and
\field{short} if omitted. (This may be changed with the
\csopt{abbreviation-name-fallback} option.) The fallback for the
\field{sort} field is given by \csopt{abbreviation-sort-fallback},
-which defaults to the \field{short} field.
+which defaults to the \field{short} field (see \sectionref{sec:fallbacks}).
For example:
\begin{codeenv}
@@ -5674,7 +5873,7 @@ The \dual\ term is defined using
\entrysection{dualindexsymbol}
-The \atentry{dualindexsymbol} entry type is similar to
+The \atentry{dualindexsymbol} \gls{entrytype} is similar to
\atentry{dualindexentry}, but by default the
field mappings are:
\begin{itemize}
@@ -5844,7 +6043,7 @@ further details.
\entrysection{dualindexnumber}
-The \atentry{dualindexnumber} entry type is almost identical to
+The \atentry{dualindexnumber} \gls{entrytype} is almost identical to
\atentry{dualindexsymbol}, but the \glspl{primaryentry} are defined using
\gls!{bibglsnewdualindexnumber},
which by default sets the \field{category} to \optfmt{index},
@@ -5854,7 +6053,7 @@ which by default sets the \field{category} to \optfmt{number}.
\entrysection{dualabbreviationentry}
-The \atentry{dualabbreviationentry} entry type is similar to
+The \atentry{dualabbreviationentry} \gls{entrytype} is similar to
\atentry{dualentry}, but by default the
field mappings are:
\begin{itemize}
@@ -5876,13 +6075,13 @@ additionally include:
\end{itemize}
You may need to add a mapping from \field{shortplural} to
\field{plural} if the default is inappropriate.
-(In \bibgls\ version 1.0 this entry type was originally called
+(In \bibgls\ version 1.0 this \gls{entrytype} was originally called
\atentry{dualentryabbreviation}. In version 1.1, it was renamed
\atentry{dualabbreviationentry} which makes for a more consistent naming scheme
\code{@dual}\meta{primary}\meta{dual}.)
The required fields are: \field{short}, \field{long} and
-\field{description}. This entry type is designed to emulate the
+\field{description}. This \gls{entrytype} is designed to emulate the
example \gls{newdualentry} command given in the \sty{glossaries}
user manual~\cite{glossaries}. The \gls{primaryentry} is an abbreviation with the given
\field{short} and \field{long} fields (but not the
@@ -5890,7 +6089,7 @@ user manual~\cite{glossaries}. The \gls{primaryentry} is an abbreviation with th
the \field{name} copied from the \field{long} field.
The fallback for the \field{sort} is given by
\csopt{abbreviation-sort-fallback}, which defaults to the
-\field{short} field.
+\field{short} field (see \sectionref{sec:fallbacks}).
For example:
\begin{codeenv}
@@ -5942,7 +6141,7 @@ to override this.
\entrysection{dualentryabbreviation}
-This entry type is deprecated as from \bibgls\ version 1.1. It's functionally
+This \gls{entrytype} is deprecated as from \bibgls\ version 1.1. It's functionally
equivalent to \atentry{dualabbreviationentry} but its name
doesn't fit the general dual entry naming scheme.
@@ -6024,7 +6223,7 @@ could be sorted numerically according to the approximate value:
\entrysection{dualabbreviation}
-The \atentry{dualabbreviation} entry type is similar to
+The \atentry{dualabbreviation} \gls{entrytype} is similar to
\atentry{dualentry}, but by default the
field mappings are:
\begin{itemize}
@@ -6068,7 +6267,7 @@ Note that \bibgls\ doesn't know what abbreviation styles
are in used, so if the \field{sort} field is missing
it will fallback on the \field{short} field. If the abbreviations
need to be sorted according to the \field{long} field instead,
-use \csopt[long]{abbreviation-sort-fallback}.
+use \csopt[long]{abbreviation-sort-fallback} (see \sectionref{sec:fallbacks}).
Terms that are defined using \atentry{dualabbreviation} will be
written to the output file using \gls!{bibglsnewdualabbreviation}.
@@ -6309,11 +6508,11 @@ defaults to \idprefix{tertiary} and can be changed with
\entrysection{tertiaryindexabbreviationentry}
-This entry type is very similar to
+This \gls{entrytype} is very similar to
\atentry{dualindexabbreviation} but creates a \gls{tertiaryentry} as
well. The required fields are: \field{short} and \field{long} (as for
\atentry{dualindexabbreviation}) and also \field{description}. The
-mappings are shared by both entry types. For example:
+mappings are shared by both \glspl{entrytype}. For example:
\begin{codeenv}
\atentry{tertiaryindexabbreviationentry}\marg{html,
\field{short} = \marg{HTML},
@@ -6388,20 +6587,21 @@ and \atentryfmt{book} as though they were both
\end{codeenv}
For convenience, \isty{glossaries-extra-bib2gls} v1.29+
provides \ics{GlsXtrBibTeXEntryAliases} which covers all the
-standard \BibTeX\ entry types. Alternatively, you can use
+standard \BibTeX\ \glspl{entrytype}. Alternatively, you can use
\csopt[bibtexentry]{unknown-entry-alias} to alias all entries
that aren't recognised by \bibgls. If you use
\csopt[same as original entry]{category}, the \field{category}
-field will be set to the original entry type (for example,
+field will be set to the original \gls{entrytype} (for example,
\code{article} or \code{book}). Similarly you can use
\csopt[same as original entry]{type} to set the \field{type}
field (but remember that the glossary types will need to be defined
in the document).
There are no required fields. The fallback for the \field{sort}
-field is given by \csopt{bibtexentry-sort-fallback}. If you want to
-access any of the \BibTeX\ fields, you will need to alias or define
-them. For example:
+field is given by \csopt{bibtexentry-sort-fallback} (see
+\sectionref{sec:fallbacks}). If you want to access any of the
+\BibTeX\ fields, you will need to alias or define them. For
+example:
\begin{codeenv}
\csopt[
\fieldfmt{title}=\field{name}
@@ -6471,7 +6671,7 @@ is followed by:
for each selected \atentry{bibtexentry} associated with that contributor. The
second line provides the internal list field
\field{bibtexentry@entrytype}, where \meta{entry-type} is the
-original entry type (before it was aliased to
+original \gls{entrytype} (before it was aliased to
\atentry{bibtexentry} and converted to \idx!{lowercase}).
For example \code{article} or \code{book}.
@@ -6592,7 +6792,7 @@ takes place. However, if the \field{adoptparents} field isn't found,
\bibgls\ will check for a simple mapping in both the
\csopt{field-aliases} and \csopt{replicate-fields} settings.
-This entry type creates a \glsdisp{mainentry}{main} \igls[textformat=emph]{progenitor}
+This \gls{entrytype} creates a \glsdisp{mainentry}{main} \igls[textformat=emph]{progenitor}
term (with all the given fields except \field{adoptparents})
and $n$ spawned \igls[textformat=emph]{progeny} terms, where
$n$ is the number of elements in the \field{adoptparents} field,
@@ -6755,14 +6955,14 @@ parents.
The following \atentryfmt{spawn\meta{single-type}} commands are all forms
of \atentry{progenitor} that create the given
\atentryfmt{\meta{single-type}} of entry. The \glspl{spawnedentry} are actually
-created with the private entry type \atentryfmt{spawned\meta{type}}. In the
+created with the private \gls{entrytype} \atentryfmt{spawned\meta{type}}. In the
case of \atentry{progenitor}, the \glspl{spawnedentry} are defined as
a \atentryfmt{spawnedindex} entry. These special
-\atentryfmt{spawned\meta{type}} entry types aren't intended for use
-in the \ext{bib} file, but if you reference the entry type (for
+\atentryfmt{spawned\meta{type}} \glspl{entrytype} aren't intended for use
+in the \ext{bib} file, but if you reference the \gls{entrytype} (for
example, with \csopt[same as entry]{category}) you will get
-\atentryfmt{spawned\meta{type}} as the entry type. The
-original entry type for the \glspl{spawnedentry} is the same as
+\atentryfmt{spawned\meta{type}} as the \gls{entrytype}. The
+original \gls{entrytype} for the \glspl{spawnedentry} is the same as
the original entry for the \glsdisp{mainentry}{main} \atentry{progenitor} entry.
There is currently only one form of \dual\ \atentry{progenitor} entry and that's
@@ -6782,7 +6982,7 @@ As \atentry{progenitor}, except that it creates
\atentry{indexplural} terms instead of \atentry{index}.
As with \atentry{indexplural}, if the \field{name} field isn't set,
it's assigned to the same value as the \field{plural} field (or the
-fallback for the \field{plural}, if not defined).
+\hyperref[sec:fallbacks]{fallback} for the \field{plural}, if not defined).
The \glspl{mainentry} are defined in the
\ext{glstex} file with \gls{bibglsnewspawnindexplural} and the
@@ -7069,9 +7269,9 @@ If omitted, the main label is assumed to be the last element.
corresponds to the first optional argument of
\cs{multiglossaryentry}. This field may be omitted.
\end{definition}
-These fields can only be used in this entry type.
+These fields can only be used in this \gls{entrytype}.
-Most resource options don't apply to this entry type. Options
+Most resource options don't apply to this \gls{entrytype}. Options
specific to \glspl{compoundentry} are listed in
\sectionref{sec:compoundentries}.
@@ -7324,6 +7524,635 @@ associated \iext{glstex} file, but the definitions contained within
the \atentry{preamble} are retained by the interpreter for subsequent
\iglspl{resourceset}.
+\section{String Concatenation}
+\label{sec:optstringconcat}
+
+Some resource options allow string \gls{concatenation} in their
+syntax. This is where fragments or substrings can be joined together
+to form a value. This is similar to the way \gls{concatenation}
+occurs in \ext{bib} files, but a different operator is used. In
+\ext{bib} files, the concatenation operator is \idx{stringconcat} (hash)
+but, since this is a problematic character to use in the optional
+argument of \gls{GlsXtrLoadResources}, the operator for string
+\gls{concatenation} in resource options is \idx{concat-plus} (plus).
+
+A string \gls{concatenation} \meta{element-list} in a resource option
+has the following syntax:
+\begin{codeenv}
+\meta{element-list} ::= \meta{element-value} | \meta{element-value} \idx{concat-plus} \meta{element-list}
+\meta{element-value} ::= \meta{string} | \meta{field-ref} | \meta{element-quark}\margm{element-list} | \meta{match-ref}
+\meta{match-ref} ::= \gls{MGP}\margm{group-ref}
+\meta{group-ref} ::= \meta{index} | \meta{name}
+\meta{string} ::= \qtdelim{\meta{tokens}} | \margm{tokens}
+\end{codeenv}
+The \meta{field-ref} syntax is described below, and is used to
+reference a field value.
+The element quarks (\meta{element-quark}, described below) take an
+\meta{element-list} argument. If the \meta{element-list} argument evaluates
+to null, they will return null.
+
+\begin{important}
+Remember that the argument of \gls{GlsXtrLoadResources} is expanded
+as it's written to the \ext{aux} file. This means that care must be
+taken to prevent premature expansion of \idxpl{quark} or any
+commands that need to be present in a string.
+\end{important}
+
+As from \styfmt{glossaries-extra} v1.51, the
+\sty{glossaries-extra-bib2gls} package (which is automatically
+loaded with the \styopt{record} option) provides the command
+\ics{GlsXtrResourceInitEscSequences} which will locally redefine
+these \idx{quark} commands to expand to their detokenized form.
+So you can do:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
+ \ics{GlsXtrResourceInitEscSequences}
+}
+\end{codeenv}
+This means that you can simply write the \idx{quark} in the resource
+option without needing to use \ics{protect} or \idx{cs.string}.
+The remainder of this section assumes that \ics{glsxtrresourceinit}
+has been redefined to use \ics{GlsXtrResourceInitEscSequences}, as
+in the above example.
+
+As with the \ext{bib} format, strings (\meta{string}) can be delimited by braces
+\code{\margm{text}} or double-quotes \code{\qtdelim{\meta{text}}}. If you
+need a literal double-quote (\idx{doublequotechar}) then either use
+brace delimiters or use \gls{quark.doublequote}. If you need the
+actual \LaTeX\ accent command \ics{umlaut} then use brace
+delimiters. If you need braces that start and end in different
+strings then use double-quote delimiters. For example:
+\begin{codeenv}
+\csopt[
+ \field{first} = "\gls{cs}\marg{emph}\idx{bgroupchar}" \idx{concat-plus} \field{name} \idx{concat-plus} "\idx{egroupchar}"
+]{assign-fields}
+\end{codeenv}
+
+The \meta{element-list} may just contain a single element, such as a
+field reference or a constant string, but it must still conform to
+the element syntax. For example, if you want to use
+\csopt{copy-to-glossary} to copy all entries to a specific glossary,
+such as \code{index}, then you will need to markup \code{index} as a
+string. For example:
+\begin{codeenv}
+\csopt[\qtdelim{index}]{copy-to-glossary}
+\end{codeenv}
+or
+\begin{codeenv}
+\csopt[\marg{index}]{copy-to-glossary}
+\end{codeenv}
+Note that the outer braces are stripped by the resource option
+parser before the content is parsed as an \meta{element-list}.
+If only a single set of braces was used, those braces would be
+stripped leaving a bare \code{index}, which would be parsed as a
+field reference.
+
+The element \idxpl{quark} are uppercase tokens that start with a leading
+backslash. They have no meaning to \bibgls's interpreter nor are
+they defined in the \LaTeX\ document outside of the scope of
+the resource command (unless they happen to coincidentally be
+defined by another package or are a custom command). \Idxpl{quark}
+occur outside of strings. Any escape sequences occurring within a
+string are considered to be \LaTeX\ commands.
+
+\nosecdef{CS}
+Returns a control sequence with the control sequence
+name obtained from concatenating \meta{element-list}.
+Note that this is different from
+\gls{cs} which expands to the detokenized control sequence name as
+the resource options are written to the \ext{aux} file.
+
+For example, if the \LaTeX\ file has:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[
+ \field{name} = "\gls{cs}\marg{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}"
+ ]{assign-fields}
+}
+\end{codeenv}
+then this will expand the options to the \ext{aux} file as
+\begin{codeenv}
+\csopt[
+\field{name} = "\csfmt{foo}\marg{" \idx{concat-plus} \field{user1} \idx{concat-plus} "}"
+]{assign-fields}
+\end{codeenv}
+Compare this with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[
+ \field{name} = \gls{CS} \marg{ \field{user1} }
+ ]{assign-fields}
+}
+\end{codeenv}
+which will set the \field{name} value to \csfmt{\meta{csname}} (no
+arguments) where \meta{csname} is the value obtained from the
+\field{user1} field for that entry. Note that \csfmt{\meta{csname}}
+will need to be defined in the document to ensure that the document
+compiles without error but will also need to be recognised by
+\bibgls\ if the field value needs to be interpreted (such as when
+obtaining the \field{sort} value).
+
+\nosecdef{MGP}
+The \meta{match-ref} element should only be used with a
+\gls{regular-expression} from an associated conditional (see
+\sectionref{sec:conditionals}).
+For example, the \meta{condition} part of an assignment rule in
+\csopt{assign-fields}.
+
+If a match was found, \gls{MGP} can be used to reference a group within the match.
+The \meta{group-ref} argument may be either an integer (the group
+index) or the group name. For example, suppose a custom field called
+\fieldfmt{ordinal} may contain content such as \code{1st} or
+\code{10th} and I want to encapsulate the suffix part without
+altering the \ext{bib} file. This can be done as follows:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{ordinal} =\oarg{o} \gls{MGP}\marg{1} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{2} + "}"
+ \oarg{ ordinal=/(\gls{cs}\marg{d}+)(st|nd|rd|th)/ }
+]{assign-fields}
+\end{codeenv}
+Alternatively, using named groups:
+\begin{codeenv*}
+\csopt[
+ ordinal =\oarg{o} \gls{MGP}\marg{num} + " \gls{cs}\marg{ord}\marg{" + \gls{MGP}\marg{suffix} + "}"
+ \oarg{ ordinal=/(\idx{regex.question}\idx{regex.lt}num\idx{regex.gt}\gls{cs}\marg{d}+)(\idx{regex.question}\idx{regex.lt}suffix\idx{regex.gt}st|nd|rd|th)/ }
+]{assign-fields}
+\end{codeenv*}
+Note that the group name shouldn't be delimited with double-quotes.
+
+\begin{important}
+The \gls{MGP} quark (which expands to the \gls{MGP} identifier for
+\csopt{assign-fields}) isn't the same as \ics{glscapturedgroup}
+(which expands to \cs{cs.string}\idx{dollarchar}, allowing a dollar
+character to be written to the \ext{aux} file within
+the replacement part of \csopt{labelify-replace}).
+\end{important}
+
+\nosecdef{TRIM}
+Returns its argument with any leading and trailing spaces removed.
+
+\nosecdef{INTERPRET}
+Interprets the contents of \meta{element-list} using \bibgls's
+interpreter and returns the result, which may be an empty string if
+the content only contains unknown commands.
+
+\nosecdef{LABELIFY}
+Converts the contents of \meta{element-list} into a label string,
+according to the \csopt{labelify} criteria.
+
+\nosecdef{LABELIFYLIST}
+Converts the contents of \meta{element-list} into a label-list string,
+according to the \csopt{labelify-list} criteria.
+
+\nosecdef{LEN}
+When used within an element list, \gls{LEN} returns the length of
+its \meta{element-list} argument as a string or null if \meta{element-list}
+evaluates to null. Note that this is different from using \gls{LEN}
+in a numerical condition where the result is always an integer (see
+\sectionref{sec:conditionals}).
+This means that \code{\gls{LEN}\margm{list1} \idx{concat-plus}
+\gls{LEN}\margm{list2}} performs string \gls{concatenation} not numerical
+addition. Instead, use \code{\gls{LEN}\marg{\meta{list1}
+\idx{concat-plus} \meta{list2}}} for the combined length.
+
+The length is the detokenised length, for example,
+if the \field{name} field has the value \code{\cs{emph}\marg{x}}
+then \code{\gls{LEN}\marg{\field{name}}} will evaluate to the string
+\qtdelim{8}. You can use
+\begin{codeenv}
+\gls{LEN}\marg{\gls{INTERPRET}\margm{element-list}}
+\end{codeenv}
+to find the length without \LaTeX\ commands.
+
+The \idxpl{quark} below identify case-changing functions. The
+\meta{element-list} argument will be converted using the appropriate
+function and the result will be returned. If \meta{element-list}
+evaluates to null then null will be returned.
+
+The case-changing functions will use the \gls{resource-locale}, but
+whether or not \bibgls\ recognises the correct rules for the locale
+depends on whether or not the locale is correctly supported by the
+Java locale provider. The \langxml\ may provide assistance with
+case-conversion (see \sectionref{sec:lang.xml}). Note that the
+case-change is performed by \bibgls\ not by inserting \LaTeX\
+case-changing commands into the code.
+
+\begin{itemize}
+\item \inlinedef{LC} converts \meta{element-list} to \idx{lowercase};
+\item \inlinedef{UC} converts \meta{element-list} to \idx{uppercase};
+\item \inlinedef{FIRSTLC} converts the first letter of
+\meta{element-list} to \idx{lowercase};
+\item \inlinedef{FIRSTUC} converts the first letter of
+\meta{element-list} to \idx{uppercase} (\idx{sentencecase});
+\item \inlinedef{TITLE} converts \meta{element-list} to \idx{titlecase}.
+\end{itemize}
+
+There is an additional token \inlinedef{NOCHANGE} which simply
+evaluates \meta{element-list} and returns it
+unchanged.\footnote{The \gls{NOCHANGE} support wasn't
+intentional, but was simply a by-product of the original
+implementation of the case-changing commands.} This isn't
+like \cs{NoCaseChange} but is more like \cs{@firstofone}. There is
+little need for it so it's not defined by
+\ics{GlsXtrResourceInitEscSequences}. The only plausible use for it
+is if you have a class or package that contains something like:
+\begin{codeenv}
+\csfmt{newcommand}\marg{\csfmt{mycase}}\marg{NOCHANGE}
+\comment{later as the result of some condition:}
+\csfmt{renewcommand}\marg{\csfmt{mycase}}\marg{FIRSTUC}
+\comment{later on:}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[
+ \field{name}=\oarg{o} \gls{cs}\marg{\csfmt{mycase}}\marg{\field{name}},
+\comment{other assignments \ldots}
+ ]{assign-fields}
+}
+\end{codeenv}
+In most cases, it should be possible to achieve the same result with a
+conditional associated with the resource option or by adjusting the
+content passed to the resource command. For example:
+\begin{codeenv}
+\csfmt{newcommand}\marg{\csfmt{nameassign}}\marg{}
+\comment{later as the result of some condition:}
+\csfmt{renewcommand}\marg{\csfmt{nameassign}}\marg{name=\oarg{o}\gls{FIRSTUC}\marg{name},}
+\comment{later on:}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[
+ \csfmt{nameassign}
+\comment{other assignments \ldots}
+ ]{assign-fields}
+}
+\end{codeenv}
+
+The field reference (\meta{field-ref}) syntax is more complicated:
+\begin{codeenv}
+\meta{field-ref} ::= \meta{value-ref} | \meta{entry-ref} \idx{follow} \meta{field-ref}
+\meta{entry-ref} ::= self | parent | root
+\meta{value-ref} ::= \meta{field-name} | \meta{label-ref}
+\meta{label-ref} ::= \meta{label-type} \idx{follow} \meta{label-delineator}
+\meta{label-type} ::= entrytype | entrylabel | entrybib
+\meta{label-delineator} ::= original | actual
+\end{codeenv}
+where \meta{field-name} is the required field name. Note that field
+names (which need to be used in a string \gls{concatenation}) can't include
+any of the \gls{concatenation} or conditional markup special characters:
+\idx{concat-plus} \idx{startoptional} \idx{endoptional}
+\idx{equalsassign} \idx{commasep} \idx{ltcmp} \idx{gtcmp} or
+\idx{doublequotechardelim}.
+
+The \meta{entry-ref} part indicates which entry the referenced field
+belongs to. The keywords are: \code{self} (the entry itself),
+\code{parent} (the entry's \parent), and \code{root} (the entry's
+\glsdisp{hierarchicalglossary}{hierarchical root}, not including the
+entry itself). Note that with options such as
+\csopt{assign-fields} the entry's \glspl{ancestor} must be
+defined before the entry in the \ext{bib} file because their fields
+can only be referenced after they have been processed. A
+grandparent entry can be referenced with \code{parent \idx{follow}
+parent \idx{follow}}. Since \qt{parent} is also a field name, if
+the keyword \code{parent} is followed by \idx{follow} then the
+keyword refers to the \gls{parententry} otherwise it refers to the
+\field{parent} field.
+
+The special keywords identify values that aren't normally stored in
+a field. The keyword must be followed by the \meta{delineator},
+which may be \code{original} or \code{actual}. Available keywords:
+
+\begin{description}
+
+\item[\code{entrytype}] the \gls{entrytype}, without the leading
+\code{@}, where \code{original} refers to the original
+\gls{entrytype} used in the \ext{bib} file and \code{actual} refers
+to the actual \gls{entrytype}, which may have changed as a result of
+\csopt{entry-type-aliases};
+
+\item[\code{entrylabel}] the entry label, where \code{original}
+refers to the original label used in the \ext{bib} file and
+\code{actual} refers to the actual label, which may have been
+altered by options such as \csopt{label-prefix};
+
+\item[\code{entrybib}] the \ext{bib} file the entry was defined in,
+where \code{original} refers to the basename (without the
+\code{.bib} extension, regardless of whether or not it was included
+in \csopt{src}) and \code{actual} refers to the file name
+(including the extension and path).
+
+\end{description}
+
+If a syntax error occurs, the error message will show how \bibgls\
+has scanned the information so far. For example, in the case of
+\code{\csopt[parent \field{name}]{assign-fields}} the message will be:
+\begin{quote}\ttfamily
+Error: Invalid syntax for option '\csopt{assign-fields}': Expected
+one of \idx{follow} \idx{concat-plus} \idx{startoptional} after
+' self \idx{follow} parent', found 'n'
+\end{quote}
+This indicates that it has read \qt{parent} as meaning the
+\field{parent} field of the current entry since it isn't followed by
+\qt{\idx{follow}}.
+
+\section{Complex Conditionals}
+\label{sec:conditionals}
+
+Some options may have a conditional in their value. In certain
+cases, such as \csopt{match}, the condition is provided as a
+\gls{regular-expression}, but other conditionals (such as in
+\csopt{assign-fields}) are complex. This section describes that
+complex conditional syntax.
+
+The tokens \idx{ampand} and \idx{pipeor} indicate logical
+\qt{AND} and \qt{OR}, respectively, and \idx{exclamnot} indicates
+negation. Parentheses \idx{openparenchar} and \idx{closeparenchar}
+may be used to control the order of precedence. For example,
+\begin{codeenv}
+\meta{boolean1} \idx{pipeor} (\meta{boolean2} \idx{ampand} \idx{exclamnot} \meta{boolean3})
+\end{codeenv}
+
+Available boolean functions are in the form:
+\begin{codeenv}
+\meta{value1} \meta{cmp} \meta{value2}
+\end{codeenv}
+where \meta{value1} is the left-hand value and \meta{value2} is the
+right-hand value. The middle \meta{cmp} operator identifies the comparison
+function.
+
+The left-hand \meta{value1} may be a field reference \meta{field-ref} or
+the integer \idx{quark} \code{\gls{LEN}\margm{element-list}} or
+the concatenate \idx{quark} \code{\gls{CAT}\margm{element-list}},
+where \meta{field-ref} references a field value and
+\meta{element-list} is an element list, using the same
+syntax described in \sectionref{sec:optstringconcat}.
+
+The right-hand \meta{value2} may be a field reference
+\meta{field-ref} or \code{\gls{CAT}\margm{element-list}} or
+\gls{NULL} or a constant string (\qtdelim{\meta{string}} or
+\margm{string}) or a number or a \gls{regular-expression}. You can't
+use \gls{LEN} on the right-hand as a numeric value (but it may occur
+inside the argument \gls{CAT}). You can't use \gls{NULL} or a
+\gls{regular-expression} on the left-hand side.
+
+Where \meta{value1} is \code{\gls{LEN}\margm{element-list}}, the length
+evaluates to an integer and may only be used in the numerical
+comparisons. If \meta{element-list} is null, then the length will be~0.
+The \gls{LEN} \idx{quark} can't be used in the right hand
+\meta{value2} part of a numerical comparison. Note that if \gls{LEN}
+occurs inside the argument of \gls{CAT} then it becomes a string not
+a number.
+
+\nosecdef{CAT}
+Where \meta{value1} or \meta{value2} is \code{\gls{CAT}\margm{element-list}}, the
+\meta{element-list} will be evaluated and treated as a string, which
+will be null if \meta{element-list} evaluates to null.
+
+\nosecdef{NULL}
+The null \idx{quark} may only be used as \meta{value2} for the
+equality and inequality comparisons. It can't be used in any other
+context. Note that the numeric \gls{LEN} doesn't return null.
+
+Where a field value is referenced (\meta{field-ref}), if the field
+value is undefined (either the field isn't set or the referenced
+ancestor entry hasn't been defined) then, if the designated action
+is \qt{fallback} (for example,
+\csopt[fallback]{assign-missing-field-action}), the fallback value
+is obtained (see \sectionref{sec:fallbacks}). If the value is still
+undefined it will be considered a null value for the purposes of the
+comparison. Note that if the designated action is \qt{empty} (for
+example, \csopt[empty]{assign-missing-field-action}) there will be
+no null values.
+
+\begin{codeenv*}
+\meta{value1}\idx{equalscmp}\gls{NULL}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is null.
+
+\begin{codeenv*}
+\meta{value1}\idx{notequalscmp}\gls{NULL}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is not null.
+
+For the remaining comparisons, null values will be treated as an
+empty string. Once the \meta{field-ref} or \gls{CAT} references have
+been evaluated, their returned value will be turned into a
+detokenized string for the purposes of the comparison.
+
+The detokenized values from a field reference may contain any TAB or
+newline characters or additional spacing that are present in the
+\ext{bib} file (unless they have already been stripped by other
+resource options or field assignments). However, redundant spacing
+in any literal strings (\qtdelim{\meta{string}} or \code{\margm{string}})
+are likely to be lost when the resource options are written to the
+\ext{aux} file.
+
+\begin{codeenv}
+\meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar}
+\meta{value1}=\idx{slashchar}\meta{regex}\idx{slashchar}i
+\end{codeenv}
+Evaluates to true if the value matches the given \gls{anchored}
+\gls{regular-expression} \meta{regex}. If \qtt{i} follows the terminating
+\idx{slashchar} then the match is case-insensitive. No other modifiers
+are recognised, but you can use embedded flag expressions, such as
+\code{?s} for \qt{single-line} mode.
+
+In the following string comparisons, the right-hand \meta{string} is
+a constant string that must be delimited with double-quotes or braces. The
+comparisons are according to the Unicode code points (not
+locale-sensitive), but if the string is followed by \qtt{i}, a
+case-insensitive comparison is used.
+
+\begin{codeenv*}
+\meta{value1}\idx{equalscmp}\meta{string}
+\meta{value1}\idx{equalscmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is equal to the string.
+For example:
+\begin{codeenv}
+\field{category}\idx{equalscmp}\qtdelim{abbreviation}
+\end{codeenv}
+
+\begin{codeenv*}
+\meta{value1}\idx{notequalscmp}\meta{string}
+\meta{value1}\idx{notequalscmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is not equal to the string.
+
+\begin{codeenv*}
+\meta{value1}\idx{ltcmp}\meta{string}
+\meta{value1}\idx{ltcmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is lexicographically less than the string.
+
+\begin{codeenv*}
+\meta{value1}\idx{lecmp}\meta{string}
+\meta{value1}\idx{lecmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is lexicographically less than or
+equal to the string.
+
+\begin{codeenv*}
+\meta{value1}\idx{gtcmp}\meta{string}
+\meta{value1}\idx{gtcmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is lexicographically greater than the string.
+
+\begin{codeenv*}
+\meta{value1}\idx{gecmp}\meta{string}
+\meta{value1}\idx{gecmp}\meta{string}i
+\end{codeenv*}
+Evaluates to true if the value is lexicographically greater than or
+equal to the string.
+
+In the following numerical comparisons, the given \meta{number}
+should use \qtt{.} for the decimal point and no number group
+separators. If the \meta{number} doesn't contain a decimal point or
+if \meta{value1} is the \code{\gls{LEN}\margm{element-list}} quark
+then an integer comparison is assumed. If \meta{value1} is
+empty or isn't numeric it will be treated as 0. The number
+shouldn't be delimited by quotes or braces.
+
+\begin{codeenv*}
+\meta{value1}\idx{equalscmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is equal to \meta{number}.
+For example:
+\begin{codeenv}
+\gls{LEN}\marg{\field{user1}}\idx{equalscmp}0.9
+\end{codeenv}
+This will return true if the \field{user1} field length is 0 and
+false otherwise. This is because \gls{LEN} enforces an integer
+comparison which means that 0.9 is converted to 0.
+Similarly:
+\begin{codeenv}
+\gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0
+\end{codeenv}
+This will return true because the \meta{number} 0 is an integer
+which enforces an integer comparison so the string \qtdelim{0.9}
+will be converted to the number~0.
+Compare this with:
+\begin{codeenv}
+\gls{CAT}\marg{\qtdelim{0.9}}\idx{equalscmp}0.0
+\end{codeenv}
+This will return false because the \meta{number} 0.0 is a decimal,
+so a decimal comparison will be used.
+
+\begin{codeenv*}
+\meta{value1}\idx{notequalscmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is not equal to \meta{number}.
+
+\begin{codeenv*}
+\meta{value1}\idx{ltcmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is less than \meta{number}.
+
+\begin{codeenv*}
+\meta{value1}\idx{lecmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is less than or equal to \meta{number}.
+
+\begin{codeenv*}
+\meta{value1}\idx{gtcmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is greater than \meta{number}.
+
+\begin{codeenv*}
+\meta{value1}\idx{gecmp}\meta{number}
+\end{codeenv*}
+Evaluates to true if the value is greater than or equal to \meta{number}.
+
+Finally, the following are string comparisons made after
+evaluating and detokenizing both \meta{value1} and \meta{value2}. The
+comparisons are case-sensitive and according to the Unicode code
+points (not locale-sensitive).
+
+\begin{codeenv*}
+\meta{value1}\idx{equalscmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is equal to \meta{value2}.
+For example:
+\begin{codeenv}
+\field{name} \idx{equalscmp} parent \idx{follow} \field{name}
+\end{codeenv}
+
+\begin{codeenv*}
+\meta{value1}\idx{notequalscmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is not equal to \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1}\idx{ltcmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is lexicographically less than
+\meta{value2}.
+
+\begin{codeenv*}
+\meta{value1}\idx{lecmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is lexicographically less than or
+equal to \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1}\idx{gtcmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is lexicographically greater than
+\meta{value2}.
+
+\begin{codeenv*}
+\meta{value1}\idx{gecmp}\meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value} is lexicographically greater than or
+equal to \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{IN} \meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is a substring of \meta{value2}.
+If \meta{value1} is empty or null it's considered
+not a substring regardless of the value of \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{NIN} \meta{value2}
+\end{codeenv*}
+The negation of the \gls{IN} test. Evaluates to true if \meta{value1} is
+not a substring of \meta{value2}. This is equivalent to:
+\begin{codeenv}
+\idx{exclamnot} \meta{value1} \gls{IN} \meta{value2}
+\end{codeenv}
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{PREFIXOF} \meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is a prefix of \meta{value2}
+(that is, \meta{value2} starts with \meta{value1}).
+If \meta{value1} is empty or null it's considered
+not a prefix regardless of \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{NOTPREFIXOF} \meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is not a prefix of \meta{value2}.
+This is equivalent to:
+\begin{codeenv}
+\idx{exclamnot} \meta{value1} \gls{PREFIXOF} \meta{value2}
+\end{codeenv}
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{SUFFIXOF} \meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is a suffix of \meta{value2}
+(that is, \meta{value2} ends with \meta{value1}).
+If \meta{value1} is empty or null it's considered
+not a suffix regardless of \meta{value2}.
+
+\begin{codeenv*}
+\meta{value1} \inlinedef{NOTSUFFIXOF} \meta{value2}
+\end{codeenv*}
+Evaluates to true if \meta{value1} is not a suffix of \meta{value2}.
+This is equivalent to:
+\begin{codeenv}
+\idx{exclamnot} \meta{value1} \gls{SUFFIXOF} \meta{value2}
+\end{codeenv}
+
+
\section{General Options}
\label{sec:generalopts}
@@ -7342,6 +8171,14 @@ a \ext{bib} managing systems, such as JabRef.
See \longarg{tex-encoding} for the \gls{encoding} used to write the \ext{glstex}
file.
+\optsection{locale}
+
+Sets the default \glsdisp{resource-locale}{locale} for the current
+\gls{resourceset}. In general, it's best to set this at the start of
+the resource option list, if required. If not set, the default
+will be the \gls{document-locale}, if supplied, otherwise the
+\gls{Java-locale} will be used.
+
\optsection{interpret-preamble}
This is a boolean option that determines whether or not the
@@ -7500,7 +8337,7 @@ one mapping. For example:
This option isn't cumulative. Multiple instances of
\csopt{entry-type-aliases} override previous instances.
If \meta{\keyvallist} is empty there will be no mappings.
-You can save the original entry type in the
+You can save the original \gls{entrytype} in the
\field{originalentrytype} field with
\csopt{save-original-entrytype}.
@@ -7548,9 +8385,9 @@ treats the entry as though it had been defined as:
\optsection{unknown-entry-alias}
If this option is set, the \meta{value} is used as the alias for any
-unknown entry types (after any aliases provided with
+unknown \glspl{entrytype} (after any aliases provided with
\csopt{entry-type-aliases} have been applied). If the value is
-missing or empty, unknown entry types will be ignored with a
+missing or empty, unknown \glspl{entrytype} will be ignored with a
warning.
\optsection{action}
@@ -7674,10 +8511,124 @@ This just does:
\begin{codeenv}
\cmd{begingroup}
\cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{}
- \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[indexgroup]{style}}
+ \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},
+ \printglossopt[indexgroup]{style}}
\cmd{endgroup}
\end{codeenv}
+\optsection{copy-to-glossary}
+
+This option can selectively copy an entry to a glossary after it has
+been defined. If the supplied value \meta{list} is empty, no copying is
+performed (except as a result of other options, such as
+\csopt{action} or \csopt{secondary}). If set, the \meta{list}
+argument is a list of string \glspl{concatenation} with optional
+conditionals. Take care that constant strings are correctly
+delimited, as described below, to ensure that they are not mistaken
+for field labels.
+
+The evaluation of the target glossary label for each entry is
+performed while the \ext{glstex} file is being written (after
+sorting) so all field values should be available in any field reference.
+The \csopt{action} option is implemented first, so the
+selected entry will first either be defined or copied according to
+\csopt{action}. If the \csopt{copy-to-glossary} instruction is
+successful, the entry will then be copied to the target glossary using
+\gls{bibglscopytoglossary}.
+
+The \csopt{copy-to-glossary} value should be a comma-separated list,
+where the syntax for each item in the list is in the form:
+\begin{codeenv}
+\meta{element-list} \oargm{condition}
+\end{codeenv}
+where \meta{element-list} is a string \gls{concatenation} (see
+\sectionref{sec:optstringconcat}) and \meta{condition} is a complex
+conditional (see \sectionref{sec:conditionals}). For each
+\meta{element-list} \oargm{condition} specification, if the
+condition evaluates to false or if the \meta{element-list} evaluates
+to null then the copy instruction won't be added.
+The fallback action for a missing field value is governed by the
+\csopt{copy-to-glossary-missing-field-action} setting. The result of
+the string concatenation (if not null) is the label of the target
+glossary.
+
+You can have multiple copy instructions to copy an entry to multiple
+glossaries. The definition of \gls{bibglscopytoglossary} will ensure
+that an entry will only be copied to the designated glossary if it
+isn't already in the glossary's internal list and will silently do
+nothing if the glossary doesn't exist.
+
+Remember that constant strings need to be marked with braces or
+double-quote delimiters. For example, if you want to copy \emph{all}
+entries to the \code{index} glossary then either do:
+\begin{codeenv}
+\csopt[\qtdelim{index}]{copy-to-glossary}
+\end{codeenv}
+or
+\begin{codeenv}
+\csopt[\marg{index}]{copy-to-glossary}
+\end{codeenv}
+Note that the outer braces are stripped by the resource option
+parser, which first splits the \code{\meta{option}\dequals\margm{value}} list supplied via
+\gls{GlsXtrLoadResources} into \meta{option} and \meta{value} pairs, and then
+parses each \meta{option}. So by the time that the
+\csopt{copy-to-glossary} option has its value parsed, the value has
+become \code{\qtdelim{index}} or \code{\marg{index}}, respectively,
+in the above two examples.
+
+Remember that the \meta{value} itself may be a comma-separated list.
+The outer grouping hides the inner list comma from the initial
+\code{\meta{option}\dequals\margm{value}} split. For example, to copy all entries
+to the \code{index} and \code{symbols} glossaries:
+\begin{codeenv}
+\csopt[\qtdelim{index}, \qtdelim{symbols}]{copy-to-glossary}
+\end{codeenv}
+or
+\begin{codeenv}
+\csopt[\marg{index}, \marg{symbols}]{copy-to-glossary}
+\end{codeenv}
+
+The following example will only copy entries to the \code{index}
+glossary if their actual entry type is \code{index}:
+\begin{codeenv}
+\csopt[\qtdelim{index} \oarg{ entrytype \idx{follow} actual \idx{equalscmp} \qtdelim{index} }]{copy-to-glossary}
+\end{codeenv}
+Alternatively, to copy aliased custom entry types
+\atentryfmt{person} entries to a custom glossary \code{person} and
+\atentryfmt{place} to a custom glossary \code{place}:
+\begin{codeenv}
+\csopt[
+ entrytype \idx{follow} original
+ \oarg{ entrytype \idx{follow} original =\idx{slashchar}person\idx{regexpor}place\idx{slashchar} }
+]{copy-to-glossary}
+\end{codeenv}
+
+If the glossary types don't conveniently match the entry type,
+the instructions can be split into a list.
+For example:
+\begin{codeenv}
+\csopt[
+ \qtdelim{abbreviations} \oarg{ entrytype \idx{follow} actual = \qtdelim{abbreviation} },
+ \qtdelim{symbols} \oarg{ entrytype \idx{follow} actual = \qtdelim{symbol} },
+ \qtdelim{numbers} \oarg{ entrytype \idx{follow} actual = \qtdelim{number} },
+]{copy-to-glossary}
+\end{codeenv}
+Each instruction in the list will be tried and the copy instruction
+will only be written if the condition evaluates to true and a
+non-null value is successfully returned.
+
+\optsection{copy-to-glossary-missing-field-action}
+
+This option indicates what to do if a source field identified in
+\csopt{copy-to-glossary} is missing. The value may be one of:
+\begin{itemize}
+\item \optfmt{skip}: return null;
+\item \optfmt{fallback}: use the fallback for the missing field
+(see \sectionref{sec:fallbacks}), if
+one is available, otherwise return null (default);
+\item \optfmt{empty}: treat the missing value as empty.
+\end{itemize}
+Returning null will result in the copy instruction being omitted.
\section{Selection Options}
\label{sec:selectionopts}
@@ -7722,12 +8673,14 @@ the \csopt{src} option.
\end{codeenv}
will assume \csopt[\ics{jobname}]{src}. Remember that subsequent uses
of \gls{GlsXtrLoadResources} append a suffix, so in general it's
-best to always supply \csopt{src}.
-
-If you have non-ASCII characters in the \ext{bib} filename but
-aren't using \XeLaTeX\ or \LuaLaTeX, then you will need to use
-\ics{detokenize} to prevent expansion when the information is
-written to the \ext{aux} file. Similarly for any special characters
+best to always supply \csopt{src}, except for small test cases with
+a single \gls{resourcecommand}.
+
+With old \LaTeX\ kernels, if you have non-ASCII characters in the
+\ext{bib} filename but aren't using \XeLaTeX\ or \LuaLaTeX, then you
+will need to use \ics{detokenize} to prevent expansion when the
+information is written to the \ext{aux} file. Newer \LaTeX\ kernels
+have better support for UTF-8. Similarly for any special characters
that need protecting (although it's better not to use special
characters in filenames). For example:
\begin{codeenv}
@@ -7925,16 +8878,16 @@ The value is required for this key but may be empty, which indicates
that the setting is switched off, otherwise
\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where
\meta{key} is the name of a field or \optfmt{id} for the entry's
-label or \optfmt{entrytype} for the \bibgls\ entry type (as in
+label or \optfmt{entrytype} for the \bibgls\ \gls{entrytype} (as in
the part after \verb|@| identifying the entry not the \field{type}
field identifying the glossary label). If you've used
-\csopt{entry-type-aliases}, this refers to the target entry type not
-the original entry type specified in the \ext{bib} file.
+\csopt{entry-type-aliases}, this refers to the target \gls{entrytype} not
+the original \gls{entrytype} specified in the \ext{bib} file.
-The \meta{regex} part should be a \idx{regex} conforming
+The \meta{regexp} part should be a \gls{regular-expression} conforming
to
\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
-Pattern class}~\cite{pattern}. The pattern is anchored
+Pattern class}~\cite{pattern}. The pattern is \gls{anchored}
(\code{oo}\idx{matchanydot}\idx{zeroormore} matches
\code{oops} but not \code{loops}) and \meta{regexp} can't be
empty. Remember that \TeX\ will expand the option list as
@@ -8530,19 +9483,27 @@ This defaults to just \meta{name}.
This option governs the rule used by \csopt{flatten-lonely} to
determine which \glspl{sub-entry} (that have no \glspl{sibling}) to adjust and
-which \glsdisp{parententry}{parents} to remove. The value may be one of the following:
+which \glsdisp{parententry}{parents} to remove. The value may be one
+of the following, where \meta{condition} is the condition provided
+by \csopt{flatten-lonely-condition}:
\begin{description}
\item[\optfmt{only unrecorded parents}] Only the \glspl{sub-entry}
-that have a \parent\ without a \igls{locationlist} will be altered.
-The \gls{parententry} will be removed from the selection.
+that have a \parent\ without a \igls{locationlist} (and have
+\meta{condition} evaluate to true) will be altered.
+The \gls{parententry} will be removed from the selection
+if the child entry is adjusted.
This value is the default setting.
+
\item[\optfmt{discard unrecorded}] This setting will adjust all
-\glspl{sub-entry} that have no \glspl{sibling} regardless of whether or not the
+\glspl{sub-entry} that have no \glspl{sibling} (and have
+\meta{condition} evaluate to true) regardless of whether or not the
\parent\ has a \igls{locationlist}.
Only the \glspl{parententry} that don't have a \gls{locationlist} will be
-removed from the selection.
+removed from the selection if the child entry is adjusted.
+
\item[\optfmt{no discard}] This setting will adjust all
-\glspl{sub-entry} that don't have \glspl{sibling} regardless of whether or not the
+\glspl{sub-entry} that don't have \glspl{sibling} (and have
+\meta{condition} evaluate to true) regardless of whether or not the
\parent\ has a \igls{locationlist}. No entries will be discarded, so
\glspl{parententry} that don't have a \igls{locationlist} will still appear in the
glossary.
@@ -8551,6 +9512,45 @@ In the above, the \igls{locationlist} includes \glspl{record} and
cross-references obtained from the \field{see} or \field{seealso}
fields. See \csopt{flatten-lonely} for further details.
+\optsection{flatten-lonely-condition}
+
+The value may either be empty, to indicate true (the default), or a
+complex condition using syntax described in
+\sectionref{sec:conditionals}. After taking into account
+\csopt{flatten-lonely} and \csopt{flatten-lonely-rule}, this option
+determines whether or not the child entry will be adjusted. If the
+condition evaluates to false, the child entry won't be adjusted.
+
+For example, if both the parent entry and the child entry have long
+names, it may be better to keep their hierarchy. The following
+will only flatten lonely entries where both the child name and the
+parent name have less then 25 characters:
+\begin{codeenv*}
+ \csopt[postsort]{flatten-lonely},
+ \csopt[\gls{LEN}\marg{parent \idx{follow} \field{name}} \idx{ltcmp} 25 \idx{ampand} \gls{LEN}\marg{\field{name}} \idx{ltcmp} 25]{flatten-lonely-condition}
+\end{codeenv*}
+Alternatively, for a combined length of less than 50 characters:
+\begin{codeenv*}
+ \csopt[postsort]{flatten-lonely},
+ \csopt[\gls{LEN}\marg{parent \idx{follow} \field{name} \idx{concat-plus} \field{name}} \idx{ltcmp} 50]{flatten-lonely-condition}
+\end{codeenv*}
+This doesn't include the number of characters taken up by the
+separator but the maximum value can be adjusted to allow for that,
+given a constant string separator.
+
+\optsection{flatten-lonely-missing-field-action}
+
+This option indicates what to do if a source field identified in
+\csopt{flatten-lonely-condition} is missing. The value may be one of:
+\begin{itemize}
+\item \optfmt{skip}: return null;
+\item \optfmt{fallback}: use the fallback for the missing field
+(see \sectionref{sec:fallbacks}), if
+one is available, otherwise return null (default);
+\item \optfmt{empty}: treat the missing value as empty.
+\end{itemize}
+Returning null will result in the flatten lonely instruction being omitted.
+
\optsection{strip-missing-parents}
The \sty{glossaries} package requires that all \glspl{childentry} must be
@@ -9079,9 +10079,15 @@ remove the unwanted characters. (Remember that \isty{babel} can make
some of these punctuation characters active, in which case they need
to be stripped.)
-\item If \bibgls\ hasn't detected \sty{fontspec} in the document's
-transcript file, the value is then decomposed and all non-ASCII
-characters are removed.
+\item If \bibgls\ doesn't allow non-ASCII characters in labels, the
+value is then decomposed and all non-ASCII characters are removed.
+UTF-8 support is automatic if \bibgls\ detects \sty{fontspec} in the document's
+transcript file, otherwise UTF-8 in labels will only be supported if
+\bibgls\ detects that the versions of \sty{glossaries} and \sty{glossaries-extra}
+are new enough to support it.
+To ensure better support for UTF-8 with \pdfLaTeX, make sure you
+have a recent \TeX\ distribution and up-to-date versions of
+\sty{glossaries} and \sty{glossaries-extra}.
\end{enumerate}
For example, suppose the \ext{bib} file contains:
@@ -9101,13 +10107,13 @@ will convert the \field{name} field into:
\begin{verbatim}
Angstrom stergaard d'Arcy and Fotheringay-Smythe
\end{verbatim}
-if the document hasn't used \sty{fontspec} otherwise it will be:
+if \bibgls\ doesn't support non-ASCII characters in labels otherwise it will be:
\begin{verbatim}
Ångström Østergaard d'Arcy and Fotheringay-Smythe
\end{verbatim}
Note that \O\ is considered an unmodified letter and so can't
be decomposed into a basic Latin letter with a combining diacritic.
-It's therefore removed completely from the non-\sty{fontspec}
+It's therefore removed completely from the ASCII label
version. Whereas \AA\ can be decomposed into \qt{A} followed by the
\qt{combining ring above} character and \"o can be decomposed into \qt{o}
followed by the \qt{combining diaresis} character. You can use
@@ -9146,13 +10152,13 @@ or:
\begin{verbatim}
Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe
\end{verbatim}
-depending on whether or not \sty{fontspec} was detected.
+depending on whether or not UTF-8 labels are supported.
\optsection[\subsubsection]{labelify-replace}
This option takes a comma-separated list as a value with each
element in the list in the form \code{\margm{regex}\margm{replacement}}
-where \meta{regex} is a \idx{regex} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
+where \meta{regex} is a \gls{regular-expression} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
Pattern class}~\cite{pattern}) and \meta{replacement}
is the replacement text. The value is required for this key but
may be empty, which indicates that the
@@ -9180,6 +10186,14 @@ characters are automatically stripped), but
\csopt{labelify-replace}, and it may be needed
for that.
+\begin{important}
+You can't use the \gls{MGP} quark (which expands to the \gls{MGP}
+identifier in a string \gls{concatenation}) to identify the captured group in this
+context, as the replacement text needs to use the correct
+\gls{regular-expression} syntax.
+\end{important}
+
+
Both \csopt{labelify} and \csopt{labelify-list} use the
\csopt{labelify-replace} setting to
perform substitutions. For example, to replace the sub-string \qt{ and }
@@ -9200,7 +10214,7 @@ or:
\begin{verbatim}
Ångström, Østergaard, d'Arcy,Fotheringay-Smythe
\end{verbatim}
-depending on whether or not \sty{fontspec} was detected.
+depending on whether or not UTF-8 labels are supported.
Note that this produces the same result regardless of whether or not
the Oxford comma is present as \verb*|, and | would first be
@@ -9230,7 +10244,7 @@ or:
\begin{verbatim}
Ångström,Ostergaard,dArcy,FotheringaySmythe
\end{verbatim}
-depending on whether or not \sty{fontspec} was detected.
+depending on whether or not UTF-8 labels are supported.
\optsection[\subsubsection]{label-prefix}
@@ -9756,14 +10770,14 @@ The \meta{value} may be:
\begin{itemize}
\item \optfmt{false}: switch off this setting (default);
\item \optfmt{same as entry}: set the
-\field{category} to the \ext{bib} entry type used to define it
+\field{category} to the \ext{bib} \gls{entrytype} used to define it
(\idx!{lowercase} and without the initial \code{@}) after any aliasing,
if applicable;
\item \optfmt{same as original entry}: (new to v1.4) set the \field{category}
-to the original entry type (\idx!{lowercase} and without
+to the original \gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased);
+\optfmt{same as entry} if the \gls{entrytype} wasn't aliased);
\item \optfmt{same as base}: (new to v1.1) set the \field{category}
to the base name of the \ext{bib} file (without the extension)
@@ -9780,14 +10794,14 @@ This will override any
\field{category} fields supplied in the \ext{bib} file.
When used with \csopt{entry-type-aliases}, the option \csopt[same as
-entry]{category} refers to the \emph{target} entry type whereas
+entry]{category} refers to the \emph{target} \gls{entrytype} whereas
\csopt[same as original entry]{category} refers to the
-\emph{original} entry type given in the \ext{bib} file. In both
+\emph{original} \gls{entrytype} given in the \ext{bib} file. In both
cases, the value is converted to \idx!{lowercase} to ensure consistency.
An alternative is to use \csopt[category]{save-original-entrytype}.
When combined with \csopt[changed]{save-original-entrytype-action}
it's then possible to only set the \field{category} to the original
-entry type for aliased entries and leave it unmodified for unaliased
+\gls{entrytype} for aliased entries and leave it unmodified for unaliased
entries.
For example, if the \ext{bib} file contains:
@@ -9849,12 +10863,12 @@ The \meta{value} may be one of:
\item \optfmt{false}: switches off this setting (default);
\item \optfmt{same as entry}: set the \field{type} field
- to the entry type (\idx!{lowercase} and without the initial \code{@});
+ to the \gls{entrytype} (\idx!{lowercase} and without the initial \code{@});
\item \optfmt{same as original entry}: set the \field{type}
- to the original entry type (\idx!{lowercase} and without
+ to the original \gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
- \optfmt{same as entry} if the entry type wasn't aliased);
+ \optfmt{same as entry} if the \gls{entrytype} wasn't aliased);
\optfmt{same as base}: set the \field{type} field
to the base name of the corresponding \ext{bib} file
@@ -9877,13 +10891,13 @@ which may be inappropriate.
identified by \meta{label}.
\end{itemize}
When used with \csopt{entry-type-aliases}, the option \csopt[same as
-entry]{type} refers to the \emph{target} entry type and \csopt[same
-as original entry]{type} refers to the \emph{original} entry type
+entry]{type} refers to the \emph{target} \gls{entrytype} and \csopt[same
+as original entry]{type} refers to the \emph{original} \gls{entrytype}
given in the \ext{bib} file.
An alternative is to use \csopt[type]{save-original-entrytype}.
When combined with \csopt[changed]{save-original-entrytype-action}
it's then possible to only set the \field{type} to the original
-entry type for aliased entries and leave it unmodified for unaliased
+\gls{entrytype} for aliased entries and leave it unmodified for unaliased
entries.
\begin{important}
@@ -9962,19 +10976,6 @@ value of the \field{adoptparents} list by the \gls{progeny}
entries spawned by the \atentry{progenitor} type of entry.
The default is \field{parent}.
-\optsection[\subsubsection]{abbreviation-name-fallback}
-
-The entry types that define abbreviations (such as
-\atentry{abbreviation} and \atentry{acronym}) will, by default,
-fallback on the \field{short} field if the \field{name} field is
-missing and it's required for some reason (for example, with
-\csopt[name]{sort-field}). If you prefer to
-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 (not an internal field)
-but can't be the \field{sort} field.
-
\optsection[\subsubsection]{ignore-fields}
The \csopt{ignore-fields} key indicates that you want \bibgls\ to
@@ -10023,7 +11024,7 @@ mappings and trails aren't permitted. (That is, \meta{field1}
and \meta{field2} can't be the same nor can you have both
\meta{field1}\dequals\meta{field2} and
\meta{field2}\dequals\meta{field3}.) If you want to swap
-fields you need to use one of the dual entry types instead.
+fields you need to use one of the dual \glspl{entrytype} instead.
Field aliases are performed before \csopt{ignore-fields},
so if \meta{field1} is listed in \csopt{ignore-fields} it won't
be ignored (unless \meta{field2} is in \csopt{ignore-fields}).
@@ -10053,9 +11054,22 @@ keys:
\optsection[\subsubsection]{replicate-fields}
+\begin{important}
+Note the difference in syntax between \csopt{replicate-fields} and
+\csopt{assign-fields}. Both have a \keyvallist\ as the option
+argument, but the \keyval\ syntax is different. In the case of
+\csopt{replicate-fields}, the left hand side (\meta{key}) is the
+\emph{source} field. The right hand side (\meta{value}) is a
+comma-separated list of \emph{destination} fields. The value of the
+source field will be copied into each of the destination fields.
+In the case of \csopt{assign-fields}, the left hand side
+(\meta{key}) is the \emph{destination} field and the right hand side
+\emph{value} is an assignment expression with an optional
+conditional.
+\end{important}
+
The value of one field can be copied to other fields using
-this option where each \meta{key}\dequals\meta{value} pair
-is in the form
+this option where each \keyval\ pair is in the form
\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}}
where all values are field names. The value is required for this key
but may be empty, which indicates that the setting is switched off.
@@ -10161,11 +11175,340 @@ This option indicates what to do if a source field identified in
\begin{itemize}
\item \optfmt{skip}: skip the replication of the missing field
(default);
-\item \optfmt{fallback}: use the fallback for the missing field, if
+\item \optfmt{fallback}: use the fallback for the missing field
+(see \sectionref{sec:fallbacks}), if
one is available (otherwise skip);
\item \optfmt{empty}: make the target field empty.
\end{itemize}
+\optsection[\subsubsection]{assign-fields}
+
+\begin{important}
+Note the difference in syntax between \csopt{replicate-fields} and
+\csopt{assign-fields}, as highlighted in the
+\csopt{replicate-fields} section, above. The \csopt{assign-fields}
+option is implemented after the \csopt{replicate-fields} option (see
+\sectionref{sec:resourcesets}).
+\end{important}
+
+The \csopt{assign-fields} option is a more complicated way of setting a
+field than \csopt{replicate-fields}. Each \keyval\ element of the
+\keyvallist\ argument has the syntax:
+\begin{codeenv}
+\meta{dest-field} \dequals\oargm{override} \meta{element-list} \oargm{condition}
+\end{codeenv}
+If the destination field (\meta{dest-field}) is already set, it will
+only be overwritten if \csopt[true]{assign-override} or if
+\oarg{override} is \qtt{o}. The \meta{dest-field} is simply the name
+of the field for the entry under consideration and doesn't use the
+more complex \meta{field-ref} syntax used in \meta{element-list},
+which is described in \sectionref{sec:optstringconcat}.
+
+The \oargm{override} following the equal sign is optional and may be
+used to counteract the \csopt{assign-override} setting for the given
+assignment. The \meta{override} value may be either \qtt{o}
+(override) or \qtt{n} (no override). If not present, the
+\csopt{assign-override} setting will be used.
+
+The \meta{element-list} is a string \gls{concatenation}, as
+described in \sectionref{sec:optstringconcat}. If any individual
+element in the list evaluates to null, the entire string is deemed
+to be null, in which case the assignment won't be made.
+
+The \oargm{condition} part is optional. If present, the assignment
+is only made if the condition evaluates to true. The condition
+should be placed in square brackets after the \meta{element-list}
+part. This is a complex conditional, as described in
+\sectionref{sec:conditionals}.
+
+Note that, unlike most \keyval\ options, the value part
+(\meta{element-list} \oargm{condition}) should not be grouped. The
+\csopt{assign-fields} option is parsed in a different way to the
+other \keyvallist\ options. However, it's best to group the \emph{entire}
+\meta{value} argument of \csopt{assign-fields}. For example:
+\begin{codeenv}
+\csopt[
+\field{name} \idx{equalsassign} \field{text} \idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol}
+]{assign-fields}
+\end{codeenv}
+Don't do \code{\field{name} \idx{equalsassign} \marg{\field{text}
+\idx{concat-plus} \qtdelim{, } \idx{concat-plus} \field{symbol}}}.
+
+\begin{important}
+Remember that field values may be altered before or after
+\csopt{assign-fields} by other resource options (see
+\sectionref{sec:resourcesets}). The assignment will use the value
+current at the time it is referenced during the processing of
+\csopt{assign-fields}. If you need to reference the destination
+field in the assignment, make sure that the override setting is on
+if the field needs to be updated.
+\end{important}
+
+For example, suppose I have defined the custom fields
+\fieldfmt{surname} and \fieldfmt{forename}, and I have the following
+in my \ext{bib} file:
+\begin{codeenv}
+\atentry{index}\marg{Smith}
+\atentry{index}\marg{Jane-Smith,
+ \fieldfmt{forename}=\marg{Jane},
+ \field{parent}=\marg{Smith}
+}
+\end{codeenv}
+Suppose that what I actually want is:
+\begin{codeenv}
+\atentry{index}\marg{Smith}
+\atentry{index}\marg{Jane-Smith,
+ \fieldfmt{forename}=\marg{Jane},
+ \fieldfmt{surname}=\marg{Smith},
+ \field{parent}=\marg{Smith},
+ \field{name}=\marg{Jane},
+ \field{text}=\marg{Jane Smith}
+}
+\end{codeenv}
+This is quite repetitive to type out for every person you need to
+index. The \csopt{replicate-fields} option can reduce some of this.
+For example:
+\begin{codeenv}
+\csopt{replicate-fields}=\marg{
+ \fieldfmt{forename}=\marg{name},
+ \fieldfmt{surname}=\marg{parent}
+}
+\end{codeenv}
+This doesn't deal with the \field{text} field and also has a problem
+if the \field{parent} field (which should contain a label) doesn't
+match the surname. For example, I might also have:
+\begin{codeenv}
+\atentry{index}\marg{de-la-Fontaine,
+ \field{name}=\marg{de la Fontaine}
+}
+\atentry{index}\marg{Margaret-de-la-Fontaine,
+ \fieldfmt{forename}=\marg{Margaret},
+ \field{parent}=\marg{de-la-Fontaine}
+}
+\end{codeenv}
+In this case the custom \fieldfmt{surname} field needs to match the
+parent's \field{name} field, not the parent's label.
+
+The desired result can instead be obtained with:
+\begin{codeenv}
+\csopt{assign-fields}=\marg{
+ \fieldfmt{surname} = parent \idx{follow} \field{name},
+ \field{name} = self \idx{follow} \fieldfmt{forename},
+ \field{text} = self \idx{follow} \fieldfmt{forename}
+ \idx{concat-plus} \qtdelim{ } \idx{concat-plus} self \idx{follow} \fieldfmt{surname}
+}
+\end{codeenv}
+The \code{self \idx{follow}} part is optional so this can be written
+more compactly as:
+\begin{codeenv}
+\csopt{assign-fields}=\marg{
+ \fieldfmt{surname} = parent \idx{follow} \field{name},
+ \field{name} = \fieldfmt{forename},
+ \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
+}
+\end{codeenv}
+The last assignment in the above can also be written as:
+\begin{codeenv}
+\field{text} = \fieldfmt{forename} \idx{concat-plus} \marg{ } \idx{concat-plus} \fieldfmt{surname}
+\end{codeenv}
+Suppose, for some reason, I want the first use to show the surname
+in bold. This means I need to add
+\code{\cs{textbf}\idx{bgroupchar}} before the value of the
+surname field and the closing \idx{egroupchar} needs to go after.
+This can be achieved with:
+\begin{codeenv}
+\field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ \cs{textbf}\idx{bgroupchar}} \idx{concat-plus} \fieldfmt{surname} \qtdelim{\idx{egroupchar}}
+\end{codeenv}
+Note that because there are unbalanced braces in the string
+fragments, it's necessary to use quote delimiters. Since \cs{textbf}
+is robust, there's no need to protect it from expansion.
+
+Suppose, instead, I want the surname in \idx{uppercase} on first
+use. I could simply replace \cs{textbf} with \cs{MakeUppercase}, but
+I can get \bibgls\ to do the case-conversion instead:
+\begin{codeenv}
+\field{first} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \gls{UC}\marg{ \fieldfmt{surname} }
+\end{codeenv}
+This assumes that \ics{GlsXtrResourceInitEscSequences} has been
+added to the definition of \cs{glsxtrresourceinit}, as described in
+\sectionref{sec:quarks}. Otherwise you would need to protect \gls{UC}.
+
+In the above example, the \fieldfmt{surname} field is obtained from
+the value of the parent's \field{name} according to the assignment:
+\begin{codeenv}
+\fieldfmt{surname} = parent \idx{follow} \field{name},
+\end{codeenv}
+In the case of the Smith entry, the \field{name} field hasn't been
+set.
+
+If a referenced field hasn't been set then the behaviour depends on
+the \csopt{assign-missing-field-action} setting. The default
+behaviour is to use the fallback, if provided (see
+\sectionref{sec:fallbacks}). In the case of \atentry{index}, the
+fallback for the \field{name} field is the entry's label. This means
+that the Jane-Smith entry will have the \fieldfmt{surname} field set
+to \qt{Smith}.
+
+If the fallback isn't set or if there is no fallback then the
+assignment instruction will be skipped. Similarly, if an ancestor is
+referenced but doesn't exist then assignment will again be skipped.
+
+\begin{important}
+The ancestor entries must be defined first to ensure that they have
+been processed and have had their fields set before they can be
+referenced in an assignment.
+\end{important}
+
+Since I haven't imposed any conditions on the assignments, the
+instructions will be attempted on all entries. This includes the
+parent entries.
+
+The first instruction attempts to set the \fieldfmt{surname} field
+to the parent's \field{name}. Neither the Smith nor the
+de-la-Fontaine entries have a parent entry, so this instruction is
+skipped for both of them.
+
+The second instruction attempts to set the \field{name} field to the
+entry's \fieldfmt{forename} field. The de-la-Fontaine entry already
+has the \field{name} field set so the instruction is automatically
+skipped (because of the default \csopt[false]{assign-override}).
+The Smith entry doesn't have the \field{name} field set so the
+assignment will be attempted but will fail because the
+\fieldfmt{forename} field isn't set and doesn't have a fallback.
+
+The \field{text} (and \field{first}) instruction similarly
+references the \fieldfmt{forename} field, which isn't set, so the
+instruction is skipped. The instruction also contains a reference to
+the \fieldfmt{surname} field, but that part of the assignment isn't
+reached as the attempt stops at the first unset reference.
+
+This means that neither the Smith not the de-la-Fontaine entries
+will be affected by the above \csopt{assign-fields} setting.
+
+Each instruction will be attempted, in turn, unless the \csopt{assign-override}
+setting prevents it. This means it's possible to have multiple
+assignments for a particular field. The first one that succeeds will
+be the one that has effect (with \csopt[false]{assign-override}).
+For example:
+\begin{codeenv}
+\csopt{assign-fields}=\marg{
+ \fieldfmt{surname} = parent \idx{follow} \field{name},
+ \fieldfmt{surname} = \field{name},
+ \field{name} = \fieldfmt{forename},
+ \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
+}
+\end{codeenv}
+This has two instructions for the \fieldfmt{surname}. The first one
+will be applied to entries that have a parent and the second one
+will be applied to the other entries (that don't already have the
+\fieldfmt{surname} set).
+
+Suppose I also have some monarchs, who are more typically only
+referred to by their forename (with no surname), possibly prefixed by their rank and
+suffixed by their ordinal. Let's further suppose that in my document
+I have also defined the custom fields \fieldfmt{rank} and
+\fieldfmt{ordinal}, and in my \ext{bib} file I have:
+\begin{codeenv}
+\atentry{indexplural}\marg{king}
+\atentry{indexplural}\marg{queen}
+\atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}}
+\strut
+\atentry{index}\marg{King-Stephen,
+ \field{parent}=\marg{king},
+ \fieldfmt{forename}=\marg{Stephen}
+}
+\atentry{index}\marg{Empress-Matilda,
+ \field{parent}=\marg{empress},
+ \fieldfmt{forename}=\marg{Matilda},
+}
+\atentry{index}\marg{Elizabeth-I,
+ \field{parent}=\marg{queen},
+ \fieldfmt{forename}={Elizabeth},
+ \fieldfmt{ordinal}={I}
+}
+\end{codeenv}
+The earlier assignment rules won't be appropriate for these cases,
+as they would result in the \field{text} fields: \qt{Stephen kings},
+\qt{Matilda empresses} and \qt{Elizabeth queens}.
+
+In this case, the assignment rules need to depend on the type of
+entry. I could test if the parent label is \qt{king} or \qt{empress}
+or \qt{queen}, but a more reliable approach is to have custom entry
+types which can be aliased:
+
+\begin{codeenv}
+\atentry{index}\marg{Smith}
+\atentryfmt{person}\marg{Jane-Smith,
+ \fieldfmt{forename}=\marg{Jane},
+ \field{parent}=\marg{Smith}
+}
+\atentry{index}\marg{de-la-Fontaine,
+ \field{name}=\marg{de la Fontaine}
+}
+\atentryfmt{person}\marg{Margaret-de-la-Fontaine,
+ \fieldfmt{forename}=\marg{Margaret},
+ \field{parent}=\marg{de-la-Fontaine}
+}
+\strut
+\atentry{indexplural}\marg{king}
+\atentry{indexplural}\marg{queen}
+\atentry{indexplural}\marg{empress,\field{plural}=\marg{empresses}}
+\strut
+\atentryfmt{monarch}\marg{King-Stephen,
+ \field{parent}=\marg{king},
+ \fieldfmt{forename}=\marg{Stephen}
+}
+\atentryfmt{monarch}\marg{Empress-Matilda,
+ \field{parent}=\marg{empress},
+ \fieldfmt{forename}=\marg{Matilda},
+}
+\atentryfmt{monarch}\marg{Elizabeth-I,
+ \field{parent}=\marg{queen},
+ \fieldfmt{forename}={Elizabeth},
+ \fieldfmt{ordinal}={I}
+}
+\end{codeenv}
+The resource options are now:
+\begin{codeenv}
+\csopt[person=index,monarch=index]{entry-type-aliases},
+\csopt[
+ \field{name} = \fieldfmt{forename} \idx{concat-plus} \qt{\idx{nbspchar}} \fieldfmt{ordinal},
+ \field{name} = \fieldfmt{forename},
+ \fieldfmt{surname} = parent \idx{follow} \field{name}
+ \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} },
+ \field{text} = \fieldfmt{forename} \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{surname}
+ \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{person} },
+ \field{first} = \gls{FIRSTUC} \marg{ parent \qt{follow} \field{text} } \idx{concat-plus} \qtdelim{ } \idx{concat-plus} \fieldfmt{name}
+ \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} },
+ \field{text} = \fieldfmt{name}
+ \oarg{ entrytype \idx{follow} original \idx{equalscmp} \qtdelim{monarch} }
+]{assign-fields}
+\end{codeenv}
+
+Additional fields can be added to accommodate nicknames or other
+forms of address, which will add to the complexity of the assignment
+specification.
+
+\optsection[\subsubsection]{assign-override}
+
+This is a boolean option. The default setting is
+\csopt[false]{assign-override}. If \optfmt{true},
+\csopt{assign-fields} will override the existing value if the
+target field is already set.
+
+\optsection[\subsubsection]{assign-missing-field-action}
+
+This option indicates what to do if a source field identified in
+\csopt{assign-fields} is missing. The value may be one of:
+\begin{itemize}
+\item \optfmt{skip}: skip the assignment;
+\item \optfmt{fallback}: use the fallback for the missing field
+(see \sectionref{sec:fallbacks}), if
+one is available, otherwise skip the assignment (default);
+\item \optfmt{empty}: treat the missing value as empty.
+\end{itemize}
+Return null will result in the assignment instruction being omitted.
+
\optsection[\subsubsection]{counter}
The \csopt{counter} option assigns the default counter to use
@@ -10322,7 +11665,7 @@ had to stop when it wrapped round to its starting point.
\optsection[\subsubsection]{save-original-entrytype}
The \meta{value} may be the keywords \code{false} or \code{true} or
-the name of a field in which to store the original entry type (as
+the name of a field in which to store the original \gls{entrytype} (as
given in the \ext{bib} file but without the leading \idx{atchar} and
converted to \idx!{lowercase}). The setting is
\csopt[false]{save-original-entrytype}. If \meta{value} is omitted or the
@@ -10338,19 +11681,19 @@ setting is governed by \csopt{save-original-entrytype-action}.
\optsection[\subsubsection]{save-original-entrytype-action}
This option determines whether or not \csopt{save-original-entrytype}
-should save the original entry type. No action is performed when
+should save the original \gls{entrytype}. No action is performed when
\csopt[false]{save-original-entrytype} otherwise the action is determined
by \meta{value} which may be one of the following keywords:
\begin{itemize}
-\item \code{always}: always save the original entry type (default);
+\item \code{always}: always save the original \gls{entrytype} (default);
\item \code{no override}: don't override a field that's already been
set;
\item \code{changed override} or \code{changed} or \code{diff}:
-only save the original entry type if it's different from the final
-entry type;
+only save the original \gls{entrytype} if it's different from the final
+\gls{entrytype};
\item \code{changed no override}:
-only save the original entry type if it's different from the final
-entry type and the specified field hasn't been set.
+only save the original \gls{entrytype} if it's different from the final
+\gls{entrytype} and the specified field hasn't been set.
\end{itemize}
The \qt{no override} options make no difference if the given field
is unknown (such as \field{originalentrytype}). For known fields, bear in
@@ -10359,7 +11702,7 @@ other options, such as \csopt{ignore-fields}.
The \qt{changed} options ignore case. For example, if the \ext{bib}
file defined an entry with \atentryfmt{INDEX} then both the original
-and final entry type will be \code{index}.
+and final \gls{entrytype} will be \code{index}.
\subsection{Field Adjustments}
\label{sec:fieldmods}
@@ -10863,7 +12206,7 @@ If true, this is a shortcut for:
This will remove any labels in an entry's \field{see} or
\field{seealso} field where the referenced label doesn't have any
records and hasn't been selected as another form of dependency and
-whose entry type is either \atentry{index} or \atentry{indexplural}
+whose \gls{entrytype} is either \atentry{index} or \atentry{indexplural}
and doesn't have the \field{see}, \field{seealso} or \field{alias}
fields set.
@@ -10947,7 +12290,7 @@ An appropriate filter is needed to switch on pruning. (This is in
addition to the criteria that the pruned entry has no records, isn't
dependent on another entry, and hasn't previously been selected.)
This type of pruning is usually only necessary for indexes so a
-useful filter may be simply on the entry type (either
+useful filter may be simply on the \gls{entrytype} (either
\atentry{index} or \atentry{indexplural}):
\begin{codeenv}
\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},
@@ -11589,7 +12932,7 @@ are written to the \ext{aux} file.
\optsection[\subsubsection]{append-prefix-field-nbsp-match}
-The value is the \idx{regex} that identifies prefixes that should be
+The value is the \gls{regular-expression} that identifies prefixes that should be
followed by \idx{nbspchar} instead of \ics{space}. The default
is \csopt[\idx{matchanydot}]{append-prefix-field-nbsp-match} which indicates a
single character.
@@ -11620,6 +12963,12 @@ the original value is encapsulated by a command or \bibgls\ will
perform the actual \idx{case-change} according to its own algorithm.
The results can vary according to the field content.
+Where \bibgls\ itself performs the case change, its case-changing
+functions will use the \gls{resource-locale}, but whether or not
+\bibgls\ recognises the correct rules for the locale depends on
+whether or not the locale is correctly supported by the Java locale
+provider. The \langxml\ may provide assistance with case-conversion.
+
Each of the case-changing resource options may take one of the
following values:
\begin{itemize}
@@ -11711,6 +13060,24 @@ example:
\end{itemize}
+If you need to selectively change the case, based on some condition
+(such as the \gls{entrytype}) then you can use the
+\csopt{assign-fields} option instead, but remember that you will
+need the override setting on. For example:
+\begin{codeenv}
+\csopt[
+ \field{name} =\oarg{o} \gls{TITLE}\marg{ \field{name} }
+ \oarg{ entrytype \idx{follow} original = \qtdelim{entry} }
+]{assign-fields}
+\end{codeenv}
+This will convert the \field{name} field to \idx{titlecase} for
+entries that were defined in the \ext{bib} file with
+\atentry{entry}. Note that if you also use a case-changing option,
+for example, \csopt{name-case-change}, then all entries will have
+the change applied, according to the option's designated behaviour,
+regardless of whether or not the applicable field has already been
+altered by \csopt{assign-fields}.
+
\begin{important}
Major changes have been introduced to \sty{mfirstuc} v2.08. Some of
the information below refers to older versions and is not
@@ -11746,12 +13113,18 @@ package documentation for further details~\cite{textcase,mfirstuc}.
For the settings where \bibgls\ itself performs the \idx{case-change}, then
\bibgls\ will iterate over each token of the field value and apply
-the following rules:
+the rules listed below. Note that the case-change implemented by
+\bibgls\ recognises the \gls{resource-locale}, but whether or not it
+recognises the correct rules for the locale depends on whether or
+not the locale is correctly supported by the Java locale provider.
+
\begin{enumerate}
\item If the token is a normal Unicode alphabetic character, it will
be replaced with the corresponding upper or lower case character, as
-appropriate.
+appropriate. In some cases, a single character, such as \ss, is
+replaced by multiple characters, such as SS.
+
For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is
used as the replacement, for \optfmt{uc} the \idx{uppercase} character is
used as the replacement, and for \optfmt{lc} the \idx{lowercase} character
@@ -12168,13 +13541,14 @@ field.
Applies a case-change to the \field{name} field.
This option may take one of the values described above.
-If the \field{text} field hasn't been set, the \field{name}
-value is first copied to the \field{text} field. If the \field{name}
-field hasn't been set (for example, with the \atentry{index} entry
-type), it's copied from the fallback value (which
-depends on the entry type) unless the entry type is
-\atentry{abbreviation} or \atentry{acronym}, in which case if
-the \field{name} field is missing no action is performed.
+If the \field{text} field hasn't been set, the \field{name} value is
+first copied to the \field{text} field. If the \field{name} field
+hasn't been set (for example, with the \atentry{index}
+\gls{entrytype}), it's copied from the fallback value (which depends
+on the \gls{entrytype}, see \sectionref{sec:fallbacks}) unless the
+\gls{entrytype} is \atentry{abbreviation} or \atentry{acronym}, in
+which case if the \field{name} field is missing no action is
+performed.
\optsection[\subsubsection]{description-case-change}
@@ -12192,7 +13566,8 @@ The \meta{setting} should be
the same as the permitted values for the above options. This
option is applied after all fields have been parsed but before
\csopt{interpret-fields}. If the
-specified field is missing, the fallback for that field (if known) is copied
+specified field is missing, the fallback for that field (if known,
+see \sectionref{sec:fallbacks}) is copied
into the field. For example:
\begin{codeenv}
\csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change}
@@ -12211,13 +13586,587 @@ field and convert \fieldfmt{nametitle} to \idx{titlecase}:
This means that it's possible to fetch the value of
\fieldfmt{nametitle} instead of \field{name}, which provides an
expandable \idx{titlecase} form that's suitable for the PDF
-bookmarks.
+bookmarks. (Note that \LaTeX3 now provides some expandable
+case-changing commands.)
This option isn't cumulative. If used multiple times in the same
\igls{resourceset}, the last instance will be the one used. If
the \keyvallist\ is missing, no general case-changing is applied
(the default).
+\section{Field Fallbacks}
+\label{sec:fallbacks}
+
+The options in this section don't modify any field values but
+provide instructions on what to do if \bibgls\ wants to know the
+value of a field where the field hasn't been explicitly set. The most common
+case is querying the \field{sort} field value with the default
+\csopt[\field{sort}]{sort-field} setting. Being able to vary the
+fallback used according to the \gls{entrytype} allows a more flexible
+approach than explicitly setting the \field{sort} field in the
+\ext{bib} file.
+
+Note that if you specify a different field to use for the sort value
+with \csopt{sort-field} then the fallback for that field will be used
+if that field is missing. The \field{sort} fallbacks will be
+irrelevant if the \field{sort} field isn't being queried. If the
+fallback system fails to provide a value for the field identified by
+\csopt{sort-field} then \bibgls\ will follow the rule given by the
+\csopt{missing-sort-fallback} setting.
+
+If you require a complex sort value that can't be implemented by the
+fallback system, you can use \csopt{assign-fields} to explicitly set
+the \field{sort} field to a string expression
+(\sectionref{sec:optstringconcat}). Bear in mind that if the
+\field{sort} field is actually set to a value, either in the
+\ext{bib} file or through resource options, then \emph{the
+\field{sort} fallback won't be used} and the sort fallback options
+describe in this section won't have any effect.
+
+There are other fields that \bibgls\ may want to query that won't
+necessarily be set in the \ext{bib} file but may be inferred from
+another field. For example, if the \field{sort} field fallback
+references the \field{name} field then the \field{name} field will
+also need a fallback if it hasn't been set.
+
+Another possibility is that the interpreter encounters content that
+includes commands such as \ics{gls}. Since the interpreter can't
+tell at what point in the document the first use flag is changed,
+\ics{gls} is treated as \ics{glstext} (and similarly \ics{glspl} is
+treated as \ics{glsplural}) so the \field{text} (or \field{plural})
+field will be queried by the interpreter.
+
+The commands \ics{newglossaryentry} and \ics{longnewglossaryentry}
+are the foundation for all commands that define glossary entries.
+These commands both require that either the \field{name} or the
+\field{parent} field are set. If the \field{name} is omitted, then
+its value is obtained from the \gls{parententry}['s] name. The
+\field{description} must also be provided but may be set to empty.
+(Some entry types, such as \atentry{index}, will set
+\field{description} to empty if that field is missing, but for other
+entry types, such as \atentry{entry}, the \field{description} is
+required and will trigger a warning if omitted.)
+
+All other entry definition commands, such as \ics{newabbreviation} and
+\ics{glsxtrnewsymbol}, internally use one of those foundation
+commands.\footnote{Or the internal command that both
+\cs{newglossaryentry} and \cs{longnewglossaryentry} use.} In the
+case of \ics{newabbreviation} (and \ics{newacronym}), the
+\field{name} field is set by the style using values obtained from
+the \field{short} and\slash or \field{long} fields. This is
+information that \bibgls\ is unaware of and may guess incorrectly
+when trying to determine an appropriate value for the \field{name}
+field if it is omitted (which is typically the case) from
+abbreviation entry types, such as \atentry{abbreviation} or
+\atentry{acronym}.
+
+The general \atentry{entry} entry type, uses the same rules as
+\ics{newglossaryentry}:
+\begin{description}
+\item[\field{name}] If the \field{parent} field has been set, then
+the parent's \field{name} field is used. If the parent's
+\field{name} field isn't set, then the fallback for the parent's
+\field{name} field is used (which will depend on the parent's
+\gls{entrytype}). If neither the \field{name} nor the \field{parent}
+field is set, then a warning is issued since at least one of those
+fields must be set for \atentry{entry}.
+
+\item[\field{text}] If the \field{text} field is missing, it's
+obtained from the \field{name} field or the fallback for the
+\field{name} field, if that hasn't been set.
+
+\item[\field{plural}] If the \field{name} field has been set then
+the \field{plural} value is obtained by appending \ics{glspluralsuffix}
+to the value of the \field{text} field (or the fallback for the
+\field{text} field, if that hasn't been set).
+
+If the \field{name} field hasn't been set but the \field{parent}
+field has been set, then the \field{plural} is obtained from the
+parent's \field{plural} field. If the parent's \field{plural} field
+hasn't been set then the fallback for that value will be used,
+according to the parent's \gls{entrytype}.
+
+\item[\field{first}] The fallback for the \field{first} field is
+obtained from the \field{text} field (or the fallback for the
+\field{text} field, if that hasn't been set).
+
+\item[\field{firstplural}] The fallback for the \field{firstplural}
+field is obtained by appending \ics{glspluralsuffix} to the value of
+the \field{first} field, if that field has been set, otherwise it's
+obtained from the \field{plural} field (or the fallback for the
+\field{plural} field if that isn't set).
+
+\end{description}
+
+Note that although \bibgls\ follows the \ics{newglossaryentry} rules
+in order to obtain the fallback, it doesn't explicitly set those
+fields in the \ext{glstex} file if they weren't provided in the
+\ext{bib} file or set using options such as \csopt{replicate-fields}
+or \csopt{assign-fields}.
+
+The exception to this is the \field{sort} field, which will be
+obtained from the \field{name} field for most \glspl{entrytype} unless
+overridden by one of the applicable sort fallback options, such as
+\csopt{entry-sort-fallback}. If the designated fallback (such as
+\field{name}) is missing, then the fallback value for that field
+will be used.
+
+The \atentry{index} and \atentry{indexplural} entry types are
+slightly different. They have their own rules for obtaining the
+value of the \field{name} field, and will explicitly set it in the
+\ext{glstex} file via the helper commands \gls{bibglsnewindex}
+and \gls{bibglsnewindexplural}.
+
+In the case of \atentry{index}, if the \field{name} field is
+missing, its value will be obtained from the entry's original label.
+If the \field{sort} field is missing, its value is obtained from the
+\field{name} field unless a different fallback is specified with
+\csopt{custom-sort-fallbacks}. The remaining fallbacks are as for
+\atentry{entry}.
+
+It's more complicated for \atentry{indexplural}, which has the following
+fallback rules:
+\begin{description}
+\item[\field{name}] If the \field{name} field is missing, its value
+is obtained from the entry's \field{plural} field (or the fallback
+for the \field{plural} field, if that field is missing).
+
+\item[\field{plural}] If the \field{plural} field is missing, its
+value is obtained by appending \ics{glspluralsuffix} to the value
+of the \field{text} field (or the fallback for the \field{text}
+field, if that field is missing).
+
+\item[\field{text}] If the \field{text} field is missing, its value
+is obtained from the entry's original label.
+
+\item[\field{sort}] If the \field{sort} field is missing, its value
+is obtained from the \field{name} field unless a different fallback
+is specified with \csopt{custom-sort-fallbacks}.
+\end{description}
+The remaining fallbacks are as for \atentry{entry}.
+
+The most awkward of all the \glspl{entrytype} are, as indicated earlier,
+the abbreviations where the field values such as \field{name} and
+\field{text} are set by the abbreviation style. Therefore, there are resource
+options specifically to identify the most appropriate fallback
+values for abbreviations. The default is to use the value of the
+\field{short} field as the fallback for the \field{name},
+\field{sort} and \field{text} fields. If this is inappropriate for
+your abbreviation style then you will need to use the options listed below to
+provide more appropriate fallbacks. These options don't actually set
+the \field{name} and \field{text} fields in the \ext{glstex} file
+and don't include any style formatting (such as font changing
+commands), which are irrelevant to \bibgls.\footnote{The \field{sort} field
+will be set in the \ext{glstex} file as it's useful for debugging,
+but it's typically irrelevant.}
+
+For other entry types, see their description in \sectionref{sec:bib}.
+
+\optsection{abbreviation-name-fallback}
+
+The \glspl{entrytype} that define abbreviations (such as
+\atentry{abbreviation} and \atentry{acronym}) will, by default,
+fallback on the \field{short} field if the \field{name} field is
+missing and it's required for some reason (for example, with
+\csopt[name]{sort-field}). If you prefer to
+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 (not an internal field)
+but can't be the \field{sort} field.
+
+Note that the default fallback for the \field{sort} field for
+abbreviations is given by \csopt{abbreviation-sort-fallback} which
+is set to \field{short} not \field{name} by default. So changing the
+fallback for the \field{name} field won't have an effect unless the
+\field{sort} fallback is changed to \field{name} or
+\csopt[\field{name}]{sort-field} is used or the \field{name} field
+is referenced in an option such as \csopt{assign-fields}.
+
+Field concatenation isn't available for this option.
+
+\optsection{abbreviation-text-fallback}
+
+Similar to \csopt{abbreviation-name-fallback} but for the
+\field{text} field. The default fallback is the \field{short} field.
+Field concatenation isn't available for this option.
+
+Note that you can't have both
+\csopt[\field{text}]{abbreviation-name-fallback} and
+\csopt[\field{name}]{abbreviation-text-fallback} as it would cause
+an infinite loop.
+
+\optsection{abbreviation-sort-fallback}
+
+The \glspl{entrytype} that define abbreviations (such as
+\atentry{abbreviation} and \atentry{acronym}) will, by default,
+fallback on the \field{short} 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. 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} 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\
+tries to access the \field{sort} field for an abbreviation 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 \glspl{entrytype} (such as \atentry{entry} and
+\atentry{dualentry}) will, by default, fallback on the \field{name}
+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} 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
+glossary contains \iglspl{homograph} (terms with the same spelling) which
+can't be distinguished by the sort comparators. For example, suppose
+my file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{pagelist,
+ \field{name}=\marg{page list},
+ \field{description}=\marg{a list of individual pages or page ranges}
+}
+\strut
+\atentry{index}\marg{glossary}
+\strut
+\atentry{entry}\marg{glossarylist,
+ \field{parent}=\marg{glossary},
+ \field{description}=\marg{list of technical words}
+}
+\strut
+\atentry{entry}\marg{glosscol,
+ \field{parent}=\marg{glossary},
+ \field{description}=\marg{collection of glosses}
+}
+\end{codeenv}
+Now first consider a document that uses the default settings:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+A test document describing \cs{glspl}\marg{pagelist} and
+\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list).
+\strut
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+The default behaviour for \atentry{entry} if the \field{sort} field
+is missing is to fallback on the \field{name} field. If the
+\field{name} field is missing (as with \code{glossarylist} and
+\code{glosscol}), then the value is obtained from the
+\field{name} field from the \gls{parententry}. The \gls{parententry} for these
+\glspl{homograph} is the \code{glossary} entry, which was defined with
+\atentry{index} and doesn't have the \field{name} field. For the
+\atentry{index} entries, if \field{name} is missing the value is
+obtained from the label.
+
+Therefore both \code{glossarylist} and \code{glosscol} end
+up with the same sort value: \code{glossary}. This triggers a
+message in verbose mode (\longarg{verbose}) which can be found
+in the transcript file:
+\begin{verbatim}
+Identical sort values for 'glossarylist' and 'glosscol'
+Falling back on ID
+\end{verbatim}
+So the actual sort values used are \qt{glossarylist} and
+\qt{glosscol}. This puts the \code{glossarylist} entry
+before the \code{glosscol} entry.
+
+Now suppose a minor modification is made to the document:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}
+ \oarg{
+ \csopt[entries]{src},
+ \csopt[description]{entry-sort-fallback}
+ }
+\end{codeenv}
+This means that when the sort function fails to find the
+\field{sort} field for the terms defined with \atentry{entry}, it
+will fallback on the \field{description} field. This doesn't affect
+the terms defined with \atentry{index}, which still fallback on the
+\field{name} field. This time there's no message in the transcript
+file and the \code{glosscol} entry now comes before the
+\code{glossarylist} entry.
+
+\begin{important}
+The \csopt{entry-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a term defined with
+\atentry{entry} 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{symbol-sort-fallback}
+
+The \glspl{entrytype} that define symbols (such as \atentry{symbol} and
+\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} 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{symbol-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a symbol 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{bibtexentry-sort-fallback}
+
+The \glsdisp{mainentry}{main} \atentry{bibtexentry}
+\glspl{entrytype} will, by default,
+fallback on the \field{name} 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.
+
+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
+\bibgls\ tries to access the \field{sort} field for a \gls{mainentry}
+defined with \atentry{bibtexentry} 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{custom-sort-fallbacks}
+
+The value should be a \keyvallist\ in the form
+\meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the
+\emph{original} \gls{entrytype} (before being aliased with
+\csopt{entry-type-aliases}). This will override any of the sort fallback
+options listed below for entries whose original \gls{entrytype} 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
+\gls{entrytype} was \entryfmt{unit}), the \code{pi} entry will use the
+\field{user1} field for the sort fallback (because its original
+\gls{entrytype} 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 \gls{entrytype} aliased then \meta{entrytype}
+is its actual \gls{entrytype}. 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 \glspl{dualentry}. For example:
+\begin{codeenv}
+\csopt[
+ \entryref{dualindexnumber}=\field{description},
+ \entryfmt{dualindexnumbersecondary}=\field{user1}
+]{custom-sort-fallbacks}
+\end{codeenv}
+Note that the \gls{entrytype} 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
+\gls{entrytype} 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{field-concat-sep}
+
+This option sets the field concatenation separator to \meta{value}
+used by the \field{sort} fallback options. The default is a space.
+An empty value indicates no separator. You may use
+\gls{uhex}\meta{hex} to indicate a character by its hexadecimal code
+(see \sectionref{sec:quarks}). Note that the more complex field
+concatenation specification described in
+\sectionref{sec:optstringconcat} isn't available for this option.
+
+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[~]{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.
+
\section{Plurals}
\label{sec:plurals}
@@ -13175,7 +15124,7 @@ considered consecutive.
then the \glspl{location} aren't considered consecutive.
\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the
pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}}
-used in the \idx{regex} will match any digits in the
+used in the \gls{regular-expression} will match any digits in the
Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic
characters outside the Basic Latin set.}
\begin{verbatim}
@@ -14087,8 +16036,8 @@ The special \code{nameref} \glspl{location} (see
be set.
As from \bibgls\ v1.7, any awkward characters in the file path are
-replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII} characters when
-\sty{fontspec} is loaded) \gls{bibglshrefunicode}. Both commands
+replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII}
+characters, when supported) \gls{bibglshrefunicode}. Both commands
take two arguments: the hexadecimal character code and the actual
character. In the case of \gls{bibglshrefchar}, the second
argument is ignored, and the first is preceded by a literal percent
@@ -14239,7 +16188,8 @@ values to determine the order. By default, this sort value is
obtained from the \field{sort} field but for greater flexibility
it's best to not actually set this field. \bibgls\ has a set of fallbacks
that it uses if a field it needs to access is missing. These
-fallbacks depend on the entry type and resource settings.
+fallbacks depend on the \gls{entrytype} and resource settings (see
+\sectionref{sec:fallbacks}).
For example, if a term defined with \atentry{index} doesn't have the
\field{sort} field set then \bibgls\ will use the value given by the
@@ -14266,7 +16216,7 @@ any entries then I can, for example, sort terms defined with
If the field used to obtain the sort value is changed
(with \csopt{sort-field}) then the \field{sort} field won't be
queried. This reduces the flexibility of selecting the most
-appropriate field for given entry types. For example,
+appropriate field for given \glspl{entrytype}. For example,
\csopt[name]{sort-field} will force all entries to be sorted by the
\field{name} field, which may not be appropriate for symbols.
@@ -14339,10 +16289,24 @@ command definitions for the \bibgls\ interpreter and load it with
\optsection{sort}
The \csopt{sort} key indicates how \glspl{primaryentry} should be sorted.
-If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the
-\csopt{sort} option isn't used then \csopt[doc]{sort} is assumed if the
-document has a language that's been detected by \sty{tracklang},
-otherwise \csopt[locale]{sort} is assumed.
+If the \meta{value} is omitted, \csopt[resource]{sort} is assumed.
+Note the differences between the keywords \optfmt{resource},
+\optfmt{doc} and \optfmt{locale}:
+\begin{description}
+\item[\optfmt{resource}] The default \gls{resource-locale}, which
+can be specified with the \csopt{locale} option. If that option
+hasn't been set, then \optfmt{resource} will be equivalent to
+\optfmt{doc}. This option is new to \bibgls\ v3.3. Previous versions
+had \csopt[doc]{sort} as the default.
+
+\item[\optfmt{doc}] The \gls{document-locale} if it has been detected by
+\sty{tracklang}. If no document language has been detected (or
+identified with \longarg{locale}), then
+\optfmt{doc} will be equivalent to \optfmt{locale}.
+
+\item[\optfmt{locale}] The default \gls{Java-locale}.
+
+\end{description}
The \optfmt{\meta{method}\dhyphen reverse} options reverse the
result returned by the corresponding \meta{method} comparator.
@@ -14375,14 +16339,17 @@ can affect the order.
\begin{tabular}{ll}
\meta{lang tag} & sort according to this language tag\tabularnewline
\meta{lang tag}\optfmt{-reverse} & reverse sort according to this language tag\tabularnewline
-\optfmt{doc} & sort according to the document
-language\tabularnewline
-\optfmt{doc-reverse} & reverse sort according to the document
-language\tabularnewline
+\optfmt{resource} & sort according to the default
+\gls{resource-locale}\tabularnewline
+\optfmt{resource-reverse} & reverse sort according to the default
+\gls{resource-locale}\tabularnewline
+\optfmt{doc} & sort according to the \gls{document-locale}\tabularnewline
+\optfmt{doc-reverse} & reverse sort according to the
+\gls{document-locale}\tabularnewline
\optfmt{locale} & sort according to the default
-locale\tabularnewline
+\gls{Java-locale}\tabularnewline
\optfmt{locale-reverse} & reverse sort according to the default
-locale\tabularnewline
+\gls{Java-locale}\tabularnewline
\optfmt{custom} & sort according to \csopt[\meta{custom
rule}]{sort-rule}\tabularnewline
\optfmt{custom-reverse} & reverse sort according to \csopt[\meta{custom rule}]{sort-rule}
@@ -14640,23 +16607,31 @@ given by the \idx{IETF} language tag \meta{lang tag}.
\item \meta{lang tag}\optfmt{-reverse}: reverse sort according to the rules of the locale
given by the \idx{IETF} language tag \meta{lang tag}.
+\item \optfmt{resource}: equivalent to
+\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
+from the default \gls{resource-locale}.
+
+\item \optfmt{resource-reverse}: equivalent to
+\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained
+from the default \gls{resource-locale}.
+
\item \optfmt{locale}: equivalent to
\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
-from the \idx{JRE}['s] default locale (which usually matches the
+from the \gls{Java-locale} (which usually matches the
operating system's locale).
\item \optfmt{locale-reverse}: equivalent to
\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained
-from the \idx{JRE}.
+from the \gls{Java-locale}.
-\item \optfmt{doc}: sort the entries according to the document
-language. This is equivalent to \csopt[\meta{lang tag}]{sort}
+\item \optfmt{doc}: sort the entries according to the
+\gls{document-locale}. This is equivalent to \csopt[\meta{lang tag}]{sort}
where \meta{lang tag} is the locale associated with the document
language. In the case of a multi-lingual document, \meta{lang tag}
is the locale of the last language resource file to be loaded through
\isty{tracklang}'s interface. It's best to explicitly set the locale
-for multi-lingual documents to avoid confusion. If no languages have been tracked, this
-option is equivalent to \csopt[locale]{sort}.
+for multi-lingual documents to avoid confusion. If no document
+language has been set, this option is equivalent to \csopt[locale]{sort}.
\item \optfmt{doc-reverse}: as \optfmt{doc} but in reverse order.
@@ -14667,7 +16642,7 @@ rule provided by \csopt{sort-rule}.
rule provided by \csopt{sort-rule}.
\end{itemize}
-Note that \csopt[\meta{locale}]{sort} can provide more detail about the
+Note that \csopt[\meta{lang tag}]{sort} can provide more detail about the
given locale than \csopt[doc]{sort}, depending on how the document
language has been specified. For example, with:
\begin{codeenv}
@@ -14692,8 +16667,11 @@ only likely to cause a difference if a language has different
sorting rules according to the region or if the language may be
written in multiple scripts.
-If no language package is loaded then the default is \csopt[locale]{sort}
-rather than \csopt[doc]{sort}. For example, with:
+If no \gls{document-locale} has been set and the
+\csopt{locale} resource option hasn't been used
+then the \csopt[resource]{sort} and \csopt[doc]{sort}
+will be equivalent to \csopt[locale]{sort}.
+For example, with:
\begin{codeenv}
\cmd{documentclass}\marg{article}
\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
@@ -14711,6 +16689,12 @@ For example:
\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}}
\end{codeenv}
+Alternatively (as from \bibgls\ v3.3), use \csopt{locale}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[en-GB]{locale},\csopt[english-terms]{src}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[de-DE-1996]{locale},\csopt[german-terms]{src}}
+\end{codeenv}
+
\subsubsection{Letter (Non Locale)}
The sort methods listed in \tableref{tab:sortoptionsletter}
@@ -15353,20 +17337,21 @@ 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.
+and adjust the fallbacks instead (see
+\sectionref{sec:fallbacks}). The \csopt{sort-field} option is
+provided if you want to use a specific field regardless of the
+\gls{entrytype}.
\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
-entry type.
+\gls{entrytype}.
If no fallback field can be found, the entry's label will be used.
For the specific case with the default \csopt[sort]{sort-field}
setting, the fallback for the \field{sort} field is governed not
-only by the entry type but also by some associated settings:
+only by the \gls{entrytype} but also by some associated settings:
\begin{itemize}
\item If the entry's original type (before being aliased with
@@ -15380,10 +17365,10 @@ missing the value is obtained from the field identified by
\csopt{entry-sort-fallback}. If that field is also missing then
that field's fallback is used.
-\item For the index entry types like \atentry{index} or
+\item For the index \glspl{entrytype} like \atentry{index} or
\atentry{indexplural}, then if the \field{sort} field is missing the
value is obtained from the \field{name} field. If that field is also
-missing, then the value is obtained from the particular entry type's
+missing, then the value is obtained from the particular \gls{entrytype}['s]
fallback for the \field{name} field. (For example, the entry's label
for \atentry{index} or the \field{plural} field for
\atentry{indexplural}.)
@@ -15393,7 +17378,7 @@ example, \atentry{abbreviation} or \atentry{acronym}) then if the
\field{sort} field is missing, \bibgls\ will fallback on the field
given by \csopt{abbreviation-sort-fallback}.
-\item The symbol-like entry types fallback on the field given by
+\item The symbol-like \glspl{entrytype} fallback on the field given by
\csopt{symbol-sort-fallback} if the \field{sort} field is missing.
\item Entries defined using \atentry{bibtexentry} fallback on the field
@@ -15414,20 +17399,22 @@ follows:
\item If \csopt[\meta{fallback-field}]{missing-sort-fallback} is set, then
\bibgls\ will fallback on the value provided by the field
\meta{fallback-field}. If \meta{fallback-field} is
-missing, then \bibgls\ will query the entry type's fallback for
+missing, then \bibgls\ will query the \gls{entrytype}['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:
+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 \gls{entrytype} has a fallback rule for
+\meta{sort-field}, then that rule is used (see
+\sectionref{sec:fallbacks}). When \csopt[sort]{sort-field} this
+means:
\begin{itemize}
-\item If the entry's original entry type has been identified in
+\item If the entry's original \gls{entrytype} has been identified in
\csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the
designated custom setting.
@@ -15466,371 +17453,6 @@ 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 \glspl{dualentry}. 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
-\atentry{dualentry}) will, by default, fallback on the \field{name}
-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} 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
-glossary contains \iglspl{homograph} (terms with the same spelling) which
-can't be distinguished by the sort comparators. For example, suppose
-my file \filefmt{entries.bib} contains:
-\begin{codeenv}
-\atentry{index}\marg{pagelist,
- \field{name}=\marg{page list},
- \field{description}=\marg{a list of individual pages or page ranges}
-}
-\strut
-\atentry{index}\marg{glossary}
-\strut
-\atentry{entry}\marg{glossarylist,
- \field{parent}=\marg{glossary},
- \field{description}=\marg{list of technical words}
-}
-\strut
-\atentry{entry}\marg{glosscol,
- \field{parent}=\marg{glossary},
- \field{description}=\marg{collection of glosses}
-}
-\end{codeenv}
-Now first consider a document that uses the default settings:
-\begin{codeenv}
-\cmd{documentclass}\marg{article}
-\strut
-\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra}
-\strut
-\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
-\strut
-\cmd{begin}\marg{document}
-A test document describing \cs{glspl}\marg{pagelist} and
-\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list).
-\strut
-\cs{printunsrtglossary}
-\cmd{end}\marg{document}
-\end{codeenv}
-The default behaviour for \atentry{entry} if the \field{sort} field
-is missing is to fallback on the \field{name} field. If the
-\field{name} field is missing (as with \code{glossarylist} and
-\code{glosscol}), then the value is obtained from the
-\field{name} field from the \gls{parententry}. The \gls{parententry} for these
-\glspl{homograph} is the \code{glossary} entry, which was defined with
-\atentry{index} and doesn't have the \field{name} field. For the
-\atentry{index} entries, if \field{name} is missing the value is
-obtained from the label.
-
-Therefore both \code{glossarylist} and \code{glosscol} end
-up with the same sort value: \code{glossary}. This triggers a
-message in verbose mode (\longarg{verbose}) which can be found
-in the transcript file:
-\begin{verbatim}
-Identical sort values for 'glossarylist' and 'glosscol'
-Falling back on ID
-\end{verbatim}
-So the actual sort values used are \qt{glossarylist} and
-\qt{glosscol}. This puts the \code{glossarylist} entry
-before the \code{glosscol} entry.
-
-Now suppose a minor modification is made to the document:
-\begin{codeenv}
-\gls{GlsXtrLoadResources}
- \oarg{
- \csopt[entries]{src},
- \csopt[description]{entry-sort-fallback}
- }
-\end{codeenv}
-This means that when the sort function fails to find the
-\field{sort} field for the terms defined with \atentry{entry}, it
-will fallback on the \field{description} field. This doesn't affect
-the terms defined with \atentry{index}, which still fallback on the
-\field{name} field. This time there's no message in the transcript
-file and the \code{glosscol} entry now comes before the
-\code{glossarylist} entry.
-
-\begin{important}
-The \csopt{entry-sort-fallback} setting is only used when \bibgls\
-tries to access the \field{sort} field for a term defined with
-\atentry{entry} 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{abbreviation-sort-fallback}
-
-The entry types that define abbreviations (such as
-\atentry{abbreviation} and \atentry{acronym}) will, by default,
-fallback on the \field{short} 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. 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} 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\
-tries to access the \field{sort} field for an abbreviation 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{symbol-sort-fallback}
-
-The entry types that define symbols (such as \atentry{symbol} and
-\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} 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{symbol-sort-fallback} setting is only used when \bibgls\
-tries to access the \field{sort} field for a symbol 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{bibtexentry-sort-fallback}
-
-The \glsdisp{mainentry}{main} \atentry{bibtexentry} entry types will, by default,
-fallback on the \field{name} 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.
-
-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
-\bibgls\ tries to access the \field{sort} field for a \gls{mainentry}
-defined with \atentry{bibtexentry} 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{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[~]{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
@@ -15842,7 +17464,7 @@ and \csopt[\meta{boolean}]{secondary-trim-sort}.
\optsection{sort-replace}
-This option may be used to perform \idx{regex} substitutions
+This option may be used to perform \gls{regular-expression} substitutions
on the sort value and has the same syntax as \csopt{labelify-replace}.
The value is required for this key but may be empty, which indicates
that the setting is switched off.
@@ -15915,6 +17537,13 @@ the protected write is performed. For example:
\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}}
\end{codeenv}
Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}.
+Note that \ics{GlsXtrResourceInitEscSequences} performs a similar
+assignment, so you can instead do:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{}
+ \ics{GlsXtrResourceInitEscSequences}
+}
+\end{codeenv}
The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by
the \styopt{record} option) provides some commands for common rule blocks
@@ -16791,12 +18420,14 @@ for \csopt{secondary}.
If you use any of the locale-sensitive numeric sort methods
described in \sectionref{sec:numerical},
such as \csopt[numeric]{sort}, use this option to set
-the locale. The value may be:
+the locale if the default \gls{resource-locale} isn't appropriate. The value may be:
\begin{itemize}
-\item\optfmt{locale}: use Java's default locale (which is usually
-the operating system's locale);
-\item\optfmt{doc}: use the document's locale or, if not set, assume
+\item\optfmt{resource}: use the default \gls{resource-locale}, if
+set, otherwise assume \optfmt{doc};
+\item\optfmt{doc}: use the \gls{document-locale} or, if not set, assume
\csopt[locale]{numeric-locale};
+\item\optfmt{locale}: use the \gls{Java-locale} (which is usually
+the operating system's locale);
\item\meta{lang-tag}: set to the locale identified by the given
a valid language tag \meta{lang-tag}.
\end{itemize}
@@ -16804,19 +18435,32 @@ Use \csopt{dual-numeric-locale} for
\csopt{dual-sort} and \csopt{secondary-numeric-locale}
for \csopt{secondary}.
+\begin{important}
+If you use the \csopt{locale} resource option with \csopt[resource]{numeric-locale},
+then the \csopt{locale} option must be come before
+\csopt{numeric-locale}.
+\end{important}
+
\optsection{date-sort-locale}
If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
then you can set the locale used by Java's date-time parser.
-The default setting is \csopt[locale]{date-sort-locale}.
+The default setting is \csopt[resource]{date-sort-locale}.
-The value may be \optfmt{locale} (use Java's default locale),
-\optfmt{doc} (use the document's locale) or a valid language tag
-\meta{lang-tag} identifying the locale.
+The value may be \optfmt{resource} (use the \gls{resource-locale}),
+\optfmt{doc} (use the \gls{document-locale}),
+\optfmt{locale} (use the \gls{Java-locale}),
+or a valid language tag \meta{lang-tag} identifying the locale.
Use \csopt{dual-date-sort-locale} and \csopt{secondary-date-sort-locale}
for the dual and secondary.
+\begin{important}
+If you use the \csopt{locale} resource option with \csopt[resource]{date-sort-locale},
+then the \csopt{locale} option must be come before
+\csopt{date-sort-locale}.
+\end{important}
+
\optsection{date-sort-format}
If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
@@ -17005,8 +18649,8 @@ or
\end{definition}
If the \meta{field} is omitted, the value of \csopt{sort-field} is
used. Remember that when the \glspl{primaryentry} are sorted, the
-\field{sort} field will be set, which means that the fallback field
-(such as \field{name}) won't be used in the
+\field{sort} field will be set, which means that the \field{sort} fallback field
+(see \sectionref{sec:fallbacks}) won't be used in the
\glsdisp{secondaryglossary}{secondary} sort. In
general it's best to supply the field unless one type is sorted and the
other isn't. (The actual sort value obtained by the
@@ -17405,19 +19049,19 @@ should be one of:
\begin{itemize}
\item \optfmt{false}: switches off this setting (default);
-\item \optfmt{same as entry}: sets the \field{type} to the entry
-type (\idx!{lowercase} and without
+\item \optfmt{same as entry}: sets the \field{type} to the
+\gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{dualentry}, the \field{type} will be set to
\optfmt{dualentry}.
If you've used \csopt{entry-type-aliases}, this refers to the target
-entry type not the original entry type provided in the \ext{bib}
+\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{type} field
-to the original entry type (\idx!{lowercase} and without
+to the original \gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased).
+\optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
\item \optfmt{same as base}: sets the \field{type} to the base name
of the \ext{bib} file (without the extension) that provided the
@@ -17470,19 +19114,19 @@ file (or created through a mapping). The \meta{value} may be empty or
one of:
\begin{itemize}
\item \optfmt{false}: switch off this setting (default);
-\item \optfmt{same as entry}: sets the \field{category} to the entry
-type (\idx{lowercase} and without
+\item \optfmt{same as entry}: sets the \field{category} to the
+\gls{entrytype} (\idx{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{dualentry}, the \field{category} will be set to
\optfmt{dualentry}.
If you've used \csopt{entry-type-aliases}, this refers to the target
-entry type not the original entry type provided in the \ext{bib}
+\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{category} field
-to the original entry type (\idx{lowercase} and without
+to the original \gls{entrytype} (\idx{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased).
+\optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
\item \optfmt{same as base}: sets the \field{category} to the base
name of the \ext{bib} file (without the extension) that provided the
@@ -17523,7 +19167,7 @@ field instead.
If this option is used, this will add \ics{glsxtrprovidestoragekey}
to the start of the \iext{glstex} file providing the key given by
-\meta{value}. Any entries defined using a dual entry type, such as
+\meta{value}. Any entries defined using a dual \gls{entrytype}, such as
\atentry{dualentry}, will be written to the \ext{glstex} file with
an extra field called \meta{value} that is set to the mirror entry.
If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If
@@ -17633,7 +19277,7 @@ will combine the dual entries with the \glspl{primaryentry} and sort them
all according to the \optfmt{en-GB} locale (British English).
If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If
-\meta{value} is omitted, \optfmt{locale} is assumed.
+\meta{value} is omitted, \optfmt{resource} is assumed.
\optsection[\subsubsection]{dual-sort-field}
@@ -17801,7 +19445,7 @@ The \field{see} field isn't listed in \csopt{dual-entry-map} so its
value is simply copied directly over to the \field{see} field in the
dual entry. Note that the missing \field{plural} and
\field{descriptionplural} fields have been filled in using their
-fallback values.
+fallback values (see \sectionref{sec:fallbacks}).
In general \bibgls\ doesn't try to supply missing fields, but in the
dual entry cases it needs to do this for the mapped fields. This is
@@ -17891,7 +19535,7 @@ The default setting is:
This is like \csopt{dual-entry-map} but applies to both the dual
\atentry{dualindexabbreviation} and tertiary
-\atentry{tertiaryindexabbreviationentry} entry types.
+\atentry{tertiaryindexabbreviationentry} \glspl{entrytype}.
The default setting is:
\begin{codeenv}
\csopt[
@@ -18157,7 +19801,7 @@ commands like \cs{gls} that are internally used by \cs{mgls}.
\item[\optfmt{default}]
Behaves like \csopt[true]{compound-has-records} if the current
\gls{resourceset} has any \ext{bib} files containing one or more
-\atentry{compoundset} entry types. Otherwise behaves like
+\atentry{compoundset} \glspl{entrytype}. Otherwise behaves like
\csopt[false]{compound-has-records}.
\end{description}
@@ -18212,18 +19856,18 @@ with the relevant command (\ics{Glsxtrmultientryadjustedname} for
Set the \field{type} field of the \glslink{compmainlabel}{main
entries}. The \meta{value} is required and should be one of:
\begin{itemize}
-\item \optfmt{same as entry}: sets the \field{type} to the entry
-type (\idx!{lowercase} and without
+\item \optfmt{same as entry}: sets the \field{type} to the
+\gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{index}, the \field{type} will be set to \optfmt{index}.
If you've used \csopt{entry-type-aliases}, this refers to the target
-entry type not the original entry type provided in the \ext{bib}
+\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{type} field
-to the original entry type (\idx!{lowercase} and without
+to the original \gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased).
+\optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
\item \optfmt{same as base}: sets the \field{type} to the base name
of the \ext{bib} file (without the extension) that provided the
@@ -18250,18 +19894,18 @@ entries}. The \meta{value} is required and should be one of:
\item \optfmt{same as main}: sets the \field{type} to the same as
the \glslink{compmainlabel}{main entry}.
-\item \optfmt{same as entry}: sets the \field{type} to the entry
-type (\idx!{lowercase} and without
+\item \optfmt{same as entry}: sets the \field{type} to the
+\gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{index}, the \field{type} will be set to \optfmt{index}.
If you've used \csopt{entry-type-aliases}, this refers to the target
-entry type not the original entry type provided in the \ext{bib}
+\gls{entrytype} not the original \gls{entrytype} provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{type} field
-to the original entry type (\idx!{lowercase} and without
+to the original \gls{entrytype} (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased).
+\optfmt{same as entry} if the \gls{entrytype} wasn't aliased).
\item \optfmt{same as base}: sets the \field{type} to the base name
of the \ext{bib} file (without the extension) that provided the
@@ -18605,7 +20249,7 @@ long form for the \dual\ abbreviation.
\formatdef{bibglsnewdualindexabbreviationsecondary}
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
-\atentry{dualindexabbreviation} entry type.
+\atentry{dualindexabbreviation} \gls{entrytype}.
The definition provided in the \ext{glstex} file is:
\begin{codeenv}
\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{}
@@ -18649,7 +20293,7 @@ are changed).
\formatdef{bibglsnewdualentryabbreviation}
This command is used to define \primary\ terms identified with the
-(now deprecated) entry type
+(now deprecated) \gls{entrytype}
\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
file is:
\begin{codeenv}
@@ -18663,7 +20307,7 @@ Note that this definition ignores the \meta{description} argument.
\formatdef{bibglsnewdualentryabbreviationsecondary}
This command is used to define \glsdisp{dualentry}{secondary} terms identified with the
-(now deprecated) entry type
+(now deprecated) \gls{entrytype}
\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
file is:
\begin{codeenv}
@@ -20497,6 +22141,26 @@ field using:
\section{Other}
+\cssection{bibglscopytoglossary}
+
+\formatdef{bibglscopytoglossary}
+This command is provided if the \csopt{copy-to-glossary} option is
+set and is used to copy an entry to another glossary. The definition
+is:
+\begin{codeenv}
+\cmd{providecommand}\marg{\gls{bibglscopytoglossary}}[2]{\comment{}
+ \ics{ifglossaryexists*}\marg{}\comment{}
+ \marg{\ics{GlsXtrIfInGlossary}\marg{\idx{param}1}\marg{\idx{param}2}\marg{}\marg{\ics{glsxtrcopytoglossary}\marg{\idx{param}1}\marg{\idx{param}2}}}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+This ensures that the entry is only copied if the glossary exists
+and if the entry hasn't already been copied to it.
+
+This command isn't used by the \csopt[copy]{action} or
+\csopt[copy or define]{action} settings, which use \ics{glsxtrcopytoglossary}
+directly.
+
\cssection{bibglssettotalrecordcount}
\formatdef{bibglssettotalrecordcount}
@@ -21536,7 +23200,7 @@ The contents of \filefmt{interpret-preamble2.bib} are as follows:
\filesection{constants.bib}
The \exfile{constants.bib} file contains mathematical constants.
-These all use a custom entry type \atentryfmt{constant}, which must
+These all use a custom \gls{entrytype} \atentryfmt{constant}, which must
be aliased otherwise the entries will all be ignored. The entries
all have custom fields, which also need to be aliased.
For example:
@@ -21570,7 +23234,7 @@ is treated as though it was defined as:
\field{category}=\marg{constant}
}
\end{codeenv}
-This use of custom fields and entry types allows more flexibility.
+This use of custom fields and \glspl{entrytype} allows more flexibility.
For example, I may have another document that uses the same
\ext{bib} file but requires a different definition:
\begin{codeenv}
@@ -21642,7 +23306,7 @@ so most packages should be loaded before \sty{glossaries-extra}.
Instead, I've just put a comment in the \ext{bib} file as a
reminder.
-All entries are defined using a custom entry type
+All entries are defined using a custom \gls{entrytype}
\atentryfmt{chemical}. This must be aliased using
\csopt{entry-type-aliases} or the entries will be ignored. For
example, to make \atentryfmt{chemical} behave like \atentry{symbol}:
@@ -21680,7 +23344,7 @@ The contents of \filefmt{chemicalformula.bib} are as follows:
\filesection{bacteria.bib}
The \exfile{bacteria.bib} file contains bacteria abbreviations.
-These all use the \atentry{abbreviation} entry type with a
+These all use the \atentry{abbreviation} \gls{entrytype} with a
\field{short} and \field{long} field.
The entries all have a custom field \fieldfmt{identifier} set to
@@ -21694,20 +23358,20 @@ The contents of \filefmt{bacteria.bib} are as follows:
\filesection{baseunits.bib}
The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries
-are all defined using the custom \atentryfmt{unit} entry
-type. This must be aliased with \csopt{entry-type-aliases} otherwise
+are all defined using the custom \atentryfmt{unit}
+\gls{entrytype}. This must be aliased with \csopt{entry-type-aliases} otherwise
\bibgls\ will ignore all the entries. For example:
\begin{codeenv}
\csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}
\end{codeenv}
will make \bibgls\ treat the entries as though they were defined
-using \atentry{symbol}. (Remember that \atentry{symbol} entry types use the label
-as the fallback field for \field{sort}.)
+using \atentry{symbol}. (Remember that \atentry{symbol} \glspl{entrytype}
+use the label as the fallback field for \field{sort}.)
The entries all have custom fields \fieldfmt{unitname},
\fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must
be aliased or copied to \field{name} if \atentryfmt{unit} is aliased
-to an entry type that requires it. The other custom fields may be aliased or
+to an \gls{entrytype} that requires it. The other custom fields may be aliased or
copied to \field{symbol} and \field{description} as required. The
\fieldfmt{unitsymbol} fields all use \ics{si} provided by the
\isty{siunitx} package, so that package must be loaded in the
@@ -21726,7 +23390,7 @@ The contents of \filefmt{baseunits.bib} are as follows:
\filesection{derivedunits.bib}
The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib}
-but contains derived units and in this case the custom entry type
+but contains derived units and in this case the custom \gls{entrytype}
is \atentryfmt{measurement}, which must be aliased
otherwise the entries will all be ignored.
The entries all have a custom field \fieldfmt{identifier} set to
@@ -21822,8 +23486,8 @@ An alternative approach would be to format the names using
\BibTeX's contributor syntax and use
\csopt[name]{bibtex-contributor-fields} to convert them.
-There are also some synonyms provided with \atentry{index} entry
-types that have the \field{alias} field to redirect to the
+There are also some synonyms provided with \atentry{index}
+\glspl{entrytype} that have the \field{alias} field to redirect to the
\gls{mainentry}. These don't include a \field{description} or any of the other
fields as that would be redundant. All the information can be found
in the \gls{mainentry}.
@@ -21855,7 +23519,7 @@ example, the \field{description} field could contain a brief summary
(or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's
syntax instead with \csopt{bibtex-contributor-fields} to convert it.
Alternatively, the entries could be defined using standard \BibTeX\
-entry types that are all aliased to \atentry{bibtexentry}.
+\glspl{entrytype} that are all aliased to \atentry{bibtexentry}.
The contents of \filefmt{books.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/books.bib}
@@ -21952,7 +23616,7 @@ The contents of \filefmt{films.bib} are as follows:
\filesection{citations.bib}
The \exfile{citations.bib} file is actually a \BibTeX\ file, but it
-can be parsed by \bibgls\ if the \BibTeX\ entry types are converted
+can be parsed by \bibgls\ if the \BibTeX\ \glspl{entrytype} are converted
to \atentry{bibtexentry}, which can easily be done with:
\begin{codeenv}
\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
@@ -22213,7 +23877,7 @@ and \csfmt{Lightning} commands:
This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning}
are as defined by \sty{marvosym}.
-This file uses a custom entry type \atentryfmt{icon}, which must be
+This file uses a custom \gls{entrytype} \atentryfmt{icon}, which must be
aliased to a recognised entry identifier otherwise the entries will
all be ignored. For example:
\begin{codeenv}
@@ -22809,7 +24473,7 @@ to use:
\csopt[all]{selection}
\end{codeenv}
in order to select all entries. I also need to alias the custom
-\atentryfmt{constant} entry type otherwise all the entries will be
+\atentryfmt{constant} \gls{entrytype} otherwise all the entries will be
ignored. I decided to make \atentryfmt{constant} behave like
\atentry{number} for semantic reasons:
\begin{codeenv}
@@ -22995,7 +24659,7 @@ efficient to instruct \bibgls\ to not save the number list with:
\csopt[false]{save-locations}
\end{codeenv}
All entries are defined in \exfile{chemicalformula.bib} using
-a custom entry type \atentryfmt{chemical} which needs to be aliased
+a custom \gls{entrytype} \atentryfmt{chemical} which needs to be aliased
in order for the entries to be recognised:
\begin{codeenv}
\csopt[chemical=symbol]{entry-type-aliases}
@@ -23006,7 +24670,7 @@ and the chemical name in the \field{description} field:
\begin{codeenv}
\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases}
\end{codeenv}
-The \atentry{symbol} entry type falls back on the label for the
+The \atentry{symbol} \gls{entrytype} falls back on the label for the
\field{sort} value by default, but I've decided
to fallback on the \field{name} field for sorting:
\begin{codeenv}
@@ -23227,14 +24891,14 @@ that may need extended characters in the group titles.
The \csopt{group} option requires the \longarg{group} switch to
ensure that the \field{group} field is correctly assigned.
-The \exfile{baseunits.bib} file use a custom entry type
+The \exfile{baseunits.bib} file use a custom \gls{entrytype}
\atentryfmt{unit}, which must be aliased otherwise \bibgls\
will ignore the entries. I decided to use \atentry{symbol} for
semantic reasons:
\begin{codeenv}
\csopt[unit=symbol]{entry-type-aliases}
\end{codeenv}
-Similarly for the custom \atentryfmt{measurement} entry type in
+Similarly for the custom \atentryfmt{measurement} \gls{entrytype} in
\exfile{derivedunits.bib}:
\begin{codeenv}
\csopt[measurement=symbol]{entry-type-aliases}
@@ -23305,7 +24969,7 @@ used with book or report type of classes. I've also used the
\styopt{nomain} option to suppress the creation of the \gls{mainglossary}
as I want to define my own glossary types instead.
-As before the custom entry types need to be aliased:
+As before the custom \glspl{entrytype} need to be aliased:
\begin{codeenv}
\csopt[unit=symbol]{entry-type-aliases}
\end{codeenv}
@@ -23358,7 +25022,7 @@ This time I want two glossaries containing all the units (base and
derived) where the first glossary is ordered by name and the second
is ordered by symbol. This can be done with a single resource
command that instructs \bibgls\ to make the custom \atentryfmt{unit}
-and \atentryfmt{measurement} entry types behave like
+and \atentryfmt{measurement} \glspl{entrytype} behave like
\atentry{dualsymbol}:
\begin{codeenv}
\csopt[
@@ -23368,7 +25032,7 @@ and \atentryfmt{measurement} entry types behave like
\end{codeenv}
This causes the \field{name} and \field{symbol} fields to be swapped in the
dual list. Remember that the fallback for the \field{sort} field is the label
-for the symbol entry types so I need \csopt[\field{name}]{symbol-sort-fallback}
+for the symbol \glspl{entrytype} so I need \csopt[\field{name}]{symbol-sort-fallback}
to fallback on \field{name} field instead. (Alternative, I could just sort by
the \field{name} field instead using \csopt[\field{name}]{sort-field}.)
@@ -24086,7 +25750,7 @@ modified version of \gls{bibglsnewbibtexentry} that assigns
\gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{}
}
\end{codeenv}
-The standard \BibTeX\ entry types need aliasing to
+The standard \BibTeX\ \glspl{entrytype} need aliasing to
\atentry{bibtexentry}:
\begin{codeenv}
\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
@@ -24096,7 +25760,7 @@ and the \fieldfmt{title} field is aliased to \field{name}:
\csopt[\fieldfmt{title}=\field{name}]{field-aliases}
\end{codeenv}
(The other fields aren't required for the glossary lists.)
-The \field{category} is set to the original entry type:
+The \field{category} is set to the original \gls{entrytype}:
\begin{codeenv}
\csopt[same as original entry]{category}
\end{codeenv}
@@ -24105,7 +25769,7 @@ So, for example, an entry that's provided in the \ext{bib} file with
\code{article}. (Compare this with \csopt[same as entry]{category}
which would set the \field{category} to \code{bibtexentry}.)
The spawned entries are all defined using \atentry{contributor} and
-aren't aliased so both the entry type and the original entry type
+aren't aliased so both the \gls{entrytype} and the original \gls{entrytype}
are \code{contributor}.
In order to list the titles according to category, I've use this as
@@ -24157,7 +25821,7 @@ same label, the citation can easily be obtained with
\cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
\cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
\end{codeenv}
-Note that this needs to be done for each \BibTeX\ entry type, but in
+Note that this needs to be done for each \BibTeX\ \gls{entrytype}, but in
this case the \ext{bib} file only contains \atentryfmt{article} and
\atentryfmt{book} entries. (Similarly for the group titles above.)
@@ -24417,7 +26081,7 @@ generic \cs{textweathersymbol} command and omit the \styoptfmt{weather}
option when loading the package, but the method used here
demonstrates how to deal with such conflicts.)
-The custom entry type \atentryfmt{icon} must be aliased for the
+The custom \gls{entrytype} \atentryfmt{icon} must be aliased for the
entries to be recognised:
\begin{codeenv}
\csopt[icon=symbol]{entry-type-aliases}
@@ -24498,7 +26162,7 @@ This example is a better approach than the
example, this requires both \isty{marvosym} and \isty{ifsym} so the
same patch is applied to avoid conflict.
-As before, the custom entry type \atentryfmt{icon} must be aliased for the
+As before, the custom \gls{entrytype} \atentryfmt{icon} must be aliased for the
entries to be recognised:
\begin{codeenv}
\csopt[icon=symbol]{entry-type-aliases}
@@ -24523,7 +26187,7 @@ There's no \csopt{sort-field} option in this example. The default
entries, the fallback value will be used. In the case of the topic
titles (\atentry{index} and \atentry{indexplural}), I want to sort
by the \field{name}, which is the default fallback if the
-\field{sort} field is missing for the index entry types.
+\field{sort} field is missing for the index \glspl{entrytype}.
The default fallback for the \field{sort} field for \atentry{symbol}
entries is the label, but in this case I want to use the
@@ -25208,7 +26872,7 @@ decided to use a dual entry system. Since the entries aren't defined
using any dual types, I've used \csopt{entry-type-aliases} to
make \bibgls\ treat them as though they were, and I also need to
alias the custom \atentryfmt{chemical}, \atentryfmt{unit} and
-\atentryfmt{measurement} entry types:
+\atentryfmt{measurement} \glspl{entrytype}:
\begin{codeenv}
\csopt[
abbreviation=dualindexabbreviation,
@@ -25241,15 +26905,15 @@ defined before \gls{GlsXtrLoadResources}:
\field{category}=\marg{index},\idx{param}3}\marg{}\comment{}
}
\end{codeenv}
-However, this will affect all \atentry{dualindexabbreviation} entry
-types, but it's not necessary for the bacteria abbreviations.
+However, this will affect all \atentry{dualindexabbreviation}
+\glspl{entrytype}, but it's not necessary for the bacteria abbreviations.
Instead it's simpler to just keep a record of the dual label so that
the short form can be obtained from the dual entry:
\begin{codeenv}
\csopt{dual-field}
\end{codeenv}
-By default, the \atentry{dualindexabbreviation} entry type falls back on the
+By default, the \atentry{dualindexabbreviation} \gls{entrytype} falls back on the
\field{short} field if the \field{name} is omitted. In this case I
want it to fall back on the \field{long} field instead.
\begin{codeenv}
@@ -25300,15 +26964,15 @@ I've also redefined \cs{glstreenamefmt} to prevent the names
appearing in bold, which means I also need to redefine
\cs{glstreegroupheaderfmt} to keep the headers bold.
-All the \atentryfmt{dualindex\meta{type}} entry types provide a primary
+All the \atentryfmt{dualindex\meta{type}} \glspl{entrytype} provide a primary
entry that behaves like \atentry{index}. The secondary behaves like
\atentryfmt{\meta{type}}. This means that the primaries are
conveniently gathered together with all the unaliased \atentry{index}
-entries, so the primary entry type needs to be set to \code{index}:
+entries, so the primary \gls{entrytype} needs to be set to \code{index}:
\begin{codeenv}
\csopt[index]{type}
\end{codeenv}
-The dual entry type depends on the entry's category. Since I've
+The dual \gls{entrytype} depends on the entry's category. Since I've
defined my custom glossaries with a label that matches the
custom \fieldfmt{identifier} field, I can both alias this custom field
to the \field{category} field and also set \csopt{dual-type} so that
@@ -25524,7 +27188,7 @@ and \figureref{fig:sample-multi1.pdf2}.
\filesection{sample-multi2.tex}
This example is an alternative approach to
-\exfile{sample-multi1.tex}. Instead of using dual entry types to
+\exfile{sample-multi1.tex}. Instead of using dual \glspl{entrytype} to
define entries that appear in both a glossary and the index, this
example makes use of \csopt{record-label-prefix} to reselect the
recorded entries for the index. This is more complicated but it
@@ -25866,7 +27530,7 @@ The abbreviations all need to be sorted according to the long form:
\begin{codeenv}
\csopt[\field{long}]{abbreviation-sort-fallback}
\end{codeenv}
-The custom entry types and fields again need to be aliased
+The custom \glspl{entrytype} and fields again need to be aliased
\begin{codeenv}
\csopt[
chemical=index,
@@ -25891,8 +27555,8 @@ The chemical formulae and icons are now defined using
they're appropriate for alphabetical sorting. (Both \atentry{entry}
and \atentry{symbol} require the \field{description} field, which is
why I've aliased \atentryfmt{chemical} and \atentryfmt{icon}
-to \atentry{index} here.) The custom \atentryfmt{measurement} entry
-type has a \field{description} field (obtained from
+to \atentry{index} here.) The custom \atentryfmt{measurement}
+\gls{entrytype} has a \field{description} field (obtained from
\fieldfmt{unitname}), so that's aliased to \atentry{entry} as again
the \field{name} field is suitable for alphabetical sorting.