summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src/bib2gls.tex')
-rw-r--r--support/bib2gls/src/bib2gls.tex183
1 files changed, 167 insertions, 16 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index aadbf0c5c7..30b252fd4a 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/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}