summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-02-25 21:29:39 +0000
committerKarl Berry <karl@freefriends.org>2018-02-25 21:29:39 +0000
commit9a8a1754a015e59822d1282bc58a93625aad626b (patch)
treeba2de184c48d63121e0c0f8ea1658b93a8dca771 /Master/texmf-dist/source/support
parentc866cc1cc9d403e1ea81bea28950da1ac62494a7 (diff)
bib2gls (25feb18)
git-svn-id: svn://tug.org/texlive/trunk@46742 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/support')
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib8
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zipbin132823 -> 138027 bytes
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib179
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod24
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex765
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zipbin19544 -> 18730 bytes
-rw-r--r--Master/texmf-dist/source/support/bib2gls/src/texparser-src.zipbin610669 -> 700783 bytes
7 files changed, 876 insertions, 100 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib
index 3f131eb252d..da1a2047b4b 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib
@@ -70,6 +70,14 @@
year=2017
}
+@misc{javacldr,
+ author={Oracle},
+ title={Adoption of Unicode CLDR Data and the java.locale.providers
+System Property},
+ note={\url{https://docs.oracle.com/javase/8/docs/technotes/guides/intl/enhancements.8.html#cldr}},
+ year = 2018
+}
+
@inbook{iterationtips,
author = "Nicola L. C. Talbot",
title = "{\LaTeX} for Administrative Work",
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
index 95f6c3cdf85..008daefa215 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
Binary files differ
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
index f517f088b20..a400cdf49bf 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
@@ -22,6 +22,11 @@
long = {{}\TeX\ Users Group}
}
+@abbreviation{CLDR,
+ short = {CLDR},
+ long = {Unicode Common Locale Data Repository}
+}
+
@abbreviation{SIunit,
short = {SI unit},
long = {International System of Units},
@@ -499,6 +504,30 @@ given label},
category={command}
}
+@dualindexentry{bibglssetunicodegrouptitle,
+ name={\csfmt{bib\-gls\-set\-unicode\-group\-title}},
+ user1={\marg{\margm{label}\margm{character}\margm{id}\margm{type}}},
+ description={sets the Unicode script, category or character code
+title},
+ category={command}
+}
+
+@dualindexentry{bibglsunicodegroup,
+ name={\csfmt{bib\-gls\-unicode\-group}},
+ user1={\margm{label}\margm{character}\margm{id}\margm{type}},
+ description={expands to the Unicode script or category label or
+character code},
+ category={command}
+}
+
+@dualindexentry{bibglsunicodegrouptitle,
+ name={\csfmt{bib\-gls\-unicode\-group\-title}},
+ user1={\margm{label}\margm{character}\margm{id}\margm{type}},
+ description={expands to the Unicode script or category label or
+character code},
+ category={command}
+}
+
@dualindexentry{bibglssetnumbergrouptitle,
name={\csfmt{bib\-gls\-set\-number\-group\-title}},
user1={\marg{\margm{value}\margm{id}\margm{type}}},
@@ -955,6 +984,27 @@ name},
parent={resourceoptions}
}
+@dualindexentry{opt.labelify,
+ name={\csoptfmt{labelify}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+@dualindexentry{opt.labelify-list,
+ name={\csoptfmt{labelify\dhyphen list}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+@dualindexentry{opt.labelify-replace,
+ name={\csoptfmt{labelify\dhyphen replace}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
@dualindexentry{opt.action,
name={\csoptfmt{action}},
user1={\meta{value}},
@@ -1285,6 +1335,27 @@ field\dhyphen locale}},
parent={resourceoptions}
}
+@dualindexentry{opt.group-formation,
+ name={\csoptfmt{group\dhyphen formation}},
+ user1={\meta{value}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+@dualindexentry{opt.secondary-group-formation,
+ name={\csoptfmt{secondary\dhyphen group\dhyphen formation}},
+ user1={\meta{value}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+@dualindexentry{opt.dual-group-formation,
+ name={\csoptfmt{dual\dhyphen group\dhyphen formation}},
+ user1={\meta{value}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
@dualindexentry{opt.save-child-count,
name={\csoptfmt{save\dhyphen child\dhyphen count}},
user1={\meta{value}},
@@ -2143,10 +2214,19 @@ cs}\margm{Glspl-like cs}},
category={command}
}
+@index{alpha,
+ name={\csfmt{alpha}},
+ user1={},
+ description={Greek letter alpha $\alpha$},
+ note={kernel command (maths mode only)},
+ category={command}
+}
+
@index{omicron,
name={\csfmt{omicron}},
user1={},
- description={custom command},
+ description={Greek letter omicron $\omicron$},
+ note={provided by \styfmt{glossaries-extra-bib2gls}},
category={command}
}
@@ -2405,8 +2485,8 @@ cs}\margm{Glspl-like cs}},
parent={packages}
}
-@index{pifonts,
- name={\styfmt{pifonts}},
+@index{pifont,
+ name={\styfmt{pifont}},
category={package},
parent={packages}
}
@@ -2417,12 +2497,42 @@ cs}\margm{Glspl-like cs}},
parent={packages}
}
+@index{xspace,
+ name={\styfmt{xspace}},
+ category={package},
+ parent={packages}
+}
+
@index{fourier,
name={\styfmt{fourier}},
category={package},
parent={packages}
}
+@index{lipsum,
+ name={\styfmt{lipsum}},
+ category={package},
+ parent={packages}
+}
+
+@index{natbib,
+ name={\styfmt{natbib}},
+ category={package},
+ parent={packages}
+}
+
+@index{textcomp,
+ name={\styfmt{textcomp}},
+ category={package},
+ parent={packages}
+}
+
+@index{MnSymbol,
+ name={\styfmt{MnSymbol}},
+ category={package},
+ parent={packages}
+}
+
@index{wasysym,
name={\styfmt{wasysym}},
category={package},
@@ -2459,6 +2569,12 @@ cs}\margm{Glspl-like cs}},
parent={packages}
}
+@index{tipa,
+ name={\styfmt{tipa}},
+ category={package},
+ parent={packages}
+}
+
@index{mfirstuc,
name={\styfmt{mfirstuc}},
category={package},
@@ -2495,6 +2611,12 @@ cs}\margm{Glspl-like cs}},
parent={packages}
}
+@index{glossaries-extra-bib2gls,
+ name={\styfmt{glossaries\dhyphen extra\dhyphen bib2gls}},
+ category={package},
+ parent={packages}
+}
+
@index{glossary-list,
name={\styfmt{glossary\dhyphen list}},
category={package},
@@ -2555,6 +2677,12 @@ cs}\margm{Glspl-like cs}},
parent={packages}
}
+@index{amsmath,
+ name={\styfmt{amsmath}},
+ category={package},
+ parent={packages}
+}
+
@index{textcase,
name={\styfmt{textcase}},
category={package},
@@ -4167,6 +4295,35 @@ field.},
parent={commandlineoptions}
}
+@dualindexentry{switch.force-cross-resource-refs,
+ name={\longargfmt{force\dhyphen cross\dhyphen resource\dhyphen refs}},
+ symbol={\shortargfmt{x}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+@dualindexentry{switch.no-force-cross-resource-refs,
+ name={\longargfmt{no\dhyphen force\dhyphen cross\dhyphen resource\dhyphen refs}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+@dualindexentry{switch.support-unicode-script,
+ name={\longargfmt{support\dhyphen unicode\dhyphen script}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+@dualindexentry{switch.no-support-unicode-script,
+ name={\longargfmt{no\dhyphen support\dhyphen unicode\dhyphen script}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
@dualindexentry{switch.packages,
name={\longargfmt{packages}},
symbol={\shortargfmt{p}},
@@ -4351,6 +4508,10 @@ field.},
name={custom group}
}
+@index{localeprovider,
+ name={locale provider}
+}
+
@index{ignoredglossary,
name={ignored glossary},
plural={ignored glossaries}
@@ -5697,7 +5858,17 @@ defined},
name={\csfmt{glshex}},
user1={},
description={expands to \cs{cs.string}\cs{u}},
- note={provided by \styfmt{glossaries-extra} v1.21+},
+ note={provided by \styfmt{glossaries-extra} v1.21+ (moved to
+\styfmt{glossaries-extra-bib2gls} in v1.27)},
+ category={command}
+}
+
+@index{glsxtrprovidecommand,
+ name={\csfmt{glsxtrprovidecommand}},
+ user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}},
+ description={behaves like \cs{providecommand} in the document but
+ like \cs{renewcommand} in \bibgls},
+ note={provided by \styfmt{glossaries-extra-bib2gls} v1.27+},
category={command}
}
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod
index f41ce3bcf96..c1c986bef27 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod
@@ -84,6 +84,28 @@ Interpret tilde character as a normal space.
Interpret tilde as a non-breaking space (default).
+=item B<--force-cross-resource-refs> or B<-x>
+
+Force cross-resource referencing mode on.
+
+=item B<--no-force-cross-resource-refs>
+
+Don't force cross-resource referencing mode on (default).
+
+=item B<--support-unicode-script>
+
+Text superscript (\textsuperscript) or subscripts (\textsubscript)
+will use Unicode superscript/subscript characters if available.
+For example, \textsuperscript{2} will be converted to U+00B2
+(superscript two).
+
+=item B<--no-support-unicode-script>
+
+Text superscript (\textsuperscript) or subscripts (\textsubscript)
+won't be converted to Unicode superscript/subscript characters.
+For example, \textsuperscript{2} will be converted to <sup>2</sup>
+and the markup will be stripped leaving just the character 2.
+
=item B<--packages> I<list> (or B<-p> I<list>)
Instruct the TeX parser library to pretend the packages listed
@@ -185,7 +207,7 @@ Write B<\glsnoexpandfields> to the B<.glstex> file (default).
=head1 REQUIRES
-Java 7 and a TeX distribution.
+Java 7 or later and a TeX distribution.
=head1 LICENSE
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index 538acf5c19b..8c6e3fedabb 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -48,6 +48,8 @@
\glsxtrprovidestoragekey{note}{}{}
+\providecommand{\omicron}{o}
+
% put break before dash to avoid confusion with a hyphen
\newcommand{\dhyphen}{%
\texorpdfstring
@@ -343,6 +345,8 @@
\newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}}
+\newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}}
+
\newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}%
{%
\let\csfmt\code
@@ -605,21 +609,23 @@
}
\newlength\imagewidth
+\newcount\tmpctr
+
\newcommand*{\pdftwocol}[3][1]{%
\renewcommand{\tabcolsep}{2pt}%
\setlength{\imagewidth}{\dimexpr.5\linewidth-2\tabcolsep}%
\def\tabcontents{\begin{tabular}{@{}cc@{}}}%
- \count0=\numexpr#1-1\relax
+ \tmpctr\numexpr#1-1\relax
\loop
- \advance\count0 by 1\relax
+ \advance\tmpctr by 1\relax
\eappto\tabcontents{\noexpand\frame{%
- \noexpand\includegraphics[page=\the\count0,width=\noexpand\imagewidth]{#2}}}%
- \ifodd\count0
+ \noexpand\includegraphics[page=\the\tmpctr,width=\noexpand\imagewidth]{#2}}}%
+ \ifodd\tmpctr
\appto\tabcontents{&}%
\else
\appto\tabcontents{\\}%
\fi
- \ifnum\count0<#3
+ \ifnum\tmpctr<#3
\repeat
\appto\tabcontents{\end{tabular}}%
\tabcontents
@@ -1030,6 +1036,8 @@ the corresponding set of \ext{bib} files:
(if not already done in any of the previous steps);
\item any fields that have been identified by
\csopt{bibtex-contributor-fields} are converted;
+ \item any fields that must be converted into a label form
+ (\csopt{labelify} or \csopt{labelify-list}) are processed;
\item any fields whose value must be a label are interpreted
if \csopt{interpret-label-fields} is set;
\item the \field{parent} field is adjusted according to the label prefix
@@ -1093,13 +1101,17 @@ of dependencies are instances of commands such as \cs{gls} being
found (for example, in the \field{description} field), or the
cross-reference fields (\field{see}, \field{seealso} or
\field{alias}) in recorded entries that reference unrecorded
-entries. The \qt{cross-referenced by} dependencies enabled with
+entries.
+
+The \qt{cross-referenced by} dependencies enabled with
\csopt[recorded and deps and see]{selection} (where an unrecorded
entry references a recorded entry through the cross-reference
-fields) aren't supported across \idxpl{resourceset}.
+fields) \emph{aren't supported} across \idxpl{resourceset} (even with
+\longarg{force-cross-resource-refs}).
-A \idx{crossresourceref} is a reference from an entry provided in one
-\idx{resourceset} to an entry in another \idx{resourceset}. Since
+A \idx{crossresourceref} is a reference from a recorded entry provided in one
+\idx{resourceset} to an unrecorded entry in another \idx{resourceset}.
+Since
the contents of each \idx{resourceset}['s] preamble must be
processed before fields can be interpreted and one
\idx{resourceset}['s] preamble may contain definitions that override
@@ -1119,11 +1131,13 @@ The mode can only be enabled if the following condition is satisfied:
\begin{itemize}
\item the interpreter is off (\longarg{no-interpret}), or
\item every \idx{resourceset} either doesn't have a preamble
-(provided by \atentry{preamble} in the associated \ext{bib} files) or has
-\csopt[false]{interpret-preamble} or
-\csopt[false]{interpret-label-fields} set.
+(\atentry{preamble}) or has \csopt[false]{interpret-preamble} set.
\end{itemize}
-Note that if you don't use either \csopt[recorded and
+If you know the preamble contents won't cause a problem, you
+can force the \idxpl{crossresourceref} mode on with
+\longarg{force-cross-resource-refs}.
+
+If you don't use either \csopt[recorded and
deps]{selection} or \csopt[recorded and deps and see]{selection}
then the dependencies aren't picked up for that \idx{resourceset}
(and so can't be cross-referenced from another \idx{resourceset}).
@@ -1293,7 +1307,11 @@ The other cases that the interpreter is used for are:
\begin{itemize}
\item when \csopt{set-widest} is used to determine the width of
the \field{name} field;
-\item if \csopt[true]{interpret-label-fields} and the
+\item if \csopt{labelify} or \csopt{labelify-list} are set the
+identified field values are first interpreted (if they contain
+\idx{escchar} \idx{bgroupchar} \idx{egroupchar}
+\idx{nbspchar} or \idx{mshiftchar}) before being converted to labels;
+\item if \csopt[true]{interpret-label-fields} is set and the
\field{parent}, \field{category}, \field{type}, \field{group},
\field{seealso} or \field{alias} fields contain \idx{escchar}
or \idx{bgroupchar} or \idx{egroupchar} the interpreter is used
@@ -1304,26 +1322,41 @@ characters allowed in a label).
The \longarg{no-interpret} switch will turn off the interpreter, but
the library will still be used to parse the \ext{aux} and \ext{bib}
-files. Note that the \field{see} field doesn't use the interpreter as
+files. Note that the \field{see} field doesn't use the interpreter
+with \csopt[true]{interpret-label-fields} as
it may legitimately contain \LaTeX\ code in the optional tag part
(such as \cs{seealsoname}).
-The parser has a different concept of expansion to \LaTeX\
+The parser has a different concept of expansion to \TeX\
and will expand some things that aren't expanded by \LaTeX\
(such as \ics{MakeUppercase} and \ics{char}) and won't expand other commands
that would be expanded by \LaTeX\ (such as commands defined
in terms of complicated internals).
-The \file{texparserlib.jar} library is not a
-\TeX\ engine and there are plenty of situations where it doesn't
-work. In particular, in this case it's being used in a fragmented
-context without knowing most of the packages used by the
-document\footnote{\bibgls\ can detect from the log file a small
-number of packages that the parser can support, such as
-\isty{pifonts}, \isty{upgreek}, \isty{wasysym}, \isty{amssymb},
-\isty{stix}, \isty{mhchem} and \isty{bpchem}. There's also partial
-support for \isty{siunitx}'s \ics{si} command.}\ or any custom
-commands or environments provided within the document.
+The \file{texparserlib.jar} library is not a \TeX\ engine and there
+are plenty of situations where it doesn't work. In particular, in
+this case it's being used in a fragmented context without knowing
+most of the packages used by the document or any custom commands or
+environments provided within the document.
+
+\bibgls\ can detect from the log file a small
+number of packages that the parser recognises. Note that in
+some cases there's only very limited support. For example,
+\isty{siunitx}'s \ics{si} command is recognised but other
+commands aren't from that package aren't. \bibgls\ checks for the
+following packages:
+\isty{amsmath}, \isty{amssymb}, \isty{pifont}, \isty{textcase},
+\isty{wasysym}, \isty{lipsum}, \isty{natbib}, \isty{mhchem},
+\isty{bpchem}, \isty{stix}, \isty{textcomp}, \isty{MnSymbol},
+\isty{fourier}, \isty{upgreek}, \isty{xspace}, \isty{siunitx},
+\isty{fontenc} and \isty{tipa}. If you're wondering about the
+selection, the \file{texparserlib.jar} library was originally written for
+another application that required support for some of them. There
+are a few other packages that the library supports (see
+\url{https://github.com/nlct/texparser/tree/master/src/java/lib/latex}), but \bibgls\
+doesn't check for them as they're unlikely to be needed within
+field values. (You can explicitly request them with
+\longarg{packages} if required.)
Since the parser doesn't have a full set of commands available
within the \LaTeX\ document, when it encounters \ics{renewcommand} it
@@ -1332,8 +1365,32 @@ defined, it will simply behave like \cs{newcommand}. Whereas
with \ics{providecommand} the parser will only define the command
if it's unrecognised.
+If a command isn't recognised, you can provide it in the
+\atentry{preamble} and use \ics{char} to map a symbol to the most
+appropriate Unicode character. For example, suppose your document
+loads a package that provides symbols for use on maps, such as
+\csfmt{Harbour}, \csfmt{Battlefield} and \csfmt{Stadium}, then you
+can provide versions of these commands just for \bibgls's
+use:\footnote{These commands won't work with PDF\LaTeX, as the
+\cs{char} values are too large, but they're fine for \bibgls.}
+\begin{verbatim}
+@preamble{"\providecommand{\Harbour}{\char"2693}
+\providecommand{\Battlefield}{\char"2694}
+\providecommand{\Stadium}{\char"26BD}"}
+\end{verbatim}
+Since these use \cs{providecommand}, they won't overwrite the
+document's version (provided these commands have been defined before
+\cs{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\
+to not write the \atentry{preamble} contents to the resource file
+using \csopt[false]{write-preamble}. Now you can either sort these
+symbols by
+their Unicode values (\csopt[letter-case]{sort}) or provide a custom
+rule that recognises these Unicode characters (for example,
+\csopt[custom]{sort},
+\csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}).
+
\TeX\ syntax can be quite complicated and, in some cases, far too
-complicated for simple regular expressions. The library performs
+complicated for simple regular expressions. The \TeX\ parser library performs
better than a simple pattern match, and that's the purpose of
\file{texparserlib.jar} and why it's used by \bibgls\ (and by
\idx{convertgls2bib}). When
@@ -1409,7 +1466,7 @@ code. For simplicity, \bibgls\ uses the library's HTML output and
then strips the HTML markup and trims any leading or trailing
spaces. The library method that writes \idx{non-ASCII} characters
using \qtt{\&x\meta{hex};} markup is overridden by \bibgls\ to just
-write the Unicode character, which means that the letter-based
+write the actual Unicode character, which means that the letter-based
sorting options will sort according to the integer value \meta{hex}
rather than the string \qtt{\&x\meta{hex};}.
@@ -1439,7 +1496,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 0x4D (Latin upper case letter \qtt{M}, decimal value 77).
+character \hex{4D} (Latin upper case letter \qtt{M}, decimal value 77).
For the \code{v} entry, the code is:
\begin{verbatim}
@@ -1450,9 +1507,9 @@ The transcript shows:
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 0x76
+which consists of two Unicode characters \hex{76}
(Latin lower case letter \qtt{v}, decimal value 118) and
-0x20D7 (combining right arrow above, decimal value 8407).
+\hex{20D7} (combining right arrow above, decimal value 8407).
For the \code{set} entry, the code is:
\begin{verbatim}
@@ -1464,7 +1521,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 0x53 (Latin upper case letter \qtt{S}, decimal value~83).
+character \hex{53} (Latin upper case letter \qtt{S}, decimal value~83).
For the \code{card} entry, the code is:
\begin{verbatim}
@@ -1478,9 +1535,10 @@ So the \field{sort} value for this entry is set to \qtt{|S|}
(the \textbar\ characters from the definition of \csfmt{card} provided
in \atentry{preamble} have been included, but the
font change has been discarded). In this case the sort value
-consists of three Unicode characters 0x7C (vertical line, decimal
+consists of three Unicode characters \hex{7C} (vertical line, decimal
value 124),
-0x53 (Latin upper case letter \qtt{S}, decimal value 83) and 0x7C again.
+\hex{53} (Latin upper case 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}
as the sort value.
@@ -1591,11 +1649,31 @@ However, if I change the locale to \csopt[sv]{sort}, the
letter group.
If you are using Java~8, you can set the
-\code{java.locale.providers} property to \code{CLDR,JRE} to use
-the Common Locale Data Repository, which has more extensive
-support for locales than the native \idx{JRE}.
+\code{java.locale.providers} property~\cite{javacldr} to use
+the \idx{CLDR} \idx{localeprovider}, which has more extensive
+support for locales than the native \idx{JRE}. For example:
+\begin{verbatim}
+java.locale.providers=CLDR,JRE
+\end{verbatim}
This isn't available for Java~7, and should be enabled by default
-for the proposed Java~9.
+for the proposed Java~9. Alternatively, you can provide your own
+rule using \csopt[custom]{sort} and \csopt{sort-rule}. The property
+can either be set in a script that runs \bibgls, for example,
+\begin{verbatim}
+java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@"
+\end{verbatim}
+(where \verb|$jarpath| is the path to the \file{bib2gls.jar}
+file and \verb|"$@"| is the argument list) or you can set the
+property as the default for all Java applications by adding
+the definition to the \code{\_JAVA\_OPTIONS} environment variable.
+For example, in a bash shell:
+\begin{verbatim}
+export _JAVA_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI'
+\end{verbatim}
+or in Windows:
+\begin{verbatim}
+set _JAVA_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI
+\end{verbatim}
\chapter{Command Line Options}
\label{sec:switches}
@@ -1735,6 +1813,61 @@ space (default).
The interpreter treats a tilde character \idx{nbspchar} as a normal
space.
+\argsection{force-cross-resource-refs}
+
+Force \idx{crossresourceref} mode on (see
+\sectionref{sec:resourcesets}).
+
+\argsection{no-force-cross-resource-refs}
+
+Don't force \idx{crossresourceref} mode on (default).
+The mode will be enabled if applicable (see
+\sectionref{sec:resourcesets}).
+
+\argsection{support-unicode-script}
+
+Text superscript (\cs{textsuperscript}) and subscript
+(\cs{textsubscript}) will use Unicode super/subscript characters
+if available (default). For example,
+\begin{verbatim}
+\textsuperscript{(2)}
+\end{verbatim}
+will be converted to \hex{207D} (superscript left parenthesis)
+\hex{00B2} (superscript two) \hex{207E} (superscript right
+parenthesis). If the entire contents of the argument can't be
+represented by Unicode characters, the interpreter uses \verb|<sup>|
+and \verb|<sub>| markup, which is then stripped by \bibgls. For
+example,
+\begin{verbatim}
+\textsuperscript{(2,3)}
+\end{verbatim}
+will be converted to
+\begin{verbatim}
+<sup>(2,3)</sup>
+\end{verbatim}
+(since there's no superscript comma). The markup is stripped leaving
+just \code{(2,3)}.
+
+Superscripts and subscripts in maths mode always use markup
+regardless of this setting. Some supported packages that use
+\idx{spchar} or \idx{sbchar} as shortcuts within an encapsulating
+command may internally use the same code as \cs{textsuperscript} and
+\cs{textsubscript}, in which case they will be sensitive to this
+setting.
+
+\argsection{no-support-unicode-script}
+
+Text superscript (\cs{textsuperscript}) and subscript
+(\cs{textsubscript}) won't use Unicode super/subscript characters.
+Note that if other commands are provided that expand to Unicode
+superscript or subscript characters, then they won't be affected by
+this setting. For example, if \csfmt{superiortwo} is defined as
+\begin{verbatim}
+\providecommand{\superiortwo}{\char"B2}
+\end{verbatim}
+then it will be interpreted as \hex{00B2} (superscript two) even if
+this setting is on.
+
\argsection{packages}
Instruct the interpreter to pretend the packages listed
@@ -2001,7 +2134,7 @@ option. You will need to use \ics{glsxtrsetgrouptitle} to provide an
associated title if the \meta{label} isn't the same as the title.
Remember that the label can't contain any active characters, so you
can't use non-ASCII characters in \meta{label} with \sty{inputenc}
-(but you can with \sty{fontspec}).
+(but you can use non-ASCII alphanumerics with \sty{fontspec}).
\end{description}
@@ -2339,7 +2472,8 @@ Each entry type may have required fields, optional fields and
ignored fields. These are set using a \keyvallist\ within
\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the
\ext{bib} file. Most keys recognised by
-\gls{newglossaryentry} may be used as a field.
+\gls{newglossaryentry} may be used as a field. In general, you
+shouldn't need to use the \field{sort} field.
Predefined fields for use in \ext{bib} files are listed in
Tables~\ref{tab:fields}, \ref{tab:bib2glsfields},
@@ -2349,23 +2483,21 @@ custom keys in your document using \ics{glsaddkey} or
first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\
recognises them as a field name.
-Fields that may be set by \bibgls\ when it creates the \iext{glstex}
+Internal fields that may be set by \bibgls\ when it creates the \iext{glstex}
files are listed in Table~\ref{tab:internalfields}. These typically
-shouldn't be set in the \ext{bib} file (although you may need
-\field{sort} for cases where \bibgls\ doesn't recognise any of the
-commands in the \field{name} field). Some of these fields can be set
+shouldn't be set in the \ext{bib} file. Some of these fields can be set
for a particular document using a resource option, such as
\csopt{type} or \csopt{category}.
There are also some fields that are set and used by
\styfmt{glossaries} or \styfmt{glossaries-extra} listed in
-Table~\ref{tab:baseinternalfields} that are unrecognised by \bibgls.
+Table~\ref{tab:baseinternalfields} that aren't recognised by \bibgls.
In most cases these fields don't have a designated key and are only
intended for internal use by \bibgls\ or by the \styfmt{glossaries} or
\styfmt{glossaries-extra} package. Note that the value of the \field{sort} field
written to the \ext{bib} file doesn't always exactly match the sort
value used by \bibgls\ (which is stored in \field{bib2gls@sort}).
-Any special characters found in sort value are always substituted
+Any special characters found in the sort value are always substituted
before writing the \ext{bib} file to avoid syntax errors.
Any unrecognised fields will be ignored by \bibgls. This is more
@@ -2511,6 +2643,13 @@ For example:
description={rectangular array of values, denoted $\mtx{M}$}
}
\end{verbatim}
+Alternatively you can use \ics{glsxtrprovidecommand} which behaves
+the same as \ics{providecommand} within the document but behaves
+like \ics{renewcommand} within \bibgls, which allows you to change
+\bibgls's internal definition of a command without affecting the
+definition within the document (if it's already been defined before
+the resource file is input). In general, it's best to just use
+\cs{providecommand}.
The \TeX\ parser library used by \bibgls\ will parse the contents of
\atentry{preamble} before trying to interpret the field value used
@@ -2534,8 +2673,9 @@ For example:
\end{verbatim}
Neither entry has the \field{sort} field, so \bibgls\ has to fall
back on the \field{name} field and, since this contains the special
-characters \idx{escchar} \idx{mshiftchar} \idx{bgroupchar}
-\idx{egroupchar}, the \TeX\ parser library is used to interpret it.
+characters \idx{escchar} (backslash), \idx{mshiftchar} (maths
+shift), \idx{bgroupchar} (begin group) and
+\idx{egroupchar} (end group), the \TeX\ parser library is used to interpret it.
The definitions provided by \atentry{preamble} allow \bibgls\ to
deduce that the \field{sort} value of the \code{S} entry is just
\code{S} and the \field{sort} value of the \code{card} entry is
@@ -2701,7 +2841,7 @@ The \ext{bib} file is now:
}
\end{verbatim}
This has removed the \csfmt{setfmt} command from the definition of
-\csfmt{cardfmt}. Now the definitions in the document:
+\csfmt{cardfmt}. Now the definitions in the document are:
\begin{verbatim}
\newcommand{\gset}[1]{\glsxtrentryfmt{set}{#1}}
\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardinality}{#2}}
@@ -4141,7 +4281,9 @@ way the entries are sorted and on the \csopt{dual-sort} setting.
Make sure that you use \isty{glossaries-extra} with the
\styopt{record} package option. This ensures that \bibgls\ can pick
-up the required information from the \iext{aux} file. It also
+up the required information from the \iext{aux} file, and it also
+loads the supplementary \ics{glossaries-extra-bib2gls} package
+(from version 1.27 onwards). The option also
switches on the \styopt[none]{sort} package option (if you have a new
enough version of the base \isty{glossaries} package), which means
that there's no attempt to assign or process the \field{sort} key if
@@ -4382,9 +4524,13 @@ contents will still be written to the \iext{glstex} file, but any
commands provided in the preamble won't be recognised if the
interpreter is needed to determine an entry's sort value.
-A related option is \csopt{interpret-label-fields} which governs
-whether or not fields that must only contain a label should be
-interpreted.
+Related options are \csopt{set-widest}, which uses the interpreter
+to determine the widest name for the \glostyle{alttree} style,
+\csopt{interpret-label-fields}, which governs whether or not fields
+that must only contain a label should be interpreted,
+\csopt{labelify}, which converts a field into a string suitable for
+use as a label, and \csopt{labelify-list}, which converts a field
+into a string suitable for use as a comma-separated list of labels.
\optsection{write-preamble}
@@ -4449,7 +4595,7 @@ selected. This will then be implemented as follows:
\end{itemize}
\item If the \field{type} is known then:
\begin{itemize}
- \item if the interpret resolves all \field{name} fields for that
+ \item if the interpreter resolves all \field{name} fields for that
type to the empty string (that is the \field{name} fields all consist of
unknown commands) then
\begin{itemize}
@@ -5534,12 +5680,189 @@ supplementary resource files (omitting the primary
This is a boolean option that determines whether or not the fields
that may only contain labels should have their values interpreted
(\field{parent}, \field{category}, \field{type}, \field{group},
-\field{seealso} and \field{alias}).
+\field{seealso} and \field{alias}). Although this option interprets
+commands within those fields, it doesn't strip any characters that
+can't be used within a label.
+
The default setting is \csopt[false]{interpret-label-fields}.
Note that if this setting is on, cross-resource references aren't
permitted. This setting has no effect if the interpreter has been
disabled.
+Related settings are \csopt{labelify} and
+\csopt{labelify-list} which can be used to strip content that
+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}
+
+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
+\csopt{labelify-list}, then \csopt{labelify-list} takes precedence.)
+Note that if this setting is on, cross-resource references aren't
+permitted.
+
+Each listed field will be converted into a string suitable
+for use as a label. (Not necessarily a glossary entry label, but
+any label that may be used in the construction of a control sequence
+name.)
+
+The conversion is performed in the following order:
+\begin{enumerate}
+\item If the interpreter is on and the value contains
+any of the characters \idx{escchar} (backslash), \idx{bgroupchar}
+(begin group), \idx{egroupchar} (end group), \idx{nbspchar}
+(non-breakable space) or \idx{mshiftchar} (maths shift), then the value is
+be interpreted.
+
+\item Any substitutions that have been specified with
+\csopt{labelify-replace} are performed.
+
+\item All characters that aren't alphanumeric or the space character
+ or the punctuation
+characters \code{.} (full stop), \code{-} (hyphen), \code{+} (plus),
+\code{:} (colon), \code{;} (semi-colon), \code{\string|} (pipe),
+\code{/} (forward slash), \code{!} (exclamation mark), \code{?}
+(question mark), \code{*} (asterisk), \code{<} (less than), \code{>}
+(greater than), \code{\textasciigrave} (backtick), \code{'}
+(apostrophe) or \code{@} (at-sign) are stripped. If you want to
+retain commas, use \csopt{labelify-list} instead. If you want to
+strip any of the allowed punctuation, use \csopt{labelify-replace} to
+remove the unwanted characters.
+
+\item If \bibgls\ hasn't detected \sty{fontspec} in the document's
+transcript file, the value is then decomposed and all non-ASCII
+characters are removed.
+\end{enumerate}
+
+For example, suppose the \ext{bib} file contains:
+\begin{verbatim}
+@index{sample,
+ name={\AA ngstr\"om, \O stergaard, d'Arcy, and Fotheringay-Smythe}
+}
+\end{verbatim}
+Then
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=entries,% data in entries.bib
+ labelify={name}
+]
+\end{verbatim}
+will convert the \field{name} field into
+\begin{verbatim}
+Angstrom stergaard d'Arcy and Fotheringay-Smythe
+\end{verbatim}
+if the document hasn't used \sty{fontspec} otherwise it will be
+\begin{verbatim}
+Ångström Østergaard d'Arcy and Fotheringay-Smythe
+\end{verbatim}
+Note that \O\ is considered an unmodified letter and so can't
+be decomposed into a basic Latin letter with a combining diacritic.
+It's therefore removed completely from the non-\sty{fontspec}
+version. Whereas \AA\ can be decomposed into \qt{A} followed by the
+\qt{combining ring above} character and \"o can be decomposed into \qt{o}
+followed by the \qt{combining diaresis} character. You can use
+\csopt{labelify-replace} to replace non-ASCII characters into
+the closest match. Alternatively, switch to using \XeLaTeX\ or
+\LuaLaTeX.
+
+You can use this option with \csopt{replicate-fields} if you need
+to retain the original:
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=entries,% data in entries.bib
+ replicate-fields={name={user1}},
+ labelify={user1}
+]
+\end{verbatim}
+
+\optsection{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
+list of labels. Any empty elements are removed. For example, with
+the \ext{bib} entry from above:
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=entries,% data in entries.bib
+ replicate-fields={name={user1}},
+ labelify-list={user1}
+]
+\end{verbatim}
+will convert the \field{user1} field into
+\begin{verbatim}
+Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe
+\end{verbatim}
+or
+\begin{verbatim}
+Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
+\optsection{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}
+where \margm{regex} is a regular expression (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
+Pattern class}~\cite{pattern}) and \meta{replacement}
+is the replacement text. Remember that the argument of
+\cs{GlsXtrLoadResources} is expanded when written to the \ext{aux}
+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
+perform substitutions. For example, to replace the sub-string \qt{ and }
+(including spaces) with a comma:
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=entries,% data in entries.bib
+ replicate-fields={name={user1}},
+ labelify-replace={{ and }{,}},
+ labelify-list={user1}
+]
+\end{verbatim}
+The earlier example will now end up as
+\begin{verbatim}
+Angstrom, stergaard, d'Arcy,Fotheringay-Smythe
+\end{verbatim}
+or
+\begin{verbatim}
+Ångström, Østergaard, d'Arcy,Fotheringay-Smythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
+Note that this produces the same result regardless of whether or not
+the Oxford comma is present as \verb*|, and | would first be
+converted to \verb|,,| and then the empty element is removed
+resulting in a single comma.
+
+You can have more than one replacement:
+\begin{verbatim}
+\GlsXtrLoadResources[
+ src=entries,% data in entries.bib
+ replicate-fields={name={user1}},
+ labelify-replace={
+ { and }{,},% first substitution
+ {[ '\string\-]}{},% second substitution
+ {\string\u00D8}{O}% third substitution
+ },
+ labelify-list={user1}
+]
+\end{verbatim}
+This additionally removes the space, apostrophe and hyphen
+characters (second substitution) and replaces \qt{\O} (\hex{00D8})
+with \qt{O} (third substitution) so the string now ends up as
+\begin{verbatim}
+Angstrom,Ostergaard,dArcy,FotheringaySmythe
+\end{verbatim}
+or
+\begin{verbatim}
+Ångström,Ostergaard,dArcy,FotheringaySmythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
\optsection{strip-missing-parents}
The \sty{glossaries} package requires that all child entries must be
@@ -6705,8 +7028,8 @@ the field is defined (so \ics{GlsXtrIfFieldUndef} does the
This option may only be used with the \longarg{group} switch.
This will set the \field{group} field to \meta{value} unless
\meta{value} is \optfmt{auto}, in which case the value is
-set automatically during the sorting.
-For example:
+set automatically during the sorting (see also
+\csopt{group-formation}). For example:
\begin{verbatim}
\GlsXtrLoadResources[sort=integer,group={Constants},
src={entries-constants}% data in entries-constants.bib
@@ -8209,8 +8532,8 @@ This only detects base 10 integers (unlike the numeric methods
such as \csopt[hexadecimal]{sort} or \csopt[float]{sort}) but in
addition to recognising all the digits in the Unicode \idx{numberdecimaldigit}
category it also recognises the subscript and
-superscript digits, such as \textsuperscript{1} (0x00B9)
-and \textsuperscript{2} (0x00B2).
+superscript digits, such as \textsuperscript{1} (\hex{00B9})
+and \textsuperscript{2} (\hex{00B2}).
As with the letter sort methods, letters are compared using a
character code comparison not by a locale alphabet. The closest
@@ -8274,8 +8597,8 @@ indicates the hexadecimal character code. The first three characters
from each string are identical (\code{abc}). At this point there's
no difference detected, so the comparator moves on to the next
character, \code{1\hexsb{31}} for the first string and
-\code{6\hexsb{36}} for the second string. Since 0x31 is less than
-0x36, the first string (\code{abc12foo}) is considered less than the second
+\code{6\hexsb{36}} for the second string. Since \hex{31} is less than
+\hex{36}, the first string (\code{abc12foo}) is considered less than the second
(\code{abc6bar}).
With the letter-number comparison using
@@ -8301,8 +8624,9 @@ such as chemical formulae, rather than for words or phrases.)
Signed integers are also recognised, so \code{abc-12foo} is less
than \code{abc+6bar}, which is again different from the result
-obtained with a straight letter comparator where the character~\code{+} (0x2B)
-comes before the character~\code{-} (0x2D). The sign must be followed by at
+obtained with a straight letter comparator where the
+character~\code{+} (\hex{2B})
+comes before the character~\code{-} (\hex{2D}). The sign must be followed by at
least one digit for it to be recognised as a number otherwise it's
treated as a punctuation character.
@@ -8613,6 +8937,9 @@ to be the default for that locale but you can change this with
own custom pattern you must make sure that it matches the selected
\optfmt{sort} option.
+Take care if you switch from using the \idx{JRE} to the \idx{CLDR}
+ \idx{localeprovider} as you may find the default pattern changes.
+
The locale and pattern information is used by \bibgls\ to parse the
field. If the field value can't be parsed then \bibgls\ will issue
a warning and assume the current date (or time).
@@ -8807,16 +9134,20 @@ and \csopt[\meta{boolean}]{secondary-trim-sort}.
\optsection{sort-rule}
If the \csopt[custom]{sort} option is used, the sort rule must be
-provided with \optfmt{sort-rule}. In this case the collation is
-performed using Java's
+provided with \optfmt{sort-rule}. If \csopt{sort} is not set to
+\optfmt{custom}, the \optfmt{sort-rule} setting will be ignored.
+This setting uses Java's
\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator}
-class~\cite{rulebasedcollator}. Remember that the options will be
-expanded as they are written to the \iext{aux} file, so be careful
-of any special characters that occur in the rule. For the special
-characters \idx{param} \idx{commentchar} \idx{sbchar} \idx{colsep}
-\idx{bgroupchar} and \idx{egroupchar} you can use \ics{cs.hash},
-\ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace}
-and \ics{cs.closebrace}. These will be written to the \ext{aux} file
+class~\cite{rulebasedcollator}, and the rule syntax needs to conform
+to that format.
+
+Remember that the options will be expanded as they are written to
+the \iext{aux} file, so be careful of any special characters that
+occur in the rule. For the special characters \idx{param}
+\idx{commentchar} \idx{sbchar} \idx{colsep} \idx{bgroupchar} and
+\idx{egroupchar} you can use \ics{cs.hash}, \ics{cs.percent},
+\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and
+\ics{cs.closebrace}. These will be written to the \ext{aux} file
with the leading backslash, but \bibgls\ will remove it for this
resource option. Remember that the \styfmt{glossaries} package
provides \ics{glsbackslash} and \ics{glstildechar} which can be used
@@ -8840,7 +9171,9 @@ code) to represent a Unicode character. For example:
\end{verbatim}
It's best to use \ics{cs.string} rather than \ics{protect} to avoid
unwanted spaces interfering with \meta{hex}. Note that
-\sty{glossaries-extra} v1.21+ provides \ics{glshex}
+\sty{glossaries-extra} v1.21+ provides\footnote{The command
+definition was moved to \isty{glossaries-extra-bib2gls} from version
+1.27 since it's only needed with \bibgls.}\ \ics{glshex}
which just does \stringu\ so you can do
\verb|\glshex 00E6| instead of \verb|\string\u00E6|.
This is only one character different, but you can redefine
@@ -8851,8 +9184,84 @@ the protected write is performed. For example:
\end{verbatim}
Then you can just do \verb|\u00E6| instead of \verb|\string\u00E6|.
-If \csopt{sort} is not set to \optfmt{custom}, the
-\optfmt{sort-rule} setting will be ignored.
+The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by
+the \styopt{record} option) provides some commands for common rule blocks
+that may be used in the construction of custom rules. For example:
+\begin{verbatim}
+sort-rule={\glsxtrcontrolrules
+ ;\glsxtrspacerules
+ ;\glsxtrnonprintablerules
+ ;\glsxtrcombiningdiacriticrules
+ ,\glsxtrhyphenrules
+ <\glsxtrgeneralpuncrules
+ <\glsxtrdigitrules
+ <\glsxtrfractionrules
+ <\glsxtrMathItalicGreekIrules
+ <\glsxtrGeneralLatinIVrules
+ <\glsxtrLatinAA
+ <\glsxtrLatinOslash
+}
+\end{verbatim}
+This places the Greek maths symbols (such as \ics{alpha}) before the
+Latin block. See the \sty{glossaries-extra} documentation for
+further details of these commands.
+
+You might find it convenient to provide similar commands in a
+package for rules you may often need. For example, suppose I have a
+package called, say, \styfmt{mapsymbols} for providing map symbols:
+\begin{verbatim}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{mapsymbols}
+% some package or font loading stuff here to provide
+% the appropriate symbols
+\newcommand{\Stadium}{...}
+\newcommand{\Battlefield}{...}
+\newcommand{\Harbour}{...}
+% etc
+
+% Provide a rule block:
+\newcommand{\MapSymbolOrder}{%
+ \glshex 2694 % crossed-swords 0x2694
+ < \glshex 2693 % anchor 0x2693
+ < \glshex 26BD % football 0x26BD
+}
+\end{verbatim}
+In addition to \filefmt{mapsymbols.sty}, I also need to create
+\filefmt{mapssymbols.bib} to provide the appropriate definitions for
+\bibgls:
+\begin{verbatim}
+@preamble{"\glsxtrprovidecommand{\Harbour}{\char"2693}
+\glsxtrprovidecommand{\Battlefield}{\char"2694}
+\glsxtrprovidecommand{\Stadium}{\char"26BD}"}
+\end{verbatim}
+The use of \ics{glsxtrprovidecommand} will override any previous
+definitions of these commands in \bibgls's interpreter but will act
+like \ics{providecommand} within the document, and so won't
+interfere with the commands defined in \filefmt{mapsymbols.sty}.
+Now I can just do
+\begin{verbatim}
+\usepackage{mapsymbols}% my custom package
+\usepackage[record]{glossaries-extra}
+
+\GlsXtrLoadResources[
+ src={mapsymbols,% <--- my custom mapsymbols.bib
+ entries% data in entries.bib
+ },
+ sort={custom},
+ sort-rule={\glsxtrcontrolrules % control codes
+ ;\glsxtrspacerules % space characters
+ ;\glsxtrnonprintablerules % non-printable characters
+ ;\glsxtrcombiningdiacriticrules % combining diacritics
+ ,\glsxtrhyphenrules % hyphens
+ <\glsxtrgeneralpuncrules % general punctuation
+ <\glsxtrdigitrules % 0, ..., 9
+ <\glsxtrfractionrules % fraction symbols
+ <\MapSymbolOrder % <--- custom map symbols
+ <\glsxtrMathItalicGreekIrules % math-greek symbols
+ <\glsxtrGeneralLatinIrules % Latin letters
+ }
+]
+\end{verbatim}
\optsection{break-at}
@@ -9468,10 +9877,10 @@ rule) and punctuation comes last;
rule) and white space comes last;
\item\optfmt{punc-first-space-zero}: punctuation comes first
(although numbers may come before)
-and white space is replaced by the digit~\code{0} (0x30);
+and white space is replaced by the digit~\code{0} (\hex{30});
\item\optfmt{punc-last-space-zero}: punctuation comes last
(although numbers may come after)
-and white space is replaced by the digit~\code{0} (0x30).
+and white space is replaced by the digit~\code{0} (\hex{30}).
\item\optfmt{punc-first-space-zero-match-next}: punctuation comes first
(although numbers may come before)
and white space is replaced by zero;
@@ -9483,22 +9892,22 @@ Remember that the reverse sort methods will invert order governed by this settin
For the \optfmt{space-zero-match-next} settings, the sort value will
have all spaces replaced with a digit that represents zero. If the
-space isn't followed by a digit, the basic Latin \code{0} (0x30)
+space isn't followed by a digit, the basic Latin \code{0} (\hex{30})
will be used, otherwise \bibgls\ will try to match the zero with the
following digit group. For example, if the space is followed by
-\textsuperscript{1} (0xB9) the space will be replaced by
-\textsuperscript{0} (0x2070), resulting in the sub-string
-\code{\textsuperscript{01}} (0xB9 0x2070).
+\textsuperscript{1} (\hex{B9}) the space will be replaced by
+\textsuperscript{0} (\hex{2070}), resulting in the sub-string
+\code{\textsuperscript{01}} (\hex{B9} \hex{2070}).
If just the \optfmt{space-zero}
(without the \optfmt{-match-next}) is used then the space will just
be replaced with \code{0} resulting in the sub-string
-\code{0\textsuperscript{1}} (0x30 0x2070). In this case, the
+\code{0\textsuperscript{1}} (\hex{30} \hex{2070}). In this case, the
\code{0} will be distinct from \textsuperscript{1} (rather than
being considered a leading zero). However, for
other numbering systems the \code{0} will be treated as a leading
zero. For example, if the space is followed by the Devanagari digit
-one (0x0967) then the sub-string will be 0x30 0x0967 but here the
+one (\hex{0967}) then the sub-string will be \hex{30} \hex{0967} but here the
mixture is allowed to form a number (with a leading zero) as both
characters belong to the Unicode category \idx{numberdecimaldigit}.
@@ -9690,6 +10099,46 @@ the year and era:
\end{verbatim}
(The use of \csfmt{number} strips the leading zero from the year.)
+\optsection{group-formation}
+
+If the \field{group} field hasn't been set in
+the \ext{bib} file or through options like \csopt{group}, then it is
+assigned according to this option's setting during sorting. Permitted values:
+\begin{itemize}
+\item\optfmt{default}: the group is assigned according to
+the sort method's default group formation. This is the default
+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,
+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.
+
+\item\optfmt{unicode script}: the group is set to
+\icswithargs{bibglsunicodegroup}, where the first argument is the
+label identifying the Unicode script of the first significant
+character of the sort value. For example, the label \code{LATIN}
+indicates Latin, \code{GREEK} indicates Greek and \code{COMMON}
+indicates common characters (such as mathematical Greek characters
+that are often used with non-Greek scripts).
+
+\item\optfmt{unicode category and script}: the group is set to
+\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.
+\end{itemize}
+This option has no effect with \longarg{no-group} or if no sorting
+is applied. Use \csopt{secondary-group-formation} for secondary
+sorting and \csopt{dual-group-formation} for dual entries.
+
\section{Secondary Glossary}
\label{sec:secondaryopts}
@@ -9921,6 +10370,10 @@ As \csopt{date-sort-locale} but for secondary date-time sorting.
As \csopt{date-sort-format} but for secondary date-time sorting.
+\optsection{secondary-group-formation}
+
+As \csopt{group-formation} but for secondary sorting.
+
\section{Dual Entries}
\label{sec:dualopts}
@@ -10342,6 +10795,11 @@ use a date/time sort.
As \csopt{date-sort-format} but for dual entries that
use a date/time sort.
+\optsection[\subsubsection]{dual-group-formation}
+
+As \csopt{group-formation} but for dual sorting.
+
+
\subsection{Dual Mappings}
\label{sec:dualoptsmap}
@@ -11474,6 +11932,13 @@ defines the entries. The actual group heading is inserted by
the entry has a \field{group} field and comparing it to the previous
entry's \field{group} field.
+The default behaviour of the group formation implemented by the sort
+methods may be changed with \csopt{group-formation}. With any
+setting other than \csopt[default]{group-formation}, the group label
+is set to \cs{bibglsunicodegroup} and the title is set to
+\cs{bibglsunicodegrouptitle} (see below) otherwise the label and
+title are determined by the sort method.
+
The collators used by the locale and letter-based rules save the
following information for each entry based on the first significant letter of
the \field{sort} field (if the letter is recognised as alphabetical,
@@ -11802,6 +12267,98 @@ This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sor
This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting
(\tableref{tab:sortoptionsdatetime}).
+\cssection{bibglssetunicodegrouptitle}
+
+\formatdef{bibglssetunicodegrouptitle}
+This command is used to assign the group titles when the group
+formation is set to any value other than the default. For example,
+this command will be used with \csopt[codepoint]{group-formation}.
+The label is obtained from \cs{bibglsunicodegroup} and the title is
+obtained from \cs{bibglsunicodegrouptitle}.
+
+\cssection{bibglsunicodegroup}
+
+\formatdef{bibglsunicodegroup}
+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
+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);
+\item\csopt[unicode script]{group-formation}: the \meta{label} is the
+Unicode script associated with \meta{character} (for example,
+\code{LATIN});
+\item\csopt[unicode category and script]{group-formation}: the \meta{label}
+identifies both the Unicode category and script associated with
+\meta{character} (for example, \code{Lu.LATIN}).
+\end{itemize}
+(Similarly for \csopt{secondary-group-formation} and
+\csopt{dual-group-formation}.) By default this command expands to
+\meta{type}\meta{label}.
+
+The \meta{character} is the first significant character of the sort
+value. The \meta{id} is the hexadecimal code of (possibly decomposed)
+\meta{character}.
+
+For example, with \csopt[codepoint]{group-formation}, an unset
+\field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a
+significant character distinct from \qt{A} then the \field{group}
+field will be assigned using:
+\begin{verbatim}
+group={\bibglsunicodegroup{å}{Å}{C5}{}}
+\end{verbatim}
+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).
+
+If instead \qt{\AA} is considered equivalent to \qt{A} according to the
+collator, then with \csopt[codepoint]{group-formation}, the value will be:
+\begin{verbatim}
+group={\bibglsunicodegroup{a}{Å}{61}{}}
+\end{verbatim}
+Note that the \meta{id} is now \hex{61} (the decomposed \qt{A}) not
+\hex{C5}.
+
+\cssection{bibglsunicodegrouptitle}
+
+\formatdef{bibglsunicodegrouptitle}
+The title for Unicode group formations by default simply expands to
+\code{\cs{unexpanded}\margm{label}} so you will need to change it to
+something more appropriate. For example (before the \idx{resourceset}):
+\begin{verbatim}
+\newcommand{\bibglsunicodegrouptitle}[4]{%
+ \ifnum"#3>64
+ \ifnum"#3 < 91
+ A--Z%
+ \else
+ \ifnum"#3 > 96
+ \ifnum"#3 < 123
+ A--Z%
+ \fi
+ \fi
+ \fi
+ \fi
+}
+\end{verbatim}
+This will make the title \qt{A--Z} if \meta{id} is greater
+than 64 and less than 91 or greater than 96 and less than 123
+(and will be empty otherwise).
+
+Note that this setting can create an odd effect if the sorting
+causes the groups to be split up. For example, if some of the sort values
+start with extended or non-Latin characters this can break up the
+groups. First check how the group labels are assigned using:
+\begin{verbatim}
+\newcommand{\bibglsunicodegrouptitle}{\bibglsunicodegroup}
+\end{verbatim}
+then adjust the definition of \cs{bibglsunicodegroup} until the
+grouping is correct, and then change the definition of
+\cs{bibglsunicodegrouptitle} so that the title is correct.
+
\cssection{bibglshypergroup}
\formatdef{bibglshypergroup}
@@ -12742,14 +13299,18 @@ type. There are some non-standard fields: \fieldfmt{born},
unless keys are provided (using \cs{glsaddkey} or
\cs{glsaddstoragekey}) or the fields are aliased (using
\csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died}
-fields have dates that are \emph{almost} in the default \code{en-GB} locale
-format, but they include a tilde \verb|~| to prevent awkward line
-breaks. By default \bibgls's interpreter converts \verb|~| to the non-breaking
-space character 0xA0 which isn't recognised by the date format.
-This can easily be fixed with the \longarg{break-space} switch which
-will interpret \verb|~| as a normal breakable space (0x20), so
-with that switch \csopt[date]{sort} or \csopt[date-reverse]{sort}
-can be used on either of those fields.
+fields have dates that are \emph{almost} in the default \code{en-GB}
+locale format with the \idx{JRE} \idx{localeprovider}, but they include a
+tilde \verb|~| to prevent awkward line breaks. By default \bibgls's
+interpreter converts \verb|~| to the non-breaking space character
+\hex{A0} which isn't recognised by the date format. This can easily
+be fixed with the \longarg{break-space} switch which will interpret
+\verb|~| as a normal breakable space (\hex{20}), so with that switch
+\csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on
+either of those fields. However, the \idx{CLDR} has a slightly
+different default format than the \idx{JRE} for dates with
+\code{en-GB}, so it's probably simplest to actually specify the
+required format.
An alternative approach would be to provide a command that can be
modified in the document to adjust the date style. For example, the
@@ -12940,7 +13501,9 @@ 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}).
+reproduced with a lower case Latin \qt{o}). Note that
+\isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+)
+provides all the missing Greek letters (such as \cs{omicron}).
The \ext{bib} file could just use \code{o}:
\begin{verbatim}
@@ -12968,7 +13531,9 @@ but \LaTeX\ needs a definition for this, so it's provided in the
\begin{verbatim}
@preamble{"\providecommand{\omicron}{o}"}
\end{verbatim}
-The \TeX\ parser library similarly provides the missing upper case
+(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
Greek letters, and these can be dealt with in the same way.
The contents of \filefmt{mathgreek.bib} are as follows:
@@ -14422,8 +14987,18 @@ option:
\csopt[date:user1:bybirth]{secondary}
\end{codeenv}
This sorts according to the \field{user1} field (which was
-originally the \fieldfmt{birth} field). I've changed the
-date group headings by redefining \gls{bibglsdategroup} and
+originally the \fieldfmt{birth} field).
+Note that different locales have different default date formats.
+There may also be a difference in the default date format depending
+on the Java \idx{localeprovider}. For example, if you switch from
+using the \idx{JRE} to using the \idx{CLDR} you may find a change in
+the default format. In case the format provided in the \ext{bib}
+file isn't recognised, the required format can be set with:
+\begin{codeenv}
+ \csopt[d MMM YYYY G]{secondary-date-sort-format}
+\end{codeenv}
+
+I've changed the date group headings by redefining \gls{bibglsdategroup} and
\gls{bibglsdategrouptitle}, which means that the grouping in the
\code{bybirth} glossary will be in the form \meta{year} \meta{era}:
\begin{verbatim}
diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
index 1734a891ea2..9c0d593a2a1 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
Binary files differ
diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
index 6c29443e9cf..3cbb272504b 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
Binary files differ