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.tex1740
1 files changed, 1126 insertions, 614 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
index a18fcdfcfe..52f02cce2a 100644
--- a/support/bib2gls/src/bib2gls.tex
+++ b/support/bib2gls/src/bib2gls.tex
@@ -42,6 +42,7 @@
\usepackage{tikz}
\usepackage{tcolorbox}
\usepackage{datetime2}
+\usepackage{mfirstuc-english}
\usepackage{listings}
\usepackage{scrhack}
\usepackage[hidelinks]{hyperref}
@@ -1121,7 +1122,7 @@ documents}}
\newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}}
-\newcommand{\argsection}[2][\section]{%
+\newcommand{\argsection}[2][\subsection]{%
\def\switcharg{}%
\def\switchalt{}%
\def\switchaltpdf{}%
@@ -2117,6 +2118,9 @@ the corresponding set of \ext{bib} files:
\item end punctuation is checked according to
\csopt{check-end-punctuation};
+ \item \field{name} adjustment is performed if
+ \csopt{compound-adjust-name} is set (and the criteria is met);
+
\item \field{name} case-change is performed if
\csopt{name-case-change} is set;
@@ -2155,8 +2159,12 @@ are converted.
If \csopt[recorded and deps and see]{selection} then any
\glspl{recordedentry} that have been cross-referenced by an
\gls{unrecordedentry}, will register a dependency with the
-\gls{unrecordedentry}. Finally, \glspl{supplementalrecord} are added to
-entries.
+\gls{unrecordedentry}.
+
+The \gls{compoundentry} options \csopt{compound-dependent} and
+\csopt{compound-add-hierarchy} are implemented, if enabled.
+
+Finally, \glspl{supplementalrecord} are added to entries.
\item[Stage 4 (Selection, Sorting, Writing)] Entries are selected
from the list according to the \csopt{selection} setting, sorting is
@@ -2955,7 +2963,7 @@ set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI
\chapter{Command Line Options}
\label{sec:switches}
-\setsecdepth{0}
+\setsecdepth{1}
The syntax of \bibgls\ is:
\begin{alltt}
@@ -2965,6 +2973,8 @@ where \meta{filename} is the name of the \ext{aux} file. (The
extension may be omitted.) Only one \meta{filename} is permitted.
Available options are listed below.
+\section{Common Options}
+
\argsection{help}
Display the help message and quit.
@@ -2997,12 +3007,16 @@ Some messages are written to the terminal. To completely suppress
all messages (except errors), switch on the silent mode.
For additional information messages, switch on the verbose mode.
-\argsection{silent}
+\argsection{quiet}
Suppresses all messages except for errors that would normally be
written to the terminal. Warnings and informational messages are
written to the transcript file, which can be inspected afterwards.
+\argsection{silent}
+
+Synonym of \longarg{quiet}.
+
\argsection{locale}
Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag.
@@ -3017,13 +3031,216 @@ If a document doesn't have any locale support or has support
for more than one language then it's best to explicitly set
the required locale in the appropriate \idx{resourceset}.
-\argsection{log-file}
+\argsection{group}
-Sets the name of the transcript file. By default, the name is the
-same as the \iext{aux} file but with a \iext{glg} extension. Note that
-if you use \bibgls\ in combination with \idx{xindy} or
-\idx{makeindex}, you will need to change the transcript file name to
-prevent conflict.
+The \styfmt{glossaries-extra} \styopt{record} package option
+automatically creates a new internal field called \field{group}. If the
+\longarg{group} switch is used with the default \csopt[auto]{group}
+option then, when sorting, \bibgls\ will try
+to determine the letter group for each entry and assign it to the
+\field{group} field. (Some \csopt{sort} options ignore this
+setting.) This value will be picked up by \ics{printunsrtglossary}
+if group headings are required (for example with the
+\glostyle{indexgroup} style) or if group separators are required
+(for example, the \glostyle{index} style with the default
+\styopt[false]{nogroupskip}). If you don't require grouping within
+the glossary, there's no need to use this switch. Note that this
+switch doesn't automatically select an appropriate glossary style.
+
+\begin{important}
+The \field{group} field should typically not be set in the \ext{bib}
+file and will trigger a warning if found. The explicit use of the
+\field{group} key will override \bibgls's normal group formation
+behaviour, which can cause unexpected results. The custom use of the
+\field{group} field requires some care. As a general rule, if you
+find yourself wanting to use the \field{group} field in the
+\ext{bib} file, then the chances are that what you actually have is
+a \gls{hierarchicalglossary} (list of topics) and what you really
+need is the \field{parent} field. Compare the example files
+\exfile{sample-textsymbols.tex} and
+\exfile{sample-textsymbols2.tex}. See also
+\sectionref{sec:logicaldivisions}.
+\end{important}
+There are eight types of groups:
+\begin{description}
+\item[\idx{lettergroup}] The first non-ignored character of the
+sort value is alphabetic. This type of group occurs when using the
+alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
+with the letter sort methods listed in
+\tableref{tab:sortoptionsletter} or with the letter-number sort
+methods listed in \tableref{tab:sortoptionsletternumber}. The group
+label is obtained from \gls!{bibglslettergroup}.
+
+\item[\idx{nonlettergroup} (or \idx{symbolgroup})]
+The first non-ignored character of all the sort values within this group
+are non-alphabetical. This type of group occurs when using the
+alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
+with the letter sort methods listed in
+\tableref{tab:sortoptionsletter} or with the letter-number sort
+methods listed in \tableref{tab:sortoptionsletternumber}.
+The alphabetic sort methods ignore many punctuation
+characters, so an entry that has a non-alphabetic initial
+character in the sort value may actually be placed in a
+\idx{lettergroup}.
+The group label is obtained from \gls!{bibglsothergroup}.
+
+\item[\idx{emptygroup}] The sort value is empty when sorting with an
+alphabetical, letter or letter-number method, typically a
+result of the original value consisting solely of commands that \bibgls\
+can't interpret. The group label is obtained from \gls!{bibglsemptygroup}.
+
+\item[\idx{numbergroup}] The entries were sorted by one of the
+numeric comparisons listed in \tableref{tab:sortoptionsnumerical}.
+The group label is obtained from \gls!{bibglsnumbergroup}.
+
+\item[\idx{datetimegroup}] The entries were sorted by one of the date-time
+comparisons listed in \tableref{tab:sortoptionsdatetime} (where both
+date and time are present).
+The group label is obtained from \gls!{bibglsdatetimegroup}.
+
+\item[\idx{dategroup}] The entries were sorted by one of the date
+comparisons (where the time is omitted).
+The group label is obtained from \gls!{bibglsdategroup}.
+
+\item[\idx{timegroup}] The entries were sorted by one of the time
+comparisons (where the date is omitted).
+The group label is obtained from \gls!{bibglstimegroup}.
+
+\item[\idx{customgroup}] The group label is explicitly set either by
+aliasing a field (with \csopt{field-aliases}) or by using the
+\csopt[\meta{label}]{group} resource option. You will need to use
+\gls{glsxtrsetgrouptitle} in the document 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 use
+non-ASCII alphanumerics with \sty{fontspec}).
+
+\end{description}
+
+The \idx{lettergroup} titles will typically have the first character
+converted to \idx{uppercase} for the alphabet sort methods
+(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily
+be a single character (depending on the sort rule), but may be
+composed of multiple characters, such as a \idx{digraph} (two
+characters) or \idx{trigraph} (three characters).
+
+For example, if the sort rule recognises the digraph \qt{dz} as a
+letter, then it will be converted to \qt{Dz} for the group title.
+There are some exceptions to this. For example, the Dutch digraph
+\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated
+by the following line in the \langxml:
+\begin{verbatim}
+<entry key="grouptitle.case.ij">IJ</entry>
+\end{verbatim}
+If there isn't a \idx{grouptitle.case.lc} key (where
+\meta{lc} is the \idx!{lowercase} version), then only the first character
+will be converted to \idx{uppercase} otherwise the value supplied by the
+resource file is used. This resource key is only checked for
+the alphabetical comparisons listed in
+\tableref{tab:sortoptionsrule}. If the initial part of the sort
+value isn't recognised as a letter according to the sort rule, then
+the entry will be in a \idx{nonlettergroup} (even if the character is
+alphabetical).
+
+The letter (\tableref{tab:sortoptionsletter}) and letter-number
+(\tableref{tab:sortoptionsletternumber}) methods only select the
+first character of the sort value for the group. If the character is
+alphabetical\footnote{according to Java's
+\code{Character.isAlphabetic(int)} method} then it will be a
+\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive
+ordering (such as \csopt[letter-nocase]{sort}) will convert the
+letter group character to \idx{uppercase}. The case-sensitive ordering
+(such as \csopt[letter-case]{sort}) won't change the case.
+
+Glossary styles with navigational links to groups (such as
+\glostyle{indexhypergroup}) require an extra run for the ordinary
+\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For
+example, for the document \filefmt{myDoc.tex}:
+\begin{verbatim}
+pdflatex myDoc
+makeglossaries myDoc
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+On the first \appfmt{pdflatex} call, there's no glossary. On the second
+\appfmt{pdflatex}, there's a glossary but the glossary must be
+processed to find the group information, which is written to the
+\iext{aux} file as
+\nosecdef{@gls@hypergroup}
+The third \appfmt{pdflatex} reads this information and is then able
+to create the navigation links.
+
+With \bibgls, if the \optfmt{type} is provided (through the
+\field{type} field or via options such as \csopt{type} and
+\csopt{dual-type}) then this information can be determined when
+\bibgls\ is ready to write the \iext{glstex} file, which means that
+the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know
+the glossary type then it will fallback on the original method
+which requires an extra \LaTeX\ run.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[main]{type}\comment{put these entries in the 'main' glossary}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib}
+ \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary}
+}
+\end{codeenv}
+Here the \csopt{type} is set and \bibgls\ can detect that
+\isty{hyperref} has been loaded, so if the \longargfmt{group} switch
+is used, then the group hyperlinks can be set (using
+\gls!{bibglshypergroup}). This means that the build process is
+just:
+\begin{verbatim}
+pdflatex myDoc
+bibtex --group myDoc
+pdflatex myDoc
+\end{verbatim}
+Note that this requires \isty{glossaries} v4.32+. If your version of
+\sty{glossaries} is too old then \bibgls\ can't override
+the default behaviour of \isty{glossary-hypernav}'s
+\ics{glsnavhypertarget}.
+
+If \isty{hyperref} isn't loaded or the \longargfmt{group} switch
+isn't used or the \field{type} isn't set or your version of
+\sty{glossaries} is too old, then the information can't be saved in
+the \ext{glstex} file.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib}
+\end{codeenv}
+This requires the build process:
+\begin{verbatim}
+pdflatex myDoc
+bibtex --group myDoc
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+because the group hyperlink information can't be determined by
+\bibgls, so it's best to always set the \optfmt{type} if you want
+hyper-group styles, and make sure you have an up-to-date version of
+\styfmt{glossaries} (and \styfmt{glossaries-extra}).
+
+\argsection{no-group}
+
+Don't automatically set the \field{group} field with
+\csopt[auto]{group} (default). The glossary won't have groups even if a
+group style, such as \glostyle{indexgroup}, is used (unless the
+\field{group} field is set to a custom value).
+
+\section{File Options}
\argsection{dir}
@@ -3078,223 +3295,95 @@ the other files. In this case you need to invoke \bibgls\ with the
bib2gls -d tmp mydoc
\end{verbatim}
-\argsection{interpret}
+\argsection{log-file}
-Switch on the interpreter mode (default). See \sectionref{sec:texparserlib}
-for more details.
+Sets the name of the transcript file. By default, the name is the
+same as the \iext{aux} file but with a \iext{glg} extension. Note that
+if you use \bibgls\ in combination with \idx{xindy} or
+\idx{makeindex}, you will need to change the transcript file name to
+prevent conflict.
-\argsection{no-interpret}
+\argsection{tex-encoding}
-Switch off the interpreter mode. See \sectionref{sec:texparserlib}
-for more details about the interpreter.
+\bibgls\ tries to determine the character \igls{encoding} to use for the
+output files. If the document has loaded the \isty{inputenc} package then
+\bibgls\ can obtain the value of the \gls{encoding} from the
+\iext{aux} file. This is then converted to a name
+recognised by Java. For example, \code{utf8} will be mapped to
+\code{UTF-8}. If the \isty{fontspec} package has been loaded,
+\styfmt{glossaries-extra} will assume the \gls{encoding} is \code{utf8} and
+write that value to the \ext{aux} file.
-\argsection{no-break-space}
+If neither package has been loaded, \bibgls\ will assume the \idx{JVM}['s]
+default \gls{encoding} (identified by the \code{file.encoding} property). If this is
+incorrect or if \bibgls\ can't work out the appropriate mapping then you can
+specify the correct \gls{encoding} using \longargfmt{tex-encoding} \meta{name} where
+\meta{name} is the \gls{encoding} name (such as \code{UTF-8}).
-The interpreter treats a tilde character \idx{nbspchar} as a non-breakable
-space (default). Similarly \ics{nobreakspace} produces a
-non-breakable space character (\hex{00A0}).
+If you have a problem with non-ASCII characters not displaying
+correctly in your document:
+\begin{itemize}
+\item Check that the file \gls{encoding} of your document \ext{tex} file (or files)
+has been correctly set by your text editor.
+\item Check that your document supports that \gls{encoding} (for example,
+through the \isty{inputenc} package).
+\item Check \bibgls's transcript file (\ext{glg}) for the line that
+starts
+\begin{verbatim}
+TeX character encoding:
+\end{verbatim}
+This should be followed by the \gls{encoding} used by \bibgls\ when
+creating the \ext{glstex} files. If this is incorrect use
+\longargfmt{tex-encoding}.
+\item Check that the \gls{encoding} of the \ext{bib} files (set by your
+text editor or bibliographic management system) matches the \gls{encoding}
+line in the \ext{bib} file or the \csopt{charset} resource option.
+\end{itemize}
+
+\section{Interpreter Options}
\argsection{break-space}
The interpreter treats a tilde character \idx{nbspchar} as a normal
space. Similarly \ics{nobreakspace} just produces a space.
-\argsection{cite-as-record}
-
-Treat instances of \code{\ics{citation}\margm{label}} found in the
-\ext{aux} file as though it was actually an \idx{ignoredrecord}:
-\begin{codeenv}
-\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{}
-\end{codeenv}
-Note that \code{\cs{citation}\marg{*}} will always be skipped. Use
-\csopt[all]{selection} to select all entries.
-This switch is most useful in conjunction with
-\atentrypageref{bibtexentry}.
-
-\argsection{no-cite-as-record}
-
-Don't check for instances of \ics{citation} in the \ext{aux} file
-(default).
-
-\argsection{warn-non-bib-fields}
-
-If any internal fields are found in the \ext{bib} file, this setting
-will issue a warning as their use can cause unexpected results.
-The fields checked for are those listed in Tables~\ref{tab:internalfields}
-and \ref{tab:baseinternalfields} with a few exceptions, notably
-\field{type} and \field{sort}. Ideally you shouldn't need to use
-\field{sort} as there should be an appropriate fallback set up to
-use if \field{sort} isn't set, such as the label for symbols or the
-name for terms or the short form for abbreviations.
-
-This is the default setting and was added as some users were
-confused over which fields could be used in the \ext{bib} file.
-The use of these fields can break \bibgls's normal behaviour and
-cause unexpected results.
-
-The check is performed before field aliasing, so it's possible to
-alias a field to an internal field, such as \field{group}, without
-triggering this warning. If you do this you need to make sure you
-have taken appropriate precautions to avoid unexpected results.
-
-\argsection{no-warn-non-bib-fields}
-
-Switches off the check for non-bib fields. If you use this option
-you need to make sure you have taken appropriate precautions to
-avoid unexpected results.
-
-\argsection{warn-unknown-entry-types}
-
-If any unknown entry types are found in the \ext{bib} file, \bibgls\
-will issue a warning with this option set (default).
-
-\argsection{no-warn-unknown-entry-types}
-
-This option will suppress the warning if an unknown entry types are
-found in the \ext{bib} file.
-
-\argsection{collapse-same-location-range}
-
-Collapse any explicit \gls{location} range into a normal \gls{record} if
-the \glspl{location} are the same (default).
-
-\argsection{no-collapse-same-location-range}
-
-Don't collapse any explicit \gls{location} range into a normal
-\gls{record} if the \glspl{location} are the same.
-
-\argsection{merge-wrglossary-records}
-
-For use with the \styopt{indexcounter} package option
-(\styfmt{glossaries-extra} v1.29+), this switch merges an entry's
-\counter{wrglossary} records for the same page \gls{location}. This is the
-default setting. (See also \csopt{save-index-counter}.)
-
-\argsection{no-merge-wrglossary-records}
-
-Don't merge an entry's \counter{wrglossary} records. This means that you
-may end up with duplicate page numbers in the entry's \gls{locationlist},
-but they will link to different parts of the page.
-
-\argsection{merge-nameref-on}
-
-The \styopt[nameref]{record} package option (introduced to
-\sty{glossaries-extra} version 1.37) provides extra information
-in the record when indexing, obtained from \ics{@currentlabelname},
-\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as:
-\begin{codeenv}
-\format{glsxtr@record}
-\end{codeenv}
-the record is written as:
-\nosecdef{glsxtr@record@nameref}
-If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href}
-will always be empty. The most reliable target is given by
-\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the
-associated counter name and \meta{hcounter} is
-obtained from \cs{theHentrycounter}, which is set to the hyper
-target command \csfmt{theH}\meta{counter} during indexing. Since
-this information can't be included in the \gls{location} when indexing
-with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries}
-package tries to obtain a prefix from which the target name can be
-formed. This doesn't work if \csfmt{theH}\meta{counter} can't be
-formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in
-broken links. Since \bibgls\ doesn't have the same restrictions, the
-actual target can be included in the record. You can then customize
-the document to choose whether to use \meta{href} (to link to the
-nearest anchor) or \meta{hcounter} to link to the place where the
-indexing counter was incremented.
-
-The \code{nameref} record will be written to the \igls{locationlist} using:
-\nosecdef{glsxtrdisplaylocnameref}
-The \meta{file} part will be empty for normal internal \glspl{location},
-and will be set to the corresponding file name for
-\glsdisp{supplementalrecord}{supplemental locations}.
-
-With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be
-\code{Doc-Start} at the start of the document and is updated
-globally on every instance of \ics{refstepcounter}. The
-\meta{title} is updated locally by certain commands, such as
-\ics{section} or \ics{caption}. This means that the \meta{href}
-may not always correspond to the \meta{title}, so using
-the \styopt[nameref]{record} package option can have unpredictable
-results if the \meta{title} is used as link text with \meta{href} as
-the target.
-
-For compactness, \bibgls\ tries to merge duplicate or near
-duplicate records. There are four possible rules that it will
-use for \code{nameref} records, identified by \meta{rule} in the
-\longarg{merge-nameref-on} switch:
-\begin{itemize}
-\item \optfmt{location}: merge records that match on the
-\meta{prefix}, \meta{counter} and \meta{location} parts (as regular
-records);
-\item \optfmt{title}: merge records that match on the \meta{counter}
-and \meta{title} parts;
-\item \optfmt{href}: merge records that match on the \meta{counter}
-and \meta{href} parts;
-\item \optfmt{hcounter}: merge records that match on the \meta{counter}
-and \meta{hcounter} parts.
-\end{itemize}
-The default \meta{rule} is \optfmt{hcounter}. Note that for all
-rules the \meta{counter} must match. See the \qt{Nameref Record}
-section of the \sty{glossaries-extra} user manual for further
-details.
+\argsection{no-break-space}
-\argsection{force-cross-resource-refs}
+The interpreter treats a tilde character \idx{nbspchar} as a non-breakable
+space (default). Similarly \ics{nobreakspace} produces a
+non-breakable space character (\hex{00A0}).
-Force \igls{crossresourceref} mode on (see
-\sectionref{sec:resourcesets}).
+\argsection{custom-packages}
-\argsection{no-force-cross-resource-refs}
+Instruct the interpreter to parse the package files identified in
+\meta{list}. The package files need to be quite simple. When this
+switch is used, the interpreter can recognise \ics{ProvidesPackage},
+\ics{DeclareOption} (and \ics{DeclareOption*}),
+\ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage},
+but it can't deal with complicated code. In the case of
+\ics{RequirePackage}, support will also be governed by
+\longargfmt{custom-packages}. This option has a cumulative action.
-Don't force \igls{crossresourceref} mode on (default).
-The mode will be enabled if applicable (see
-\sectionref{sec:resourcesets}).
+\argsection{ignore-packages}
-\argsection{support-unicode-script}
+This option is cumulative. When the document \iext{log} file is
+parsed for known packages, \bibgls\ will skip the check for any
+listed in \meta{list}. Note that this option simply instructs
+\bibgls\ to ignore the package information in the log file. Any packages
+that are identified with \longarg{packages} will be passed to the
+interpreter if support is available, even if the package is also
+listed in \longargfmt{ignore-packages}. Note that
+unknown packages can't be included in the ignored \meta{list}.
-Text superscript (\ics{textsuperscript}) and subscript
-(\ics{textsubscript}) will use Unicode super/subscript characters
-if available (default). For example,
-\begin{codeenv}
-\cs{textsuperscript}\marg{(2)}
-\end{codeenv}
-will be converted to \code{\textsuperscript{(2)}}, which consists
-of: \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{codeenv}
-\cs{textsuperscript}\marg{(2,3)}
-\end{codeenv}
-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)}.
+\argsection{interpret}
-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.
+Switch on the interpreter mode (default). See \sectionref{sec:texparserlib}
+for more details.
-\argsection{no-support-unicode-script}
+\argsection{no-interpret}
-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{codeenv}
-\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}}
-\end{codeenv}
-then it will be interpreted as \hex{00B2} (superscript two) even if
-this setting is on.
+Switch off the interpreter mode. See \sectionref{sec:texparserlib}
+for more details about the interpreter.
\argsection{list-known-packages}
@@ -3354,125 +3443,79 @@ provide support for known packages that aren't checked for when the
\ext{log} file is parsed. If you want \bibgls\ to parse an
unsupported package use \longarg{custom-packages}.
-\argsection{custom-packages}
-
-Instruct the interpreter to parse the package files identified in
-\meta{list}. The package files need to be quite simple. When this
-switch is used, the interpreter can recognise \ics{ProvidesPackage},
-\ics{DeclareOption} (and \ics{DeclareOption*}),
-\ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage},
-but it can't deal with complicated code. In the case of
-\ics{RequirePackage}, support will also be governed by
-\longargfmt{custom-packages}. This option has a cumulative action.
-
-\argsection{ignore-packages}
-
-This option is cumulative. When the document \iext{log} file is
-parsed for known packages, \bibgls\ will skip the check for any
-listed in \meta{list}. Note that this option simply instructs
-\bibgls\ to ignore the package information in the log file. Any packages
-that are identified with \longarg{packages} will be passed to the
-interpreter if support is available, even if the package is also
-listed in \longargfmt{ignore-packages}. Note that
-unknown packages can't be included in the ignored \meta{list}.
-
-\argsection{mfirstuc-protection}
-
-Commands like \ics{Gls} use \ics{makefirstuc} provided by the
-\isty{mfirstuc} package. This command has limitations and one of the
-things that can break it is the use of a referencing command
-at the start of its argument. The \sty{glossaries-extra} package has
-more detail about the problem in the \qt{Nested Links} section of
-the user manual~\cite{glossaries-extra}. If a glossary field starts
-with one of these problematic commands, the recommended method (if
-the command can't be replaced) is to insert an empty group in front
-of it.
+\argsection{support-unicode-script}
-For example, the following definition
+Text superscript (\ics{textsuperscript}) and subscript
+(\ics{textsubscript}) will use Unicode super/subscript characters
+if available (default). For example,
\begin{codeenv}
-\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}}
+\cs{textsuperscript}\marg{(2)}
\end{codeenv}
-will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use.
-The above example would be written in a \ext{bib} file as:
+will be converted to \code{\textsuperscript{(2)}}, which consists
+of: \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{codeenv}
-\atentry{abbreviation}\marg{shtml,
- \field{short}=\marg{shtml},
- \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}}
-}
+\cs{textsuperscript}\marg{(2,3)}
\end{codeenv}
-The default \sty{mfirstuc} protection will automatically insert an empty
-group before \code{\cs{glsps}\marg{ssi}} when writing the definition
-in the \ext{glstex} file.
-
-The argument for this switch should either be a comma-separated list
-of fields or the keyword \code{all} (which indicates all fields).
-\bibgls\ will automatically insert an empty group at the start of
-the listed fields that start with a problematic command, and a
-warning will be written to the transcript. Unknown fields are
-skipped even if they're included in the list. An empty argument is
-equivalent to \longarg{no-mfirstuc-protection}. The default value is
-\code{all}.
-
-\argsection{no-mfirstuc-protection}
-
-Switches off the \isty{mfirstuc} protection mechanism described
-above.
-
-\argsection{mfirstuc-math-protection}
-
-This works in the same way as \longarg{mfirstuc-protection} but
-guards against fields starting with inline maths
-(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the
-\field{name} field starts with
-\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style
-automatically tries to convert the first letter of the name to
-\idx{uppercase}, then this will cause a problem.
+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)}.
-With \longarg{mfirstuc-math-protection} set, \bibgls\ will
-automatically insert an empty group at the start of the field and
-write a warning in the transcript. This setting is on by default.
+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-mfirstuc-math-protection}
+\argsection{no-support-unicode-script}
-Switches off the above.
+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{codeenv}
+\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}}
+\end{codeenv}
+then it will be interpreted as \hex{00B2} (superscript two) even if
+this setting is on.
-\argsection{nested-link-check}
+\section{Record Options}
-By default, \bibgls\ will parse certain fields for potential nested links.
-(See the section \qt{Nested Links} in the \sty{glossaries-extra}
-user manual~\cite{glossaries-extra}.)
+\argsection{cite-as-record}
-The default set of fields to check are: \field{name}, \field{text},
-\field{plural}, \field{first}, \field{firstplural}, \field{long},
-\field{longplural}, \field{short}, \field{shortplural} and
-\field{symbol}.
+Treat instances of \code{\ics{citation}\margm{label}} found in the
+\ext{aux} file as though it was actually an \idx{ignoredrecord}:
+\begin{codeenv}
+\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{}
+\end{codeenv}
+Note that \code{\cs{citation}\marg{*}} will always be skipped. Use
+\csopt[all]{selection} to select all entries.
+This switch is most useful in conjunction with
+\atentrypageref{bibtexentry}.
-You can change this set of fields using
-\longarg{nested-link-check} \meta{value} where \meta{value} may be
-\optfmt{none} (don't parse any of the fields) or a comma-separated
-list of fields to be checked.
+\argsection{no-cite-as-record}
-\argsection{no-nested-link-check}
+Don't check for instances of \ics{citation} in the \ext{aux} file
+(default).
-Equivalent to \longarg{nested-link-check} \optfmt{none}.
+\argsection{collapse-same-location-range}
-\argsection{shortcuts}
+Collapse any explicit \gls{location} range into a normal \gls{record} if
+the \glspl{location} are the same (default).
-Some entries may reference another entry within a field, using
-commands like \ics{gls}, so \bibgls\ parses the fields for these
-commands to determine dependent entries to allow them to be selected
-even if they haven't been used within the document.
-The \styopt{shortcuts} package option provided by
-\styfmt{glossaries-extra} defines various synonyms, such as \ics{ac}
-which is equivalent to \ics{gls}. By default the value of the
-\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the
-\iext{aux} file. This then allows \bibgls\ to additionally search for
-those shortcut commands while parsing the fields.
+\argsection{no-collapse-same-location-range}
-You can override the \styopt{shortcuts} setting using
-\longarg{shortcuts} \meta{value} (where \meta{value} may take
-any of the allowed values for the \styopt{shortcuts} package option),
-but in general there is little need to use this switch.
+Don't collapse any explicit \gls{location} range into a normal
+\gls{record} if the \glspl{location} are the same.
\argsection{map-format}
@@ -3566,6 +3609,153 @@ the same list. (For example, \encap{glsnumberformat} as the default
and \encap{hyperbf} or \encap{hyperit} for a
\gls{principallocation}.)
+\argsection{merge-nameref-on}
+
+The \styopt[nameref]{record} package option (introduced to
+\sty{glossaries-extra} version 1.37) provides extra information
+in the record when indexing, obtained from \ics{@currentlabelname},
+\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as:
+\begin{codeenv}
+\format{glsxtr@record}
+\end{codeenv}
+the record is written as:
+\nosecdef{glsxtr@record@nameref}
+If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href}
+will always be empty. The most reliable target is given by
+\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the
+associated counter name and \meta{hcounter} is
+obtained from \cs{theHentrycounter}, which is set to the hyper
+target command \csfmt{theH}\meta{counter} during indexing. Since
+this information can't be included in the \gls{location} when indexing
+with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries}
+package tries to obtain a prefix from which the target name can be
+formed. This doesn't work if \csfmt{theH}\meta{counter} can't be
+formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in
+broken links. Since \bibgls\ doesn't have the same restrictions, the
+actual target can be included in the record. You can then customize
+the document to choose whether to use \meta{href} (to link to the
+nearest anchor) or \meta{hcounter} to link to the place where the
+indexing counter was incremented.
+
+The \code{nameref} record will be written to the \igls{locationlist} using:
+\nosecdef{glsxtrdisplaylocnameref}
+The \meta{file} part will be empty for normal internal \glspl{location},
+and will be set to the corresponding file name for
+\glsdisp{supplementalrecord}{supplemental locations}.
+
+With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be
+\code{Doc-Start} at the start of the document and is updated
+globally on every instance of \ics{refstepcounter}. The
+\meta{title} is updated locally by certain commands, such as
+\ics{section} or \ics{caption}. This means that the \meta{href}
+may not always correspond to the \meta{title}, so using
+the \styopt[nameref]{record} package option can have unpredictable
+results if the \meta{title} is used as link text with \meta{href} as
+the target.
+
+For compactness, \bibgls\ tries to merge duplicate or near
+duplicate records. There are four possible rules that it will
+use for \code{nameref} records, identified by \meta{rule} in the
+\longarg{merge-nameref-on} switch:
+\begin{itemize}
+\item \optfmt{location}: merge records that match on the
+\meta{prefix}, \meta{counter} and \meta{location} parts (as regular
+records);
+\item \optfmt{title}: merge records that match on the \meta{counter}
+and \meta{title} parts;
+\item \optfmt{href}: merge records that match on the \meta{counter}
+and \meta{href} parts;
+\item \optfmt{hcounter}: merge records that match on the \meta{counter}
+and \meta{hcounter} parts.
+\end{itemize}
+The default \meta{rule} is \optfmt{hcounter}. Note that for all
+rules the \meta{counter} must match. See the \qt{Nameref Record}
+section of the \sty{glossaries-extra} user manual for further
+details.
+
+\argsection{merge-wrglossary-records}
+
+For use with the \styopt{indexcounter} package option
+(\styfmt{glossaries-extra} v1.29+), this switch merges an entry's
+\counter{wrglossary} records for the same page \gls{location}. This is the
+default setting. (See also \csopt{save-index-counter}.)
+
+\argsection{no-merge-wrglossary-records}
+
+Don't merge an entry's \counter{wrglossary} records. This means that you
+may end up with duplicate page numbers in the entry's \gls{locationlist},
+but they will link to different parts of the page.
+
+\argsection{record-count}
+
+Switch on record counting. This will ensure that when each entry
+is written to the \iext{glstex} file, \bibgls\ will additionally
+set the following fields
+\begin{itemize}
+\item \field{recordcount}: set to the total
+number of records found for the entry;
+\item \field{recordcount.counter}: set to the total
+number of records found for the entry for the given counter.
+\end{itemize}
+These fields can then be used with the \gls{rgls}-like commands.
+The default behaviour of
+\nosecdef{rgls}
+is to check the \field{recordcount} field against the \catattr{recordcount}
+attribute value. This attribute can be set with
+\nosecdef{GlsXtrSetRecordCountAttribute}
+where \meta{category list} is a comma-separated list
+of category labels and \meta{value} is a positive integer.
+If the value of the \field{recordcount} field is greater than
+\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise
+it does
+\nosecdef{rglsformat}
+instead.
+If the use of \gls{rglsformat} is triggered in this way,
+then \gls{rgls} writes a \gls{record} to the \iext{aux} file
+with the \glsopt{format} set to \encap{glstriggerrecordformat}.
+This ensures that the \gls{recordcount} is correct on the next run,
+but the \gls{record} isn't added to the \gls{locationlist} as
+\bibgls\ recognises it as a special \igls{ignoredrecord}.
+Note that the entry will still appear in the usual glossary unless
+you assign it to a different one with \csopt{trigger-type}.
+
+If the \catattr{recordcount} attribute hasn't been set
+\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls}
+uses the same internal command used by \ics{gls}.) You can use
+\ics{glsxtrenablerecordcount} to redefine \ics{gls}
+to \gls{rgls}, so that you can continue to use \ics{gls}
+without having to switch command name.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib}
+ \csopt[ignored]{trigger-type},
+ \csopt[abbreviation]{category}
+}
+\cs{glsxtrenablerecordcount}
+\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1}
+\end{codeenv}
+See the \sty{glossaries-extra} user manual~\cite{glossaries-extra}
+for further details.
+
+\argsection{no-record-count}
+
+Switch off record counting. (Default.)
+
+\argsection{record-count-unit}
+
+Automatically implements \longarg{record-count} and additionally
+sets the \field{recordcount.counter.location} fields.
+These fields can then be used with the \gls{rgls}-like
+commands.
+
+\argsection{no-record-count-unit}
+
+Switches off unit record counting. (Default.)
+Note that you need \longarg{no-record-count} to completely
+switch off record counting.
+
\argsection{retain-formats}
It's possible that you may not want to lose certain \gls{location}
@@ -3586,251 +3776,46 @@ to an ordinary \gls{record}.
Normal \gls{location} merging rules apply (default).
-\argsection{group}
-
-The \styfmt{glossaries-extra} \styopt{record} package option
-automatically creates a new internal field called \field{group}. If the
-\longarg{group} switch is used with the default \csopt[auto]{group}
-option then, when sorting, \bibgls\ will try
-to determine the letter group for each entry and assign it to the
-\field{group} field. (Some \csopt{sort} options ignore this
-setting.) This value will be picked up by \ics{printunsrtglossary}
-if group headings are required (for example with the
-\glostyle{indexgroup} style) or if group separators are required
-(for example, the \glostyle{index} style with the default
-\styopt[false]{nogroupskip}). If you don't require grouping within
-the glossary, there's no need to use this switch. Note that this
-switch doesn't automatically select an appropriate glossary style.
-
-\begin{important}
-The \field{group} field should typically not be set in the \ext{bib}
-file and will trigger a warning if found. The explicit use of the
-\field{group} key will override \bibgls's normal group formation
-behaviour, which can cause unexpected results. The custom use of the
-\field{group} field requires some care. As a general rule, if you
-find yourself wanting to use the \field{group} field in the
-\ext{bib} file, then the chances are that what you actually have is
-a \gls{hierarchicalglossary} (list of topics) and what you really
-need is the \field{parent} field. Compare the example files
-\exfile{sample-textsymbols.tex} and
-\exfile{sample-textsymbols2.tex}. See also
-\sectionref{sec:logicaldivisions}.
-\end{important}
-There are eight types of groups:
-\begin{description}
-\item[\idx{lettergroup}] The first non-ignored character of the
-sort value is alphabetic. This type of group occurs when using the
-alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
-with the letter sort methods listed in
-\tableref{tab:sortoptionsletter} or with the letter-number sort
-methods listed in \tableref{tab:sortoptionsletternumber}. The group
-label is obtained from \gls!{bibglslettergroup}.
-
-\item[\idx{nonlettergroup} (or \idx{symbolgroup})]
-The first non-ignored character of all the sort values within this group
-are non-alphabetical. This type of group occurs when using the
-alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
-with the letter sort methods listed in
-\tableref{tab:sortoptionsletter} or with the letter-number sort
-methods listed in \tableref{tab:sortoptionsletternumber}.
-The alphabetic sort methods ignore many punctuation
-characters, so an entry that has a non-alphabetic initial
-character in the sort value may actually be placed in a
-\idx{lettergroup}.
-The group label is obtained from \gls!{bibglsothergroup}.
-
-\item[\idx{emptygroup}] The sort value is empty when sorting with an
-alphabetical, letter or letter-number method, typically a
-result of the original value consisting solely of commands that \bibgls\
-can't interpret. The group label is obtained from \gls!{bibglsemptygroup}.
-
-\item[\idx{numbergroup}] The entries were sorted by one of the
-numeric comparisons listed in \tableref{tab:sortoptionsnumerical}.
-The group label is obtained from \gls!{bibglsnumbergroup}.
-
-\item[\idx{datetimegroup}] The entries were sorted by one of the date-time
-comparisons listed in \tableref{tab:sortoptionsdatetime} (where both
-date and time are present).
-The group label is obtained from \gls!{bibglsdatetimegroup}.
-
-\item[\idx{dategroup}] The entries were sorted by one of the date
-comparisons (where the time is omitted).
-The group label is obtained from \gls!{bibglsdategroup}.
-
-\item[\idx{timegroup}] The entries were sorted by one of the time
-comparisons (where the date is omitted).
-The group label is obtained from \gls!{bibglstimegroup}.
-
-\item[\idx{customgroup}] The group label is explicitly set either by
-aliasing a field (with \csopt{field-aliases}) or by using the
-\csopt[\meta{label}]{group} resource option. You will need to use
-\gls{glsxtrsetgrouptitle} in the document 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 use
-non-ASCII alphanumerics with \sty{fontspec}).
-
-\end{description}
-
-The \idx{lettergroup} titles will typically have the first character
-converted to \idx{uppercase} for the alphabet sort methods
-(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily
-be a single character (depending on the sort rule), but may be
-composed of multiple characters, such as a \idx{digraph} (two
-characters) or \idx{trigraph} (three characters).
-
-For example, if the sort rule recognises the digraph \qt{dz} as a
-letter, then it will be converted to \qt{Dz} for the group title.
-There are some exceptions to this. For example, the Dutch digraph
-\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated
-by the following line in the \langxml:
-\begin{verbatim}
-<entry key="grouptitle.case.ij">IJ</entry>
-\end{verbatim}
-If there isn't a \idx{grouptitle.case.lc} key (where
-\meta{lc} is the \idx!{lowercase} version), then only the first character
-will be converted to \idx{uppercase} otherwise the value supplied by the
-resource file is used. This resource key is only checked for
-the alphabetical comparisons listed in
-\tableref{tab:sortoptionsrule}. If the initial part of the sort
-value isn't recognised as a letter according to the sort rule, then
-the entry will be in a \idx{nonlettergroup} (even if the character is
-alphabetical).
+\section{Bib File Options}
-The letter (\tableref{tab:sortoptionsletter}) and letter-number
-(\tableref{tab:sortoptionsletternumber}) methods only select the
-first character of the sort value for the group. If the character is
-alphabetical\footnote{according to Java's
-\code{Character.isAlphabetic(int)} method} then it will be a
-\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive
-ordering (such as \csopt[letter-nocase]{sort}) will convert the
-letter group character to \idx{uppercase}. The case-sensitive ordering
-(such as \csopt[letter-case]{sort}) won't change the case.
+\argsection{warn-non-bib-fields}
-Glossary styles with navigational links to groups (such as
-\glostyle{indexhypergroup}) require an extra run for the ordinary
-\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For
-example, for the document \filefmt{myDoc.tex}:
-\begin{verbatim}
-pdflatex myDoc
-makeglossaries myDoc
-pdflatex myDoc
-pdflatex myDoc
-\end{verbatim}
-On the first \appfmt{pdflatex} call, there's no glossary. On the second
-\appfmt{pdflatex}, there's a glossary but the glossary must be
-processed to find the group information, which is written to the
-\iext{aux} file as
-\nosecdef{@gls@hypergroup}
-The third \appfmt{pdflatex} reads this information and is then able
-to create the navigation links.
+If any internal fields are found in the \ext{bib} file, this setting
+will issue a warning as their use can cause unexpected results.
+The fields checked for are those listed in Tables~\ref{tab:internalfields}
+and \ref{tab:baseinternalfields} with a few exceptions, notably
+\field{type} and \field{sort}. Ideally you shouldn't need to use
+\field{sort} as there should be an appropriate fallback set up to
+use if \field{sort} isn't set, such as the label for symbols or the
+name for terms or the short form for abbreviations.
-With \bibgls, if the \optfmt{type} is provided (through the
-\field{type} field or via options such as \csopt{type} and
-\csopt{dual-type}) then this information can be determined when
-\bibgls\ is ready to write the \iext{glstex} file, which means that
-the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know
-the glossary type then it will fallback on the original method
-which requires an extra \LaTeX\ run.
+This is the default setting and was added as some users were
+confused over which fields could be used in the \ext{bib} file.
+The use of these fields can break \bibgls's normal behaviour and
+cause unexpected results.
-For example:
-\begin{codeenv}
-\cmd{documentclass}\marg{article}
-\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
-\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
-\strut
-\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib}
- \csopt[main]{type}\comment{put these entries in the 'main' glossary}
-}
-\strut
-\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib}
- \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary}
-}
-\end{codeenv}
-Here the \csopt{type} is set and \bibgls\ can detect that
-\isty{hyperref} has been loaded, so if the \longargfmt{group} switch
-is used, then the group hyperlinks can be set (using
-\gls!{bibglshypergroup}). This means that the build process is
-just:
-\begin{verbatim}
-pdflatex myDoc
-bibtex --group myDoc
-pdflatex myDoc
-\end{verbatim}
-Note that this requires \isty{glossaries} v4.32+. If your version of
-\sty{glossaries} is too old then \bibgls\ can't override
-the default behaviour of \isty{glossary-hypernav}'s
-\ics{glsnavhypertarget}.
+The check is performed before field aliasing, so it's possible to
+alias a field to an internal field, such as \field{group}, without
+triggering this warning. If you do this you need to make sure you
+have taken appropriate precautions to avoid unexpected results.
-If \isty{hyperref} isn't loaded or the \longargfmt{group} switch
-isn't used or the \field{type} isn't set or your version of
-\sty{glossaries} is too old, then the information can't be saved in
-the \ext{glstex} file.
+\argsection{no-warn-non-bib-fields}
-For example:
-\begin{codeenv}
-\cmd{documentclass}\marg{article}
-\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
-\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
-\strut
-\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib}
-\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib}
-\end{codeenv}
-This requires the build process:
-\begin{verbatim}
-pdflatex myDoc
-bibtex --group myDoc
-pdflatex myDoc
-pdflatex myDoc
-\end{verbatim}
-because the group hyperlink information can't be determined by
-\bibgls, so it's best to always set the \optfmt{type} if you want
-hyper-group styles, and make sure you have an up-to-date version of
-\styfmt{glossaries} (and \styfmt{glossaries-extra}).
+Switches off the check for non-bib fields. If you use this option
+you need to make sure you have taken appropriate precautions to
+avoid unexpected results.
-\argsection{no-group}
+\argsection{warn-unknown-entry-types}
-Don't automatically set the \field{group} field with
-\csopt[auto]{group} (default). The glossary won't have groups even if a
-group style, such as \glostyle{indexgroup}, is used (unless the
-\field{group} field is set to a custom value).
+If any unknown entry types are found in the \ext{bib} file, \bibgls\
+will issue a warning with this option set (default).
-\argsection{tex-encoding}
+\argsection{no-warn-unknown-entry-types}
-\bibgls\ tries to determine the character \igls{encoding} to use for the
-output files. If the document has loaded the \isty{inputenc} package then
-\bibgls\ can obtain the value of the \gls{encoding} from the
-\iext{aux} file. This is then converted to a name
-recognised by Java. For example, \code{utf8} will be mapped to
-\code{UTF-8}. If the \isty{fontspec} package has been loaded,
-\styfmt{glossaries-extra} will assume the \gls{encoding} is \code{utf8} and
-write that value to the \ext{aux} file.
+This option will suppress the warning if an unknown entry types are
+found in the \ext{bib} file.
-If neither package has been loaded, \bibgls\ will assume the \idx{JVM}['s]
-default \gls{encoding} (identified by the \code{file.encoding} property). If this is
-incorrect or if \bibgls\ can't work out the appropriate mapping then you can
-specify the correct \gls{encoding} using \longargfmt{tex-encoding} \meta{name} where
-\meta{name} is the \gls{encoding} name (such as \code{UTF-8}).
-
-If you have a problem with non-ASCII characters not displaying
-correctly in your document:
-\begin{itemize}
-\item Check that the file \gls{encoding} of your document \ext{tex} file (or files)
-has been correctly set by your text editor.
-\item Check that your document supports that \gls{encoding} (for example,
-through the \isty{inputenc} package).
-\item Check \bibgls's transcript file (\ext{glg}) for the line that
-starts
-\begin{verbatim}
-TeX character encoding:
-\end{verbatim}
-This should be followed by the \gls{encoding} used by \bibgls\ when
-creating the \ext{glstex} files. If this is incorrect use
-\longargfmt{tex-encoding}.
-\item Check that the \gls{encoding} of the \ext{bib} files (set by your
-text editor or bibliographic management system) matches the \gls{encoding}
-line in the \ext{bib} file or the \csopt{charset} resource option.
-\end{itemize}
+\section{Field Options}
\argsection{no-expand-fields}
@@ -3858,6 +3843,104 @@ expansion switched on with \gls{glssetexpandfield}
before the entries are defined (that is, before using
\gls!{GlsXtrLoadResources}).
+\argsection{mfirstuc-protection}
+
+Commands like \ics{Gls} use \ics{makefirstuc} provided by the
+\isty{mfirstuc} package. This command has limitations and one of the
+things that can break it is the use of a referencing command
+at the start of its argument. The \sty{glossaries-extra} package has
+more detail about the problem in the \qt{Nested Links} section of
+the user manual~\cite{glossaries-extra}. If a glossary field starts
+with one of these problematic commands, the recommended method (if
+the command can't be replaced) is to insert an empty group in front
+of it.
+
+For example, the following definition
+\begin{codeenv}
+\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}}
+\end{codeenv}
+will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use.
+The above example would be written in a \ext{bib} file as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{shtml,
+ \field{short}=\marg{shtml},
+ \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}}
+}
+\end{codeenv}
+The default \sty{mfirstuc} protection will automatically insert an empty
+group before \code{\cs{glsps}\marg{ssi}} when writing the definition
+in the \ext{glstex} file.
+
+The argument for this switch should either be a comma-separated list
+of fields or the keyword \code{all} (which indicates all fields).
+\bibgls\ will automatically insert an empty group at the start of
+the listed fields that start with a problematic command, and a
+warning will be written to the transcript. Unknown fields are
+skipped even if they're included in the list. An empty argument is
+equivalent to \longarg{no-mfirstuc-protection}. The default value is
+\code{all}.
+
+\argsection{no-mfirstuc-protection}
+
+Switches off the \isty{mfirstuc} protection mechanism described
+above.
+
+\argsection{mfirstuc-math-protection}
+
+This works in the same way as \longarg{mfirstuc-protection} but
+guards against fields starting with inline maths
+(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the
+\field{name} field starts with
+\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style
+automatically tries to convert the first letter of the name to
+\idx{uppercase}, then this will cause a problem.
+
+With \longarg{mfirstuc-math-protection} set, \bibgls\ will
+automatically insert an empty group at the start of the field and
+write a warning in the transcript. This setting is on by default.
+
+\argsection{no-mfirstuc-math-protection}
+
+Switches off the above.
+
+\argsection{nested-link-check}
+
+By default, \bibgls\ will parse certain fields for potential nested links.
+(See the section \qt{Nested Links} in the \sty{glossaries-extra}
+user manual~\cite{glossaries-extra}.)
+
+The default set of fields to check are: \field{name}, \field{text},
+\field{plural}, \field{first}, \field{firstplural}, \field{long},
+\field{longplural}, \field{short}, \field{shortplural} and
+\field{symbol}.
+
+You can change this set of fields using
+\longarg{nested-link-check} \meta{value} where \meta{value} may be
+\optfmt{none} (don't parse any of the fields) or a comma-separated
+list of fields to be checked.
+
+\argsection{no-nested-link-check}
+
+Equivalent to \longarg{nested-link-check} \optfmt{none}.
+
+\argsection{shortcuts}
+
+Some entries may reference another entry within a field, using
+commands like \ics{gls}, so \bibgls\ parses the fields for these
+commands to determine dependent entries to allow them to be selected
+even if they haven't been used within the document.
+The \styopt{shortcuts} package option provided by
+\styfmt{glossaries-extra} defines various synonyms, such as \ics{ac}
+which is equivalent to \ics{gls}. By default the value of the
+\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the
+\iext{aux} file. This then allows \bibgls\ to additionally search for
+those shortcut commands while parsing the fields.
+
+You can override the \styopt{shortcuts} setting using
+\longarg{shortcuts} \meta{value} (where \meta{value} may take
+any of the allowed values for the \styopt{shortcuts} package option),
+but in general there is little need to use this switch.
+
\argsection{trim-fields}
Trim leading and trailing spaces from all field values. For example,
@@ -3922,6 +4005,19 @@ bib2gls --trim-except-fields short --trim-except-fields long myDoc
Don't trim any leading or trailing spaces from field values (but see
the above note about \sty{xkeyval}). This is the default setting.
+\section{Other Options}
+
+\argsection{force-cross-resource-refs}
+
+Force \igls{crossresourceref} mode on (see
+\sectionref{sec:resourcesets}).
+
+\argsection{no-force-cross-resource-refs}
+
+Don't force \igls{crossresourceref} mode on (default).
+The mode will be enabled if applicable (see
+\sectionref{sec:resourcesets}).
+
\argsection{provide-glossaries}
This setting will make \bibgls\ add the line
@@ -3946,76 +4042,6 @@ default since it's a useful way of detecting misspelt glossary
labels. It's harder to detect the problem if a misspelt label has
caused an entry to be added to a hidden glossary.
-\argsection{record-count}
-
-Switch on record counting. This will ensure that when each entry
-is written to the \iext{glstex} file, \bibgls\ will additionally
-set the following fields
-\begin{itemize}
-\item \field{recordcount}: set to the total
-number of records found for the entry;
-\item \field{recordcount.counter}: set to the total
-number of records found for the entry for the given counter.
-\end{itemize}
-These fields can then be used with the \gls{rgls}-like commands.
-The default behaviour of
-\nosecdef{rgls}
-is to check the \field{recordcount} field against the \catattr{recordcount}
-attribute value. This attribute can be set with
-\nosecdef{GlsXtrSetRecordCountAttribute}
-where \meta{category list} is a comma-separated list
-of category labels and \meta{value} is a positive integer.
-If the value of the \field{recordcount} field is greater than
-\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise
-it does
-\nosecdef{rglsformat}
-instead.
-If the use of \gls{rglsformat} is triggered in this way,
-then \gls{rgls} writes a \gls{record} to the \iext{aux} file
-with the \glsopt{format} set to \encap{glstriggerrecordformat}.
-This ensures that the \gls{recordcount} is correct on the next run,
-but the \gls{record} isn't added to the \gls{locationlist} as
-\bibgls\ recognises it as a special \igls{ignoredrecord}.
-Note that the entry will still appear in the usual glossary unless
-you assign it to a different one with \csopt{trigger-type}.
-
-If the \catattr{recordcount} attribute hasn't been set
-\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls}
-uses the same internal command used by \ics{gls}.) You can use
-\ics{glsxtrenablerecordcount} to redefine \ics{gls}
-to \gls{rgls}, so that you can continue to use \ics{gls}
-without having to switch command name.
-
-For example:
-\begin{codeenv}
-\gls{GlsXtrLoadResources}\oarg{
- \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib}
- \csopt[ignored]{trigger-type},
- \csopt[abbreviation]{category}
-}
-\cs{glsxtrenablerecordcount}
-\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1}
-\end{codeenv}
-See the \sty{glossaries-extra} user manual~\cite{glossaries-extra}
-for further details.
-
-\argsection{no-record-count}
-
-Switch off record counting. (Default.)
-
-\argsection{record-count-unit}
-
-Automatically implements \longarg{record-count} and additionally
-sets the \field{recordcount.counter.location} fields.
-These fields can then be used with the \gls{rgls}-like
-commands.
-
-\argsection{no-record-count-unit}
-
-Switches off unit record counting. (Default.)
-Note that you need \longarg{no-record-count} to completely
-switch off record counting.
-
\chapter{\iext{bib} Format}
\label{sec:bib}
\setsecdepth{1}
@@ -4270,6 +4296,15 @@ but it doesn't add any information to the cross-referencing part of the
or \bibgls}%
{tab:baseinternalfields}
+\printfields
+ [%
+ Only available for \atentry{compoundset}. These correspond to the
+ arguments of \ics{multiglossaryentry}.%
+ ]%
+ {compoundsetfield}%
+ {Compound Set Fields}%
+ {tab:compoundsetfields}
+
\clearpage
\section{Standard Entry Types}
@@ -6713,6 +6748,222 @@ the \ext{glstex} file with \gls{bibglsnewspawndualindexentry} and
\gls{bibglsnewspawndualindexentrysecondary}. The spawned
\gls{progeny} are defined with \gls{bibglsnewspawnedindex}.
+\section{Compound Entry Sets}
+\label{sec:compoundsetentry}
+
+A \gls{compoundentry} isn't an entry in the same sense as the above
+but corresponds to a multi-entry (compound or combined) set provided
+by \sty{glossaries-extra} v1.48+, which is defined by the command
+\ics{multiglossaryentry} (or \ics{providemultiglossaryentry}).
+These are referred to as multi-entries in \sty{glossaries-extra} but
+are referred to as \glspl{compoundentry} here to avoid confusion
+with the \glspl{multientrytype}.
+
+Essentially, a label is defined that refers to a set of labels
+corresponding to entries that \emph{have already been defined}. One
+element in the set is considered the \gls{compmainlabel}. Entry
+labels may appear in multiple sets.
+
+A \gls{compoundentry} provides a convenient way to apply commands
+like \ics{gls} to multiple entries in one command (such as \ics{mgls}).
+\Gls{compoundentry} labels may only be used in the \cs{mgls}-like
+commands or in a \gls{cross-referencefield}.
+
+For example, consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
+\cs{setabbreviationstyle}\marg{long-only-short-only}
+\cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{}
+ \cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
+}
+\cs{newabbreviation}\marg{clostridium}\marg{C.}\marg{Clostridium}
+\gls{newglossaryentry}\marg{botulinum}\marg{name=botulinum,
+ description=\marg{},parent=clostridium}
+\gls{newglossaryentry}\marg{perfringens}\marg{name=perfringens,
+ description=\marg{},parent=clostridium}
+\cmd{begin}\marg{document}
+\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum},
+\cs{gls}\marg{clostridum} \cs{gls}\marg{perfringens},
+\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}.
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{quote}
+Clostridium botulinum,
+C. perfringens,
+C. botulinum.
+\end{quote}
+followed by the glossary. This is very cumbersome. Defining a
+\gls{compoundentry} label simply provides a shortcut:
+\begin{codeenv*}
+\ics{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum}
+\ics{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens}
+\end{codeenv*}
+(This has to be done after the entries have been defined.) Now the
+entries can be more compactly referenced:
+\begin{codeenv*}
+\ics{mgls}\marg{cbot},
+\ics{mgls}\marg{cperf},
+\ics{mgls}\marg{cbot}.
+\end{codeenv*}
+Each \gls{compoundentry} set must contain at least two elements. The
+\gls{compmainlabel} is the label of the element that is considered
+the main entry of the set. If the \gls{compmainlabel} isn't
+identified in \cs{multiglossaryentry} then it's assumed to be the
+last element in the set.
+
+In the above example, \code{botulinum} is the \gls{compmainlabel} of
+the \code{cbot} set, and \code{perfringens} is the
+\gls{compmainlabel} of the \code{cperf} set. In both sets,
+\code{clostridium} is the \qt{\gls{compotherlabel}}. If there are
+more than two elements in the set then \qt{others} refers to all the
+elements except for the \gls{compmainlabel}. An entry can be a
+\gls{compmainlabel} of one set and an \gls{compotherlabel} of
+another set.
+
+The options, which can be applied to all sets with
+\ics{multiglossaryentrysetup} or to a specific set using the
+first optional argument of \ics{multiglossaryentry}, determine
+if each element of the list has a separate hyperlink to their
+own target, or if only the main element should have a hyperlink, or
+if the entire content of \ics{mgls} should be a single hyperlink to
+the main entry's target.
+
+With \bibgls, the entries that form the set should be in \ext{bib} files as usual.
+The \gls{compoundentry} set may either be defined in the document \ext{tex}
+file using \ics{multiglossaryentry} (or \ics{providemultiglossaryentry})
+or they can be defined in the \ext{bib} file using
+\atentry{compoundset}. Remember that the set can only be defined
+after the entries that make up the elements of the set have been
+defined. If any \ext{bib} files in a \gls{resourceset} contain
+\atentry{compoundset}, the definitions will be added at the end of
+the \ext{glstex} file (using \gls{bibglsdefcompoundset}).
+
+If you have multiple \glspl{resourceset} that reuse the same
+\ext{bib} file containing \atentry{compoundset} then either redefine
+\gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry} or
+prevent duplicate definitions with \csopt[false]{compound-write-def}.
+
+The elements of the set will still need to be indexed as usual to
+ensure that they have \glspl{record} to enable selection.
+
+The above example can be converted to \bibgls\ as follows
+(\glspl{compoundentry} defined in the document \ext{tex} file):
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
+\cs{setabbreviationstyle}\marg{long-only-short-only}
+\cs{renewcommand}*\marg{\cs{glsxtronlyname}}\marg{\comment{}
+ \cs{protect}\cs{glslongonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
+}
+\gls{GlsXtrLoadResources}\oarg{\csopt[bacteria]{src}}
+\cs{multiglossaryentry}\marg{cbot}\marg{clostridium,botulinum}
+\cs{multiglossaryentry}\marg{cperf}\marg{clostridium,perfringens}
+\cmd{begin}\marg{document}
+\cs{mgls}\marg{cbot}, \cs{mgls}\marg{cperf}, \cs{mgls}\marg{cbot}.
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+Note that \cs{multiglossaryentry} must come after \gls{GlsXtrLoadResources}.
+
+The \file{bacteria.bib} contains the definitions in the usual way:
+\begin{codeenv}
+\atentry{abbreviation}\marg{clostridium,
+ \field{short}=\marg{C.},
+ \field{long}=\marg{Clostridium}
+}
+\atentry{index}\marg{botulinum,
+ \field{parent}=\marg{clostridium}
+}
+\atentry{index}\marg{perfringens,
+ \field{parent}=\marg{clostridium}
+}
+\end{codeenv}
+
+Alternatively, the \glspl{compoundentry} can be defined in the
+\ext{bib} file instead:
+\begin{codeenv}
+\atentry{compoundset}\marg{cbot,
+ \field{elements}=\marg{clostridium,botulinum}
+}
+\atentry{compoundset}\marg{cperf,
+ \field{elements}=\marg{clostridium,perfringens}
+}
+\end{codeenv}
+The \cs{multiglossaryentry} commands should now be removed from the
+\ext{tex} file.
+
+There's a difference between these two methods on the first \LaTeX\
+build. In the first example, \code{cbot} is known, so
+\code{\cs{mgls}\marg{cbot}} can perform
+\code{\cs{gls}\marg{clostridum} \cs{gls}\marg{botulinum}}. These
+commands aren't yet defined so they are both replaced by \qt{??}
+(resulting in \qt{?? ??}). As usual, the \gls{locationlist} is
+unreliable until entries are defined and the unknown markers \qt{??}
+can be replaced with the correct content. If the document is in a
+file called \filefmt{myDoc.tex} then the document build:
+\begin{codeenv}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{codeenv}
+will have \glspl{location} in the resulting PDF file, but they may
+be incorrect if the associated temporary files were initially
+missing.
+
+In the second example, \code{cbot} is unknown, so
+\code{\cs{mgls}\marg{cbot}} is simply displayed as \qt{??}.
+In this case, the \ext{aux} file contains information that
+\code{cbot} has been referenced, but there are no associated
+\glspl{record}. The entries that belong to the \code{cbot} set will
+be selected as they are considered dependent on the
+\gls{compoundentry}. In this case, if you are starting from scratch
+(no associated temporary files), you will need:
+\begin{codeenv}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{codeenv}
+At this point, the \glspl{locationlist} will appear.
+After that, you can reduce the document build to:
+\begin{codeenv}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{codeenv}
+(Until you later add new entries.)
+
+If you don't want \glspl{location} for the
+\glslink{compotherlabel}{other elements} then set the
+\idx{encap} to \encap{glsignore}:
+\begin{codeenv*}
+\ics{multiglossaryentrysetup}\marg{encapothers=\encap{glsignore}}
+\end{codeenv*}
+
+\entrysection{compoundset}
+The following fields are available:
+\begin{definition}
+\item[\field{elements}] The comma-separated list of element labels.
+This corresponds to the final argument of \cs{multiglossaryentry}.
+(Required.)
+\item[\field{main}] The \gls{compmainlabel}. This field is optional.
+If omitted, the main label is assumed to be the last element.
+\item[\field{options}] A comma-separated list of options. This
+corresponds to the first optional argument of
+\cs{multiglossaryentry}. This field may be omitted.
+\end{definition}
+These fields can only be used in this entry type.
+
+Most resource options don't apply to this entry type. Options
+specific to \glspl{compoundentry} are listed in
+\sectionref{sec:compoundentries}.
+
\chapter{Resource File Options}
\label{sec:resourceopts}
@@ -16410,6 +16661,10 @@ the entry's \parent\ (new to v1.9). If the entry doesn't have a
\parent\ or if the \parent\ doesn't have the \field{type} field set,
then no change is made.
+\item \optfmt{same as category} set the \field{type} field
+to the same value as the \field{category} field
+(\field{type} unchanged if \field{category} not set);
+
\item \meta{label}: sets the \field{type} field to \meta{label}.
\end{itemize}
@@ -17025,6 +17280,254 @@ empty the \field{category} is left unchanged. Unlike
the \csopt{category} and \csopt{dual-category} options, there are no
recognised keywords.
+\section{Compound (Combined or Multi) Entries}
+\label{sec:compoundentries}
+
+These options refer to \glspl{compoundentry} which are either
+defined in a \ext{bib} file with \atentry{compoundset} or are
+defined in the document using \cs{multiglossaryentry} (or
+\cs{provideglossaryentry}). See \sectionref{sec:compoundsetentry}
+for further details.
+
+\optsection{compound-options-global}
+
+This is a boolean option. The default is
+\csopt[true]{compound-options-global}.
+
+If \optfmt{true}, the \gls{compoundentry} options described in this
+section, except for \csopt{compound-write-def}, pick up all
+\glspl{compoundentry} provided in the document (defined either with
+\atentry{compoundset} or in the document with
+\ics{multiglossaryentry}).
+
+If \optfmt{false}, options only apply to \glspl{compoundentry} defined
+with \atentry{compoundset} in the current \gls{resourceset}.
+
+If \igls{crossresourceref} are disabled then any instances of
+\atentry{compoundset} in subsequent \glspl{resourceset} can only be
+picked up from the \ext{aux} file on the next build.
+
+\optsection{compound-dependent}
+
+This is a boolean option. The default is
+\csopt[false]{compound-dependent}.
+
+If you have chosen to switch off indexing for the \glspl{compotherlabel}
+then they may not be selected (unless they have been indexed via
+another method, such as explicitly using \cs{gls}). You can use this
+option to make the \glspl{compotherlabel} dependencies of the
+\gls{compmainlabel} (if the entry given by \gls{compmainlabel} is
+present in the current \gls{resourceset}).
+
+This means that if the \gls{compmainlabel} is selected then the
+\glspl{compotherlabel} should also be selected (if dependencies are
+part of the selection criteria).
+
+\optsection{compound-add-hierarchy}
+
+This is a boolean option. The default is
+\csopt[false]{compound-add-hierarchy}.
+If true, this will set the \field{parent} field for each element
+$e_i$ to the previous element $e_{i-1}$ in the list, provided that:
+\begin{itemize}
+\item the element $e_i$ isn't the first element in the list;
+\item the element $e_i$ and the previous element $e_{i-1}$ are
+present in the current \gls{resourceset};
+\item the element $e_i$ doesn't already have the \field{parent} field set;
+\item the element $e_i$ isn't an \gls{ancestor} of the previous element $e_{i-1}$.
+\item the previous element $e_{i-1}$ isn't an \gls{ancestor} of the
+element $e_i$.
+\end{itemize}
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{abbreviation}\marg{clostridium,
+ \field{short}=\marg{C.},
+ \field{long}=\marg{Clostridium}
+}
+\atentry{index}\marg{botulinum}
+\atentry{compoundset}\marg{cbot,
+ \field{elements}=\marg{clostridium,botulinum}}
+\end{codeenv}
+Then the \code{botulinum} entry will have its \field{parent} field
+set to \code{clostridium}. The \code{clostridium} entry won't be
+adjusted (since it's the first element in the list).
+
+\optsection{compound-has-records}
+
+This option may take one of the following values:
+\begin{description}
+\item[\optfmt{true}]
+Any \gls{compoundentry} referenced with commands like
+\ics{mgls} is considered to have \glspl{record} for each element for
+selection purposes, even if there are no \glspl{record} in the \ext{aux}
+file. (This is useful on the first \LaTeX\ run where the
+\glspl{compoundentry} are defined with \atentry{compoundset}.)
+
+\item[\optfmt{false}]
+The element \glspl{record} are created as they normally are with
+commands like \cs{gls} that are internally used by \cs{mgls}.
+
+\item[\optfmt{default}]
+Behaves like \csopt[true]{compound-has-records} if the current
+\gls{resourceset} has any \ext{bib} files containing one or more
+\atentry{compoundset} entry types. Otherwise behaves like
+\csopt[false]{compound-has-records}.
+\end{description}
+
+The default is \csopt[default]{compound-has-records}.
+If the value is omitted, \optfmt{true} is assumed.
+
+\optsection{compound-adjust-name}
+
+If an entry has been identified as the \gls{compmainlabel} in any
+\glspl{compoundentry} then the \field{name} field can be adjusted
+with this option. Allowed values:
+\begin{itemize}
+\item \optfmt{false} don't adjust the \field{name} field (default);
+\item \optfmt{unique} only adjust the \field{name} field if
+the entry is the \gls{compmainlabel} of exactly one set;
+\item \optfmt{once} adjust the \field{name} field if
+the entry is the \gls{compmainlabel} of any set. Only one adjustment
+is made. If the entry is the \gls{compmainlabel} of multiple
+\glspl{compoundentry} there's no guarantee which set will be chosen
+for the adjustment.
+\end{itemize}
+
+If the value isn't supplied, \optfmt{once} is assumed. As with
+\csopt{name-case-change}, the pre-adjusted \field{name} value will
+be copied to the \field{text} field provided the \field{text} field
+hasn't already been set and provided that the entry isn't an
+abbreviation.
+
+The adjusted value will be in the form:
+\begin{codeenv*}
+\ics{glsxtrmultientryadjustedname}\margm{sublist1}\margm{name}\margm{sublist2}\marg{mlabel}
+\end{codeenv*}
+where \meta{label} is the \gls{compoundentry} label, \meta{name} was
+the value of the \field{name} field before the adjustment,
+\meta{sublist1} is the list of \glspl{compotherlabel} before the
+\gls{compmainlabel} (which will be empty if the \gls{compmainlabel}
+is the first element in the set) and
+\meta{sublist2} is the list of \glspl{compotherlabel} after the
+\gls{compmainlabel} (which will be empty if the \gls{compmainlabel}
+is the last element in the set).
+
+The adjustment is made before \csopt{name-case-change} (if set).
+The control sequence case changes (such as
+\csopt[firstuc-cs]{name-case-change}) will replace \cs{glsxtrmultientryadjustedname}
+with the relevant command (\ics{Glsxtrmultientryadjustedname} for
+\optfmt{firstuc-cs}, \ics{GlsXtrmultientryadjustedname} for
+\optfmt{title-cs} and \cs{GLSxtrmultientryadjustedname} for
+\optfmt{uc-cs}).
+
+\optsection{compound-main-type}
+
+Set the \field{type} field of the \glslink{compmainlabel}{main
+entries}. The \meta{value} is required and should be one of:
+\begin{itemize}
+\item \optfmt{same as entry}: sets the \field{type} to the entry
+type (\idx!{lowercase} and without
+the initial \code{@}). For example, if the entry was defined with
+\atentry{index}, the \field{type} will be set to \optfmt{index}.
+If you've used \csopt{entry-type-aliases}, this refers to the target
+entry type not the original entry type provided in the \ext{bib}
+file.
+
+\item \optfmt{same as original entry}: set the \field{type} field
+to the original entry type (\idx!{lowercase} and without
+the initial \code{@}) before it was aliased (behaves like
+\optfmt{same as entry} if the entry type wasn't aliased).
+
+\item \optfmt{same as base}: sets the \field{type} to the base name
+of the \ext{bib} file (without the extension) that provided the
+entry definition;
+
+\item \optfmt{same as category}: sets the \field{type} to the same
+as the \field{category} field;
+
+\item \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's \parent. If the entry doesn't have a
+\parent\ or if the \parent\ doesn't have the \field{type} field set,
+then no change is made.
+
+\item \meta{label}: sets the \field{type} field to \meta{label}.
+\end{itemize}
+
+This setting is governed by \csopt{compound-type-override}.
+
+\optsection{compound-other-type}
+
+Set the \field{type} field of the \glslink{compotherlabel}{other
+entries}. The \meta{value} is required and should be one of:
+\begin{itemize}
+\item \optfmt{same as main}: sets the \field{type} to the same as
+the \glslink{compmainlabel}{main entry}.
+
+\item \optfmt{same as entry}: sets the \field{type} to the entry
+type (\idx!{lowercase} and without
+the initial \code{@}). For example, if the entry was defined with
+\atentry{index}, the \field{type} will be set to \optfmt{index}.
+If you've used \csopt{entry-type-aliases}, this refers to the target
+entry type not the original entry type provided in the \ext{bib}
+file.
+
+\item \optfmt{same as original entry}: set the \field{type} field
+to the original entry type (\idx!{lowercase} and without
+the initial \code{@}) before it was aliased (behaves like
+\optfmt{same as entry} if the entry type wasn't aliased).
+
+\item \optfmt{same as base}: sets the \field{type} to the base name
+of the \ext{bib} file (without the extension) that provided the
+entry definition;
+
+\item \optfmt{same as category}: sets the \field{type} to the same
+as the \field{category} field;
+
+\item \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's \parent. If the entry doesn't have a
+\parent\ or if the \parent\ doesn't have the \field{type} field set,
+then no change is made.
+
+\item \meta{label}: sets the \field{type} field to \meta{label}.
+\end{itemize}
+
+This setting is governed by \csopt{compound-type-override}.
+
+\optsection{compound-type-override}
+
+This is a boolean option. The default is
+\csopt[false]{compound-type-override}.
+
+If \optfmt{true}, then the options \csopt{compound-main-type}
+and \csopt{compound-other-type} will overwrite the \field{type}
+field otherwise those options will only set the \field{type} field
+if it hasn't already been set.
+
+\optsection{compound-write-def}
+
+If \glspl{compoundentry} are defined in the \ext{bib} files using
+\atentry{compoundset}, this option governs whether or not to write
+their definition to the \ext{glstex} file. The value may be one of:
+\begin{definition}
+\item[\optfmt{none}] Don't write the definitions to the \ext{glstex}
+file. For example, if you are reloading a \ext{bib} file from
+another \gls{resourceset}, you will need this option to prevent
+duplicate definitions. (The alternative is to define
+\gls{bibglsdefcompoundset} to use \ics{providemultiglossaryentry}
+instead of \ics{multiglossaryentry}.)
+
+\item[\optfmt{all}] Write all definitions to the \ext{glstex} file,
+regardless of whether or not they have been referenced using
+commands like \cs{mgls}.
+
+\item[\optfmt{ref}] Only write the definitions for
+\glspl{compoundentry} that have been referenced using commands like
+\cs{mgls}. (Default.)
+\end{definition}
+
+The \glspl{compoundentry} are defined in the \ext{glstex} file with
+\gls{bibglsdefcompoundset}.
+
\chapter{Provided Commands}
\label{sec:bibglscs}
@@ -17707,6 +18210,15 @@ The definition is written to the \ext{glstex} file as:
}
\end{codeenv}
+\section{Compound Entry Sets}
+\label{sec:compounddefs}
+
+\cssection{bibglsdefcompoundset}
+
+\formatdef{bibglsdefcompoundset}
+
+The default definition uses \ics{multiglossaryentry}.
+
\section{Location Lists and Cross-References}
\label{sec:loclistdefs}