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.tex732
1 files changed, 695 insertions, 37 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index f8fa262b5b..7b888ea485 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/support/bib2gls/src/bib2gls.tex
@@ -151,7 +151,7 @@
},
max-loc-diff={2},
see=omit,seealso=omit,alias=omit,
- field-aliases={topics=adoptparents},
+ field-aliases={topics=adoptparents,annote=user2},
replicate-fields={name=nametitle,progeny=unsortedprogeny},
field-case-change={nametitle=title},
interpret-fields={nametitle},
@@ -296,7 +296,7 @@
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
-\newcommand{\stringu}{\idx{cs.string}\idx{u}}
+\newcommand{\stringu}{\idx{cs.string}\idx{uhex}}
\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand*{\metafilefmt}[3]{%
@@ -1080,6 +1080,8 @@
\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}}
+\newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}}
+
\newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}}
\newcommand{\argsection}[2][\section]{%
@@ -1891,22 +1893,29 @@ Although \idxpl{ignoredglossary} can't be used with
\cs{printglossary}, they can be used with \cs{printunsrtglossary},
which is designed to work without any indexing, but you need to
explicitly set the title in the optional argument to override the
-default. The \idxpl{ignoredglossary} still can't be used in
+default. \Idxpl{ignoredglossary} still can't be used in
\cs{printunsrtglossaries}, since they're not included in the list
that this command iterates over.
-So \cs{newignoredglossary} is useful with \bibgls\ if you're happy
-to use \cs{printunsrtglossary} as it reduces the overall number of
-internal control sequences. Since there is now the possibility of
-targets (created within \cs{printunsrtglossary}), it's useful to
+So \cs{newignoredglossary} (or \cs{provideignoredglossary}) is
+useful with \bibgls\ if you're happy to use \cs{printunsrtglossary}
+with the \printglossopt{type} and \printglossopt{title} options as it reduces the overall
+number of internal control sequences. \Idxpl{ignoredglossary} are
+also useful for stand-alone definitions (\ics{glsxtrglossentry}) or
+with \ics{printunsrtinnerglossary} as no title is required in those
+cases (see \exfile{sample-nested.tex} for an example).
+
+Since there is now the possibility of targets (created within \cs{printunsrtglossary} or
+\cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to
have an \idx{ignoredglossary} that doesn't suppress the hyperlinks,
which can be obtained with the starred form \ics{newignoredglossary*}
-provided by \styfmt{glossaries-extra}.
+provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}).
Some resource options, such as \csopt{master}, \csopt{secondary} and
\csopt{trigger-type}, need to ensure that a
required glossary is defined. In this case, \bibgls\ uses
-\ics{provideignoredglossary*} in the \iext{glstex} file. If you
+\ics{provideignoredglossary*} in the \iext{glstex} file
+even if \longarg{no-provide-glossaries} is set. If you
haven't already defined that glossary in the document with \cs{newglossary*},
you'll need to set the title in the optional argument of
\cs{printunsrtglossary} if you don't want the default. The glossary
@@ -1915,6 +1924,27 @@ provided in the \ext{glstex} file) but \cs{printunsrtglossary} will
just give a warning if the type is undefined so it won't interrupt
the document build.
+If you want \bibgls\ to automatically provide unknown glossaries for
+all entries that have the \field{type} field set (unrelated to the
+\csopt{master}, \csopt{secondary} and \csopt{trigger-type} options)
+then use the \longarg{provide-glossaries} switch.
+
+The base \sty{glossaries} package provides a command that can be
+used to test the existence of a glossary:
+\begin{codeenv}
+\ics{ifglossaryexists}\margm{label}\margm{true}\margm{false}
+\end{codeenv}
+The unstarred version considers ignored glossaries as non-existent
+(and so will do \meta{false} for an ignored glossary). As from
+v4.46, this command now has a starred version
+\ics{ifglossaryexists*} that considers ignored glossaries as
+existing (and so will do \meta{true} for an ignored glossary). In
+the event that you have an older version of \sty{glossaries}, the
+\sty{glossaries-extra} package (v1.44+) will provide the starred
+form if it hasn't been defined. (In general, it's best to have
+up-to-date versions of both \sty{glossaries} and
+\sty{glossaries-extra}.)
+
\section{Resource Sets}
\label{sec:resourcesets}
@@ -3785,6 +3815,30 @@ bib2gls --trim-except-fields short --trim-except-fields long myDoc
Don't trim any leading or trailing spaces from field values (but see
the above note about \sty{xkeyval}). This is the default setting.
+\argsection{provide-glossaries}
+
+This setting will make \bibgls\ add the line
+\begin{codeenv}
+\ics{provideignoredglossary*}\margm{type}
+\end{codeenv}
+to the \ext{glstex} file before an entry is defined where that entry
+has the \field{type} field set to an unknown glossary type (\bibgls\
+can detect from the \ext{aux} file all glossaries that have been
+defined with \cs{newglossary} but not those defined with \cs{newignoredglossary}).
+
+This ensures that the glossary exists, but the use of
+\ics{provideignoredglossary} (rather than \cs{newignoredglossary})
+will prevent an error if the glossary has already been defined.
+
+\argsection{no-provide-glossaries}
+
+This setting prevents \bibgls\ from providing unknown glossaries,
+except in a few documented situations (the \csopt{master},
+\csopt{trigger-type} and \csopt{secondary} options). This is the
+default since it's a useful way of detecting misspelt glossary
+labels. It's harder to detect the problem if a misspelt label has
+caused an entry to be added to a hidden glossary.
+
\argsection{record-count}
Switch on record counting. This will ensure that when each entry
@@ -4441,7 +4495,7 @@ For example:
\end{codeenv}
If the \field{sort} field is missing the default is obtained from
-the \field{name} field (unless overridden by
+the \field{name} field (unless overridden by options like
\csopt{entry-sort-fallback}). For hierarchical entries, if the
\field{name} field is omitted it will be obtained from the parent's
\field{name}.
@@ -4465,7 +4519,7 @@ designed specifically for symbols, so in the previous example, the
The required fields are \field{name} or \field{parent}. The
\field{description} field is required if the \field{name} field is
missing. If the \field{sort} field is omitted, the default sort is
-given by the entry label (unless overridden by
+given by the entry label (unless overridden by options like
\csopt{symbol-sort-fallback}). Note that this is different from
\atentry{entry} where the sort defaults to \field{name} if omitted.
@@ -4529,7 +4583,8 @@ entry.) If the name contains any characters that can't be used in
the label, you must use the \field{name} field. If the \field{sort}
field is missing the default is obtained from the \field{name}.
Note that the \atentry{index} entry type is \emph{not} governed by
-\csopt{entry-sort-fallback}. This allows \atentry{index} and
+\csopt{entry-sort-fallback} (but it is governed by
+\csopt{custom-sort-fallbacks}). This allows \atentry{index} and
\atentry{entry} to have different fallbacks if the \field{sort}
field is missing.
@@ -4554,7 +4609,8 @@ field with the plural suffix appended. If the \field{text} field is
missing, it's obtained from the original entry label. If the
\field{sort} field is missing the default is obtained from the
\field{name} field. (As with \atentry{index}, \atentry{indexplural}
-is \emph{not} governed by \csopt{entry-sort-fallback}.)
+is \emph{not} governed by \csopt{entry-sort-fallback}, but it is
+governed by \csopt{custom-sort-fallbacks}.)
All fields are optional. For example:
\begin{codeenv}
\atentry{indexplural}\marg{goose,
@@ -7232,6 +7288,21 @@ setting but parents are added even if they haven't been referenced
in the document. The other dependent entries are omitted if they
haven't been referenced in the document.
+\item \optfmt{deps but not recorded}: this first selects entries as
+though \optfmt{recorded and deps} had been used, but after all
+ancestors and dependencies have been added it then removes all
+entries that have records. This means that you end up with only the
+unrecorded dependencies. (Recorded entries will need to be selected
+in a different resource set.)
+
+\item \optfmt{ancestors but not recorded}: this first selects
+entries as though \optfmt{recorded and ancestors} had been used, but
+after all ancestors have been added it then removes all entries that
+have records. This means that you end up with only the unrecorded
+ancestors. (Recorded entries will need to be selected
+in a different resource set.) See the \exfile{sample-nested.tex}
+example document.
+
\item \optfmt{all}: add all entries found in the \ext{bib} files
supplied in the \csopt{src} option.
\end{itemize}
@@ -8197,7 +8268,8 @@ or \csopt{category} options haven't been used, the corresponding
value will default to \optfmt{master}. The \catattr{targeturl}
and \catattr{targetname} category attributes will automatically be
set, and the glossary type will be provided using
-\code{\ics{provideignoredglossary*}\margm{type}}.
+\code{\ics{provideignoredglossary*}\margm{type}} (even if
+\longarg{no-provide-glossaries} is set).
The above \filefmt{myarticle.tex} can be changed to:
\begin{codeenv}
@@ -9110,6 +9182,7 @@ the keywords allowed by \csopt{type}).
You can define the glossary before loading the resource, but
it's not required as \bibgls\ will write
\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file
+even if \longarg{no-provide-glossaries} is set
(see \sectionref{sec:newglossary}).
\optsection[\subsubsection]{progenitor-type}
@@ -9146,7 +9219,8 @@ missing and it's required for some reason (for example, with
fallback on a different field, then you can use this option to
specify the field. For example,
\csopt[long]{abbreviation-name-fallback}.
-The \meta{field} value must be a known field label.
+The \meta{field} value must be a known field (not an internal field)
+but can't be the \field{sort} field.
\optsection[\subsubsection]{ignore-fields}
@@ -10064,7 +10138,7 @@ contains definitions like:
}
\end{codeenv}
Instead of having a list of terms (glossary), suppose I want to have
-standalone definitions, where the term appears in a section heading.
+stand-alone definitions, where the term appears in a section heading.
I could define a command like this:
\begin{codeenv}
\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
@@ -10232,7 +10306,7 @@ by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
\subsection{Prefix Fields}
-\label{sec:prefixes}
+\label{sec:prefixfields}
If you use the \isty{glossaries-prefix} package, the prefix
set of fields become available (\field{prefix},
@@ -12763,15 +12837,20 @@ list that's the exact reverse of the underlying non-reversed
can affect the order.
\begin{table}[p]
-\caption{Summary of Available Sort Options: No Actual Sorting}
+\caption{Summary of Available Sort Options: No Sort Field}
\label{tab:sortoptionsnosort}
\centering
\begin{tabular}{ll}
\optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline
\optfmt{random} & shuffle entries\tabularnewline
\optfmt{use} & order of use\tabularnewline
-\optfmt{use-reverse} & reverse order of use
+\optfmt{use-reverse} & reverse order of use\tabularnewline
+\optfmt{recordcount}\textsuperscript\textdagger & order of record count\tabularnewline
+\optfmt{recordcount-reverse}\textsuperscript\textdagger & reverse order of record count
\end{tabular}
+\par
+\medskip
+\textsuperscript\textdagger Requires \longarg{record-count} switch.
\end{table}
\begin{table}[p]
@@ -12885,12 +12964,15 @@ sort\tabularnewline
\end{tabular}
\end{table}
-\subsubsection{No Sort}
+\subsubsection{No Sort Field}
-The sort methods listed in \tableref{tab:sortoptionsnosort}
+Most of the sort methods listed in \tableref{tab:sortoptionsnosort}
don't actually perform any sorting. This may cause a problem for
hierarchical entries. In some cases this can lead to detached child
entries or an attempt to define a child entry before its parent.
+The methods listed in this section all ignore the \csopt{sort-field}
+setting and all the various sort fallback settings, except where
+noted below.
\begin{itemize}
\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries.
@@ -12916,8 +12998,103 @@ first use of that term that's used as the sort value.
\item \optfmt{use-reverse}: reverses the order that would be
obtained with \csopt[use]{sort} without reference to hierarchy.
+\item \optfmt{recordcount}: order of record count (starting from 0). This order is
+determined by the total number of records written to the \iext{aux}
+file for each entry. Unlike the above methods, this performs a hierarchical sort.
+If letter groups are enabled with \longarg{group}, this method will assign the entries to
+the \idx{numbergroup}.
+
+This option requires the \longarg{record-count} switch. Although
+that switch makes \bibgls\ write the total record count to the
+\ext{glstex} file in the \field{recordcount} internal field (so that it
+can be accessed in the document), \bibgls\ doesn't actually have a
+field itself that contains the information. So although this option
+behaves much like \csopt[integer]{sort} it's not possible to select
+a field containing the required value. In the event of two or more
+entries having the same record count, the
+\csopt{identical-sort-action} option is used to determine the
+relative ordering between them.
+
+\item \optfmt{recordcount-reverse}: reverse order of record count
+(ending with 0). All the above notes applying to
+\optfmt{recordcount} also apply here.
+
\end{itemize}
+Suppose the file \filefmt{entries.bib} contains
+definitions of a set of symbols that don't have any intuitive
+ordering (for example, they are all pictographs) then there may be
+no point in trying to order them, in which case you can do:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[none]{sort}}
+\end{codeenv}
+Alternatively, you could list them in order of use:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
+\end{codeenv}
+or by frequency of use. For example, starting with entries that
+don't have any records followed by the least used entries (a rarely-used symbol
+may be harder to remember and most likely to be looked up in the glossary):
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount]{sort}}
+\end{codeenv}
+Or starting with the most used entries:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[recordcount-reverse]{sort}}
+\end{codeenv}
+It all depends on what's likely to be most useful to the reader.
+
+Consider the following:
+\begin{codeenv}
+\ics{newglossary*}\marg{frequent}\marg{Most Frequently Used Terms}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort},
+ \csopt[recordcount-reverse:frequent]{secondary}
+}
+\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
+ \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
+ \marg{}\comment{}
+ \marg{\ics{printunsrtglossaryskipentry}}\comment{}
+}
+\csfmt{begin}\marg{document}
+\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},\printglossopt[frequent]{type}}\marg{\comment{}
+ \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
+}
+\comment{Main body of the document \ldots}
+\cs{printunsrtglossary}
+\csfmt{end}\marg{document}
+\end{codeenv}
+This has a summary at the start of the document that only contains
+entries that have at least 10 records and is ordered according to
+the total number of records (starting with the most frequently used
+entry). The main glossary at the end of the document is ordered
+according to use and contains all selected entries.
+
+Compare this with the following:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[use]{sort}}
+\cs{newcommand}\marg{\csfmt{filterhook}}[1]\marg{\comment{}
+ \ics{GlsXtrIfFieldCmpNum}*\marg{\field{recordcount}}\marg{\idx{hashchar}1}\marg{>}\marg{10}\comment{}
+ \marg{}\comment{}
+ \marg{\ics{printunsrtglossaryskipentry}}\comment{}
+}
+\csfmt{begin}\marg{document}
+\cs{printunsrtglossary*}\oarg{\printglossopt[false]{target},
+ \printglossopt[Most Frequently Used Terms]{title}}\marg{\comment{}
+ \cs{let}\ics{printunsrtglossaryentryprocesshook}\csfmt{filterhook}
+}
+\comment{Main body of the document \ldots}
+\cs{printunsrtglossary}
+\csfmt{end}\marg{document}
+\end{codeenv}
+This again has a summary at the start of the document that only
+contains entries that have at least 10 records but is now ordered
+according to use.
+
+Both examples assume there are no child entries as the filtering can
+cause parent entries to be omitted. Both examples require
+\longarg{record-count} but only the first example sorts according to
+the record count.
+
\subsubsection{Alphabet}
The sort methods listed in \tableref{tab:sortoptionsrule} are for
@@ -12936,7 +13113,7 @@ given by the \idx{IETF} language tag \meta{lang tag}.
\item \optfmt{locale}: equivalent to
\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
-from the \idx{JRE} (which usually matches the
+from the \idx{JRE}['s] default locale (which usually matches the
operating system's locale).
\item \optfmt{locale-reverse}: equivalent to
@@ -13382,7 +13559,7 @@ results in the order:
\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
\code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
-Remember that the associated settings are reversed
+Remember that the associated settings are reversed as
well. So \csopt[before letter]{letter-number-rule}
results in numbers \emph{after} letters.
@@ -13478,7 +13655,7 @@ decimal sort values.
\item \optfmt{double}: double-precision sort. This is for non-locale
decimal sort values.
-\item \optfmt{float-reverse}: as above but reverses the order.
+\item \optfmt{double-reverse}: as above but reverses the order.
\item \optfmt{numeric}: locale-sensitive numeric sort. Use
\csopt{numeric-locale} to set the locale.
@@ -13638,13 +13815,20 @@ Example:
\begin{codeenv}
\gls{GlsXtrLoadResources}\oarg{
\csopt[entries-terms]{src},\comment{data in entries-terms.bib}
- \csopt[category]{sort-field},\comment{sort by 'category' field}
+ \csopt[symbol]{sort-field},\comment{sort by 'symbol' field}
\csopt[letter-case]{sort}\comment{case-sensitive letter sort}
}
\end{codeenv}
-This sorts the entries according to the \field{category} field using
+This sorts the entries according to the \field{symbol} field using
a case-sensitive letter comparison.
+\begin{important}
+In general it's better to use the default \csopt[sort]{sort-field}
+and adjust the fallbacks instead. The \csopt{sort-field} option is
+provided if you want to use a specific field regardless of the entry
+type.
+\end{important}
+
If an entry is missing a value for \meta{field}, then the value of
the fallback field will be used instead. If \csopt{missing-sort-fallback} is
set, then that's used as the fallback, otherwise it depends on the
@@ -13656,6 +13840,11 @@ setting, the fallback for the \field{sort} field is governed not
only by the entry type but also by some associated settings:
\begin{itemize}
+\item If the entry's original type (before being aliased with
+\csopt{entry-type-aliases}) is identified in
+\csopt{custom-sort-fallbacks}, then if the \field{sort} field is missing
+the value is obtained from the supplied custom mapping.
+
\item If the entry is defined using \atentry{entry} (or a dual form
that acts like \atentry{entry}), then if the \field{sort} field is
missing the value is obtained from the field identified by
@@ -13698,9 +13887,21 @@ follows:
\meta{fallback-field}. If \meta{fallback-field} is
missing, then \bibgls\ will query the entry type's fallback for
\meta{fallback-field} (not for \meta{sort-field}).
+
+The \meta{fallback-field} must be a known field but not an internal
+field. It can't be the \field{sort} field. (Take care not to cause
+an infinite loop if \csopt{sort-field} has been changed.) Unlike the
+other sort fallback options such as \csopt{entry-sort-fallback}, the
+\meta{fallback-field} can't be a keyword (to identify the label) and can't be a
+composite.
+
\item If the entry type has a fallback rule for \meta{sort-field},
then that rule is used. When \csopt[sort]{sort-field} this means:
\begin{itemize}
+\item If the entry's original entry type has been identified in
+\csopt{custom-sort-fallbacks}, then \bibgls\ will fallback on the
+designated custom setting.
+
\item If the entry was defined using one of the index types (such as
\atentry{index}), then \bibgls\ will fallback on the \field{name}
field.
@@ -13736,6 +13937,121 @@ separately from primaries, and use
\csopt{secondary-missing-sort-fallback} for \csopt{secondary}
sorting.
+\optsection{custom-sort-fallbacks}
+
+The value should be a \keyvallist\ in the form
+\meta{entrytype}\dequals\meta{field} where \meta{entrytype} is the
+\emph{original} entry type (before being aliased with
+\csopt{entry-type-aliases}). This will override any of the sort fallback
+options listed below for entries whose original entry type matches
+\meta{entrytype}.
+
+The \meta{field} may be a known field but not an internal field. For
+obvious reasons, it can't be the \field{sort} field (since
+\meta{field} is the fallback a missing \field{sort} field). It may also be one of the
+keywords: \optfmt{id} (for the entry's label) or \optfmt{original id}
+(for the entry's original label). The \meta{field} may also be a
+composite in the form \optfmt{\meta{field1}+\meta{field2}+\ldots}
+which indicates that the sort value should be obtained by
+concatenating the values of the given fields, where the separator is
+given by \csopt{field-concat-sep}.
+
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentryfmt{unit}\marg{ohm,
+ \field{name}=\marg{\cs{si}\marg{\csfmt{ohm}}},
+ \field{description}=\marg{electrical resistance}
+}
+\strut
+\atentryfmt{constant}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{the ratio of the length of the circumference
+ of a circle to its diameter},
+ \field{user1}=\marg{3.14159}
+}
+\strut
+\atentry{symbol}\marg{fx,
+ \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
+ \field{description}=\marg{a function of \idx{mshiftchar}x\idx{mshiftchar}}
+}
+\strut
+\atentry{number}\marg{zero,
+ \field{name}=\marg{0},
+ \field{description}=\marg{nothing or no quantity}
+}
+\end{codeenv}
+Then the resource options:
+\begin{codeenv}
+\csopt[\entryfmt{unit}=\entryref{symbol},\entryfmt{constant}=\entryref{number}]{entry-type-aliases},
+\csopt[\entryfmt{unit}=\field{name},\entryfmt{constant}=\field{user1}]{custom-sort-fallbacks}
+\end{codeenv}
+will treat the custom \atentryfmt{unit} and \atentryfmt{constant}
+entries as though they had been defined with \atentry{symbol}
+and \atentry{number}, respectively, but the fallback for the
+\field{sort} field is different: the \code{ohm} entry will use the
+\field{name} field for the sort fallback (because its original entry
+type was \entryfmt{unit}), the \code{pi} entry will use the
+\field{user1} field for the sort fallback (because its original
+entry type was \entryfmt{constant}) and the \code{fx} and
+\code{zero} entries will use the label for the sort fallback (since
+neither \entryfmt{symbol} nor \entryfmt{number} were identified in
+\csopt{custom-sort-fallbacks} so the \csopt{symbol-sort-fallback} is
+used).
+
+If an entry hasn't had its entry type aliased then \meta{entrytype}
+is its actual entry type. For example, consider the following
+definitions:
+\begin{codeenv}
+\atentry{abbreviation}\marg{svm,
+ \field{short}=\marg{SVM},
+ \field{long}=\marg{support vector machine}
+}
+\atentry{acronym}\marg{laser,
+ \field{short}=\marg{laser},
+ \field{long}=\marg{light amplification by stimulated emission of radiation}
+}
+\end{codeenv}
+Then \csopt[short]{abbreviation-sort-fallback} will make both
+entries fallback on the \field{short} field (since
+\csopt{abbreviation-sort-fallback} applies to both \atentry{acronym}
+and \atentry{abbreviation}), but the option:
+\begin{codeenv}
+\csopt[\entryref{abbreviation}=\field{long},\entryref{acronym}=\field{short}]{custom-sort-fallbacks}
+\end{codeenv}
+will make the entry defined with \atentry{abbreviation} fallback on
+the \field{long} field and the entry defined with \atentry{acronym}
+will fallback on the \field{short} field.
+
+Since the default setting is \csopt[short]{abbreviation-sort-fallback}
+this only needs to be:
+\begin{codeenv}
+\csopt[\entryref{abbreviation}=\field{long}]{custom-sort-fallbacks}
+\end{codeenv}
+In this case, the entry defined with \atentry{abbreviation} (\qt{SVM}) will use
+the setting given in \csopt{custom-sort-fallbacks}, but the entry
+defined with \atentry{acronym} (\qt{laser}) will use the setting given by
+\csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't
+been identified in \csopt{custom-sort-fallbacks}.
+
+This option also covers dual entries. For example:
+\begin{codeenv}
+\csopt[
+ \entryref{dualindexnumber}=\field{description},
+ \entryfmt{dualindexnumbersecondary}=\field{user1}
+]{custom-sort-fallbacks}
+\end{codeenv}
+Note that the entry type for the dual is in the form
+\code{\meta{primary entry type}secondary}.
+
+\begin{important}
+The \csopt{custom-sort-fallbacks} setting is only used when \bibgls\
+tries to access the \field{sort} field for an entry (whose original
+entry type has been identified in this setting) and finds that the field
+hasn't been set. This means that this setting has no effect if you
+explicitly set the \field{sort} field or if you change the field
+used for sorting (\csopt{sort-field}).
+\end{important}
+
\optsection{entry-sort-fallback}
The regular entry types (such as \atentry{entry} and
@@ -13744,7 +14060,17 @@ field if the \field{sort} field is missing (assuming
\csopt[sort]{sort-field}). If you prefer to
fallback on a different field, then you can use this option to
specify the field.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
+
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
This setting doesn't affect the index type of entries, such as
\atentry{index} or \atentry{indexplural}. This is useful if your
@@ -13761,7 +14087,7 @@ my file \filefmt{entries.bib} contains:
\strut
\atentry{entry}\marg{glossarylist,
\field{parent}=\marg{glossary},
- \field{description}={list of technical words}
+ \field{description}=\marg{list of technical words}
}
\strut
\atentry{entry}\marg{glosscol,
@@ -13842,9 +14168,19 @@ specify the field. For example,
\csopt[long]{abbreviation-sort-fallback}. Note that if you use
\csopt[name]{sort-field}, then the fallback field will be given by
\csopt{abbreviation-name-fallback} if the \field{name} field is
-omitted. The \meta{field} value must be a known field label.
+omitted.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
+
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\
@@ -13857,14 +14193,23 @@ for sorting (\csopt{sort-field}).
\optsection{symbol-sort-fallback}
The entry types that define symbols (such as \atentry{symbol} and
-\atentry{number}) will, by default, fallback on the label if the
+\atentry{number}) will, by default, fallback on the entry's original label if the
\field{sort} field is missing (assuming the default
\csopt[sort]{sort-field}). If you prefer to fallback on a different
field, then you can use this option to specify the field. For
-example, \csopt[name]{symbol-sort-fallback}. The \meta{field} value
-must be a known field label.
+example, \csopt[name]{symbol-sort-fallback}.
+
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{symbol-sort-fallback} setting is only used when \bibgls\
@@ -13882,7 +14227,17 @@ fallback on the \field{name} if the
\csopt[sort]{sort-field}). If you prefer to fallback on a different
field, then you can use this option to specify the field.
-Note that \csopt{missing-sort-fallback} overrides this setting.
+The \meta{field} may be a known field but not an internal
+field. It can't be the \field{sort} field. It may also be
+one of the keywords: \optfmt{id} (for the entry's label) or
+\optfmt{original id} (for the entry's original label). The
+\meta{field} may also be a composite in the form
+\optfmt{\meta{field1}+\meta{field2}+\ldots} which indicates that the
+sort value should be obtained by concatenating the values of given fields,
+where the separator is given by \csopt{field-concat-sep}.
+
+Note that \csopt{missing-sort-fallback} and
+\csopt{custom-sort-fallbacks} override this setting.
\begin{important}
The \csopt{bibtexentry-sort-fallback} setting is only used when
@@ -13893,6 +14248,60 @@ explicitly set the \field{sort} field or if you change the field used for
sorting (\csopt{sort-field}).
\end{important}
+\optsection{field-concat-sep}
+
+This option sets the field concatenation separator to \meta{value}.
+The default is a space. An empty value indicates no separator. You
+may use \ics{uhex}\meta{hex} to indicate a character by its hexadecimal
+code. For example, suppose the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{abbreviation}\marg{ac,
+ \field{short}=\marg{AC},
+ \field{long}=\marg{alternating current}
+}
+\atentry{index}\marg{acacia}
+\end{codeenv}
+Then the resource option:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[letter-nocase]{sort},
+ \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
+}
+\end{codeenv}
+will set the \code{ac} sort value to \qt{AC alternating current}.
+That is, the \field{short} value concatenated with the \field{long}
+value using the default space separator. With the
+\optfmt{letter-nocase} sort method, this will put the \code{ac}
+entry before the \code{acacia} entry (because the space character
+comes before \qt{a}).
+
+If the resource options are changed to:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[letter-nocase]{sort},
+ \csopt[\empty]{field-concat-sep},
+ \csopt[\field{short}+\field{long}]{abbreviation-sort-fallback}
+}
+\end{codeenv}
+This will obtain the sort value for abbreviations from a
+concatenation of the \meta{short} and \meta{long} values without a
+separator. This means that the \code{ac} sort value will be
+\qt{ACalternating current} and so the \code{ac} entry will
+come after the \code{acacia} entry (since \qt{l} comes after \qt{c}).
+
+This setting is only used for the sort fallback options that allow
+field concatenation (such as \csopt{entry-sort-fallback} but not
+\csopt{missing-sort-fallback}).
+
+Note that due to the way that the \keyvallist\ parser trims leading and
+trailing spaces, you can't simply do \csopt[\space]{field-concat-sep}
+to indicate a space character as the value will end up as an empty
+string. You can instead do \csopt[\stringu20]{field-concat-sep} but
+since this is the default value there shouldn't be much need for it.
+
+Remember that the separator may be replaced with a break point
+marker depending on the sort method and \csopt{break-at} setting.
+
\optsection{trim-sort}
If the interpreter is used to determine the sort value, this setting
@@ -15040,7 +15449,8 @@ in the secondary glossary will be the same as for the primary
glossary.
(If the glossary \meta{type} doesn't exist, it will be
-defined with \ics{provideignoredglossary*}\margm{type}.)
+defined with \ics{provideignoredglossary*}\margm{type}
+even if \longarg{no-provide-glossaries} is set.)
Note that if the glossary already exists and contains entries,
the existing entries aren't re-ordered. The new entries are
simply appended to the list.
@@ -19777,6 +20187,251 @@ The \exfile{topics.bib} file contains entries defined using
The contents of \filefmt{topics.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/topics.bib}
+\filesection{sample-hierarchical.tex}
+
+This example uses the \exfile{terms.bib}, \exfile{animals.bib},
+\exfile{minerals.bib} and \exfile{vegetables.bib} files to create a
+hierarchical glossary. These are specified with the resource option:
+\begin{codeenv}
+\csopt[{terms,animals,minerals,vegetables}]{src}
+\end{codeenv}
+The custom \fieldfmt{identifier} field is
+aliased to the \field{parent} field since it conveniently matches
+the labels of the animal, mineral and vegetable entries in the
+\exfile{terms.bib} file:
+\begin{codeenv}
+\csopt[{identifier=parent}]{field-aliases}
+\end{codeenv}
+The default \csopt{selection} setting means that only those terms
+referenced in the document and their dependencies are selected. The
+referenced entries simply have \qt{1} in the \idx{locationlist} as
+it's only a trivial single-paged example.
+
+The dependencies that haven't actually been referenced in the
+document don't have a \idx{locationlist}. (The \qt{seal} entry is a
+dependency, but it's also been referenced in the document, so it has a
+\idx{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow}
+entries are dependencies because they occur in the description of
+some of the referenced entries. Normally this would mean that they
+have no \idx{locationlist} after the first \LaTeX+\bibgls+\LaTeX\
+build but once the glossary has been created the references to those
+dependent entries in the descriptions will create records and so on
+the next \bibgls+\LaTeX\ they will also have \idxpl{locationlist}.
+This would make the complete document build:
+\begin{verbatim}
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+\end{verbatim}
+However, in this example I've decided to ignore any records created
+in the glossary:
+\begin{codeenv}
+\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+This means that the document build is the usual \LaTeX+\bibgls+\LaTeX.
+
+I've used the \glostyle{treegroup} style so I need to invoke
+\bibgls\ with the \longarg{group} switch. This creates letter groups
+for the top-level entries. Note that sub-entries never have letter groups.
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-hierarchical
+bib2gls --group sample-hierarchical
+pdflatex sample-hierarchical
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-hierarchical.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-hierarchical.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-hierarchical.pdf}}%
+}
+{\caption{\filefmt{sample-hierarchical.pdf}}}
+{fig:sample-hierarchical.pdf}
+\end{figure}
+
+\filesection{sample-nested.tex}
+
+As discussed in \sectionref{sec:logicaldivisions} there are three
+ways of creating logical divisions when displaying the entries
+through the use of the \field{type}, \field{group} and \field{parent} fields.
+In general, hierarchical glossaries are created with
+the \field{parent} field and an appropriate glossary style (as in
+the previous \exfile{sample-hierarchical.tex} example).
+
+This example creates a hierarchical effect but the entries don't
+actually have a hierarchical structure as none of them have the
+\field{parent} field set. Instead, what were the child entries in
+\exfile{sample-hierarchical.tex} now have the \field{type} field
+set. The hierarchical effect is achieved with
+\ics{printunsrtinnerglossary} (which requires at least
+\sty{glossaries-extra} v1.44).
+
+\begin{important}
+The \ics{printunsrtinnerglossary} command is unsuitable for use
+with tabular-like styles, such as \glostyle{long}, and can be
+problematic with \glostyle{list} styles. However, those styles
+aren't suitable for hierarchical glossaries anyway.
+\end{important}
+
+Normally, hierarchy is achieve through definitions like:
+\begin{codeenv}
+\atentry{index}\marg{animal}
+\atentry{entry}\marg{duck,\field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \field{parent}=\marg{animal}
+}
+\end{codeenv}
+The previous example did this by loading both the \exfile{terms.bib}
+and \exfile{animals.bib} files and aliasing the custom
+\fieldfmt{identifier} field to \field{parent}. In this example, the
+custom field is aliased to \field{type}, which effectively makes the
+definitions behave like:
+\begin{codeenv}
+\atentry{index}\marg{animal}
+\atentry{entry}\marg{duck,\field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \field{type}=\marg{animal}
+}
+\end{codeenv}
+The aim here is for the \code{animal} entry to be placed in the main
+glossary so that it's listed with \cs{printunsrtglossary}. The
+\code{duck} entry is placed in a glossary that has a label
+(\code{animal}) that matches the label of the \qt{parent} entry
+(even though it's technically not a parent). This new glossary
+(\code{animal}) can be automatically defined by invoking \bibgls\
+with the \longarg{provide-glossaries} switch.
+
+This example document defines a custom handler function that
+will do the current entry as normal (with \cs{glsxtrunsrtdo}) but
+will then check for the existence of a glossary that has the same
+label as the current entry. This requires the starred version of
+\ics{ifglossaryexists} to included ignored glossaries in the
+existence check. If the glossary exists, it's then displayed using
+\ics{printunsrtinnerglossary}:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{nestedhandler}}[1]\marg{\comment{}
+ \cs{glsxtrunsrtdo}\marg{\idx{hashchar}1}\comment{}
+ \ics{ifglossaryexists*}\marg{\idx{hashchar}1}\comment{}
+ \marg{\comment{}
+ \cs{printunsrtinnerglossary}\oarg{\printglossopt[\idx{hashchar}1]{type},\printglossopt[++1]{leveloffset},\printglossopt[false]{groups}}
+ \marg{}\marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+The \printglossopt{leveloffset} option is required to achieve a
+hierarchical effect (provided the glossary style supports it) and
+the \printglossopt[false]{groups} option is needed to prevent letter
+groups showing for the nested glossary, which would otherwise create
+a strange effect. (This example uses the \glostyle{treegroup} style,
+which provides a hierarchical glossary with letter groups.)
+
+The \cs{printunsrtglossary} handler macro then needs to be set to
+this custom macro when the main glossary is displayed:
+\begin{codeenv}
+\cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}}
+\end{codeenv}
+The main difficulty comes with ensuring that all the necessary
+entries are selected. Now that the custom \fieldfmt{identifier}
+field has been aliased to \field{type} rather than \field{parent},
+the \code{animal} entry is no longer considered a dependent. The
+\code{duck} entry has been referenced in the document with \cs{gls}
+but the \code{animal} entry hasn't. The previous example ensured
+that the \code{animal} entry was selected because it was a parent of
+a selected entry. If the same resource options are used in this
+example, the main glossary will be empty, which means that the
+nested glossaries won't be displayed either.
+
+One way to ensure that the \code{animal}, \code{mineral} and
+\code{vegetable} entries are selected is to identify the \field{type}
+field as a dependency field:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[{terms,animals,minerals,vegetables}]{src},
+ \csopt[{identifier=type}]{field-aliases},
+ \csopt[{type}]{dependency-fields}
+}
+\end{codeenv}
+This will achieve the same effect as the
+\exfile{sample-hierarchical.tex} document, but it's a far more
+convoluted method. The reason this example document is listed here
+is to demonstrate a sightly modified hierarchical effect that can't
+be achieved through the normal method.
+
+Suppose that, for some strange reason, I want the \qt{animal},
+\qt{mineral} and \qt{vegetable} entries to be listed in a different
+order (say, reverse alphabetical). The other entries (\qt{duck} etc)
+need to be sorted in normal alphabetical order.
+
+The \csopt{sort} option applies the same sort method to all
+hierarchical levels. The sort \emph{value} chosen for particular entries
+can be altered through the use of fallbacks (such as the
+\csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options)
+and a letter comparator may be used to resolve identical sort
+values (\csopt{identical-sort-action}), but the same sort algorithm
+is applied to all entries in the same set (primary, secondary or dual
+within the same resource set). The only way to apply different sort
+methods is to separate the entries into different resource sets (or
+use dual or secondary sorting).
+
+This can be achieved by having one resource set for the main entries
+with one sort method and another resource set for all the other
+entries with a different sort method:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[terms]{src},\csopt[en-reverse]{sort}}
+
+\gls{GlsXtrLoadResources}\oarg{\csopt[animals,minerals,vegetables]{src},\csopt[en]{sort},
+ \csopt[{identifier=type}]{field-aliases},\csopt[{type}]{dependency-fields}
+}
+\end{codeenv}
+This works when cross-resource dependencies are permitted (see
+\sectionref{sec:resourcesets}). In the event that cross-resource
+dependencies aren't permitted, the selection criteria is more
+complicated:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[terms,animals,minerals,vegetables]{src},
+ \csopt[en-reverse]{sort},
+ \csopt[{identifier=parent}]{field-aliases},
+ \csopt[ancestors but not recorded]{selection}
+}
+
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[animals,minerals,vegetables]{src},
+ \csopt[{identifier=type}]{field-aliases},
+ \csopt[{type}]{dependency-fields}
+ \csopt[en]{sort}
+}
+\end{codeenv}
+Fortunately in this example, cross-resource dependencies are
+permitted so the simpler alternative works. (If they're not
+permitted, the \bibgls\ transcript file will contain
+\qt{Cross-resource references can't be supported for resource set
+\meta{filename}}.)
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-nested
+bib2gls --group --provide-glossaries sample-nested
+pdflatex sample-nested
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-nested.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-nested.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-nested.pdf}}%
+}
+{\caption{\filefmt{sample-nested.pdf}}}
+{fig:sample-nested.pdf}
+\end{figure}
+
\filesection{sample-constants.tex}
This example uses the \exfile{constants.bib} file. The aim here
@@ -23145,6 +23800,9 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
}%
}
\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
-\renewcommand*{\bibglspassim}{}
+\glsrenewcommand*{\bibglspassim}{}
+\newcommand{\glsxtrpostnamecommand}{%
+ \glsxtrifhasfield{userii}{\glscurrententrylabel}{ (\glscurrentfieldvalue)}{}%
+}
\printunsrtglossary[type=index]
\end{document}