bib2gls (11jul20)

git-svn-id: svn://tug.org/texlive/trunk@55811 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 216 insertions, 17 deletions

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 925ea7082ca..f76575706f1 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 cd69e4802ce..6f4f6e5c4fe 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
@@ -1483,6 +1483,15 @@ name},
   category={command}
 }
 
+@bibglscommand{bibglshexunicodechar,
+  name={\csfmt{bib\-gls\-hex\-unicode\-char}},
+  user1={\margm{hex}},
+  description={produces the character with the given hexadecimal code},
+  topics={charcommands},
+  note={\bibgls\texparserdefnote},
+  category={command}
+}
+
 @bibglscommand{bibglsprimaryprefixlabel,
   name={\csfmt{bib\-gls\-primary\-prefix\-label}},
   user1={\margm{prefix}},
@@ -2287,6 +2296,13 @@ field\dhyphen locale}},
    parent={resourceoptions}
 }
 
+@resourceoption{opt.save-original-id-action,
+   name={\csoptfmt{save\dhyphen original\dhyphen id\dhyphen action}},
+   user1={\meta{value}},
+   category={resourceoption},
+   parent={resourceoptions}
+}
+
 @resourceoption{opt.short-case-change,
    name={\csoptfmt{short\dhyphen case\dhyphen change}},
    user1={\meta{value}},
@@ -2406,6 +2422,13 @@ field\dhyphen locale}},
    parent={resourceoptions}
 }
 
+@resourceoption{opt.hex-unicode-fields,
+   name={\csoptfmt{hex\dhyphen unicode\dhyphen fields}},
+   user1={\margm{list}},
+   category={resourceoption},
+   parent={resourceoptions}
+}
+
 @resourceoption{opt.post-description-dot,
    name={\csoptfmt{post\dhyphen description\dhyphen dot}},
    user1={\meta{value}},
@@ -2478,7 +2501,14 @@ field\dhyphen locale}},
 
 @resourceoption{opt.save-original-entrytype,
    name={\csoptfmt{save\dhyphen original\dhyphen entrytype}},
-   user1={\meta{boolean}},
+   user1={\meta{value}},
+   category={resourceoption},
+   parent={resourceoptions}
+}
+
+@resourceoption{opt.save-original-entrytype-action,
+   name={\csoptfmt{save\dhyphen original\dhyphen entrytype\dhyphen action}},
+   user1={\meta{value}},
    category={resourceoption},
    parent={resourceoptions}
 }
@@ -8368,6 +8398,14 @@ field.},
   parent={internalfields}
 }
 
+@field{field.originalid,
+  name={\fieldfmt{original\-id}},
+  description={The original label as given in the \ext{bib} file.},
+  note={internal field set by \appfmt{bib2gls}},
+  category={internalfield},
+  parent={internalfields}
+}
+
 @field{field.primarylocations,
   name={\fieldfmt{primarylocations}},
   description={Stores the locations that use one of the designated
@@ -15573,6 +15611,16 @@ number is hexadecimal)},
   category={command}
 }
 
