diff options
author | Karl Berry <karl@freefriends.org> | 2025-01-30 21:12:44 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2025-01-30 21:12:44 +0000 |
commit | 7b05faae6c34da7ad31197a468627ebd70225fd1 (patch) | |
tree | ff4f277dcf7e95248a86c52edeb15cef63fc39ec /Master/texmf-dist/source | |
parent | 556807178aa72213b6442ce780dd92b0efed2896 (diff) |
bib2gls (30jan25)
git-svn-id: svn://tug.org/texlive/trunk@73652 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/bib2gls-src.zip | bin | 395920 -> 395922 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/bib2gls-terms.bib | 7 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/bib2gls.bib | 104 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/bib2gls.pod | 27 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/bib2gls.tex | 750 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/texparser-src.zip | bin | 1658899 -> 1655686 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/version.tex | 4 |
7 files changed, 541 insertions, 351 deletions
diff --git a/Master/texmf-dist/source/support/bib2gls/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/bib2gls-src.zip Binary files differindex 90912a90aa4..9048c562740 100644 --- a/Master/texmf-dist/source/support/bib2gls/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/bib2gls-terms.bib b/Master/texmf-dist/source/support/bib2gls/bib2gls-terms.bib index 602e07d4d57..f1080202bda 100644 --- a/Master/texmf-dist/source/support/bib2gls/bib2gls-terms.bib +++ b/Master/texmf-dist/source/support/bib2gls/bib2gls-terms.bib @@ -534,3 +534,10 @@ Files, Text Files and File Encodings} for further information about \sectionref{sec:bibstringconcat}) and \idx{concat-plus} for resource option string concatenation (\sectionref{sec:optstringconcat}).} } + +@entry{field-reference, + name={field reference}, + user1={idx.field-reference}, + description={used in complex string concatenations (see +\sectionref{sec:optstringcont}) to reference field values} +} diff --git a/Master/texmf-dist/source/support/bib2gls/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/bib2gls.bib index fc8713663ce..0c6eb6a6e72 100644 --- a/Master/texmf-dist/source/support/bib2gls/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/bib2gls.bib @@ -2226,7 +2226,7 @@ extra code to the end of \meta{description}}, name={\csfmt{glsxtr@resource}}, user1={\margm{options}\margm{filename}}, description={this internal command is written to the \ext{aux} -file by \csref{glsxtrresourcefile} +file by \csref{GlsXtrLoadResources} to provide \bibgls\ with the resource information}, topics={internalcommands,auxcommands}, note={\styfmt{glossaries-extra} v1.08+}, @@ -2332,11 +2332,35 @@ starred version \csref{glsxtrfmt*}}, @mainglscommand{glsxtrresourcefile, name={\csfmt{gls\-xtr\-resource\-file}}, - user1={\oargm{options}\margm{filename}}, + user1={\oargm{options}\margm{basename}}, description={input the \ext{glstex} file created by \bibgls\ and - write resource instructions to the \ext{aux} file}, + write resource instructions to the \ext{aux} file. + This command is deprecated as from \sty{glossaries-extra} v1.55 + (use \gls{glsbibdata} instead)}, topics={indexing}, - note={\styfmt{glossaries-extra} v1.08+}, + note={\styfmt{glossaries-extra} v1.08+ (deprecated)}, + seealso={resourceoptions,GlsXtrLoadResources}, + category={command} +} + +@mainglscommand{GlsXtrLoadResources, + name={\csfmt{Gls\-Xtr\-Load\-Resources}}, + user1={\oargm{options}}, + description={input the \ext{glstex} file created by \bibgls\ and + write resource instructions to the \ext{aux} file}, + topics={indexing,shortcutcommands}, + note={\styfmt{glossaries-extra} v1.11+}, + seealso={resourceoptions,glsbibdata}, + category={command} +} + +@mainglscommand{glsbibdata, + name={\csfmt{gls\-bib\-data}}, + user1={\oargm{options}\margm{bib-list}}, + description={a shortcut command that uses + \csref{GlsXtrLoadResources} with \csopt[\margm{bib-list}]{src}}, + topics={indexing,shortcutcommands}, + note={\styfmt{glossaries-extra} v1.55+}, seealso={resourceoptions,GlsXtrLoadResources}, category={command} } @@ -4323,16 +4347,6 @@ pattern}}, parent={resourceoptions} } -@mainglscommand{GlsXtrLoadResources, - name={\csfmt{Gls\-Xtr\-Load\-Resources}}, - user1={\oargm{options}}, - description={a shortcut command that uses \csref{glsxtrresourcefile}}, - topics={indexing,shortcutcommands}, - note={\styfmt{glossaries-extra} v1.11+}, - seealso={resourceoptions,glsxtrresourcefile}, - category={command} -} - @mainglscommand{glsxtrcopytoglossary, name={\csfmt{gls\-xtr\-copy\-to\-glossary}}, user1={\margm{label}\margm{type}}, @@ -4464,6 +4478,29 @@ cs}\margm{Glspl-like cs}}, category={command} } +@mainglscommand{@bibgls@input, + name={\csfmt{@bibgls@input}}, + user1={\margm{filename}}, + description={this command is written to the \ext{aux} file by the +\styopt{bibglsaux} option (or by \gls{glsxtrsetbibglsaux})}, + topics={internalcommands,auxcommands,indexing}, + seealso={switch.aux-input-action,glsxtrsetbibglsaux,styopt.bibglsaux}, + note={\styfmt{glossaries-extra} v1.49+\texparserdefnote}, + category={command} +} + +@mainglscommand{glsxtrsetbibglsaux, + name={\csfmt{gls\-xtr\-set\-bib\-gls\-aux}}, + user1={\margm{basename}}, + description={an alternative to the \styopt{bibglsaux} option, this creates a separate \ext{aux} file containing all +records, which is input using \cs{@bibgls@input} instead of +\cs{@input}}, + note={\styfmt{glossaries-extra} v1.49+}, + seealso={switch.aux-input-action,styopt.bibglsaux}, + topics={indexing}, + category={command} +} + @mainglscommand{glsxtrfieldlistadd, name={\csfmt{gls\-xtr\-field\-list\-add}}, user1={\margm{label}\margm{field}\margm{item}}, @@ -5528,6 +5565,11 @@ and \L/\l\ treated as L/l}, parent={packages} } +@index{field-reference, + name={field reference (string concatenation)}, + text={field reference} +} + @index{stringconcatenation, name={string concatenation} } @@ -8452,6 +8494,18 @@ long form on \idx{firstuse}. The default definition just uses parent={packageoptions} } +@packageoption{styopt.bibglsaux, + name={\styoptfmt{bib\-gls\-aux}}, + user1={\meta{basename}}, + description={creates a separate \ext{aux} file containing all +records, which is input using \cs{@bibgls@input} instead of +\cs{@input}}, + package={glossaries-extra}, + category={packageoption}, + seealso={switch.aux-input-action,glsxtrsetbibglsaux,@bibgls@input}, + parent={packageoptions} +} + @packageoption{styopt.accsupp, name={\styoptfmt{accsupp}}, description={load the \sty{glossaries-accsupp} package to provide @@ -10856,6 +10910,13 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.aux-input-action, + name={\longargfmt{aux\dhyphen input\dhyphen action}}, + user1={\meta{setting}}, + category={switch}, + parent={commandlineoptions} +} + @switch{switch.converter.texenc, name={\longargfmt{texenc}}, user1={\meta{encoding}}, @@ -14913,6 +14974,17 @@ usual delay}, description={clears the page, creates a supplementary \ext{aux} file, and selectively inputs the given file}, note={kernel command\texparserdefnote}, + seealso={@input}, + category={command} +} + +@command{@input, + name={\csfmt{@input}}, + user1={\margm{file}}, + description={used in the \ext{aux} file to input another \ext{aux} +file, typically because the document contains \cs{include}}, + note={kernel command\texparserdefnote}, + seealso={switch.aux-input-action,@bibgls@input}, category={command} } @@ -15735,7 +15807,7 @@ warning rather than an error if the command isn't already defined}, user1={}, description={provides code that locally redefines commands during the protected write operation performed by - \csref{glsxtrresourcefile}}, + \csref{GlsXtrLoadResources}}, topics={hooks}, note={\styfmt{glossaries-extra} v1.21+}, category={command}, @@ -16300,7 +16372,7 @@ conditional in \csopt{assign-fields} conditionals. This token needs name={\csfmt{Gls\-Xtr\-Default\-Resource\-Options}}, user1={}, description={provides default options for - \csref{glsxtrresourcefile}}, + \csref{GlsXtrLoadResources}}, topics={hooks}, note={\styfmt{glossaries-extra} v1.40+}, category={command} diff --git a/Master/texmf-dist/source/support/bib2gls/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/bib2gls.pod index a6c36b9d8d6..9baa010f2f8 100644 --- a/Master/texmf-dist/source/support/bib2gls/bib2gls.pod +++ b/Master/texmf-dist/source/support/bib2gls/bib2gls.pod @@ -21,6 +21,33 @@ or in a location that can be found by kpsewhich. =over 4 +=item B<--aux-input-action> I<setting> + +Determines what to do when B<bib2gls> encounters C<\@input> in the +F<aux> file. The I<setting> may be one of: + +=over 4 + +=item B<follow> + +Follow the reference (that is, input the file as usual). + +=item B<skip-after-bibglsaux> (or B<skip after bibglsaux>) + +Follow the reference for each C<\@input> encountered until +C<\@bibgls@input> is encountered, after which skip all remaining +instances of C<\@input> (default). + +=item B<skip> + +Skip all instances of C<\@input> (but not C<\@bibgls@input> +which is always followed). + +=back + +The C<\@bibgls@input> command will be in the F<aux> file if the package +option C<bibglsaux> has been used. + =item B<--break-space> Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space. diff --git a/Master/texmf-dist/source/support/bib2gls/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/bib2gls.tex index 81cd0a4de74..2a7be1a0aae 100644 --- a/Master/texmf-dist/source/support/bib2gls/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/bib2gls.tex @@ -88,6 +88,8 @@ {}{}% } +\newcommand\dash{\,---\,} + \renewcommand{\glsentrycounterlabel}{} \renewcommand{\glssubentrycounterlabel}{} \renewcommand\glstreeitem{\par\hangindent10pt} @@ -1535,6 +1537,10 @@ enabled.) Both \XeLaTeX\ and \LuaLaTeX\ default to UTF-8 \igls{encoding}. With modern \TeX\ distributions, \pdfLaTeX\ also defaults to UTF-8 but may be changed with the \sty{inputenc} package. +The \sty{glossaries-extra} package writes the document encoding to +the \ext{aux} file so that \bibgls\ can pick it up. However, if it +doesn't match \bibgls\ expected encoding, it will have to close the +file and reopen it. The default encoding for Java applications, such as \bibgls, is the default encoding of the \idx{JVM}. This typically matches the @@ -1559,7 +1565,8 @@ file. For example, when the \ext{aux} file is opened: Reading myDoc.aux Encoding: UTF-8 \end{verbatim} -If the document encoding is detected in the \ext{aux} file, it will +If the document encoding is detected in the \ext{aux} file +(which \bibgls\ should now be able to do), the encoding will be written to the transcript. For example: \begin{verbatim} TeX character encoding: UTF-8 @@ -1736,10 +1743,10 @@ also in the \href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gall Note that there's no need to called \idx!{xindy} or \idx!{makeindex} since \bibgls\ automatically sorts the entries and collates the \glspl{location} after selecting the required entries from the \ext{bib} file and -before writing the temporary file that's input with \gls{glsxtrresourcefile} -(or the more convenient shortcut -\gls{GlsXtrLoadResources}).\footnote{This document will mostly use -the more convenient \gls{GlsXtrLoadResources}.} This +before writing the temporary file that's input with +\gls{GlsXtrLoadResources} (or the shortcut +\gls{glsbibdata}).\footnote{This document will mostly use +\gls{GlsXtrLoadResources}.} This means the entries are already defined in the correct order, and only those entries that are required in the document are defined, so \ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used. @@ -2163,8 +2170,8 @@ up-to-date versions of both \sty{glossaries} and \section{Resource Sets} \label{sec:resourcesets} -Each instance of \gls{glsxtrresourcefile} or -\gls{GlsXtrLoadResources} in the document represents a \igls{resourceset}. Each +Each instance of \gls{GlsXtrLoadResources} (or +\gls{glsbibdata}) in the document represents a \igls{resourceset}. Each \igls{resourceset} has one or more associated \iext{bib} files that provides the data for that set. Command line switches (\sectionref{sec:switches}) are applied to all \iglspl{resourceset}. @@ -2605,9 +2612,9 @@ with single quote characters for convenience, but the process isn't actually called in that way. \bibgls\ creates files with the extension \ext{glstex}, which are -input by \gls{glsxtrresourcefile} (and therefore by the shortcut -\gls{GlsXtrLoadResources}). This extension is fixed and is imposed -by both \bibgls\ and \gls{glsxtrresourcefile}. \bibgls\ also creates +input by \gls{GlsXtrLoadResources} (and therefore by the shortcut +\gls{glsbibdata}). This extension is fixed and is imposed +by both \bibgls\ and \gls{GlsXtrLoadResources}. \bibgls\ also creates a transcript file with the default extension \ext{glg}. This may be overridden by the \longarg{log-file} switch, but \bibgls\ always forbids write access to any file with the following extensions: @@ -2681,11 +2688,13 @@ If you are using a document build method that tries to determine whether or not \bibgls\ should be run, you can find the information by searching the \iext{aux} file for instances of \nosecdef{glsxtr@resource} -Each instance corresponds to an instance of \gls{glsxtrresourcefile} +Each instance corresponds to an instance of \gls{GlsXtrLoadResources} (or \gls{glsbibdata}) where \meta{filename} is the base name of the \iext{glstex} file that \bibgls\ needs to create for this resource set. If the \meta{options} part is missing the \csopt{src} option, then \meta{filename} also indicates the base name for the \iext{bib} file. +In the case of \gls{glsbibdata}, the \csopt{src} option is +automatically set to the mandatory argument. So the simplest check to determine if \bibgls\ needs to be run is to test if the \iext{aux} file contains \gls{glsxtr@resource}. For @@ -3533,6 +3542,49 @@ This option cannot be set in \gls{BibGlsOptions}. \section{File Options} +\argsection{aux-input-action} + +Determines what \bibgls\ should do if it encounters \ics{@input} in +the \ext+{aux} file. The \meta{setting} may be one of the following: +\begin{description} +\item[\optfmt{follow}] follow the reference (that is, input the file). + +\item[\optfmt{skip after bibglsaux}] follow the reference until +\gls{@bibgls@input} is encountered, after which skip all remaining +instances of \ics{@input} (default). If there is no +\styopt{bibglsaux} file, this setting is no different from +\optfmt{follow}. + +\item[\optfmt{skip-after-bibglsaux}] synonym of \optfmt{skip after +bibglsaux}. + +\item[\optfmt{skip}] skip the reference. Be careful with this +setting if you haven't used \styopt{bibglsaux} or +\gls{glsxtrsetbibglsaux} as you may cause \bibgls\ to miss records. +However, if you are using \csopt[all]{selection} and you're not +interested in locations then this might help speed up \bibgls's +processing time. +\end{description} + +This setting is designed to work with \sty{glossaries-extra}['s] +\styopt{bibglsaux} package option or with +\nosecdef{glsxtrsetbibglsaux} +which does the same thing. +This specifies a special \ext{aux} file containing the records that +\bibgls\ will read but \LaTeX\ will skip. +The reference will be written to the \ext{aux} file with +\nosecdef{@bibgls@input} +which is defined by \sty{glossaries-extra} to simply ignore its +argument but \bibgls\ will input the file (regardless of the +\longarg{aux-input-action} setting). + +Since the \styopt{bibglsaux} file contains all records and is +typically written to the \ext{aux} file after all the commands that +\bibgls\ is interested in, it's unlikely that the additional +\ext{aux} files (created by \ics{include}) will be of any interest +to \bibgls. Therefore the default setting is to ignore all +\cs{@input} after \gls{@bibgls@input}. + \argsection{dir} This option cannot be set in \gls{BibGlsOptions}. @@ -4855,7 +4907,13 @@ If used in \gls{BibGlsOptions}, this option should be specified as \bibgls\ recognises certain \glspl{entrytype}. Any unrecognised types will be ignored and a warning will be written to the transcript file. -Entries are defined in the usual \ext{bib} format: +Bib file entry types can be divided into: special entry types and +glossary entry types. The resource options mostly apply only to +the glossary entry types (except where noted). + +The glossary entry types correspond to glossary entries that can be +referenced in the document with commands like \ics{gls}. +They are defined in the usual \ext{bib} format: \begin{codeenv*} \idx{atchar}\meta{entry-type}\marg{\meta{id}, \meta{field-name-1} = \margm{text}, @@ -4929,32 +4987,6 @@ If there is no encoding line in the \ext{bib} file and the \csopt{charset} option hasn't been used, then the default encoding will be assumed (see \sectionref{sec:defencoding}). -\section{Comments} -\label{sec:bibcomments} - -The original \ext{bib} file format as defined by \BibTeX\ doesn't -have a designated comment character, but instead treats anything -outside of \code{@\meta{entry}\margm{data}} as unwanted material -that's ignored. This can catch out users who try to do something -like: -\begin{verbatim} -%@misc{sample, title={Sample} } -\end{verbatim} -In this case, the percent character is simply discarded and the -line is treated as: -\begin{verbatim} -@misc{sample, title={Sample} } -\end{verbatim} -Some applications that parse \ext{bib} files are less tolerant of -unwanted material. In the case of \bibgls, the percent character is -treated as a comment character and other unwanted material -should be omitted. Avoid using comments within field values. -Comments are best placed outside of entry definitions. - -The most common type of comment is the \gls{encoding} comment, described -above. \BibTeX's \entrydef{comment} is also supported by \bibgls\ -for general comments, but not for the \gls{encoding}. - \section{Fields} \label{sec:fields} @@ -5169,7 +5201,281 @@ Note that some resource options allow string \gls{concatenation} in their syntax. That uses a different operator. See \sectionref{sec:optstringconcat} for further details. -\section{Standard Entry Types} +\section{Special Entry Types} +\label{sec:specialentrytypes} + +The bib entry types described in this section don't correspond to +any glossary entry type. They aren't affected by most of the +resource options, including sorting or filtering. + +\subsection{Comments} +\label{sec:bibcomments} + +The original \ext{bib} file format as defined by \BibTeX\ doesn't +have a designated comment character, but instead treats anything +outside of \code{@\meta{entry}\margm{data}} as unwanted material +that's ignored. This can catch out users who try to do something +like: +\begin{verbatim} +%@misc{sample, title={Sample} } +\end{verbatim} +In this case, the percent character is simply discarded and the +line is treated as: +\begin{verbatim} +@misc{sample, title={Sample} } +\end{verbatim} +Some applications that parse \ext{bib} files are less tolerant of +unwanted material. In the case of \bibgls, the percent character is +treated as a comment character and other unwanted material +should be omitted. Avoid using comments within field values. +Comments are best placed outside of entry definitions. + +The most common type of comment is the \gls{encoding} comment, described +above. \BibTeX's \entrydef{comment} is also supported by \bibgls\ +for general comments, but not for the \gls{encoding}. + +\subsection{Preamble} +\label{sec:preamble} + +As with \BibTeX, \entrydef{preamble} is also supported by \bibgls. +This will be written to the \ext{glstex} file unless +prevented with \csopt[false]{write-preamble}. +The \texparserlib\ used by \bibgls\ will parse the contents of +\atentry{preamble} unless \csopt[false]{interpret-preamble} +(or the interpreter is switched off with \longarg{no-interpret}). + +\subsection{Compound Entry Sets} +\label{sec:compoundsetentry} + +A \gls{compoundentry} isn't a normal glossary entry +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}. They are referenced with commands +like \ics{mgls} not with the \cs{gls} set of commands. +As such, they don't belong in any glossary list, although their +component elements do. + +\begin{important} +Most resource options don't apply to this \gls{entrytype}. Options +specific to \glspl{compoundentry} are listed in +\sectionref{sec:compoundentries}. +\end{important} + +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 component 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. +If any element hasn't been selected, the \gls{compoundentry} define won't +be written to the \ext{glstex} file, regardless of the +\csopt{compound-write-def} setting. + +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{description} +\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{description} +These fields can only be used in this \gls{entrytype}. + +\section{Glossary Entry Types} +\label{sec:glossaryentrytypes} + +Each of the bib entry types listed below corresponds to one or more glossary +entries, which may be referenced in the document with commands such +as \cs{gls}. + +\subsection{Standard Entry Types} \label{sec:standardentry} \entrysection{string} @@ -5439,7 +5745,7 @@ Alternatively to avoid links with \csfmt{gcard} as well: Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands, but their actual definitions are determined in the \ext{bib} file. -\section{Single Entry Types} +\subsection{Single Entry Types} \label{sec:singleentry} The \glspl{entrytype} described in this section create a single glossary @@ -5820,7 +6126,7 @@ The resource options then need to include: If the \atentry{contributor} entry is deferred until after the corresponding \atentry{bibtexentry} then you will end up with a label clash. -\section{Dual Entry Types} +\subsection{Dual Entry Types} \label{sec:dualentry} The \glspl{entrytype} described in this section create two separate (but @@ -7036,7 +7342,7 @@ the \idx!{postdescriptionhook} is no longer required. As \atentry{dualabbreviation} but defines the entries with \gls!{bibglsnewdualacronym}. -\section{Tertiary Entry Types} +\subsection{Tertiary Entry Types} \label{sec:tertiaryentry} A \igls{tertiaryentry} type is essentially a \gls{dualentry} that creates three @@ -7121,7 +7427,7 @@ corresponding \gls{secondaryentry}. The \primary\ may be defined earlier or later in the file depending on the way the entries are sorted and on the \csopt{dual-sort} setting. -\section{Multi-Entry Types} +\subsection{Multi-Entry Types} \label{sec:multientry} A \gls{multientrytype} is an entry that may spawn multiple @@ -7618,222 +7924,6 @@ 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 \gls{entrytype}. - -Most resource options don't apply to this \gls{entrytype}. Options -specific to \glspl{compoundentry} are listed in -\sectionref{sec:compoundentries}. - \chapter{Resource File Options} \label{sec:resourceopts} @@ -7854,46 +7944,31 @@ in which case you need to prevent \bibgls\ from sorting using the \csopt[none]{sort} resource option). The \iext{glstex} resource files created by \bibgls\ are loaded in -the document using -\nosecformatdef{glsxtrresourcefile} -where \meta{filename} is the name of the resource file without the -\ext{glstex} extension. -You can have multiple \gls{glsxtrresourcefile} commands within your -document, but each \meta{filename} must be unique, otherwise \LaTeX\ -would attempt to input the same \ext{glstex} file multiple times -(\bibgls\ checks for non-unique file names). The associated data for each +the document using: +\nosecformatdef{GlsXtrLoadResources} +You can have multiple \gls{GlsXtrLoadResources} commands within your +document. The associated data for each resource file is called the \igls{resourceset} (see \sectionref{sec:resourcesets}). -There's a shortcut command that uses -\ics{jobname} in the \meta{filename}: -\nosecformatdef{GlsXtrLoadResources} -The first instance of this command is equivalent to: -\begin{codeenv} -\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}} -\end{codeenv} -Any additional use of \gls{GlsXtrLoadResources} is equivalent to: -\begin{codeenv} -\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}-\meta{n}} -\end{codeenv} -where \meta{n} is number. For example: -\begin{codeenv} -\gls{GlsXtrLoadResources}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}} -\gls{GlsXtrLoadResources}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}} -\gls{GlsXtrLoadResources}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}} -\end{codeenv} -This is equivalent to: +There's a shortcut command: +\nosecformatdef{glsbibdata} +This simply does: \begin{codeenv} -\gls{glsxtrresourcefile}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}}\marg{\cs{jobname}} -\gls{glsxtrresourcefile}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}}\marg{\cs{jobname}-1} -\gls{glsxtrresourcefile}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}}\marg{\cs{jobname}-2} +\gls{GlsXtrLoadResources}\oarg{\csopt[\margm{bib-list}]{src},\meta{options}} \end{codeenv} -In general, it's simplest just to use \gls{GlsXtrLoadResources}. + +Note that the older command \inlinedef{glsxtrresourcefile} is deprecated +as from \sty{glossaries-extra} v1.55 because it has the potential to cause +a filename clash. If you actually intend to share +\glspl{resourceset}\dash as opposed to sharing \ext{bib} files\dash +across multiple documents then you need to use the \csopt{master} +resource option (see \sectionref{sec:master}). The optional argument \meta{options} is a comma-separated \keyvallist. Allowed options are listed below. The option list applies only to that specific \meta{filename}\ext{glstex} and are -not carried over to the next instance of \gls{glsxtrresourcefile}. +not carried over to the next instance of \gls{GlsXtrLoadResources}. Only the definitions provided in \atentry{preamble} (if the interpreter is on and \csopt[true]{interpret-preamble}) are carried over to the next resource set and, possibly, @@ -7933,7 +8008,7 @@ This acts like: If you have multiple \ext{bib} files you can either select them all using \csopt[\meta{bib list}]{src} in a single -\gls{glsxtrresourcefile} call, if they all require the same settings, +\gls{GlsXtrLoadResources} call, if they all require the same settings, or you can load them separately with different settings applied. For example, if the files \filefmt{entries-terms.bib} and @@ -7949,7 +8024,7 @@ Alternatively, if they have different settings: Note that the sorting is applied to each \igls{resourceset} independently of other \iglspl{resourceset}. This means that if you have multiple instances -of \gls{glsxtrresourcefile} but only one glossary type, the glossary +of \gls{GlsXtrLoadResources} but only one glossary type, the glossary will effectively contain blocks of sorted entries. For example, if \filefmt{file1.bib} contains: \begin{codeenv} @@ -7986,7 +8061,7 @@ Abbreviation styles must be set (using \ics{setabbreviationstyle}) before the resource command that selects the abbreviations from the appropriate \ext{bib} file, since the entries are defined (through \gls{newabbreviation} or \gls{newacronym}) when -\gls{glsxtrresourcefile} inputs the \ext{glstex} file. (Similarly for any +\gls{GlsXtrLoadResources} inputs the \ext{glstex} file. (Similarly for any associated abbreviation style commands that must be set before abbreviations are defined, such as \cs{glsxtrlongshortdescname}.) @@ -8104,9 +8179,10 @@ has the following syntax: \meta{group-ref} ::= \meta{index} | \meta{name} \meta{string} ::= \qtdelim{\meta{tokens}} | \margm{tokens} \end{codeenv} -The \meta{field-ref} syntax is described below, and is used to +The \meta{field-ref} syntax is described below in \sectionref{sec:fieldref}, and is used to reference a field value. -The element quarks (\meta{element-quark}, described below) take an +The element quarks (\meta{element-quark}, described below in +\sectionref{sec:elementquarks}) take an \meta{element-list} argument. If the \meta{element-list} argument evaluates to null, they will return null. @@ -8166,6 +8242,9 @@ If only a single set of braces was used, those braces would be stripped leaving a bare \code{index}, which would be parsed as a field reference. +\subsection{Element Quarks} +\label{sec:elementquarks} + The element \idxpl{quark} are uppercase tokens that start with a leading backslash. They have no meaning to \bibgls's interpreter nor are they defined in the \LaTeX\ document outside of the scope of @@ -8490,7 +8569,10 @@ content passed to the resource command. For example: } \end{codeenv} -The field reference (\meta{field-ref}) syntax is more complicated: +\subsection{Field Reference} +\label{sec:fieldref} + +The \idx{field-reference} (\meta{field-ref}) syntax is more complicated: \begin{codeenv} \meta{field-ref} ::= \meta{value-ref} | \meta{entry-ref} \idx{follow} \meta{field-ref} \meta{entry-ref} ::= self | parent | root @@ -8535,7 +8617,8 @@ which may be \code{original} or \code{actual}. Available keywords: \code{@}, where \code{original} refers to the original \gls{entrytype} used in the \ext{bib} file and \code{actual} refers to the actual \gls{entrytype}, which may have changed as a result of -\csopt{entry-type-aliases}; +\csopt{entry-type-aliases} (but remember that you can't match the +special entry types described in \sectionref{sec:specialentrytypes}); \item[\code{entrylabel}] the entry label, where \code{original} refers to the original label used in the \ext{bib} file and @@ -9414,32 +9497,15 @@ For example: \gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} \end{codeenv} indicates that \bibgls\ must read the files -\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} and -create the file given by \ics{jobname}\iext{glstex} on the first -instance or \ics{jobname}\code{-}\meta{n}\ext{glstex} on subsequent -use. - -With \code{\gls!{glsxtrresourcefile}\oargm{options}\margm{filename}}, if -the \csopt{src} option is omitted, -the \ext{bib} file is assumed to be \meta{filename}\ext{bib}. For example: -\begin{codeenv} -\gls{glsxtrresourcefile}\marg{entries-symbols} -\end{codeenv} -indicates that \bibgls\ needs to read the file -\filefmt{entries-symbols.bib}, which contains the entry data, and create the file -\filefmt{entries-symbols.glstex}. If the \ext{bib} file is -different or if you have multiple \ext{bib} files, you need to use -the \csopt{src} option. +\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib}. -\gls{GlsXtrLoadResources} uses \ics{jobname} as the argument of -\gls{glsxtrresourcefile} on the first instance, so: -\begin{codeenv} -\gls{GlsXtrLoadResources}\oarg{} -\end{codeenv} -will assume \csopt[\ics{jobname}]{src}. Remember that subsequent uses -of \gls{GlsXtrLoadResources} append a suffix, so in general it's -best to always supply \csopt{src}, except for small test cases with -a single \gls{resourcecommand}. +If \csopt{src} is omitted or if the value is empty, it's assumed to +be the same as the basename of the \ext{glstex} file. This is +\ics{jobname} for the first instance of \gls{GlsXtrLoadResources}. +Remember that subsequent uses of \gls{GlsXtrLoadResources} append a +suffix \code{\cs{jobname}-\meta{n}}, so in general it's best to +always supply \csopt{src} (or use \gls{glsbibdata}), except for +small test cases with a single \gls{resourcecommand}. With old \LaTeX\ kernels, if you have non-ASCII characters in the \ext{bib} filename but aren't using \XeLaTeX\ or \LuaLaTeX, then you @@ -9649,6 +9715,17 @@ field identifying the glossary label). If you've used \csopt{entry-type-aliases}, this refers to the target \gls{entrytype} not the original \gls{entrytype} specified in the \ext{bib} file. +\begin{important} +Filtering options don't apply directly to \atentry{compoundset} +entries (or any of the other special entry types described in +\sectionref{sec:specialentrytypes}), so you can't +match the entry type to \atentry{compoundset}. +However, if any elements within a \gls{compoundentry} are filtered +then the \gls{compoundentry} won't be written to the \ext{glstex} +file. Use the \csopt{compound-write-def} option to determine whether +or not to write the \gls{compoundentry} to the resource file. +\end{important} + The \meta{regexp} part should be a \gls{regular-expression} conforming to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's @@ -9723,6 +9800,16 @@ empty, which indicates that the setting is switched off. If you have both \csopt{match} and \csopt{not-match} in the same resource set, the last one listed takes precedence. +\begin{important} +Filtering options don't apply directly to \atentry{compoundset} +entries (or any of the other special entry types described in +\sectionref{sec:specialentrytypes}), so you can't match the entry type to \atentry{compoundset}. +However, if any elements within a \gls{compoundentry} are filtered +then the \gls{compoundentry} won't be written to the \ext{glstex} +file. Use the \csopt{compound-write-def} option to determine whether +or not to write the \gls{compoundentry} to the resource file. +\end{important} + \optsection{match-action} The default behaviour with \csopt{match} or \csopt{not-match} @@ -10751,14 +10838,11 @@ then by default all the \gls{masterdocument}['s] you can use \optfmt{master-resources} to specify only those files that should be included. The value \meta{list} is a comma-separated list of names, where each name corresponds -to the final argument of \gls!{glsxtrresourcefile}. -Remember that \gls{GlsXtrLoadResources} is just a shortcut -for \gls{glsxtrresourcefile} that bases the name on \ics{jobname}. -(Note that, as with the argument of \gls{glsxtrresourcefile}, -the \ext{glstex} extension should not be included in \meta{list}.) The file -\primaryresourcefmt\ is considered the primary -resource file and the files \suppresourcefmt{\meta{n}} -(starting with \meta{n} equal to 1) are considered the supplementary resource files. +to the basename of the applicable \gls{resourceset}. +The file \primaryresourcefmt\ is considered the primary resource +file and the files \suppresourcefmt{\meta{n}} (starting with +\meta{n} equal to 1) are considered the supplementary resource +files. For example, to just select the first and third of the supplementary resource files (omitting the primary @@ -16253,7 +16337,7 @@ sequences are the same, so the test is retried with the first In this example, the \gls{location} has been written to the file as \code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that -\gls!{glsxtrresourcefile} changes the category code of \code{@} to allow for +\gls!{GlsXtrLoadResources} changes the category code of \code{@} to allow for internal commands in \glspl{location}.) This unusual case is for illustrative purposes. \end{enumerate} @@ -16431,7 +16515,7 @@ is left unchanged). Note that with \csopt[transfer]{alias-loc}, both the aliased entry and the target entry must be in the same resource set. (That is, both entries have been selected by the same instance of -\gls!{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version~1.12, +\gls!{GlsXtrLoadResources}.) If you have \sty{glossaries-extra} version~1.12, you may need to redefine \ics{glsxtrsetaliasnoindex} to do nothing if the \glspl{locationlist} aren't showing correctly with aliased entries. (This was corrected in version~1.13.) @@ -20188,7 +20272,7 @@ hook could contain: \end{codeenv} Note that this new field won't be available for use within the \iext{bib} file (unless it was previously defined in the document -before \gls!{glsxtrresourcefile}). +before \gls!{GlsXtrLoadResources}). \optsection[\subsubsection]{dual-date-time-field-format} diff --git a/Master/texmf-dist/source/support/bib2gls/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/texparser-src.zip Binary files differindex 42f3ae32fc0..9651574eb85 100644 --- a/Master/texmf-dist/source/support/bib2gls/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/texparser-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/version.tex b/Master/texmf-dist/source/support/bib2gls/version.tex index 610a8da5933..e7b17b8a986 100644 --- a/Master/texmf-dist/source/support/bib2gls/version.tex +++ b/Master/texmf-dist/source/support/bib2gls/version.tex @@ -1,4 +1,4 @@ \date{Version -4.2 -2025-01-24 +4.3 +2025-01-29 }% |