diff options
Diffstat (limited to 'Master/texmf-dist/source/support/bib2gls/src')
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib | 8 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip | bin | 132823 -> 138027 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib | 179 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod | 24 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex | 765 | ||||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip | bin | 19544 -> 18730 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip | bin | 610669 -> 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 Binary files differindex 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 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 Binary files differindex 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 diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip Binary files differindex 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 |