summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex')
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex2453
1 files changed, 1484 insertions, 969 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index 4f3dc88f5cf..39cd070365a 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -9,6 +9,8 @@
\documentclass[titlepage=false,index=totoc,bibliography=totoc,
fontsize=12pt,captions=tableheading]{scrreprt}
+\usepackage{pifont}
+
% Need support for extended characters
% and need a mono font that supports hyphenation
\usepackage[no-math]{fontspec}
@@ -27,7 +29,6 @@
\usepackage{etoolbox}
\usepackage{hologo}
-\usepackage{xcolor}
\usepackage{amsmath}
\usepackage{accents}
\usepackage{tikz}
@@ -41,12 +42,15 @@
entrycounter,% enable entry counting
subentrycounter,% enable entry counting
%debug=showtargets,% debugging information
- stylemods=bookindex,% adjust predefined styles and load glossary-bookindex.sty
+ stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty
style=bookindex
]
{glossaries-extra}
+\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}}
+
\glsxtrprovidestoragekey{note}{}{}
+\glsxtrprovidestoragekey{package}{}{}
\providecommand{\omicron}{o}
@@ -85,12 +89,19 @@
\newcommand{\glsxtrpostnameenvironment}{\space environment}
\newcommand{\glsxtrpostnamecounter}{\space counter}
+\newcommand*{\csfmt}[1]{%
+ \texorpdfstring
+ {\texttt{\char`\\ #1}}%
+ {\string\\#1}%
+}
+
\setabbreviationstyle[common]{short-nolong}
\GlsXtrLoadResources[
label-prefix={idx.},
save-loclist=false,
sort={letternumber-nocase},
+ sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}},
type={index},
dual-field={dualid},
match-action={add},
@@ -177,15 +188,10 @@
\let\-\empty
}
-\newcommand*{\csfmt}[1]{%
- \texorpdfstring
- {\texttt{\char`\\ #1}}%
- {\string\\#1}%
-}
-
% Provide commands that work like \gls[#1]{idx.#2}[#3]
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
+\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
\newcommand{\stringu}{\idx{cs.string}\idx{u}}
@@ -206,6 +212,7 @@
{\string\\jobname-#1.glstex}%
}
+\newcommand{\extstyopt}{\textsuperscript{\textdagger}}
\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
@@ -297,7 +304,7 @@
\newcommand*{\styopt}[2][]{%
\texorpdfstring%
{%
- \idx{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
}%
{#2\ifblank{#1}{}{=#1}}%
}
@@ -513,6 +520,69 @@
}%
}
+\newglossarystyle{styoptsummary}%
+{%
+ \setglossarystyle{mcolindex}%
+ \renewcommand{\glossarypreamble}{%
+ Most options are in the form \meta{option}=\meta{value} and
+ may have a default if \meta{value} is omitted,
+ but some options don't have values and should not have
+ one assigned. For boolean options,
+ if the value is omitted \styoptfmt{true} is assumed.
+ \extstyopt Indicates a value that's only provided by
+ \styfmt{glossaries-extra} and not by the base
+ \styfmt{glossaries} package. \par
+ }%
+ \renewcommand*{\glossaryheader}{}%
+ \renewcommand*{\glsgroupheading}[1]{%
+ \glsxtrgetgrouptitle{##1}{\thisgrptitle}%
+ \glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}%
+ \glsxtrbookindexformatheader{\thisgrptitle}%
+ \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}%
+ }%
+ \renewcommand*{\glossentry}[2]{%
+ \item \glstarget{##1}{\strut}%
+ \glsxtrifhasfield{dualid}{##1}%
+ {%
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
+ {%
+ \gls[hyper=false]{##1}%
+ }%
+ \glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}%
+ \nopagebreak\par\hspace{10pt}%
+ \Glossentrydesc{##1}.%
+ \glsxtrifhasfield{package}{##1}%
+ {\nopagebreak\par \ding{43}Provided by
+ \ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra}
+ {\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}%
+ {\styfmt{\glscurrentfieldvalue}}.}%
+ {}%
+ \glsxtrifhasfield{note}{##1}%
+ {\space \xmakefirstuc{\glscurrentfieldvalue}.}%
+ {}%
+ \par\medskip
+ }%
+}
+
+\newcommand*{\styoptsummaryhook}[1]{%
+ \edef\currentcategory{\glscategory{#1}}%
+ \ifdefstring{\currentcategory}{packageoption}%
+ {}%
+ {\printunsrtglossaryskipentry}%
+}
+
+\newcommand*{\printstyoptsummary}{%
+ \printunsrtglossary*[type=main,
+ style=styoptsummary,
+ title={Package Option Summary}
+ ]%
+ {%
+ \let\printunsrtglossaryentryprocesshook\styoptsummaryhook
+ \glsxtrlocalsetgrouptitle{glssymbols}{@}%
+ }%
+}
+
\newcommand{\entrysection}[2][\subsection]{%
#1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}]
{\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}%
@@ -672,14 +742,12 @@ files}
\DTMsetstyle{pdf}
\protected@edef\x{\endgroup
\noexpand\hypersetup{%
- pdfinfo={
- Title={\@title},
- Author={\@author},
- CreationDate={\DTMuse{creation}},
- ModDate={\DTMuse{moddate}},
- }%
- %\noexpand\pdfinfo{/CreationDate (\DTMuse{creation})
- %/ModDate (\DTMuse{moddate})}
+ pdfinfo={
+ Title={\@title},
+ Author={\@author},
+ CreationDate={\DTMuse{creation}},
+ ModDate={\DTMuse{moddate}},
+ }%
}%
}\x
@@ -726,6 +794,11 @@ entry definitions using commands like \gls{newglossaryentry}
then you can use the supplementary tool \idx{convertgls2bib}
to convert the entries to the \ext{bib} format required by
\bibgls. See \sectionref{sec:gls2bib} for further details.
+
+The supplementary file \filefmt{bib2gls-begin.pdf} is an
+introductory guide to the \sty{glossaries-extra} package, which you
+may prefer to start with if you are unfamiliar with the
+\sty{glossaries} and \sty{glossaries-extra} packages.
\end{abstract}
\frontmatter
@@ -757,8 +830,13 @@ from the \ext{bib} file. Since \bibgls\ can also perform
hierarchical sorting and can collate location lists, it doubles as
an indexing application, which means that the \idx{makeglossaries}
step can be skipped.
+Note that \bibgls\ doesn't warn you if an entry that's referenced
+in the document doesn't exist in any of the supplied \ext{bib}
+files, but instead relies on the \styfmt{glossaries-extra} package
+to generate the warning. So at the end of the document build check
+the \ext{log} file for warnings.
-You can't use \ics{glsaddall} with this method as that command works
+You can't use \ics{glsaddall} with \bibgls\ as that command works
by iterating over all defined entries and calling
\ics{glsadd}\margm{label}. On the first \LaTeX\ run there are no
entries defined, so \ics{glsaddall} does nothing. If you want to
@@ -1557,7 +1635,7 @@ For example, suppose the \ext{bib} file includes:
protects against the possibility that the \catattr{glossname}
category attribute might be set to \optfmt{firstuc}, which
automatically converts the first letter of the name to
-upper case when displaying the glossary. See also
+\idx{uppercase} when displaying the glossary. See also
\longarg{mfirstuc-protection} and
\longarg{mfirstuc-math-protection}.)
@@ -1611,7 +1689,7 @@ texparserlib: {}$\mtx{M}$ -> M
So the \field{sort} value for this entry is set to \qtt{M}. The font
change (caused by math-mode and \ics{boldsymbol}) has been
ignored. The sort value therefore consists of a single Unicode
-character \hex{4D} (Latin upper case letter \qtt{M}, decimal value 77).
+character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77).
For the \code{v} entry, the code is:
\begin{verbatim}
@@ -1623,7 +1701,7 @@ texparserlib: \marg{}\$\csfmt{vec}\marg{v}\$ -> \usebox\varrow
\end{alltt}
So the \field{sort} value for this entry is set to \qtt{\usebox\varrow},
which consists of two Unicode characters \hex{76}
-(Latin lower case letter \qtt{v}, decimal value 118) and
+(Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and
\hex{20D7} (combining right arrow above, decimal value 8407).
For the \code{set} entry, the code is:
@@ -1636,7 +1714,7 @@ texparserlib: {}$\set{S}$ -> S
\end{verbatim}
So the \field{sort} value for this entry is set to \qtt{S} (again
ignoring the font change). This consists of a single Unicode
-character \hex{53} (Latin upper case letter \qtt{S}, decimal value~83).
+character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83).
For the \code{card} entry, the code is:
\begin{verbatim}
@@ -1652,7 +1730,7 @@ in \atentry{preamble} have been included, but the
font change has been discarded). In this case the sort value
consists of three Unicode characters \hex{7C} (vertical line, decimal
value 124),
-\hex{53} (Latin upper case letter \qtt{S}, decimal value 83) and
+\hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and
\hex{7C} again.
If \csopt[false]{interpret-preamble} had been used, \csfmt{card}
wouldn't be recognised and would be discarded leaving just \qtt{S}
@@ -1701,7 +1779,7 @@ letter.)
If \csopt[letter-nocase]{sort} is used instead then, after conversion
by the interpreter, the sort values will all be changed to
-lower case. The order is now: \code{i} ($\imaginary$),
+\idx{lowercase}. The order is now: \code{i} ($\imaginary$),
\code{M} ($\mtx{M}$), \code{S} ($\set{S}$),
\code{v} ($\vec{v}$) and \code{card} ($\card{S}$).
The transcript (with \longarg{verbose}) now shows
@@ -1721,7 +1799,7 @@ M -> 'm' (M) [109]
S -> 's' (S) [115]
v -> '\usebox\varrow' (V) [118 8407]
\end{alltt}
-Note that the letter groups are upper case not lower case.
+Note that the letter groups are \idx{uppercase} not \idx{lowercase}.
Again the \code{card} entry doesn't have an associated
letter group.
@@ -1846,6 +1924,14 @@ written to the transcript file, which can be inspected afterwards.
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
+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.
+
+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}.
\argsection{log-file}
@@ -1916,7 +2002,12 @@ for more details.
\argsection{no-interpret}
Switch off the interpreter mode. See \sectionref{sec:texparserlib}
-for more details.
+for more details about the interpreter. If the interpreter is off,
+the transcript (\iext{log}) file won't be parsed, so if you need
+\bibgls\ to know that you are using \sty{fontspec} but you don't
+want the interpreter on then you must use
+\longarg{packages}\code{ fontspec} to indicate that UTF-8 is
+natively supported.
\argsection{no-break-space}
@@ -2138,7 +2229,7 @@ This works in the same way as \longarg{mfirstuc-protection} but
guards against fields starting with inline maths
(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the \field{name} field
starts with \verb|$x$| and the glossary style automatically tries to
-convert the first letter of the name to upper case, then this will
+convert the first letter of the name to \idx{uppercase}, then this will
cause a problem.
With \longarg{mfirstuc-math-protection} set, \bibgls\ will
@@ -2349,7 +2440,7 @@ can't use non-ASCII characters in \meta{label} with \sty{inputenc}
\end{description}
The \idx{lettergroup} titles will typically have the first character
-converted to upper case for the alphabet sort methods
+converted to \idx{uppercase} for the alphabet sort methods
(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily
be a single character (depending on the sort rule), but may be
composed of multiple characters, such as a \idx{digraph} (two
@@ -2364,8 +2455,8 @@ by the following line in the \langxml:
<entry key="grouptitle.case.ij">IJ</entry>
\end{verbatim}
If there isn't a \code{grouptitle.case.\meta{lc}} key (where
-\meta{lc} is the lower case version), then only the first character
-will be converted to upper case otherwise the value supplied by the
+\meta{lc} is the \idx!{lowercase} version), then only the first character
+will be converted to \idx{uppercase} otherwise the value supplied by the
resource file is used. This resource key is only checked for
the alphabetical comparisons listed in
\tableref{tab:sortoptionsrule}. If the initial part of the sort
@@ -2380,7 +2471,7 @@ alphabetical\footnote{according to Java's
\code{Character.isAlphabetic(int)} method} then it will be a
\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive
ordering (such as \csopt[letter-nocase]{sort}) will convert the
-letter group character to upper case. The case-sensitive ordering
+letter group character to \idx{uppercase}. The case-sensitive ordering
(such as \csopt[letter-case]{sort}) won't change the case.
Glossary styles with navigational links to groups (such as
@@ -2808,6 +2899,12 @@ option instead.
\caption[Fields Set by \bibgls]{Fields Sometimes Set by \bibgls\ in
the \iext{glstex} File}
\label{tab:internalfields}
+You may define and assign \field{bibtextype} (although it's more
+likely to be aliased). Don't define any of others, and don't use any
+of them in the \ext{bib} file, except for \field{group},
+\field{sort} or \field{type} although those three are best
+assigned in the resource command or by \bibgls.\par
+\bigskip
\centering
\printfields{internalfield}%
\end{table}
@@ -2815,8 +2912,12 @@ the \iext{glstex} File}
\begin{table}[hbtp]
\caption[Internal Fields Set by \styfmt{glossaries} or
\styfmt{glossaries-extra} or \bibgls]{Internal Fields Set by
-\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls\
-(don't use in \ext{bib} files)}\label{tab:baseinternalfields}
+\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls}%
+\label{tab:baseinternalfields}
+\medskip
+Don't define any of these and don't use any of them in the \ext{bib}
+file.\par
+\bigskip
\centering
\printfields{baseinternalfield}%
\end{table}
@@ -3255,6 +3356,52 @@ Example:
Terms that are defined using \atentry{index} will be written to the output
file using the command \csref{bibglsnewindex}.
+\entrysection{indexplural}
+
+The \atentry{indexplural} entry type is similar to the
+\atentry{index} entry type 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
+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. All fields are optional. For example:
+\begin{verbatim}
+@indexplural{goose,
+ plural = {geese}
+}
+
+@indexplural{duck}
+
+@indexplural{chateau,
+ text = {ch\^ateau},
+ plural = {ch\^ateaux}
+}
+\end{verbatim}
+This is equivalent to:
+\begin{verbatim}
+@indexplural{goose,
+ name = {geese},
+ text = {goose},
+ plural = {geese}
+}
+
+@indexplural{duck,
+ name = {ducks},
+ text = {duck},
+ plural = {ducks}
+}
+
+@indexplural{chateau,
+ name = {ch\^ateaux},
+ text = {ch\^ateau},
+ plural = {ch\^ateaux}
+}
+\end{verbatim}
+
+Terms that are defined using \atentry{indexplural} will be written to the output
+file using the command \csref{bibglsnewindexplural}.
+
\entrysection{abbreviation}
The \atentry{abbreviation} entry type is designed for abbreviations.
@@ -3304,7 +3451,7 @@ instead do:
\setabbreviationstyle{long-short-sc}
\GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}]
\end{verbatim}
-or to convert the short value to upper case and use the
+or to convert the short value to \idx{uppercase} and use the
\abbrstyle{long-short-sm} style instead:
\begin{verbatim}
\setabbreviationstyle{long-short-sm}
@@ -4661,7 +4808,7 @@ 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
-\atentry{bibtexentry} and converted to lower case).
+\atentry{bibtexentry} and converted to \idx!{lowercase}).
For example \code{article} or \code{book}.
You can iterate over these internal list fields using
@@ -5564,6 +5711,101 @@ that tertiary entries are created when dual entries are defined in
the \ext{glstex} file, so this will increase the total number of
entries.
+\section{Hierarchical Options}
+\label{sec:hierarchicalopts}
+
+\optsection{save-child-count}
+
+This is a boolean option. The default setting is
+\csopt[false]{save-child-count}.
+If \csopt[true]{save-child-count},
+each entry will be assigned a field called \field{childcount} with
+the value equal to the number of child entries that have been
+selected. As from version 1.5, this option also creates
+the \field{childlist} field for entries that have children
+selected. This field is in \sty{etoolbox}'s internal list
+format and can be iterated over using \ics{glsxtrfieldforlistloop}.
+
+The assignment is done using \ics{GlsXtrSetField} so there's
+no associated key. You can test if the field is set and non-zero
+using:
+\nosecformatdef{GlsXtrIfHasNonZeroChildCount}
+which is provided with \sty{glossaries-extra-bib2gls} v1.31+.
+Within \meta{true}, you can access the actual value with
+\ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count},
+this command will do \meta{false} as the \field{childcount} field
+won't be set.
+
+For example, suppose \filefmt{entries.bib} contains:
+\begin{verbatim}
+@index{birds}
+@index{duck,parent={birds}}
+@index{goose,plural={geese},parent={birds}}
+@index{swan,parent={birds}}
+
+@index{minerals}
+@index{quartz,parent={minerals}}
+@index{corundum,parent={minerals}}
+@index{amethyst,parent={minerals}}
+@index{gypsum,parent={minerals}}
+@index{gold,parent={minerals}}
+\end{verbatim}
+and the document contains:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[record,style=indexgroup]{glossaries-extra}
+
+\GlsXtrLoadResources[src={entries},save-child-count]
+
+\begin{document}
+\gls{duck} and \gls{goose}.
+\gls{quartz}, \gls{corundum}, \gls{amethyst}.
+
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+Then the \ext{glstex} file will contain:
+\begin{verbatim}
+\GlsXtrSetField{birds}{childcount}{2}
+\GlsXtrSetField{duck}{childcount}{0}
+\glsxtrfieldlistadd{birds}{childlist}{duck}
+\GlsXtrSetField{goose}{childcount}{0}
+\glsxtrfieldlistadd{birds}{childlist}{goose}
+\GlsXtrSetField{minerals}{childcount}{3}
+\GlsXtrSetField{amethyst}{childcount}{0}
+\glsxtrfieldlistadd{minerals}{childlist}{amethyst}
+\GlsXtrSetField{corundum}{childcount}{0}
+\glsxtrfieldlistadd{minerals}{childlist}{corundum}
+\GlsXtrSetField{quartz}{childcount}{0}
+\glsxtrfieldlistadd{minerals}{childlist}{quartz}
+\end{verbatim}
+Note that although \code{birds} has three children defined in the
+\ext{bib} file, only two have been selected, so the child count is
+set to 2. Similarly the \code{minerals} entry has five children
+defined in the \ext{bib} file, but only three have been selected, so
+the child count is 3.
+
+The following uses the post-description hook to show the child count
+in parentheses:
+\begin{verbatim}
+\GlsXtrLoadResources[src={entries},category=general,save-child-count]
+
+\renewcommand{\glsxtrpostdescgeneral}{%
+ \glsxtrifhasfield{childcount}{\glscurrententrylabel}
+ { (child count: \glscurrentfieldvalue.)}%
+ {}%
+}
+\end{verbatim}
+\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
+It's slightly more efficient that \ics{ifglshasfield} provided by
+the base \styfmt{glossaries} package, and it doesn't complain if the
+entry or field don't exist, but note that \ics{glsxtrifhasfield}
+implicitly scopes its content. Use the starred version to omit the
+grouping. With \sty{glossaries-extra} v1.31+ you can perform a
+numerical test with \ics{GlsXtrIfFieldNonZero} or
+\ics{GlsXtrIfFieldEqNum}.
+
\optsection{flatten}
This is a boolean option. The default value is \csopt[false]{flatten}.
@@ -5924,6 +6166,124 @@ In the above, the location list includes records and
cross-references obtained from the \field{see} or \field{seealso}
fields. See \csopt{flatten-lonely} for further details.
+\optsection{strip-missing-parents}
+
+The \sty{glossaries} package requires that all child entries must be
+defined after the parent entry. An error occurs otherwise, so
+\bibgls\ will omit the \field{parent} field if it can't be found in
+the given \idx{resourceset}. However, when the default
+\csopt[false]{strip-missing-parents} is on, this omission only occurs
+while writing the definitions in the \ext{glstex} file (after
+selection and sorting).
+
+Sorting is performed hierarchically and the \field{group} field is set
+accordingly for the top-level entries (but not for child entries),
+which means that an entry with a \field{parent} field will be
+treated by the sort method as a child entry. This can lead to a
+strange result, which \bibgls\ warns about:
+\begin{alltt}
+Parent '\meta{parent id}' not found for entry \meta{child-id}
+\end{alltt}
+
+This is the default behaviour as it may simply be a result of a
+typing mistake in the \field{parent} field. If you actually want
+missing parents to be stripped before sorting (but after the
+selection process) then use \csopt[true]{strip-missing-parents}. If
+you want all parents stripped then use \csopt{flatten} or
+\csopt[parent]{ignore-fields} instead. As from version 1.4, if you
+want \bibgls\ to create the missing parents, then you can use
+\csopt[create]{missing-parents}.
+
+\optsection{missing-parents}
+
+As an alternative to \csopt{strip-missing-parents}, as from version
+1.4 you can now use \csopt[\meta{value}]{missing-parents} where
+\meta{value} may be one of:
+\begin{itemize}
+\item \optfmt{strip}: this is equivalent to
+\csopt[true]{strip-missing-parents};
+
+\item \optfmt{warn}: this is equivalent to the default
+\csopt[false]{strip-missing-parents};
+
+\item \optfmt{create}: this will create a new \atentry{index}
+entry with the missing parent's label (after it's been processed by
+options such as \csopt{labelify}) with the \field{name} obtained
+from the \emph{original} value of the \field{parent} field (before being
+processed by options like \csopt{labelify}).
+If the child entry has the \field{type} field set, then the new
+parent entry will be given the same value. The \field{category} for
+the new parent entry can be assigned with
+\csopt{missing-parent-category}.
+\end{itemize}
+
+For example, consider the \exfile{books.bib} file which contains
+entries like
+\begin{verbatim}
+@entry{ubik,
+ name={Ubik},
+ description={novel by Philip K. Dick},
+ identifier={book},
+ author={\sortmediacreator{Philip K.}{Dick}},
+ year={1969}
+}
+\end{verbatim}
+then the field alias
+\begin{codeenv}
+\csopt[author=parent]{field-aliases}
+\end{codeenv}
+will treat
+\begin{verbatim}
+ author={\sortmediacreator{Philip K.}{Dick}},
+\end{verbatim}
+as though it had been defined as
+\begin{verbatim}
+ parent={\sortmediacreator{Philip K.}{Dick}},
+\end{verbatim}
+This can be converted into a label with the options:
+\begin{codeenv}
+ \csopt[parent]{labelify},
+ \csopt[
+ \marg{[ \cs{cs.string}\csfmt{.}]}\marg{}
+ ]{labelify-replace}
+\end{codeenv}
+If the interpreter has been provided with the definition:
+\begin{verbatim}
+\providecommand*{\sortmediacreator}[2]{#2 #1}
+\end{verbatim}
+then the \field{parent} field for the \code{ubik} entry
+will become \code{DickPhilipK} but the original value is stored
+internally when \csopt[create]{missing-parents} is set so that it
+can be used as the \field{name} if the parent needs to be created.
+Once all the entries have been processed, if \code{ubik} has been
+selected but no entry can be found with the label \code{DickPhilipK}
+then a new entry will be added as though it had been defined with:
+\begin{verbatim}
+@index{DickPhilipK,
+ name={\sortmediacreator{Philip K.}{Dick}}
+}
+\end{verbatim}
+This is an alternative approach to the \exfile{sample-authors.tex}
+document from the \hyperref[sec:examples]{examples chapter}.
+
+\optsection{missing-parent-category}
+
+If a missing parent entry is created through the use of
+\csopt[create]{missing-parents} then the \field{category} field can
+be assigned to the new parent entry with this option. The
+\meta{value} may be one of:
+\begin{itemize}
+ \item \code{same as child}: the parent entry's \field{category}
+ field is set to the same value as the child's (if set);
+ \item \code{same as base}: the parent entry's \field{category} is
+ set to the base name of the \ext{bib} file that provided the
+ child entry's definition;
+ \item \code{no value}: don't set the \field{category} field;
+ \item \meta{label}: the parent entry's \field{category} field is set to
+ \meta{label} (which shouldn't contain any special characters).
+\end{itemize}
+The default setting is \csopt[no value]{missing-parent-category}.
+
\section{Master Documents}
\label{sec:master}
@@ -6161,7 +6521,7 @@ supplementary resource files (omitting the primary
\end{verbatim}
\section{Field and Label Options}
-\label{sec:labelopts}
+\label{sec:fieldlabelopts}
The options in this section may be used to set or adjust field
values or labels. Some field values are expected to be labels (such
@@ -6169,197 +6529,10 @@ as \field{group}). These labels must not contain special
characters or commands, but it's possible to convert a field value
into a valid label using options such as \csopt{labelify}.
-\optsection{group}
-
-The \csopt{group} option may only be used with the \longarg{group} switch.
-This will set the \field{group} field to \meta{label} unless
-\meta{label} is \optfmt{auto}, in which case the value is
-set automatically during the sorting (see also
-\csopt{group-formation}).
-The corresponding title can be set
-with \gls{glsxtrsetgrouptitle} if the title is different from the
-label. The default behaviour is \csopt[auto]{group}.
-
-For example:
-\begin{verbatim}
-\GlsXtrLoadResources[sort=integer,group={Constants},
- src={entries-constants}% data in entries-constants.bib
-]
-\GlsXtrLoadResources[sort=letter-case,group={Variables},
- src={entries-variables}% data in entries-variables.bib
-]
-\end{verbatim}
-In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
-these entries will be added to the same glossary, but will
-be grouped according to each instance of \gls{GlsXtrLoadResources},
-with the provided group label.
-
-
-\optsection{category}
-
-The selected entries may all have their \field{category} field
-changed before writing their definitions to the \ext{glstex} file.
-The \meta{value} may be:
-\begin{itemize}
-\item \optfmt{same as entry}: set the
-\field{category} to the \ext{bib} entry type used to define it
-(lower case 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 (lower case and without
-the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type 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)
-that provided the entry definition;
-
-\item \optfmt{same as type}: set the \field{category} to the same
-value as the \field{type} field (if that field has been provided
-either in the \ext{bib} file or through the \csopt{type} option);
-
-\item \meta{label}: the \field{category} is set to
-\meta{label} (which mustn't contain any special characters).
-\end{itemize}
-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
-\csopt[same as original entry]{category} refers to the
-\emph{original} entry type given in the \ext{bib} file. In both
-cases, the value is converted to lower case to ensure consistency.
-
-For example, if the \ext{bib} file contains:
-\begin{verbatim}
-@entry{bird,
- name={bird},
- description = {feathered animal}
-}
-
-@index{duck}
-
-@index{goose,plural="geese"}
-
-@dualentry{dog,
- name={dog},
- description={chien}
-}
-\end{verbatim}
-then if the document contains
-\begin{verbatim}
-\GlsXtrLoadResources[category={same as entry},src={entries}]
-\end{verbatim}
-this will set the \field{category} of the \code{bird} term to
-\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and
-\code{goose} terms to \optfmt{index} (since they were defined
-with \atentry{index}), and the \field{category} of the \code{dog}
-term to \optfmt{dualentry} (since it was
-defined with \atentry{dualentry}). Note that the dual entry
-\code{dual.dog} doesn't have the category set, since that's
-governed by \csopt{dual-category} instead.
-
-If, instead, the document contains
-\begin{verbatim}
-\GlsXtrLoadResources[category={animals},src={entries}]
-\end{verbatim}
-then the \field{category} of all the primary selected entries will
-be set to \optfmt{animals}. Again the dual entry \code{dual.dog}
-doesn't have the \field{category} set.
-
-Note that the categories may be overridden by the commands,
-such as \csref{bibglsnewindex}, that are used to actually define the
-entries.
-
-For example, if the document contains
-\begin{verbatim}
-\newcommand{\bibglsnewdualentry}[4]{%
- \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}%
-}
-
-\GlsXtrLoadResources[category={animals},src={entries}]
-\end{verbatim}
-then both the \code{dog} and \code{dual.dog} entries will
-have their \field{category} field set to \optfmt{dual} since the
-new definition of \gls{bibglsnewdualentry} has overridden
-the \csopt[animals]{category} option.
-
-\optsection{type}
-
-The \meta{value} may be one of:
-\begin{itemize}
- \item \optfmt{same as entry} set the \field{type} field
- to the entry type (lower case and without the initial \code{@});
-
- \item \optfmt{same as original entry} set the \field{type}
- to the original entry type (lower case 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 base} set the \field{type} field
- to the base name of the corresponding \ext{bib} file
- (without the extension);
-
- \item \optfmt{same as category} set the \field{type} field
- to the same value as the \field{category} field
- (\field{type} unchanged if \field{category} not set);
-
- \item\meta{label} sets the \field{type} field to the glossary
- 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
-given in the \ext{bib} file. It's not possible to have both
-\csopt[same as type]{category} and \csopt[same as category]{type}.
-
-Note that this setting only changes the \field{type} field for
-primary entries. Use \csopt{dual-type} for dual entries.
-
-For example:
-\begin{verbatim}
-\usepackage[record,symbols]{glossaries-extra}
-
-\GlsXtrLoadResources[src={entries-symbols},type=symbols]
-\end{verbatim}
-
-Make sure that the glossary type has already been defined
-(see \sectionref{sec:newglossary}). In the above, the
-\styopt{symbols} option defines the \code{symbols} glossary.
-If you want to use a custom glossary, you need to provide it. For
-example:
-\begin{verbatim}
-\usepackage[record,nomain]{glossaries-extra}
-
-\newglossary*{dictionary}{Dictionary}
-
-\GlsXtrLoadResources[src={entries-symbols},type=dictionary]
-\end{verbatim}
-(The \styopt{nomain} option was added to suppress the
-creation of the default \code{main} glossary.)
-
-\optsection{trigger-type}
-
-The record counting commands, such as \ics{rgls}, use the special
-format \ics{glstriggerrecordformat}, which \bibgls\ also treats
-as an \idx{ignoredrecord}. This means the entry will still be
-identified as having a record for selection purposes, which is
-necessary for the entry to be defined for use in the document, but
-in order to prevent it from appearing in the glossary you need to
-transfer the entry with \csopt[\meta{type}]{trigger-type}.
-This will override the \csopt{type}, \csopt{dual-type},
-\csopt{tertiary-type} and the type specification in
-\csopt{secondary}.
-
-The provided value \meta{type} must be a glossary label (not one of
-the keywords allowed by \csopt{type}).
-You can define the glossary before loading the resource, but
-it's not required as \bibgls\ will write
-\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file
-(see \sectionref{sec:newglossary}).
+\subsection{Label Options}
+\label{sec:labelopts}
-\optsection{interpret-label-fields}
+\optsection[\subsubsection]{interpret-label-fields}
This is a boolean option that determines whether or not the fields
that may only contain labels should have their values interpreted
@@ -6381,7 +6554,7 @@ can't be used in labels and may be used more generally for other
fields. The \csopt{labelify} and \csopt{labelify-list} options
are performed before \csopt{interpret-label-fields}.
-\optsection{labelify}
+\optsection[\subsubsection]{labelify}
This option should take a comma-separated list of recognised field names as the
value. (If a field is present in both \csopt{labelify} and
@@ -6465,7 +6638,7 @@ to retain the original:
]
\end{verbatim}
-\optsection{labelify-list}
+\optsection[\subsubsection]{labelify-list}
This option is like \csopt{labelify} but it retains commas, as it's
designed for fields that should be converted into a comma-separated
@@ -6488,7 +6661,7 @@ or
\end{verbatim}
depending on whether or not \sty{fontspec} was detected.
-\optsection{labelify-replace}
+\optsection[\subsubsection]{labelify-replace}
This option takes a comma-separated list as a value with each
element in the list in the form \margm{regex}\margm{replacement}
@@ -6500,7 +6673,24 @@ file so take care to protect any special characters. For example, to
match a literal \idx{full-stop} use \cs{cs.string}\ics{cs.period}
rather than just \ics{cs.period} (backslash dot).
-Both \csopt{labelify} and \csopt{labelify-list} use this setting to
+In the \meta{replacement} part, you can use
+\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence.
+For example:
+\begin{verbatim}
+\csopt[{([A-Z])\string\.}{\glscapturedgroup1}]{labelify-replace}
+\end{verbatim}
+This removes any \idx{full-stop} that follows any of the characters
+A,\ldots,Z. Alternatively, you can just use \verb|\string\$|
+instead of \cs{glscapturedgroup}. If you want a literal dollar
+character, you need to use \cs{glshex}\code{24} (or
+\verb|\string\u|). This isn't recommended for labels (since special
+characters are automatically stripped), but
+\csopt{sort-replace} follows the same rules as
+\csopt{labelify-replace}, and it may be needed
+for that.
+
+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 }
(including spaces) with a comma:
\begin{verbatim}
@@ -6551,125 +6741,462 @@ or
\end{verbatim}
depending on whether or not \sty{fontspec} was detected.
-\optsection{strip-missing-parents}
+\optsection[\subsubsection]{label-prefix}
-The \sty{glossaries} package requires that all child entries must be
-defined after the parent entry. An error occurs otherwise, so
-\bibgls\ will omit the \field{parent} field if it can't be found in
-the given \idx{resourceset}. However, when the default
-\csopt[false]{strip-missing-parents} is on, this omission only occurs
-while writing the definitions in the \ext{glstex} file (after
-selection and sorting).
+The \csopt{label-prefix} option prepends \meta{tag} to each
+entry's label. This \meta{tag} will also be inserted in front of any
+cross-references, unless they start with \idprefix{dual} or
+\idprefix{extn} (where \meta{n} is an integer). Use
+\csopt{dual-prefix} to change the dual label prefixes and
+\csopt{ext-prefixes} to change the external label prefixes.
-Sorting is performed hierarchically and the \field{group} field is set
-accordingly for the top-level entries (but not for child entries),
-which means that an entry with a \field{parent} field will be
-treated by the sort method as a child entry. This can lead to a
-strange result, which \bibgls\ warns about:
-\begin{alltt}
-Parent '\meta{parent id}' not found for entry \meta{child-id}
-\end{alltt}
+For example, if the \ext{bib} file contains
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{duck} or \gls {goose}}
+}
-This is the default behaviour as it may simply be a result of a
-typing mistake in the \field{parent} field. If you actually want
-missing parents to be stripped before sorting (but after the
-selection process) then use \csopt[true]{strip-missing-parents}. If
-you want all parents stripped then use \csopt{flatten} or
-\csopt[parent]{ignore-fields} instead. As from version 1.4, if you
-want \bibgls\ to create the missing parents, then you can use
-\csopt[create]{missing-parents}.
+@entry{waterfowl,
+ name={waterfowl},
+ description={Any \gls{bird} that lives in or about water},
+ see={[see also]{duck,goose}}
+}
-\optsection{missing-parents}
+@index{duck}
-As an alternative to \csopt{strip-missing-parents}, as from version
-1.4 you can now use \csopt[\meta{value}]{missing-parents} where
-\meta{value} may be one of:
-\begin{itemize}
-\item \optfmt{strip}: this is equivalent to
-\csopt[true]{strip-missing-parents};
+@index{goose,plural="geese"}
+\end{verbatim}
+Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix}
+it's as though the entries had been defined as:
+\begin{verbatim}
+@entry{gls.bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{gls.duck} or
+\gls{gls.goose}}
+}
-\item \optfmt{warn}: this is equivalent to the default
-\csopt[false]{strip-missing-parents};
+@entry{gls.waterfowl,
+ name={waterfowl},
+ description={Any \gls{gls.bird} that lives in or about water},
+ see={[see also]{gls.duck,gls.goose}}
+}
-\item \optfmt{create}: this will create a new \atentry{index}
-entry with the missing parent's label (after it's been processed by
-options such as \csopt{labelify}) with the \field{name} obtained
-from the \emph{original} value of the \field{parent} field (before being
-processed by options like \csopt{labelify}).
-If the child entry has the \field{type} field set, then the new
-parent entry will be given the same value. The \field{category} for
-the new parent entry can be assigned with
-\csopt{missing-parent-category}.
+@index{gls.duck,name={duck}}
+
+@index{gls.goose,name={goose},plural="geese"}
+\end{verbatim}
+
+Remember to use this prefix when you reference the terms in the
+document with commands like \ics{gls}.
+
+\optsection[\subsubsection]{duplicate-label-suffix}
+
+The \sty{glossaries} package doesn't permit entries with duplicate
+labels (even if they're in different glossaries). If you
+have multiple \idxpl{resourceset} and an entry that's selected
+in one \idx{resourceset} is also selected in another, by
+default, \bibgls\ will issue a warning, but it will still write the
+entry definition to the \ext{glstex} file, which means you'll also
+get a warning from \sty{glossaries-extra} and the duplicate
+definition will be ignored, but associated internal fields
+set with commands like \cs{GlsXtrSetField} may still be set.
+
+If you actually want the duplicate, you need to specify a
+suffix with \csopt{duplicate-label-suffix}. This suffix is only
+set just before writing the entry definition to the \ext{glstex}
+file, so it doesn't affect selection criteria nor can label
+substitutions be performed in any cross-references. Options such as
+\csopt{set-widest} that reference entry labels are incompatible
+as they will use the unsuffixed label.
+
+The actual suffix is formed from \meta{value}\meta{n} where \meta{n}
+is an integer that's incremented in the event of multiple
+duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will
+change the label to \meta{id}\code{.copy1} for the first duplicate
+of the entry whose label is \meta{id}, \meta{id}\code{.copy2} for
+the second duplicate, etc.
+
+\optsection[\subsubsection]{record-label-prefix}
+
+If set, this option will cause \bibgls\ to pretend that each record
+label starts with \meta{tag}, if it doesn't already. For example, suppose
+the records in the \ext{aux} file are:
+\begin{verbatim}
+\glsxtr@record{bird}{}{page}{glsnumberformat}{1}
+\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1}
+\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1}
+\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1}
+\end{verbatim}
+The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
+though the records were given as:
+\begin{verbatim}
+\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1}
+\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1}
+\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1}
+\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1}
+\end{verbatim}
+
+
+\optsection[\subsubsection]{cs-label-prefix}
+
+If you have commands such as \ics{gls}\margm{label} or
+\ics{glstext}\marg{label} in field
+values (in situations where nested link text won't cause a problem)
+the \meta{label} will be converted as follows:
+\begin{itemize}
+\item if \meta{label} starts with \idprefix{dual} then
+\idprefix{dual} will be replaced by the \csopt{dual-prefix} value;
+\item if \meta{label} starts with \idprefix{tertiary} then
+\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value;
+\item if \meta{label} starts with \idprefix{extn} then
+\idprefix{extn} will be replaced by the corresponding
+\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is
+enabled, see \sectionref{sec:resourcesets});
+\item if \meta{label} doesn't start with one of the above recognised
+prefixes then, if \csopt{cs-label-prefix} has been used the supplied
+value will be inserted otherwise the \csopt{label-prefix} setting
+will be inserted.
\end{itemize}
+For example, given
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{duck} or \gls{goose}}
+}
+\end{verbatim}
+then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix}
+isn't included in the resource option list this will convert the
+\field{description} field to:
+\begin{verbatim}
+description = {feathered animal, such as a \gls{idx.duck} or
+\gls{idx.goose}}
+\end{verbatim}
+However with \csopt[gls.]{cs-label-prefix} the \field{description}
+field will be converted to
+\begin{verbatim}
+description = {feathered animal, such as a \gls{gls.duck} or
+\gls{gls.goose}}
+\end{verbatim}
+regardless of the \csopt{label-prefix} setting. Whereas if the
+original entry definition is
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{dual.duck} or
+\gls{dual.goose}}
+}
+\end{verbatim}
+then \idprefix{dual} will be replaced by the value of the
+\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix}
+setting.
-For example, consider the \exfile{books.bib} file which contains
-entries like
+The \csopt{cs-label-prefix} setting doesn't affect labels in the
+fields that have an entry label or label list as the value
+(\field{parent}, \field{alias}, \field{see} and \field{seealso}).
+
+\optsection[\subsubsection]{ext-prefixes}
+
+Any cross-references in the \iext{bib} file that start with
+\idprefix{extn} (where \meta{n} is a positive integer) will be
+substituted with the \meta{n}th tag listed in the comma-separated
+\meta{list}. If there aren't that many items in the list, the
+\idprefix{extn} will simply be removed. The default setting is
+an empty list, which will strip all \idprefix{extn} prefixes.
+Remember that \idx{crossresourceref} mode needs to be enabled for
+this option to work (see \sectionref{sec:resourcesets}).
+
+For example, suppose the file \filefmt{entries-terms.bib} contains:
\begin{verbatim}
-@entry{ubik,
- name={Ubik},
- description={novel by Philip K. Dick},
- identifier={book},
- author={\sortmediacreator{Philip K.}{Dick}},
- year={1969}
+@entry{set,
+ name={set},
+ description={collection of values, denoted \gls{ext1.set}}
}
\end{verbatim}
-then the field alias
-\begin{codeenv}
-\csopt[author=parent]{field-aliases}
-\end{codeenv}
-will treat
+and the file \filefmt{entries-symbols.bib} contains:
\begin{verbatim}
- author={\sortmediacreator{Philip K.}{Dick}},
+@symbol{set,
+ name={\ensuremath{\mathcal{S}}},
+ description={a \gls{ext1.set}}
+}
\end{verbatim}
-as though it had been defined as
+
+These files both contain an entry with the label \code{set}
+but the \field{description} field includes \verb|\gls{ext1.set}| which is
+referencing the entry from the other file. These
+two files can be loaded without conflict using:
\begin{verbatim}
- parent={\sortmediacreator{Philip K.}{Dick}},
+\usepackage[record,symbols]{glossaries-extra}
+
+\GlsXtrLoadResources[src={entries-terms},
+ label-prefix={gls.},
+ ext-prefixes={sym.}
+]
+
+\GlsXtrLoadResources[src={entries-symbols},
+ type=symbols,
+ label-prefix={sym.},
+ ext-prefixes={gls.}
+]
\end{verbatim}
-This can be converted into a label with the options:
-\begin{codeenv}
- \csopt[parent]{labelify},
- \csopt[
- \marg{[ \cs{cs.string}\csfmt{.}]}\marg{}
- ]{labelify-replace}
-\end{codeenv}
-If the interpreter has been provided with the definition:
+
+Now the \code{set} entry from \filefmt{entries-terms.bib}
+will be defined with the label \code{gls.set} and the
+description will be
\begin{verbatim}
-\providecommand*{\sortmediacreator}[2]{#2 #1}
+collection of values, denoted \gls{sym.set}
\end{verbatim}
-then the \field{parent} field for the \code{ubik} entry
-will become \code{DickPhilipK} but the original value is stored
-internally when \csopt[create]{missing-parents} is set so that it
-can be used as the \field{name} if the parent needs to be created.
-Once all the entries have been processed, if \code{ubik} has been
-selected but no entry can be found with the label \code{DickPhilipK}
-then a new entry will be added as though it had been defined with:
+The \code{set} entry
+from \filefmt{entries-symbols.bib} will be defined with the label
+\code{sym.set} and the description will be
\begin{verbatim}
-@index{DickPhilipK,
- name={\sortmediacreator{Philip K.}{Dick}}
+a \gls{gls.set}
+\end{verbatim}
+
+Note that in this case the \ext{bib} files have to be loaded
+as two separate resources. They can't be combined into a
+single \csopt{src} list as the labels aren't unique.
+
+If you want to allow the flexibility to choose between
+loading them together or separately, you'll have to give them
+unique labels. For example, \filefmt{entries-terms.bib} could
+contain:
+\begin{verbatim}
+@entry{set,
+ name={set},
+ description={collection of values, denoted \gls{ext1.S}}
}
\end{verbatim}
-This is an alternative approach to the \exfile{sample-authors.tex}
-document from the \hyperref[sec:examples]{examples chapter}.
+and \filefmt{entries-symbols.bib} could contain:
+\begin{verbatim}
+@symbol{S,
+ name={\ensuremath{\mathcal{S}}},
+ description={a \gls{ext1.set}}
+}
+\end{verbatim}
+Now they can be combined with:
+\begin{verbatim}
+\GlsXtrLoadResources[src={entries-terms,entries-symbols}]
+\end{verbatim}
+which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}}
+prefix from the cross-references. Alternatively:
+\begin{verbatim}
+\GlsXtrLoadResources[src={entries-terms,entries-symbols},
+ label-prefix={gls.},
+ ext-prefixes={gls.}
+]
+\end{verbatim}
+which will insert the supplied \csopt{label-prefix} at the
+start of the labels in the entry definitions and will replace
+the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the
+cross-references.
-\optsection{missing-parent-category}
+\optsection[\subsubsection]{save-original-id}
-If a missing parent entry is created through the use of
-\csopt[create]{missing-parents} then the \field{category} field can
-be assigned to the new parent entry with this option. The
-\meta{value} may be one of:
+The \meta{value} may be either the keyword \code{false} or
+the name of an internal field in which to store the entry's original
+label (as given in the \ext{bib} file). The default setting is
+\csopt[false]{save-original-id}. If \meta{value} is omitted,
+\csopt[originalid]{save-original-id} is assumed.
+
+If \meta{value} is a known field, it will be set after the field
+aliases, otherwise it will simply be added to the \ext{glstex} file
+using \ics{GlsXtrSetField} after the entry definition.
+
+\subsection{Assignments}
+\label{sec:fieldassignments}
+
+\optsection[\subsubsection]{group}
+
+The \csopt{group} option may only be used with the \longarg{group} switch.
+This will set the \field{group} field to \meta{label} unless
+\meta{label} is \optfmt{auto}, in which case the value is
+set automatically during the sorting (see also
+\csopt{group-formation}).
+The corresponding title can be set
+with \gls{glsxtrsetgrouptitle} if the title is different from the
+label. The default behaviour is \csopt[auto]{group}.
+
+For example:
+\begin{verbatim}
+\GlsXtrLoadResources[sort=integer,group={Constants},
+ src={entries-constants}% data in entries-constants.bib
+]
+\GlsXtrLoadResources[sort=letter-case,group={Variables},
+ src={entries-variables}% data in entries-variables.bib
+]
+\end{verbatim}
+In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
+these entries will be added to the same glossary, but will
+be grouped according to each instance of \gls{GlsXtrLoadResources},
+with the provided group label.
+
+
+\optsection[\subsubsection]{category}
+
+The selected entries may all have their \field{category} field
+changed before writing their definitions to the \ext{glstex} file.
+The \meta{value} may be:
\begin{itemize}
- \item \code{same as child}: the parent entry's \field{category}
- field is set to the same value as the child's (if set);
- \item \code{same as base}: the parent entry's \field{category} is
- set to the base name of the \ext{bib} file that provided the
- child entry's definition;
- \item \code{no value}: don't set the \field{category} field;
- \item \meta{label}: the parent entry's \field{category} field is set to
- \meta{label} (which shouldn't contain any special characters).
+\item \optfmt{same as entry}: set the
+\field{category} to the \ext{bib} entry type 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
+the initial \code{@}) before it was aliased (behaves like
+\optfmt{same as entry} if the entry type 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)
+that provided the entry definition;
+
+\item \optfmt{same as type}: set the \field{category} to the same
+value as the \field{type} field (if that field has been provided
+either in the \ext{bib} file or through the \csopt{type} option);
+
+\item \meta{label}: the \field{category} is set to
+\meta{label} (which mustn't contain any special characters).
\end{itemize}
-The default setting is \csopt[no value]{missing-parent-category}.
+This will override any
+\field{category} fields supplied in the \ext{bib} file.
-\optsection{abbreviation-name-fallback}
+When used with \csopt{entry-type-aliases}, the option \csopt[same as
+entry]{category} refers to the \emph{target} entry type whereas
+\csopt[same as original entry]{category} refers to the
+\emph{original} entry type given in the \ext{bib} file. In both
+cases, the value is converted to \idx!{lowercase} to ensure consistency.
+
+For example, if the \ext{bib} file contains:
+\begin{verbatim}
+@entry{bird,
+ name={bird},
+ description = {feathered animal}
+}
+
+@index{duck}
+
+@index{goose,plural="geese"}
+
+@dualentry{dog,
+ name={dog},
+ description={chien}
+}
+\end{verbatim}
+then if the document contains
+\begin{verbatim}
+\GlsXtrLoadResources[category={same as entry},src={entries}]
+\end{verbatim}
+this will set the \field{category} of the \code{bird} term to
+\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and
+\code{goose} terms to \optfmt{index} (since they were defined
+with \atentry{index}), and the \field{category} of the \code{dog}
+term to \optfmt{dualentry} (since it was
+defined with \atentry{dualentry}). Note that the dual entry
+\code{dual.dog} doesn't have the category set, since that's
+governed by \csopt{dual-category} instead.
+
+If, instead, the document contains
+\begin{verbatim}
+\GlsXtrLoadResources[category={animals},src={entries}]
+\end{verbatim}
+then the \field{category} of all the primary selected entries will
+be set to \optfmt{animals}. Again the dual entry \code{dual.dog}
+doesn't have the \field{category} set.
+
+Note that the categories may be overridden by the commands,
+such as \csref{bibglsnewindex}, that are used to actually define the
+entries.
+
+For example, if the document contains
+\begin{verbatim}
+\newcommand{\bibglsnewdualentry}[4]{%
+ \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}%
+}
+
+\GlsXtrLoadResources[category={animals},src={entries}]
+\end{verbatim}
+then both the \code{dog} and \code{dual.dog} entries will
+have their \field{category} field set to \optfmt{dual} since the
+new definition of \gls{bibglsnewdualentry} has overridden
+the \csopt[animals]{category} option.
+
+\optsection[\subsubsection]{type}
+
+The \meta{value} may be one of:
+\begin{itemize}
+ \item \optfmt{same as entry} set the \field{type} field
+ to the entry type (\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
+ the initial \code{@}) before it was aliased (behaves like
+ \optfmt{same as entry} if the entry type wasn't aliased);
+
+ \optfmt{same as base} set the \field{type} field
+ to the base name of the corresponding \ext{bib} file
+ (without the extension);
+
+ \item \optfmt{same as category} set the \field{type} field
+ to the same value as the \field{category} field
+ (\field{type} unchanged if \field{category} not set);
+
+ \item\meta{label} sets the \field{type} field to the glossary
+ 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
+given in the \ext{bib} file. It's not possible to have both
+\csopt[same as type]{category} and \csopt[same as category]{type}.
+
+Note that this setting only changes the \field{type} field for
+primary entries. Use \csopt{dual-type} for dual entries.
+
+For example:
+\begin{verbatim}
+\usepackage[record,symbols]{glossaries-extra}
+
+\GlsXtrLoadResources[src={entries-symbols},type=symbols]
+\end{verbatim}
+
+Make sure that the glossary type has already been defined
+(see \sectionref{sec:newglossary}). In the above, the
+\styopt{symbols} option defines the \code{symbols} glossary.
+If you want to use a custom glossary, you need to provide it. For
+example:
+\begin{verbatim}
+\usepackage[record,nomain]{glossaries-extra}
+
+\newglossary*{dictionary}{Dictionary}
+
+\GlsXtrLoadResources[src={entries-symbols},type=dictionary]
+\end{verbatim}
+(The \styopt{nomain} option was added to suppress the
+creation of the default \code{main} glossary.)
+
+\optsection[\subsubsection]{trigger-type}
+
+The record counting commands, such as \ics{rgls}, use the special
+format \ics{glstriggerrecordformat}, which \bibgls\ also treats
+as an \idx{ignoredrecord}. This means the entry will still be
+identified as having a record for selection purposes, which is
+necessary for the entry to be defined for use in the document, but
+in order to prevent it from appearing in the glossary you need to
+transfer the entry with \csopt[\meta{type}]{trigger-type}.
+This will override the \csopt{type}, \csopt{dual-type},
+\csopt{tertiary-type} and the type specification in
+\csopt{secondary}.
+
+The provided value \meta{type} must be a glossary label (not one of
+the keywords allowed by \csopt{type}).
+You can define the glossary before loading the resource, but
+it's not required as \bibgls\ will write
+\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file
+(see \sectionref{sec:newglossary}).
+
+\optsection[\subsubsection]{abbreviation-name-fallback}
The entry types that define abbreviations (such as
\atentry{abbreviation} and \atentry{acronym}) will, by default,
@@ -6681,7 +7208,7 @@ specify the field. For example,
\csopt[long]{abbreviation-name-fallback}.
The \meta{field} value must be a known field label.
-\optsection{ignore-fields}
+\optsection[\subsubsection]{ignore-fields}
The \csopt{ignore-fields} key indicates that you want \bibgls\ to
skip the fields listed in the supplied comma-separated \meta{list} of field
@@ -6710,7 +7237,7 @@ If you want to maintain the dependency and ancestor relationship but
omit the \field{parent} field when writing the entries to the
\ext{glstex} file, you need to use \csopt{flatten} instead.
-\optsection{field-aliases}
+\optsection[\subsubsection]{field-aliases}
You can instruct \bibgls\ to treat one field as though it
was another using this option. The value should be a comma-separated
@@ -6748,7 +7275,7 @@ keys:
]
\end{verbatim}
-\optsection{replicate-fields}
+\optsection[\subsubsection]{replicate-fields}
The value of one field can be copied to other fields using
this option where each \meta{key}\dequals\meta{value} pair
@@ -6833,14 +7360,236 @@ make a difference. The same result occurs with:
]
\end{verbatim}
-\optsection{replicate-override}
+\optsection[\subsubsection]{replicate-override}
This is a boolean option. The default setting is
\csopt[false]{replicate-override}. If \optfmt{true},
\csopt{replicate-fields} will override the existing value if the
target field is already set.
-\optsection{bibtex-contributor-fields}
+\optsection[\subsubsection]{counter}
+
+The \csopt{counter} option assigns the default counter to use
+for the selected entries. (This can be overridden with the
+\glsopt{counter} key when using commands like \csfmt{gls}.)
+The value must be the name of a counter. Since \bibgls\ doesn't know
+which counters are defined within the document, there's no check to
+determine if the value is valid (except for ensuring that
+\meta{value} is non-empty).
+
+Note that this will require an extra \LaTeX\ and \bibgls\ call since
+the counter can't be used for the indexing until the entry has been
+defined.
+
+\optsection[\subsubsection]{copy-action-group-field}
+
+This option may only be used when invoking \bibgls\ with the
+\longarg{group} (or \shortargfmt{g}) switch. If an action
+other than the default \csopt[define]{action} is set,
+this option can be used to identify a field in which to save
+the letter group information
+where \meta{value} is the name of the field. This just uses
+\cs{GlsXtrSetField}. You will need to redefine
+\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary.
+For example, if \csopt[dupgroup]{copy-action-group-field},
+\csopt[copy]{action} and \csopt[copies]{type} are set in
+the resource options and \code{copies} identifies a custom
+glossary:
+\begin{alltt}
+\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup}
+ \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
+\end{alltt}
+
+This option is ignored when used with \csopt[define]{action}.
+This option is not used by \csopt{secondary} which will
+always save the group information in the \field{secondarygroup}
+field. When used with \csopt[define or copy]{action}, entries
+that are defined will have both \field{group} and
+the field given by \csopt{copy-action-group-field} set.
+
+Note that you may do \csopt[group]{copy-action-group-field} which
+will override the \field{group} field from the original definition.
+This may be useful if you don't use grouping in the primary
+glossary. That is, you use \code{nogroupskip} and a non-group
+style. For example:
+\begin{verbatim}
+\printunsrtglossary[nogroupskip,style=index]
+\printunsrtglossary[type=copies,style=indexgroup]
+\end{verbatim}
+
+\optsection[\subsubsection]{copy-alias-to-see}
+
+If set, the value of the \field{alias} field is copied to
+the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
+
+\subsection{Field Adjustments}
+\label{sec:fieldmods}
+
+\optsection[\subsubsection]{post-description-dot}
+
+The \styopt{postdot} package option (or \styopt[false]{nopostdot})
+can be used to append a \idx{full-stop} (\idx{periodchar})\ to the
+end of all the descriptions. This can be awkward if some of the
+descriptions end with punctuation characters. This resource option
+can be used instead. The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{none}: don't append a \idx{full-stop} (default);
+\item\optfmt{all}: append a \idx{full-stop} to all \field{description}
+ fields in this resource set;
+\item\optfmt{check}: selectively append a \idx{full-stop} (see below).
+\end{itemize}
+Note that if you have dual entries and you use this option to
+append a \idx{full-stop}, then it will be copied over to the mapped field.
+This is different to the \styopt{postdot} option which doesn't
+add the dot to the field but incorporates it in the
+\idx{postdescriptionhook}. This means that a dot inserted with
+\csopt{post-description-dot} will come before the
+\idx{postdescriptionhook} whereas with \styopt{postdot} the
+punctuation comes after any category-specific hook.
+
+The \csopt[check]{post-description-dot} setting determines whether
+to append the dot as follows:
+\begin{itemize}
+\item If the \field{description} field ends with
+\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended.
+\item If the \field{description} field doesn't end with a regular
+(ungrouped letter or other) character, then a dot is appended.
+(For example, if the description ends with a control sequence
+or an end group token.)
+\item If the \field{description} field ends with a character
+that belongs to the Unicode category \idx{punctuationclose}
+or \idx{punctuationfinalquote} then the token preceding
+that character is checked.
+\item If the \field{description} field doesn't end with
+a character that belongs to the Unicode category
+\idx{punctuationother} then the dot is added.
+\end{itemize}
+Note that the interpreter isn't used during the check.
+If the \field{description} ends with a command then a dot will be
+appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if
+that command expands in such a way that it ends with a terminating
+punctuation character. This option only applies to the
+\field{description} field.
+
+\optsection[\subsubsection]{strip-trailing-nopost}
+
+This option is always performed before \csopt{post-description-dot}
+when adjusting the \field{description} field. The default
+setting is \csopt[false]{strip-trailing-nopost}. If
+\optfmt{true} any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc}
+found in the \field{description} field will be removed.
+Note that the command (possibly followed by ignored space) must be
+at the very end of the description for it to be removed. A
+description should not contain both commands. This option
+only applies to the \field{description} field.
+
+For example, \cs{nopostdesc} will be stripped from:
+\begin{verbatim}
+description={sample\nopostdesc}
+\end{verbatim}
+since it's at the end. It will also be stripped from
+\begin{verbatim}
+description={sample\nopostdesc }
+\end{verbatim}
+since the trailing space is ignored as it follows a control
+word. It won't be stripped from
+\begin{verbatim}
+description={sample\nopostdesc{} }
+\end{verbatim}
+because the final space is now significant, but even without the
+space it still won't be stripped as the field ends with
+an empty group not with \cs{nopostdesc}. Similarly it won't be
+stripped from
+\begin{verbatim}
+description={sample\nopostdesc\relax}
+\end{verbatim}
+because again it's not at the end.
+
+\optsection[\subsubsection]{check-end-punctuation}
+
+This options checks the end of all the fields given in \meta{list} for
+end of sentence punctuation. This is determined as follows, for each
+\meta{field} in the comma-separated \meta{list}:
+\begin{itemize}
+\item if the last character is of type \idx{punctuationclose}
+or \idx{punctuationfinalquote}, check the character that comes
+before it;
+\item if the character is of type \idx{punctuationother}, then check
+if it's listed in the entry given by \code{sentence.terminators}
+in \bibgls's \langxml.
+\end{itemize}
+If a sentence terminator is found, an internal field is created
+called \field{fieldendpunc} that contains the punctuation
+character. Fields whose values must be labels (such as
+\field{parent}, \field{category} and \field{type}) aren't checked,
+even if they're included in \meta{list}.
+
+The default \code{sentence.terminators} is defined in \file{bib2gls-en.xml}
+as:
+\begin{verbatim}
+<entry key="sentence.terminators">.?!</entry>
+\end{verbatim}
+Any character that isn't of type \idx{punctuationother} won't
+match.
+
+For example, the sample \exfile{books.bib} file contains:
+\begin{verbatim}
+@entry{whydidnttheyaskevans,
+ name={Why Didn't They Ask Evans?},
+ description={novel by Agatha Christie},
+ identifier={book},
+ author={\sortmediacreator{Agatha}{Christie}},
+ year={1934}
+}
+\end{verbatim}
+With \csopt[name]{check-end-punctuation}, this entry will be
+assigned an internal field called
+\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\
+as that's included in \code{sentence.terminators} and is found
+at the end of the \field{name} field:
+\begin{verbatim}
+\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?}
+\end{verbatim}
+(Note that \csopt[first,text]{check-end-punctuation} won't match
+as there's no \field{first} or \field{text} field supplied.)
+
+If you have a field that ends with an abbreviation followed by a
+\idx{full-stop}, this will be considered an end of sentence terminator, but
+the main purpose of this option is to provide a way to deal with
+cases like
+\begin{verbatim}
+Agatha Christie wrote \gls{whydidnttheyaskevans}.
+\end{verbatim}
+where the end of sentence punctuation following \cs{gls} needs to be
+discarded. This is needed regardless of whether or not
+the link text ends with an abbreviation or is a complete sentence.
+
+It's then possible to hook into the \idx{postlinkhook} \qt{discard
+period} check. By default this just checks the category attributes
+that govern whether or not to discard a following period, but
+(with \styfmt{glossaries-extra} v1.23+) it's possible to provide
+an additional check by redefining
+\nosecdef{glsxtrifcustomdiscardperiod}
+This should expand to \meta{true} if the check should be performed
+otherwise it should expand to \meta{false}. You can reference the
+label using \cs{glslabel}. For example:
+\begin{verbatim}
+\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{%
+ \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}%
+}
+\end{verbatim}
+This uses \ics{GlsXtrIfFieldUndef} rather than
+\ics{glsxtrifhasfield*} since there's no need to access the field's
+value. (The unstarred form \ics{glsxtrifhasfield} can't be used
+as it introduces implicit scoping, which would interfere with the
+punctuation lookahead.) The other difference between
+\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests
+is the case where the field is set to an empty value. In this case
+the field is defined (so \ics{GlsXtrIfFieldUndef} does the
+\meta{false} argument) but it's considered unset (so commands like
+\ics{ifglshasfield} do the \meta{false} argument).
+
+\optsection[\subsubsection]{bibtex-contributor-fields}
This option indicates that the listed fields all use \BibTeX's name
syntax (as used in \BibTeX's \code{author} and \code{editor} fields).
@@ -6888,7 +7637,7 @@ With one of the locale sort methods and with the default
Smith|John|Doe|Jane|von|Duck|Dickie
\end{verbatim}
-\optsection{contributor-order}
+\optsection[\subsubsection]{contributor-order}
The \gls{bibglscontributor} command is defined in
\bibgls's interpreter and its definition is dependent on this
@@ -6948,7 +7697,7 @@ The second resource set will use the default
\csopt[von]{bibtex-contributor-fields} setting when obtaining the
sort value.
-\optsection{date-time-fields}
+\optsection[\subsubsection]{date-time-fields}
This option indicates that the listed fields all contain
date and time information. Primary entries will have these fields
@@ -6966,7 +7715,7 @@ being parsed if it contains \idx{escchar}, \idx{mshiftchar},
\idx{nbspchar} is converted to the non-breaking space character
\hex{A0} unless \longarg{break-space} is used.)
-\optsection{date-fields}
+\optsection[\subsubsection]{date-fields}
As \csopt{date-time-fields} but for fields that only contain date
(not time) information. If parsed correctly, the field is converted
@@ -6978,7 +7727,7 @@ The fields are parsed according to
\csopt{dual-date-field-format} and
\csopt{dual-date-field-locale} for dual entries.
-\optsection{time-fields}
+\optsection[\subsubsection]{time-fields}
As \csopt{date-time-fields} but for fields that only contain time
(not date) information. If parsed correctly, the field is converted
@@ -6990,7 +7739,7 @@ The fields are parsed according to
\csopt{dual-time-field-format} and
\csopt{dual-time-field-locale} for dual entries.
-\optsection{date-time-field-format}
+\optsection[\subsubsection]{date-time-field-format}
This option also sets
\csopt[\meta{value}]{dual-date-time-field-format}.
@@ -6998,7 +7747,7 @@ The value is the format pattern used when parsing fields identified
by \csopt{date-time-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{date-field-format}
+\optsection[\subsubsection]{date-field-format}
This option also sets
\csopt[\meta{value}]{dual-date-field-format}.
@@ -7006,7 +7755,7 @@ The value is the format pattern used when parsing fields identified
by \csopt{date-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{time-field-format}
+\optsection[\subsubsection]{time-field-format}
This option also sets
\csopt[\meta{value}]{dual-time-field-format}.
@@ -7014,7 +7763,7 @@ The value is the format pattern used when parsing fields identified
by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{date-time-field-locale}
+\optsection[\subsubsection]{date-time-field-locale}
This option also sets
\csopt[\meta{value}]{dual-date-time-field-locale}.
@@ -7022,7 +7771,7 @@ The value is the locale used when parsing fields identified
by \csopt{date-time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{date-field-locale}
+\optsection[\subsubsection]{date-field-locale}
This option also sets
\csopt[\meta{value}]{dual-date-field-locale}.
@@ -7030,7 +7779,7 @@ The value is the locale used when parsing fields identified
by \csopt{date-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{time-field-locale}
+\optsection[\subsubsection]{time-field-locale}
This option also sets
\csopt[\meta{value}]{dual-time-field-locale}.
@@ -7038,291 +7787,30 @@ The value is the locale used when parsing fields identified
by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{counter}
-
-The \csopt{counter} option assigns the default counter to use
-for the selected entries. (This can be overridden with the
-\glsopt{counter} key when using commands like \csfmt{gls}.)
-The value must be the name of a counter. Since \bibgls\ doesn't know
-which counters are defined within the document, there's no check to
-determine if the value is valid (except for ensuring that
-\meta{value} is non-empty).
-
-Note that this will require an extra \LaTeX\ and \bibgls\ call since
-the counter can't be used for the indexing until the entry has been
-defined.
-
-\optsection{label-prefix}
-
-The \csopt{label-prefix} option prepends \meta{tag} to each
-entry's label. This \meta{tag} will also be inserted in front of any
-cross-references, unless they start with \idprefix{dual} or
-\idprefix{extn} (where \meta{n} is an integer). Use
-\csopt{dual-prefix} to change the dual label prefixes and
-\csopt{ext-prefixes} to change the external label prefixes.
-
-For example, if the \ext{bib} file contains
-\begin{verbatim}
-@entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{duck} or \gls {goose}}
-}
-
-@entry{waterfowl,
- name={waterfowl},
- description={Any \gls{bird} that lives in or about water},
- see={[see also]{duck,goose}}
-}
-
-@index{duck}
-
-@index{goose,plural="geese"}
-\end{verbatim}
-Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix}
-it's as though the entries had been defined as:
-\begin{verbatim}
-@entry{gls.bird,
- name={bird},
- description = {feathered animal, such as a \gls{gls.duck} or
-\gls{gls.goose}}
-}
-
-@entry{gls.waterfowl,
- name={waterfowl},
- description={Any \gls{gls.bird} that lives in or about water},
- see={[see also]{gls.duck,gls.goose}}
-}
-
-@index{gls.duck,name={duck}}
-
-@index{gls.goose,name={goose},plural="geese"}
-\end{verbatim}
-
-Remember to use this prefix when you reference the terms in the
-document with commands like \ics{gls}.
-
-\optsection{duplicate-label-suffix}
-
-The \sty{glossaries} package doesn't permit entries with duplicate
-labels (even if they're in different glossaries). If you
-have multiple \idxpl{resourceset} and an entry that's selected
-in one \idx{resourceset} is also selected in another, by
-default, \bibgls\ will issue a warning, but it will still write the
-entry definition to the \ext{glstex} file, which means you'll also
-get a warning from \sty{glossaries-extra} and the duplicate
-definition will be ignored, but associated internal fields
-set with commands like \cs{GlsXtrSetField} may still be set.
-
-If you actually want the duplicate, you need to specify a
-suffix with \csopt{duplicate-label-suffix}. This suffix is only
-set just before writing the entry definition to the \ext{glstex}
-file, so it doesn't affect selection criteria nor can label
-substitutions be performed in any cross-references. Options such as
-\csopt{set-widest} that reference entry labels are incompatible
-as they will use the unsuffixed label.
-
-The actual suffix is formed from \meta{value}\meta{n} where \meta{n}
-is an integer that's incremented in the event of multiple
-duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will
-change the label to \meta{id}\code{.copy1} for the first duplicate
-of the entry whose label is \meta{id}, \meta{id}\code{.copy2} for
-the second duplicate, etc.
+\subsection{Case-Changing}
+\label{sec:fieldcase}
-\optsection{record-label-prefix}
-
-If set, this option will cause \bibgls\ to pretend that each record
-label starts with \meta{tag}, if it doesn't already. For example, suppose
-the records in the \ext{aux} file are:
-\begin{verbatim}
-\glsxtr@record{bird}{}{page}{glsnumberformat}{1}
-\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1}
-\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1}
-\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1}
-\end{verbatim}
-The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
-though the records were given as:
-\begin{verbatim}
-\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1}
-\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1}
-\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1}
-\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1}
-\end{verbatim}
-
-
-\optsection{cs-label-prefix}
-
-If you have commands such as \ics{gls}\margm{label} or
-\ics{glstext}\marg{label} in field
-values (in situations where nested link text won't cause a problem)
-the \meta{label} will be converted as follows:
-\begin{itemize}
-\item if \meta{label} starts with \idprefix{dual} then
-\idprefix{dual} will be replaced by the \csopt{dual-prefix} value;
-\item if \meta{label} starts with \idprefix{tertiary} then
-\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value;
-\item if \meta{label} starts with \idprefix{extn} then
-\idprefix{extn} will be replaced by the corresponding
-\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is
-enabled, see \sectionref{sec:resourcesets});
-\item if \meta{label} doesn't start with one of the above recognised
-prefixes then, if \csopt{cs-label-prefix} has been used the supplied
-value will be inserted otherwise the \csopt{label-prefix} setting
-will be inserted.
-\end{itemize}
-For example, given
-\begin{verbatim}
-@entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{duck} or \gls{goose}}
-}
-\end{verbatim}
-then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix}
-isn't included in the resource option list this will convert the
-\field{description} field to:
-\begin{verbatim}
-description = {feathered animal, such as a \gls{idx.duck} or
-\gls{idx.goose}}
-\end{verbatim}
-However with \csopt[gls.]{cs-label-prefix} the \field{description}
-field will be converted to
-\begin{verbatim}
-description = {feathered animal, such as a \gls{gls.duck} or
-\gls{gls.goose}}
-\end{verbatim}
-regardless of the \csopt{label-prefix} setting. Whereas if the
-original entry definition is
-\begin{verbatim}
-@entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{dual.duck} or
-\gls{dual.goose}}
-}
-\end{verbatim}
-then \idprefix{dual} will be replaced by the value of the
-\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix}
-setting.
-
-The \csopt{cs-label-prefix} setting doesn't affect labels in the
-fields that have an entry label or label list as the value
-(\field{parent}, \field{alias}, \field{see} and \field{seealso}).
-
-\optsection{ext-prefixes}
-
-Any cross-references in the \iext{bib} file that start with
-\idprefix{extn} (where \meta{n} is a positive integer) will be
-substituted with the \meta{n}th tag listed in the comma-separated
-\meta{list}. If there aren't that many items in the list, the
-\idprefix{extn} will simply be removed. The default setting is
-an empty list, which will strip all \idprefix{extn} prefixes.
-Remember that \idx{crossresourceref} mode needs to be enabled for
-this option to work (see \sectionref{sec:resourcesets}).
-
-For example, suppose the file \filefmt{entries-terms.bib} contains:
-\begin{verbatim}
-@entry{set,
- name={set},
- description={collection of values, denoted \gls{ext1.set}}
-}
-\end{verbatim}
-and the file \filefmt{entries-symbols.bib} contains:
-\begin{verbatim}
-@symbol{set,
- name={\ensuremath{\mathcal{S}}},
- description={a \gls{ext1.set}}
-}
-\end{verbatim}
-
-These files both contain an entry with the label \code{set}
-but the \field{description} field includes \verb|\gls{ext1.set}| which is
-referencing the entry from the other file. These
-two files can be loaded without conflict using:
-\begin{verbatim}
-\usepackage[record,symbols]{glossaries-extra}
-
-\GlsXtrLoadResources[src={entries-terms},
- label-prefix={gls.},
- ext-prefixes={sym.}
-]
-
-\GlsXtrLoadResources[src={entries-symbols},
- type=symbols,
- label-prefix={sym.},
- ext-prefixes={gls.}
-]
-\end{verbatim}
-
-Now the \code{set} entry from \filefmt{entries-terms.bib}
-will be defined with the label \code{gls.set} and the
-description will be
-\begin{verbatim}
-collection of values, denoted \gls{sym.set}
-\end{verbatim}
-The \code{set} entry
-from \filefmt{entries-symbols.bib} will be defined with the label
-\code{sym.set} and the description will be
-\begin{verbatim}
-a \gls{gls.set}
-\end{verbatim}
-
-Note that in this case the \ext{bib} files have to be loaded
-as two separate resources. They can't be combined into a
-single \csopt{src} list as the labels aren't unique.
-
-If you want to allow the flexibility to choose between
-loading them together or separately, you'll have to give them
-unique labels. For example, \filefmt{entries-terms.bib} could
-contain:
-\begin{verbatim}
-@entry{set,
- name={set},
- description={collection of values, denoted \gls{ext1.S}}
-}
-\end{verbatim}
-and \filefmt{entries-symbols.bib} could contain:
-\begin{verbatim}
-@symbol{S,
- name={\ensuremath{\mathcal{S}}},
- description={a \gls{ext1.set}}
-}
-\end{verbatim}
-Now they can be combined with:
-\begin{verbatim}
-\GlsXtrLoadResources[src={entries-terms,entries-symbols}]
-\end{verbatim}
-which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}}
-prefix from the cross-references. Alternatively:
-\begin{verbatim}
-\GlsXtrLoadResources[src={entries-terms,entries-symbols},
- label-prefix={gls.},
- ext-prefixes={gls.}
-]
-\end{verbatim}
-which will insert the supplied \csopt{label-prefix} at the
-start of the labels in the entry definitions and will replace
-the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the
-cross-references.
-
-\optsection{short-case-change}
+\optsection[\subsubsection]{short-case-change}
The value of the \field{short} field may be automatically converted
-to upper or lower case. This option may take one of the following
+to \idxlink{uppercase}{upper} or \idx{lowercase}. This option may take one of the following
values:
\begin{itemize}
\item \optfmt{none}: don't apply any case-changing (default);
-\item \optfmt{lc}: convert to lower case (ignoring
+\item \optfmt{lc}: convert to \idx{lowercase} (ignoring
\idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths}
and \ics{si}\margm{text});
-\item \optfmt{uc}: convert to upper case (ignoring
+\item \optfmt{uc}: convert to \idx{uppercase} (ignoring
\idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths}
and \ics{si}\margm{text});
-\item \optfmt{lc-cs}: convert to lower case using
+\item \optfmt{lc-cs}: convert to \idx{lowercase} using
\ics{MakeTextLowercase};
-\item \optfmt{uc-cs}: convert to upper case using
+\item \optfmt{uc-cs}: convert to \idx{uppercase} using
\ics{MakeTextUppercase};
-\item \optfmt{firstuc-cs}: convert to first letter upper case using
+\item \optfmt{firstuc-cs}: convert to first letter \idx{uppercase} using
\ics{makefirstuc};
\item \optfmt{firstuc}: convert the first alphabetical letter (or
-group) to upper case. This uses the following rules:
+group) to \idx{uppercase}. This uses the following rules:
\begin{enumerate}
\item if \idx{mshiftchar}\meta{maths}\idx{mshiftchar} then stop (no case change);
\item if \ics{NoCaseChange}\margm{text} or
@@ -7332,7 +7820,7 @@ group) to upper case. This uses the following rules:
\item if \csfmt{}\meta{csname} isn't followed by a group (and it's
not \ics{protect}), then stop (no case change applied);
\item if \margm{text} (a group) then convert the entire contents of
-\meta{text} to upper case and stop;
+\meta{text} to \idx{uppercase} and stop;
\item if \meta{character} is an alphabetic character then change it
to its title case and stop;
\item otherwise skip and move on to the next token.
@@ -7481,308 +7969,22 @@ the result is
See \csopt{dual-short-case-change} to adjust the \field{dualshort}
field.
-\optsection{name-case-change}
+\optsection[\subsubsection]{name-case-change}
As \csopt{short-case-change} but is applied to the \field{name}
field. If the \field{text} field hasn't been set, the \field{name}
-value is first copied to the \field{text} field.
+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.
-\optsection{description-case-change}
+\optsection[\subsubsection]{description-case-change}
As \csopt{short-case-change} but is applied to the
\field{description} field.
-\optsection{post-description-dot}
-
-The \styopt{postdot} package option (or \styopt[false]{nopostdot})
-can be used to append a \idx{full-stop} (\idx{periodchar})\ to the
-end of all the descriptions. This can be awkward if some of the
-descriptions end with punctuation characters. This resource option
-can be used instead. The \meta{value} may be one of:
-\begin{itemize}
-\item\optfmt{none}: don't append a \idx{full-stop} (default);
-\item\optfmt{all}: append a \idx{full-stop} to all \field{description}
- fields in this resource set;
-\item\optfmt{check}: selectively append a \idx{full-stop} (see below).
-\end{itemize}
-Note that if you have dual entries and you use this option to
-append a \idx{full-stop}, then it will be copied over to the mapped field.
-This is different to the \styopt{postdot} option which doesn't
-add the dot to the field but incorporates it in the
-\idx{postdescriptionhook}. This means that a dot inserted with
-\csopt{post-description-dot} will come before the
-\idx{postdescriptionhook} whereas with \styopt{postdot} the
-punctuation comes after any category-specific hook.
-
-The \csopt[check]{post-description-dot} setting determines whether
-to append the dot as follows:
-\begin{itemize}
-\item If the \field{description} field ends with
-\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended.
-\item If the \field{description} field doesn't end with a regular
-(ungrouped letter or other) character, then a dot is appended.
-(For example, if the description ends with a control sequence
-or an end group token.)
-\item If the \field{description} field ends with a character
-that belongs to the Unicode category \idx{punctuationclose}
-or \idx{punctuationfinalquote} then the token preceding
-that character is checked.
-\item If the \field{description} field doesn't end with
-a character that belongs to the Unicode category
-\idx{punctuationother} then the dot is added.
-\end{itemize}
-Note that the interpreter isn't used during the check.
-If the \field{description} ends with a command then a dot will be
-appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if
-that command expands in such a way that it ends with a terminating
-punctuation character. This option only applies to the
-\field{description} field.
-
-\optsection{strip-trailing-nopost}
-
-This option is always performed before \csopt{post-description-dot}
-when adjusting the \field{description} field. The default
-setting is \csopt[false]{strip-trailing-nopost}. If
-\optfmt{true} any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc}
-found in the \field{description} field will be removed.
-Note that the command (possibly followed by ignored space) must be
-at the very end of the description for it to be removed. A
-description should not contain both commands. This option
-only applies to the \field{description} field.
-
-For example, \cs{nopostdesc} will be stripped from:
-\begin{verbatim}
-description={sample\nopostdesc}
-\end{verbatim}
-since it's at the end. It will also be stripped from
-\begin{verbatim}
-description={sample\nopostdesc }
-\end{verbatim}
-since the trailing space is ignored as it follows a control
-word. It won't be stripped from
-\begin{verbatim}
-description={sample\nopostdesc{} }
-\end{verbatim}
-because the final space is now significant, but even without the
-space it still won't be stripped as the field ends with
-an empty group not with \cs{nopostdesc}. Similarly it won't be
-stripped from
-\begin{verbatim}
-description={sample\nopostdesc\relax}
-\end{verbatim}
-because again it's not at the end.
-
-\optsection{check-end-punctuation}
-
-This options checks the end of all the fields given in \meta{list} for
-end of sentence punctuation. This is determined as follows, for each
-\meta{field} in the comma-separated \meta{list}:
-\begin{itemize}
-\item if the last character is of type \idx{punctuationclose}
-or \idx{punctuationfinalquote}, check the character that comes
-before it;
-\item if the character is of type \idx{punctuationother}, then check
-if it's listed in the entry given by \code{sentence.terminators}
-in \bibgls's \langxml.
-\end{itemize}
-If a sentence terminator is found, an internal field is created
-called \field{fieldendpunc} that contains the punctuation
-character. Fields whose values must be labels (such as
-\field{parent}, \field{category} and \field{type}) aren't checked,
-even if they're included in \meta{list}.
-
-The default \code{sentence.terminators} is defined in \file{bib2gls-en.xml}
-as:
-\begin{verbatim}
-<entry key="sentence.terminators">.?!</entry>
-\end{verbatim}
-Any character that isn't of type \idx{punctuationother} won't
-match.
-
-For example, the sample \exfile{books.bib} file contains:
-\begin{verbatim}
-@entry{whydidnttheyaskevans,
- name={Why Didn't They Ask Evans?},
- description={novel by Agatha Christie},
- identifier={book},
- author={\sortmediacreator{Agatha}{Christie}},
- year={1934}
-}
-\end{verbatim}
-With \csopt[name]{check-end-punctuation}, this entry will be
-assigned an internal field called
-\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\
-as that's included in \code{sentence.terminators} and is found
-at the end of the \field{name} field:
-\begin{verbatim}
-\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?}
-\end{verbatim}
-(Note that \csopt[first,text]{check-end-punctuation} won't match
-as there's no \field{first} or \field{text} field supplied.)
-
-If you have a field that ends with an abbreviation followed by a
-\idx{full-stop}, this will be considered an end of sentence terminator, but
-the main purpose of this option is to provide a way to deal with
-cases like
-\begin{verbatim}
-Agatha Christie wrote \gls{whydidnttheyaskevans}.
-\end{verbatim}
-where the end of sentence punctuation following \cs{gls} needs to be
-discarded. This is needed regardless of whether or not
-the link text ends with an abbreviation or is a complete sentence.
-
-It's then possible to hook into the \idx{postlinkhook} \qt{discard
-period} check. By default this just checks the category attributes
-that govern whether or not to discard a following period, but
-(with \styfmt{glossaries-extra} v1.23+) it's possible to provide
-an additional check by redefining
-\nosecdef{glsxtrifcustomdiscardperiod}
-This should expand to \meta{true} if the check should be performed
-otherwise it should expand to \meta{false}. You can reference the
-label using \cs{glslabel}. For example:
-\begin{verbatim}
-\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{%
- \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}%
-}
-\end{verbatim}
-This uses \ics{GlsXtrIfFieldUndef} rather than
-\ics{glsxtrifhasfield*} since there's no need to access the field's
-value. (The unstarred form \ics{glsxtrifhasfield} can't be used
-as it introduces implicit scoping, which would interfere with the
-punctuation lookahead.) The other difference between
-\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests
-is the case where the field is set to an empty value. In this case
-the field is defined (so \ics{GlsXtrIfFieldUndef} does the
-\meta{false} argument) but it's considered unset (so commands like
-\ics{ifglshasfield} do the \meta{false} argument).
-
-\optsection{copy-action-group-field}
-
-This option may only be used when invoking \bibgls\ with the
-\longarg{group} (or \shortargfmt{g}) switch. If an action
-other than the default \csopt[define]{action} is set,
-this option can be used to identify a field in which to save
-the letter group information
-where \meta{value} is the name of the field. This just uses
-\cs{GlsXtrSetField}. You will need to redefine
-\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary.
-For example, if \csopt[dupgroup]{copy-action-group-field},
-\csopt[copy]{action} and \csopt[copies]{type} are set in
-the resource options and \code{copies} identifies a custom
-glossary:
-\begin{alltt}
-\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup}
- \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
-\end{alltt}
-
-This option is ignored when used with \csopt[define]{action}.
-This option is not used by \csopt{secondary} which will
-always save the group information in the \field{secondarygroup}
-field. When used with \csopt[define or copy]{action}, entries
-that are defined will have both \field{group} and
-the field given by \csopt{copy-action-group-field} set.
-
-Note that you may do \csopt[group]{copy-action-group-field} which
-will override the \field{group} field from the original definition.
-This may be useful if you don't use grouping in the primary
-glossary. That is, you use \code{nogroupskip} and a non-group
-style. For example:
-\begin{verbatim}
-\printunsrtglossary[nogroupskip,style=index]
-\printunsrtglossary[type=copies,style=indexgroup]
-\end{verbatim}
-
-\optsection{save-child-count}
-
-This is a boolean option. The default setting is
-\csopt[false]{save-child-count}.
-If \csopt[true]{save-child-count},
-each entry will be assigned a field called \field{childcount} with
-the value equal to the number of child entries that have been
-selected.
-
-The assignment is done using \ics{GlsXtrSetField} so there's
-no associated key.
-For example, suppose \filefmt{entries.bib} contains:
-\begin{verbatim}
-@index{birds}
-@index{duck,parent={birds}}
-@index{goose,plural={geese},parent={birds}}
-@index{swan,parent={birds}}
-
-@index{minerals}
-@index{quartz,parent={minerals}}
-@index{corundum,parent={minerals}}
-@index{amethyst,parent={minerals}}
-@index{gypsum,parent={minerals}}
-@index{gold,parent={minerals}}
-\end{verbatim}
-and the document contains:
-\begin{verbatim}
-\documentclass{article}
-
-\usepackage[record,style=indexgroup]{glossaries-extra}
-
-\GlsXtrLoadResources[src={entries},save-child-count]
-
-\begin{document}
-\gls{duck} and \gls{goose}.
-\gls{quartz}, \gls{corundum}, \gls{amethyst}.
-
-\printunsrtglossaries
-\end{document}
-\end{verbatim}
-Then the \ext{glstex} file will contain:
-\begin{verbatim}
-\GlsXtrSetField{birds}{childcount}{2}
-\GlsXtrSetField{duck}{childcount}{0}
-\GlsXtrSetField{goose}{childcount}{0}
-\GlsXtrSetField{minerals}{childcount}{3}
-\GlsXtrSetField{amethyst}{childcount}{0}
-\GlsXtrSetField{corundum}{childcount}{0}
-\GlsXtrSetField{quartz}{childcount}{0}
-\end{verbatim}
-Note that although \code{birds} has three children defined in the
-\ext{bib} file, only two have been selected, so the child count is
-set to 2. Similarly the \code{minerals} entry has five children
-defined in the \ext{bib} file, but only three have been selected, so
-the child count is 3.
-
-The following uses the post-description hook to show the child count
-in parentheses:
-\begin{verbatim}
-\GlsXtrLoadResources[src={entries},category=general,save-child-count]
-
-\renewcommand{\glsxtrpostdescgeneral}{%
- \glsxtrifhasfield{childcount}{\glscurrententrylabel}
- { (child count: \glscurrentfieldvalue.)}%
- {}%
-}
-\end{verbatim}
-(\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
-It's slightly more efficient that \ics{ifglshasfield} provided by
-the base \styfmt{glossaries} package, and it doesn't complain if the
-entry or field don't exist, but note that \ics{glsxtrifhasfield}
-implicitly scopes its content. Use the starred version to omit the
-grouping.)
-
-\optsection{save-original-id}
-
-The \meta{value} may be either the keyword \code{false} or
-the name of an internal field in which to store the entry's original
-label (as given in the \ext{bib} file). The default setting is
-\csopt[false]{save-original-id}. If \meta{value} is omitted,
-\csopt[originalid]{save-original-id} is assumed.
-
-If \meta{value} is a known field, it will be set after the field
-aliases, otherwise it will simply be added to the \ext{glstex} file
-using \ics{GlsXtrSetField} after the entry definition.
-
-\optsection{copy-alias-to-see}
-
-If set, the value of the \field{alias} field is copied to
-the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
-
\section{Plurals}
\label{sec:plurals}
@@ -8022,7 +8224,7 @@ The locations are always listed in the order in which they were indexed,
(except for the cross-reference which may be placed at the start or
end of the list or omitted).
This is different to \idx!{xindy} and \idx!{makeindex} where you can
-specify the ordering (such as lower case Roman first, then digits,
+specify the ordering (such as \idx!{lowercase} Roman first, then digits,
etc), but unlike those applications, \bibgls\ allows any location,
although it may not be able to work out an integer representation.
(With \idx!{xindy}, you can define new location formats, but you need
@@ -8202,16 +8404,16 @@ $d$ is the value of \optfmt{max-loc-diff} then the locations
are consecutive otherwise they're not consecutive.
\end{enumerate}
\item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
-where \meta{n} is a lower case Roman numeral, which is converted to
+where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to
a decimal value and the test is performed in the same way as the
above \hyperref[itm:decmatch]{decimal test}.
\item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
-where \meta{n} is an upper case Roman numeral, which is converted to
+where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to
a decimal value and the test is performed
in the same way as the above \hyperref[itm:decmatch]{decimal test}.
\item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c}
-where \meta{c} is either a lower case letter from \code{a} to
-\code{z} or an upper case letter from \code{A} to \code{Z}.
+where \meta{c} is either a \idx!{lowercase} letter from \code{a} to
+\code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}.
The character is converted to its code point and the test is
performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above.
\item\label{itm:nomatch} If none of the above, the locations aren't considered
@@ -9243,15 +9445,15 @@ rule provided by \csopt{sort-rule}.
The sort methods listed in \tableref{tab:sortoptionsletter}
use letter case comparators. These simply compare the
character codes. The \optfmt{-nocase} options first convert the
-\field{sort} field to lower case before performing the sort.
+\field{sort} field to \idx{lowercase} before performing the sort.
Punctuation isn't ignored.
Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to
emulate \idx!{xindy}['s] locale letter ordering. The examples below
show the ordering of the list \code{antelope}, \code{bee}, \code{Africa},
\code{aardvark} and \code{Brazil}.
\begin{itemize}
-\item \optfmt{letter-case}: case-sensitive letter sort. Upper case
-and lower case are in separate letter groups.
+\item \optfmt{letter-case}: case-sensitive letter sort.
+\Idx{uppercase} and \idx{lowercase} are in separate letter groups.
Example:
\code{Africa} (letter group \qt{A}), \code{Brazil}
@@ -9261,7 +9463,8 @@ Example:
\item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort.
\item \optfmt{letter-nocase}: case-insensitive letter sort. (All
-upper case characters will have first been converted to lower case.)
+\idx{uppercase} characters will have first been converted to
+\idx{lowercase}.)
Example:
\code{aardvark} (letter group \qt{A}), \code{Africa}
@@ -9272,9 +9475,9 @@ Example:
\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort.
\item \optfmt{letter-upperlower}: each character pair is first
-compared according to their lower case values. If these are equal,
+compared according to their \idx{lowercase} values. If these are equal,
then they are compared according to case. This puts upper and lower
-case in the same letter group but the upper case comes first.
+case in the same letter group but the \idx{uppercase} comes first.
Example:
\code{Africa} (letter group \qt{A}), \code{aardvark} (letter group
@@ -9284,9 +9487,9 @@ Example:
\item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort.
\item \optfmt{letter-lowerupper}: each character pair is first
-compared according to their lower case values. If these are equal,
-then they are compared according to case. This puts upper and lower
-case in the same letter group but the lower case comes first.
+compared according to their \idx{lowercase} values. If these are equal,
+then they are compared according to case. This puts
+\idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first.
Example:
\code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}),
@@ -9459,7 +9662,7 @@ letter-number sort.
\item \optfmt{letternumber-nocase}: case-insensitive
letter-number sort. The sort value is first converted to lower
case. Note that \csopt[between]{letter-number-rule} doesn't make
-sense in this context as there won't be any upper case characters in
+sense in this context as there won't be any \idx!{uppercase} characters in
the sort value, so numbers will always come before letters. Example:
\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
@@ -9478,7 +9681,8 @@ letter-number sort.
\item \optfmt{letternumber-upperlower}: upper-lower
letter-number sort. This behaves slightly differently to
\optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule}
-as it will segregate the upper and lower case characters if there
+as it will segregate the \idxlink{uppercase}{upper} and
+\idx{lowercase} characters if there
are any numerical sub-strings. Example:
\code{CH\textsubscript{2}O},
@@ -9492,9 +9696,9 @@ are any numerical sub-strings. Example:
\code{Co\textsubscript{2}O\textsubscript{3}}.
The \csopt[between]{letter-number-rule} setting enforces numbers
-after upper-case (for the case-sensitive and upper-lower methods)
-which makes the \code{\textsubscript{5}} come after the upper case
-\code{O} and forces the lower case characters to come after it.
+after \idx{uppercase} (for the case-sensitive and upper-lower methods)
+which makes the \code{\textsubscript{5}} come after the \idx{uppercase}
+\code{O} and forces the \idx{lowercase} characters to come after it.
Compare this with \csopt[before letter]{letter-number-rule} which
results in the order:
@@ -9527,16 +9731,16 @@ Example:
\code{CH\textsubscript{2}O}.
The algorithm is reversed which means that when two letters are
-compared then, if both letters have the same lower case version,
-the upper-lower rule is reversed and lower case comes before
-upper case. This means that \code{o} comes before \code{O}.
-If their lower case versions aren't identical, the letter
-with the higher lower case Unicode value comes first. This means
+compared then, if both letters have the same \idx{lowercase} version,
+the upper-lower rule is reversed and \idx{lowercase} comes before
+\idx{uppercase}. This means that \code{o} comes before \code{O}.
+If their \idx{lowercase} versions aren't identical, the letter
+with the higher \idx{lowercase} Unicode value comes first. This means
that both \code{o} and \code{O} come before \code{l} which comes
before \code{H}. So far, this gives the order:
\code{o}, \code{O}, \code{l}, \code{H}.
The \csopt[between]{letter-number-rule} setting inserts numbers between
-upper and lower case letters. This puts the numbers (in reverse
+\idxlink{uppercase}{upper} and \idx{lowercase} letters. This puts the numbers (in reverse
order) between \code{o} and \code{O}.
Compare this with \csopt[before letter]{letter-number-rule} which
@@ -9573,9 +9777,9 @@ Example:
\code{CO}.
The \csopt[between]{letter-number-rule} setting enforces numbers
-after lower-case (for the lower-upper method)
+after \idx{lowercase} (for the lower-upper method)
so the \code{\textsubscript{5}} is put after \code{o}, and forces
-the upper case characters after the numbers.
+the \idx{uppercase} characters after the numbers.
Compare this with \csopt[before letter]{letter-number-rule} which
results in the order:
@@ -9925,6 +10129,26 @@ trailing spaces. The default setting is \csopt[true]{trim-sort}.
This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort}
and \csopt[\meta{boolean}]{secondary-trim-sort}.
+\optsection{sort-replace}
+
+This option may be used to perform regular expression substitutions
+on the sort value and has the same syntax as \csopt{labelify-replace}.
+This action is done after the interpreter parses the
+sort value (if applicable) and before \csopt{sort-number-pad} (if
+applicable). For example, suppose the sort value is
+\begin{verbatim}
+\ensuremath{\approx 3.14}
+\end{verbatim}
+then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but
+\begin{codeenv}
+\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace}
+\end{codeenv}
+can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can
+now be parsed as a number if \csopt[double]{sort} has been used.
+
+Use \csopt{dual-sort-replace} for dual
+and \csopt{secondary-sort-replace} for secondary sort methods.
+
\optsection{sort-rule}
If the \csopt[custom]{sort} option is used, the sort rule must be
@@ -10080,6 +10304,16 @@ and \qt{seal} becomes \verb"seal|". The default marker is \verb"|"
which is commonly placed in collation rules before digits but
after the ignored characters, such as spaces and hyphens.
+Note that this action removes non-letters, so for example,
+if the sort value is \verb"# (parameter)" then it will be converted
+to \verb"parameter|" (hash, space and parentheses removed).
+If you only want to break at spaces (optionally following a command)
+use the following instead:
+\begin{codeenv}
+ \csopt[none]{break-at},
+ \csopt[\marg{,? +}\marg{|}]{sort-replace}
+\end{codeenv}
+
You can change the construction of the break points with
\csopt[\meta{option}]{break-at} where \meta{option} may be one of:
\begin{itemize}
@@ -10093,12 +10327,12 @@ For example, the sort value \qt{Tom, Dick, and Harry} becomes
characters.
\item \optfmt{character}: break after each character.
\item \optfmt{sentence}: break after each sentence.
-\item \optfmt{upper-notlower}: break after any upper case character
-that's not followed by a lower case character. For example,
+\item \optfmt{upper-notlower}: break after any \idx{uppercase} character
+that's not followed by a \idx{lowercase} character. For example,
\qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes
\verb"W|3C|".
-\item \optfmt{upper-upper}: break after any upper case character
-that's followed by an upper case character.
+\item \optfmt{upper-upper}: break after any \idx{uppercase} character
+that's followed by an \idx{uppercase} character.
\item \optfmt{upper-notlower-word}: first applies break-points
according to \optfmt{upper-notlower} and then according to
\optfmt{word}.
@@ -10106,7 +10340,8 @@ according to \optfmt{upper-notlower} and then according to
according to \optfmt{upper-upper} and then according to
\optfmt{word}.
\item \optfmt{none}: don't create break points. Use this option to
-emulate \idx{makeindex} or \idx{xindy}'s letter ordering.
+emulate \idx{makeindex} or \idx{xindy}'s letter ordering, or combine
+with \csopt{sort-replace} to insert custom break points.
\end{itemize}
This option is ignored when used with the non-alphabetic \csopt{sort} options.
@@ -10616,9 +10851,10 @@ letter.
letter.
\item\optfmt{between}: (default) numbers come between letter cases.
With the \optfmt{-case} or \optfmt{-upperlower} sort options,
-this will put numbers after upper case and before lower case.
+this will put numbers after \idx{uppercase} and before
+\idx{lowercase}.
With the \optfmt{-lowerupper} sort option, this will put numbers
-after lower case and before upper case. This setting doesn't make
+after \idx{lowercase} and before \idx{uppercase}. This setting doesn't make
much sense with the \optfmt{-nocase} option but, if used, this will put
numbers before letters.
\item\optfmt{first}: numbers are considered less than all
@@ -10628,8 +10864,8 @@ characters (including punctuation and spaces).
\end{itemize}
Note that the reverse sort methods will invert this setting.
Remember also that the case-insensitive letter-number sort methods always
-first convert the \field{sort} field to lower case, which means that
-if you use one of them then there won't be any upper case
+first convert the \field{sort} field to \idx{lowercase}, which means that
+if you use one of them then there won't be any \idx{uppercase}
characters.
Use \csopt{letter-number-punc-rule} to determine the relative
@@ -10846,7 +11082,7 @@ Then the entries can be sorted by date of birth using:
\end{verbatim}
The \code{G} (era) date pattern specifier expects a string, such as
-\qt{AD}. It will match lower case forms, such as \qt{ad}, so if you
+\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you
have \verb|\textsc{ad}| the interpreter will convert this to
\code{ad} (stripping the text-block command). However, in general
it's best to supply a semantic command that ensures that the
@@ -10905,15 +11141,15 @@ setting.
\item\optfmt{codepoint}: the group is set to
\icswithargs{bibglsunicodegroup}, where the first argument is the
-first significant character (converted to lower case and decomposed,
+first significant character (converted to \idx{lowercase} and decomposed,
if applicable) of the sort value.
\item\optfmt{unicode category}: the group is set to
\icswithargs{bibglsunicodegroup}, where the first argument is the
label identifying the Unicode category of the first significant
character of the sort value. For example, the label \code{Ll}
-signifies a lower case letter and \code{Lu} signifies an upper case
-letter.
+signifies a \idx!{lowercase} letter and \code{Lu} signifies an
+\idx!{uppercase} letter.
\item\optfmt{unicode script}: the group is set to
\icswithargs{bibglsunicodegroup}, where the first argument is the
@@ -10927,7 +11163,7 @@ that are often used with non-Greek scripts).
\icswithargs{bibglsunicodegroup}, where the first argument is the
label corresponding to the Unicode category and script of the first
significant character of the sort value. For example, the label
-\code{Ll.LATIN} indicates a lower case Latin letter.
+\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter.
\end{itemize}
This option has no effect with \longarg{no-group} or if no sorting
is applied. Use \csopt{secondary-group-formation} for secondary
@@ -11094,6 +11330,10 @@ As \csopt{missing-sort-fallback} but for secondary sorting.
As \csopt{trim-sort} but for secondary sorting.
+\optsection{secondary-sort-replace}
+
+As \csopt{sort-replace} but for secondary sorting.
+
\optsection{secondary-sort-rule}
As \csopt{sort-rule} but for secondary custom sorting.
@@ -11303,7 +11543,7 @@ file (or created through a mapping). The \meta{value} is required.
The \meta{value} may be:
\begin{itemize}
\item \optfmt{same as entry}: sets the \field{type} to the entry
-type (lower case and without
+type (\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}.
@@ -11312,7 +11552,7 @@ entry type not the original entry type provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{type} field
-to the original entry type (lower case and without
+to the original entry type (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
\optfmt{same as entry} if the entry type wasn't aliased).
@@ -11361,7 +11601,7 @@ file (or created through a mapping). The \meta{value} may be empty.
The \meta{value} may be:
\begin{itemize}
\item \optfmt{same as entry}: sets the \field{category} to the entry
-type (lower case and without
+type (\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}.
@@ -11370,7 +11610,7 @@ entry type not the original entry type provided in the \ext{bib}
file.
\item \optfmt{same as original entry}: set the \field{category} field
-to the original entry type (lower case and without
+to the original entry type (\idx{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
\optfmt{same as entry} if the entry type wasn't aliased).
@@ -11411,7 +11651,9 @@ to the start of the \iext{glstex} file providing the key given by
\meta{value}. Any entries defined using \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 \code{dual} is assumed.
+omitted \csopt[dual]{dual-field} is assumed. If you use a different
+value, you will need to redefine \gls{GlsXtrDualField} (either
+locally or globally).
For example, if the \ext{bib} file contains
\begin{verbatim}
@@ -11531,6 +11773,10 @@ As \csopt{missing-sort-fallback} but for dual sorting.
As \csopt{trim-sort} but for dual sorting.
+\optsection[\subsubsection]{dual-sort-replace}
+
+As \csopt{sort-replace} but for dual sorting.
+
\optsection[\subsubsection]{dual-sort-rule}
As \csopt{sort-rule} but for \csopt[custom]{dual-sort}.
@@ -11820,13 +12066,39 @@ defined with \atentry{dualsymbol} instead of \atentry{dualentry}.
Analogous to \csopt{dual-entry-backlink} but for entries
defined with \atentry{dualabbreviationentry} instead of
-\atentry{dualentry}.
+\atentry{dualentry}. This setting can be problematic as the
+backlinks rely on the relevant field being known to \bibgls.
+Since the abbreviation style typically sets the \field{name}
+field (and sometimes the \field{description} field as well), you may
+find that no backlink appears. A simple workaround is to
+use \csopt{dual-field} (or \csopt[dual]{dual-field})
+to store the dual label in the \field{dual} field, and then
+use a style that checks for this field and adds the backlink.
+
+With \sty{glossaries-extra} v1.30+ you can use
+\nosecdef{GlsXtrDualBackLink}
+which encapsulates \meta{text} with a hyperlink to the dual.
+The \meta{label} identifies the entry that requires a backlink.
+The dual's label is obtained from the field given by
+\nosecdef{GlsXtrDualField}
+which defaults to \field{dual}. Note that if you assign a
+different field label with \csopt{dual-field}, then you will
+need to redefine \gls{GlsXtrDualField} as appropriate.
+
+For example:
+\begin{verbatim}
+\renewcommand*{\glsuserdescription}[2]{%
+ \GlsXtrDualBackLink{\glslonguserfont{#1}}{#2}%
+}
+\setabbreviationstyle{long-short-user}
+\GlsXtrLoadResources[src={entries},dual-field]
+\end{verbatim}
\optsection[\subsubsection]{dual-entryabbrv-backlink}
-Analogous to \csopt{dual-entry-backlink} but for entries
+As \csopt{dual-abbrventry-backlink} but for entries
defined with \atentry{dualentryabbreviation} instead of
-\atentry{dualentry}.
+\atentry{dualabbreviationentry}.
\optsection[\subsubsection]{dual-indexentry-backlink}
@@ -11919,7 +12191,7 @@ file is:
\longnewglossaryentry*{#1}{name={#3},#2}{#4}%
}
\end{verbatim}
-This uses the starred form of \gls{longnewglossaryentry} that
+This uses the starred form \ics{longnewglossaryentry*} that
doesn't automatically append \ics{nopostdesc} (which interferes with
the post-description hooks provided by category attributes).
@@ -11970,15 +12242,29 @@ file is:
\newglossaryentry{#1}{name={#1},category={index},description={},#2}%
}
\end{verbatim}
-This makes the \field{name} default to the \meta{label}, assigns the
+This makes the \field{name} default to the \meta{label}, assigns
the \field{category} to \code{index} and sets an empty
\field{description}. These settings may be overridden by
\meta{options}.
Note that the \field{description} doesn't include
-\ics{nopostdesc} to allow for the post-description hook used by
+\ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by
category attributes.
+\cssection{bibglsnewindexplural}
+
+\formatdef{bibglsnewindexplural}
+This command is used to define terms identified with the
+\atentry{indexplural} type. The definition provided in the \ext{glstex}
+file is:
+\begin{verbatim}
+\providecommand{\bibglsnewindexplural}[3]{%
+ \newglossaryentry{#1}{name={#3},category={indexplural},description={},#2}%
+}
+\end{verbatim}
+This assigns the \field{category} to \code{indexplural} and sets an empty
+\field{description}. These settings may be overridden by \meta{options}.
+
\cssection{bibglsnewabbreviation}
\formatdef{bibglsnewabbreviation}
@@ -12771,7 +13057,7 @@ according to the rule):
For example, if the rule recognises the digraph \qt{dz}, then the
title is \qt{Dz}. Exceptions to this are included in the \langxml.
If the key \code{grouptitle.case.\meta{lc}} exists, where
-\meta{lc} is the lower case version of \meta{title}, then the value
+\meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value
of that key is used instead. For example, the Dutch digraph \qt{ij}
should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes:
\begin{verbatim}
@@ -12779,7 +13065,7 @@ should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes:
\end{verbatim}
(See the \longarg{group} switch for more details.)
\item \meta{letter} This is the actual letter at the start of the
-given entry's \field{sort} field, which may be lower case or may
+given entry's \field{sort} field, which may be \idx!{lowercase} or may
contain diacritics that don't appear in \meta{title}.
\item \meta{id} A numeric identifier. This may be the collation key
or the code point for the given letter, depending on the sort
@@ -12799,6 +13085,51 @@ This field needs to expand to a simple label, which \csref{bibglslettergroup}
is designed to do. Note that non-letter groups are dealt with
separately (see below).
+\cssection{bibglssetlastgrouptitle}
+
+In the last resource (\ext{glstex}) file, after all the relevant
+group titles have been set with the commands listed below, there's a
+final title setting:
+\formatdef{bibglssetlastgrouptitle}
+This does nothing by default, but the arguments are set to
+correspond to the group with the maximum id for that resource file.
+It's provided as a convenient way of overriding the final group
+title without the inconvenience of looking up the group label in the
+\ext{glstex} file. If you have multiple glossaries or if you want to
+override a different group, then you need to inspect the
+\ext{glstex} file to work out the corresponding label (by finding
+the \field{group} assignment for one of the entries in that group).
+
+The \meta{cs} argument is the control sequence used in the
+\field{group} field to obtain the label from \meta{specs}. For
+example, if the highest \meta{id} is 2147418112 from
+\begin{codeenv}
+\field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}
+\end{codeenv}
+then the last group is identified with
+\begin{verbatim}
+\bibglssetlastgrouptitle{\bibglslettergroup}{{Ø}{Ø}{2147418112}{}}
+\end{verbatim}
+In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs}
+are the arguments for that command. If you want \gls{bibglssetlastgrouptitle}
+to change the group title then you need to define it before the
+\idx{resourceset}. For example:
+\begin{verbatim}
+\newcommand*{\bibglssetlastgrouptitle}[2]{%
+ \glsxtrsetgrouptitle{#1#2}{Foreign Words}}
+
+\GlsXtrLoadResources[sec={entries}]
+\end{verbatim}
+If you need to change a particular group title, then it has to be
+done after the \idx{resourceset}:
+\begin{verbatim}
+\GlsXtrLoadResources[sec={entries}]
+
+\glsxtrsetgrouptitle
+ {\bibglslettergroup{{Ø}{Ø}{2147418112}{}}}% label
+ {Foreign Words}% title
+\end{verbatim}
+
\cssection{bibglssetlettergrouptitle}
For each \idx{lettergroup} that's detected, \bibgls\ will write the line:
@@ -13105,11 +13436,11 @@ obtained from \cs{bibglsunicodegrouptitle}.
The \meta{label} depends on the \csopt{group-formation} setting:
\begin{itemize}
\item\csopt[codepoint]{group-formation}: the \meta{label} is the
-Unicode value of \meta{character} (converted to lower case and
+Unicode value of \meta{character} (converted to \idx!{lowercase} and
decomposed, if applicable);
\item\csopt[unicode category]{group-formation}: the \meta{label} is the
Unicode category of \meta{character} (for example, \code{Lu} means
-an upper case letter);
+an \idx!{uppercase} letter);
\item\csopt[unicode script]{group-formation}: the \meta{label} is the
Unicode script associated with \meta{character} (for example,
\code{LATIN});
@@ -13136,7 +13467,7 @@ whereas with \csopt[unicode category and script]{group-formation} it will be:
\begin{verbatim}
group={\bibglsunicodegroup{Lu.LATIN}{Å}{C5}{}}
\end{verbatim}
-(upper case Latin letter).
+(\idx!{uppercase} Latin letter).
If instead \qt{\AA} is considered equivalent to \qt{A} according to the
collator, then with \csopt[codepoint]{group-formation}, the value will be:
@@ -14358,6 +14689,30 @@ doesn't occur in the \field{description} field. (Note that
The contents of \filefmt{films.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/films.bib}
+\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
+to \atentry{bibtexentry}, which can easily be done with
+\begin{codeenv}
+entry-type-aliases=\marg{\ics{GlsXtrBibTeXEntryAliases}}
+\end{codeenv}
+The field names will also need to be defined or aliased. For
+example:
+\begin{codeenv}
+field-aliases=\marg{title=name}
+\end{codeenv}
+If \bibgls\ is then run with \longarg{cite-as-record} any
+\ics{citation} commands found in the \ext{aux} file will be treated
+as ignored records. The \atentry{preamble} provides a formatting
+command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand}
+is required rather than \cs{newcommand} as it will appear in both
+the \iext{bbl} and the \iext{glstex} files. (In general it's best to
+use \cs{providecommand} rather than \cs{newcommand} in the
+\atentry{preamble} but in this case it's essential.)
+The contents of \filefmt{citations.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/citations.bib}
+
\filesection{mathgreek.bib}
The \exfile{mathgreek.bib} file contains Greek letters for use in
@@ -14368,7 +14723,7 @@ by the \field{name} field (for example, with \csopt[name]{sort-field})
the \TeX\ parser library recognises all the mathematical Greek letter commands
provided in the \LaTeX\ kernel. Additionally it recognises
\ics{omicron} which isn't provided by \LaTeX\ (the symbol can be
-reproduced with a lower case Latin \qt{o}). Note that
+reproduced with a \idx!{lowercase} Latin \qt{o}). Note that
\isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+)
provides all the missing Greek letters (such as \cs{omicron}).
@@ -14400,7 +14755,7 @@ but \LaTeX\ needs a definition for this, so it's provided in the
\end{verbatim}
(With \sty{glossaries-extra} v1.27+, this is no longer needed.)
The \TeX\ parser library and \sty{glossaries-extra-bib2gls}
-similarly provide the missing upper case
+similarly provide the missing \idx!{uppercase}
Greek letters, and these can be dealt with in the same way.
The contents of \filefmt{mathgreek.bib} are as follows:
@@ -16042,7 +16397,7 @@ field with \csopt{field-aliases}:
\csopt[author=parent]{field-aliases}
\end{codeenv}
but the author's label in the \exfile{people.bib}
-file is just the lower case surname.
+file is just the \idx!{lowercase} surname.
Remember from \sectionref{sec:texparserlib} that the interpreter
will be used on the \field{parent} field if the value contains
@@ -16117,8 +16472,6 @@ The resulting document is shown in \figureref{fig:sample-authors.pdf}.
\lstinputlisting[firstline=5]{../examples/sample-authors.tex}
-\lstinputlisting[firstline=5]{../examples/sample-authors.tex}
-
\begin{figure}
\figcontents
{%
@@ -16128,6 +16481,167 @@ The resulting document is shown in \figureref{fig:sample-authors.pdf}.
{fig:sample-authors.pdf}
\end{figure}
+\filesection{sample-citations.tex}
+
+This example uses the \BibTeX\ file \exfile{citations.bib} to create
+a document that has both a bibliography created by \BibTeX\ and
+glossaries created by \bibgls\ listing the authors and the titles.
+There are no glossary reference commands, such as \cs{gls}, but
+\bibgls\ can be run with \longarg{cite-as-record} to treat the
+\ics{citation} commands (written to the \ext{aux} file by \ics{cite})
+as ignored records. Since \cs{cite} doesn't record the page number,
+there are no associated locations.
+
+The \code{main} glossary isn't required, so I've used
+\styopt{nomain} to suppress its creation. I want to use both the
+\glostyle{altlist} and \glostyle{indexgroup} styles but none of the
+other styles, so I've used \styopt{nostyles} to prevent the
+automatic loading of the default style packages and
+\styopt{stylemods} to load the \sty{glossary-tree} and
+\sty{glossary-list} packages and patch the styles. A \idx{full-stop}
+is automatically placed after the descriptions with
+\styopt{postdot}.
+\begin{verbatim}
+\usepackage[record,% using bib2gls
+nomain,% don't define main glossary
+postdot,% full stop after descriptions
+nostyles,% don't load default styles
+% load glossary-tree and glossary-list and patch styles:
+stylemods={tree,list}
+]{glossaries-extra}
+\end{verbatim}
+Next I need to create the glossaries for the list of authors and
+list of titles:
+\begin{codeenv}
+\cs{newglossary*}\marg{contributors}\marg{Authors}
+\cs{newglossary*}\marg{titles}\marg{Titles}
+\end{codeenv}
+The simplest way of assigning the authors to the \code{contributors}
+glossary and the titles to the \code{titles} glossary is to use
+\begin{codeenv}
+\csopt[contributors]{type}
+\end{codeenv}
+in the \idx{resourceset} and provide a
+modified version of \ics{bibglsnewbibtexentry} that assigns
+\field{type} after the options:
+\begin{codeenv}
+\cs{newcommand}\marg{\cs{bibglsnewbibtexentry}}[4]\marg{\idx{commentchar}
+ \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{name=\marg{\idx{param}3},\idx{param}2,type=\marg{titles}}\marg{\idx{param}4}\idx{commentchar}
+}
+\end{codeenv}
+The standard \BibTeX\ entry types need aliasing to
+\atentry{bibtexentry}:
+\begin{codeenv}
+\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
+\end{codeenv}
+and the \fieldfmt{title} field is aliased to \field{name}:
+\begin{codeenv}
+\csopt[title=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:
+\begin{codeenv}
+\csopt[same as original entry]{category}
+\end{codeenv}
+So, for example, an entry that's provided in the \ext{bib} file with
+\atentryfmt{article} has the \field{category} field set to
+\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
+are \code{contributor}.
+
+In order to list the titles according to category, I've use this as
+the sort field:
+\begin{codeenv}
+\csopt[category]{sort-field}
+\end{codeenv}
+and setting the sort suffix to the \field{name} field sub-sorts
+the \atentry{bibtexentry} types according to the title
+(which was aliased to the \field{name}) and the
+\atentry{contributor} types according to the author:
+\begin{codeenv}
+\csopt[name]{sort-suffix}
+\end{codeenv}
+
+Next the groups identified by the labels \code{article} and \code{book}
+are assigned titles.
+\begin{codeenv}
+\cs{glsxtrsetgrouptitle}\marg{article}\marg{Articles}
+\cs{glsxtrsetgrouptitle}\marg{book}\marg{Books}
+\end{codeenv}
+The \field{group} field is actually set to the associated letter by the default
+\csopt{sort} method. The desired labels are stored in the \field{category}
+field. Since the entries are sorted by category, then they are naturally
+in those sub-blocks, which means that the group titles can be set by locally
+redefining \ics{glsxtrgroupfield} to \code{category}:
+\begin{codeenv}
+\cs{printunsrtglossary*}[type=titles,style=indexgroup]
+\marg{\idx{commentchar}
+ \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{category}\idx{commentchar}
+ \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\idx{commentchar}
+ \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\idx{commentchar}
+}
+\end{codeenv}
+There's no \field{description} field set for these entries, but the
+\idx{postdescriptionhook} can still be used to append information.
+In this case, I've appended a cross-reference to the bibliography.
+Since the bibliography entry and the glossary term both have the
+same label, the citation can easily be obtained with
+\code{\ics{cite}\marg{\cs{glscurrententrylabel}}}:
+\begin{codeenv}
+\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
+this case the \ext{bib} file only contains \atentryfmt{article} and
+\atentryfmt{book} entries. (Similarly for the group titles above.)
+
+The list of contributors can simply be displayed with:
+\begin{codeenv}
+\cs{printunsrtglossary}[type=contributors,style=altlist]
+\end{codeenv}
+This will only list the names as there's no description, but again
+the \idx{postdescriptionhook} can be used, in this case for the \code{contributor}
+category. The hook iterates
+over the internal list provided by the \field{bibtexentry} field.
+This allows the titles to be listed as well:
+\begin{codeenv}
+\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\idx{commentchar}
+ \ics{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\idx{commentchar}
+ \marg{\idx{commentchar}
+ \cs{glsxtrfieldforlistloop}
+ \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\idx{commentchar}
+ \marg{\csfmt{contributorhandler}}\idx{commentchar}
+ }\idx{commentchar}
+ \marg{\ics{par} No titles.}\idx{commentchar}
+}
+\end{codeenv}
+The handler macro displays the name of the associated
+\atentry{bibtexentry} term and the citation:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}}
+\end{codeenv}
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-citations
+bib2gls --group --cite-as-record sample-citations
+bibtex sample-citations
+pdflatex sample-citations
+pdflatex sample-citations
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-citations.pdf}.
+
+\lstinputlisting[firstline=7]{../examples/sample-citations.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-citations.pdf}{2}}
+{\caption{\filefmt{sample-citations.pdf}}}
+{fig:sample-citations.pdf}
+\end{figure}
+
\filesection{sample-msymbols.tex}
This example uses \exfile{bigmathsymbols.bib},
@@ -16430,7 +16944,7 @@ the \atentry{preamble} definition, which is now in the resource file.
The tagging format is governed by \ics{glsxtrtagfont} which
underlines its argument by default. I've redefined it to also
-convert the letter to uppercase:
+convert the letter to \idx{uppercase}:
\begin{verbatim}
\renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}}
\end{verbatim}
@@ -16471,7 +16985,7 @@ location lists. This doesn't affect the entries that haven't been
indexed.
I decided to convert the first letter of the \field{name} field to
-uppercase. Since the \field{name} is implicitly set for
+\idx{uppercase}. Since the \field{name} is implicitly set for
abbreviations based on the style, I've decided to implement this
through the \catattr{glossname} attribute rather than using
\csopt{name-case-change}:
@@ -17149,7 +17663,7 @@ rule for the duals, but with the numbers padded:
\end{codeenv}
This method doesn't work as well as the method used in
\exfile{sample-chemical.tex} as it doesn't separate the capitals,
-digits and lower case characters in the way that can be achieved with the
+digits and \idx!{lowercase} characters in the way that can be achieved with the
letter-number methods. An improvement can be made by changing the
break-points. I could use \csopt[upper-upper]{dual-break-at} but
this would put \qt{seal} before \qt{sea lion} in the \code{animal}
@@ -17865,6 +18379,7 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf},
{fig:sample-multi2.pdf3}
\end{figure}
+\printstyoptsummary
\printcommandsummary
\bibliographystyle{plain}