+@command{cs.symbol,
+  name={\csfmt{symbol}},
+  user1={\margm{number}},
+  description={accesses the character identified by \meta{number}
+(use \code{\csfmt{symbol}\marg{\idx{doublequotecharhex}\meta{hex}}} if the
+number is hexadecimal)},
+  note={kernel command\texparserdefnote},
+  category={command}
+}
+
 @command{number,
   name={\csfmt{number}},
   user1={\meta{value}},
diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
index aadbf0c5c73..30b252fd4a1 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
+++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
@@ -43,6 +43,7 @@
 \usepackage{tcolorbox}
 \usepackage{datetime2}
 \usepackage{listings}
+\usepackage{scrhack}
 \usepackage[hidelinks]{hyperref}
 \usepackage{cleveref}
 \usepackage[% v1.21+
@@ -1994,6 +1995,11 @@ the corresponding set of \ext{bib} files:
   \begin{itemize}
   \item field aliases are performed (\csopt{field-aliases}); 
 
+  \item known fields identified with \csopt{save-original-id} and
+  \csopt{save-original-entrytype} are set (internal fields that
+  don't have a corresponding key for use with \gls!{newglossaryentry} aren't 
+  set until the \ext{glstex} file is written);
+
   \item ignored fields (identified by \csopt{ignore-fields}) are
   removed;
 
@@ -2061,6 +2067,9 @@ the corresponding set of \ext{bib} files:
   \csopt{interpret-fields} are replaced with their interpreted
   values;
 
+  \item any fields that have been identified with
+  \csopt{hex-unicode-fields} will have Unicode characters replaced;
+
   \item check for \field{nonumberlist}.
   \end{itemize}
 \item The dual version (if appropriate) is created.
@@ -8841,15 +8850,41 @@ cross-references.
 
 \optsection[\subsubsection]{save-original-id}
 
-The \meta{value} may be either the keyword \code{false} or
-the name of an internal field in which to store the entry's original
+The \meta{value} may be the keywords \code{false} or \code{true} or
+the name of a field in which to store the entry's original
 label (as given in the \ext{bib} file). The default setting is
-\csopt[false]{save-original-id}. If \meta{value} is omitted,
-\csopt[originalid]{save-original-id} is assumed.
-
-If \meta{value} is a known field, it will be set after the field
-aliases, otherwise it will simply be added to the \ext{glstex} file
-using \ics{GlsXtrSetField} after the entry definition. 
+\csopt[false]{save-original-id}. If \meta{value} is omitted or is the
+keyword \code{true}, then \field{originalid} is assumed.
+
+If \meta{value} has an associated key in \gls!{newglossaryentry}
+(for example, one provided with \cs{glsaddstoragekey}) it will be
+set after the field aliases, otherwise (for example,
+\field{originalid}) it will simply be added to the \ext{glstex} file
+using \ics{GlsXtrSetField} after the entry definition (which means
+the field can't be referenced in other resource options). This
+setting is governed by \csopt{save-original-id-action}.
+
+\optsection[\subsubsection]{save-original-id-action}
+
+This option determines whether or not \csopt{save-original-id}
+should save the original entry label. No action is performed when
+\csopt[false]{save-original-id} otherwise the action is determined
+by \meta{value} which may be one of the following keywords:
+\begin{itemize}
+\item \code{always}: always save the original label (default);
+\item \code{no override}: don't override a field that's already been
+set;
+\item \code{changed override} or \code{changed} or \code{diff}:
+only save the original label if it's different from the final label;
+\item \code{changed no override}:
+only save the original label if it's different from the final label
+and the specified field hasn't been set. 
+\end{itemize}
+The \qt{no override} options make no difference if the given field
+has no associated key in \gls!{newglossaryentry} (such as
+\field{originalid}). For known fields, bear in mind that the field
+will be set after field aliasing but before other options, such as
+\csopt{ignore-fields}.
 
 \optsection[\subsubsection]{dependency-fields}
 
@@ -9049,6 +9084,11 @@ entry]{category} refers to the \emph{target} entry type whereas
 \csopt[same as original entry]{category} refers to the
 \emph{original} entry type given in the \ext{bib} file.  In both
 cases, the value is converted to \idx!{lowercase} to ensure consistency.
+An alternative is to use \csopt[category]{save-original-entrytype}.
+When combined with \csopt[changed]{save-original-entrytype-action}
+it's then possible to only set the \field{category} to the original
+entry type for aliased entries and leave it unmodified for unaliased
+entries.
 
 For example, if the \ext{bib} file contains:
 \begin{codeenv}
@@ -9137,8 +9177,17 @@ which may be inappropriate.
 When used with \csopt{entry-type-aliases}, the option \csopt[same as
 entry]{type} refers to the \emph{target} entry type and \csopt[same
 as original entry]{type} refers to the \emph{original} entry type
-given in the \ext{bib} file.  It's not possible to have both
+given in the \ext{bib} file.  
+An alternative is to use \csopt[type]{save-original-entrytype}.
+When combined with \csopt[changed]{save-original-entrytype-action}
+it's then possible to only set the \field{type} to the original
+entry type for aliased entries and leave it unmodified for unaliased
+entries.
+
+\begin{important}
+It's not possible to have both
 \csopt[same as type]{category} and \csopt[same as category]{type}.
+\end{important}
 
 Note that this setting only changes the \field{type} field for
 primary entries. Use \csopt{dual-type} for dual entries.
@@ -9228,6 +9277,15 @@ but can't be the \field{sort} field.
 The \csopt{ignore-fields} key indicates that you want \bibgls\ to
 skip the fields listed in the supplied comma-separated \meta{list} of field
 labels. Remember that unrecognised fields will always be skipped.
+However, an unrecognised field can still be referenced with some
+options (such as \csopt{replicate-fields}) whereas any field
+excluded with \csopt{ignore-fields} will be discarded and can't be
+referenced.
+
+This setting is always implemented after \csopt{field-aliases} (see
+\sectionref{sec:resourcesets}). If a field has been aliased then the
+original field name is no longer present and so ignoring it will
+have no effect.
 
 For example, suppose my \ext{bib} file contains:
 \begin{codeenv}
@@ -9301,13 +9359,18 @@ but may be empty, which indicates that the setting is switched off.
 
 This option copies the contents
 of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\
-(only if the target field isn't already set with
+(but only if the target field isn't already set with
 \csopt[false]{replicate-override}). This action is
 performed after \csopt{ignore-fields} (see
 \sectionref{sec:resourcesets}). If the source field is missing, the
 \csopt{replicate-missing-field-action} setting determines the
 action.
 
+If the target field doesn't have an associated key recognised by
+\gls{newglossaryentry} then the value will be saved using
+\cs{GlsXtrSetField}.  Special internal fields aren't permitted as
+either source or target fields.
+
 For example, suppose \filefmt{people.bib} contains:
 \begin{codeenv}
 \atentry{entry}\marg{alexander,
@@ -9457,11 +9520,45 @@ the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
 
 \optsection[\subsubsection]{save-original-entrytype}
 
-If this is set to \optfmt{true}, the original entry type
-(without the leading \idx{atchar}) is stored in the 
-\field{originalentrytype} field. If no entry aliasing has been
-applied (with \csopt{entry-type-aliases}) the field will be set to
-the actual entry type.
+The \meta{value} may be the keywords \code{false} or \code{true} or
+the name of a field in which to store the original entry type (as
+given in the \ext{bib} file but without the leading \idx{atchar} and
+converted to \idx!{lowercase}). The setting is
+\csopt[false]{save-original-entrytype}. If \meta{value} is omitted or the
+keyword \code{true}, then \csopt[originalentrytype]{save-original-entrytype} 
+If \meta{value} has an associated key in \gls!{newglossaryentry}
+(for example, one provided with \cs{glsaddstoragekey}) it will be
+set after the field aliases, otherwise (for example,
+\field{originalentrytype}) it will simply be added to the \ext{glstex} file
+using \ics{GlsXtrSetField} after the entry definition (which means
+the field can't be referenced in other resource options). This
+setting is governed by \csopt{save-original-entrytype-action}.
+
+\optsection[\subsubsection]{save-original-entrytype-action}
+
+This option determines whether or not \csopt{save-original-entrytype}
+should save the original entry type. No action is performed when
+\csopt[false]{save-original-entrytype} otherwise the action is determined
+by \meta{value} which may be one of the following keywords:
+\begin{itemize}
+\item \code{always}: always save the original entry type (default);
+\item \code{no override}: don't override a field that's already been
+set;
+\item \code{changed override} or \code{changed} or \code{diff}:
+only save the original entry type if it's different from the final
+entry type;
+\item \code{changed no override}:
+only save the original entry type if it's different from the final
+entry type and the specified field hasn't been set. 
+\end{itemize}
+The \qt{no override} options make no difference if the given field
+is unknown (such as \field{originalentrytype}). For known fields, bear in
+mind that the field will be set after field aliasing but before
+other options, such as \csopt{ignore-fields}.
+
+The \qt{changed} options ignore case. For example, if the \ext{bib}
+file defined an entry with \atentryfmt{INDEX} then both the original
+and final entry type will be \code{index}.
 
 \subsection{Field Adjustments}
 \label{sec:fieldmods}
@@ -10200,6 +10297,18 @@ bookmarks by adjusting the definition of the custom command:
   \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}%
 }
 \end{codeenv}
+With \pdfLaTeX\ and \sty{fontenc}, you will need 
+\sty{hyperref}'s \styoptfmt{unicode} option:
+\begin{codeenv}
+\cs{usepackage}\oarg{\styoptfmt{unicode}}\marg{hyperref}
+\end{codeenv}
+If you still encounter problems with the Unicode characters not
+appearing in the PDF bookmarks, then try the
+\csopt{hex-unicode-fields} option. For example:
+\begin{codeenv}
+\csopt[pdfname]{hex-unicode-fields}
+\end{codeenv}
+This still requires \sty{hyperref}'s \styoptfmt{unicode} option.
 
 \optsection[\subsubsection]{interpret-fields-action}
 
@@ -10216,6 +10325,27 @@ If a field value consists solely of commands that are unknown to the
 interpreter, then the resulting value will end up empty. In this
 case, it may be more appropriate to leave the field unchanged.
 
+\optsection[\subsubsection]{hex-unicode-fields}
+
+This option will convert any Unicode characters (outside of the
+Basic Latin set) that are found in the listed fields into
+\code{\gls{bibglshexunicodechar}\margm{hex-code}} where
+\meta{hex-code} is the hexadecimal character code.
+
+The \meta{list} should be a comma-separated list of field names.
+This action is performed after \csopt{interpret-fields}.
+
+If the field contents need to be added to the PDF bookmarks (as in
+the earlier example) then you need to make sure you use
+\sty{hyperref}'s \styoptfmt{unicode} option
+otherwise you'll get the warning:
+\begin{verbatim}
+Token not allowed in a PDF string (PDFDocEncoding):
+removing `\char'
+\end{verbatim}
+and the bookmarks will show \idx{doublequotecharhex}\meta{hex-code}
+instead of the Unicode character.
+
 \optsection[\subsubsection]{date-time-fields}
 
 This option indicates that the listed fields all contain 
@@ -14295,7 +14425,7 @@ field concatenation (such as \csopt{entry-sort-fallback} but not
 \csopt{missing-sort-fallback}). 
 
 Note that due to the way that the \keyvallist\ parser trims leading and
-trailing spaces, you can't simply do \csopt[\space]{field-concat-sep}
+trailing spaces, you can't simply do \csopt[~]{field-concat-sep}
 to indicate a space character as the value will end up as an empty
 string. You can instead do \csopt[\stringu20]{field-concat-sep} but
 since this is the default value there shouldn't be much need for it.
@@ -15378,9 +15508,12 @@ significant character of the sort value. For example, the label
 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.
+
+\begin{important}
 Settings other than the default can cause the groups to become
 fragmented, so care is needed if you use this option.
 See also \sectionref{sec:logicaldivisions}.
+\end{important}
 
 \section{Secondary Glossary}
 \label{sec:secondaryopts}
@@ -17499,6 +17632,24 @@ second argument is ignored.
 \formatdef{bibglshrefunicode}
 Expands to the second argument. The first argument is ignored.
 
+\cssection{bibglshexunicodechar}
+
+\formatdef{bibglshexunicodechar}
+This command is used by the \csopt{hex-unicode-fields} option when
+replacing any Unicode characters. The argument \meta{hex} is the hexadecimal
+character code. Note that the argument isn't preceded by the double-quote
+character~\idx{doublequotecharhex} (which is normally used to
+identify hexadecimal numbers in \LaTeX). Instead, the definition
+needs to insert this character, if appropriate.
+
+If \bibgls\ has detected that the \sty{hyperref} package has been
+loaded, it will provide a definition that may be used in PDF
+bookmarks provided that \sty{hyperref}'s \styoptfmt{unicode} option is
+set. Otherwise the command will simply do
+\code{\ics{cs.symbol}\marg{\idx{doublequotecharhex}\meta{hex}}}
+(which will require an appropriate font in order to render the
+symbol correctly).
+
 \section{Letter Groups}
 \label{sec:lettergroupdefs}
 
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 7e2fa7c8fec..a5cc4072729 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
index 051f47a6833..a09583725cb 100644
--- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
+++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip