diff options
Diffstat (limited to 'Master/texmf-dist')
29 files changed, 1411 insertions, 238 deletions
diff --git a/Master/texmf-dist/doc/support/bib2gls/CHANGES b/Master/texmf-dist/doc/support/bib2gls/CHANGES index f7279391084..48af0c3703d 100644 --- a/Master/texmf-dist/doc/support/bib2gls/CHANGES +++ b/Master/texmf-dist/doc/support/bib2gls/CHANGES @@ -1,3 +1,29 @@ +v1.4 (2018-04-09): + + * added switches: + + --list-known-packages + --custom-packages + --cite-as-record + --no-cite-as-record + --merge-wrglossary-records + --no-merge-wrglossary-records + + * added resource options: + + - missing-parents + - missing-parent-category + - bibtexentry-sort-fallback + - save-index-counter + + * added extra keyword "same as original entry" + to category and type assignments. + + * added new entry types: + + - @bibtexentry + - @contributor + v1.3 (2018-03-05): * bug fix: check for quoted path elements (spaces in file names) diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 b/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 index a5b9fdd713f..0db7814c41f 100644 --- a/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 +++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "BIB2GLS 1" -.TH BIB2GLS 1 "2018-03-04" "perl v5.18.4" "bib2gls" +.TH BIB2GLS 1 "2018-04-07" "perl v5.18.4" "bib2gls" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -205,6 +205,19 @@ Interpret tilde character as a normal space. .IP "\fB\-\-no\-break\-space\fR" 4 .IX Item "--no-break-space" Interpret tilde as a non-breaking space (default). +.IP "\fB\-\-cite\-as\-record\fR" 4 +.IX Item "--cite-as-record" +Treat \fB\ecitation\fR as an ignored record. +.IP "\fB\-\-no\-cite\-as\-record\fR" 4 +.IX Item "--no-cite-as-record" +Don't check for instances of \fB\ecitation\fR in the \fB.aux\fR file (default). +.IP "\fB\-\-merge\-wrglossary\-records\fR" 4 +.IX Item "--merge-wrglossary-records" +Merge an entry's \fBwrglossary\fR records for the same page locations. +(For use with the \fBindexcounter\fR package option.) +.IP "\fB\-\-no\-merge\-wrglossary\-records\fR" 4 +.IX Item "--no-merge-wrglossary-records" +Don't merge an entry's \fBwrglossary\fR records. .IP "\fB\-\-force\-cross\-resource\-refs\fR or \fB\-x\fR" 4 .IX Item "--force-cross-resource-refs or -x" Force cross-resource referencing mode on. @@ -230,14 +243,27 @@ in \fIlist\fR have been used by the document. Note that there's only a limited number of packages supported by the TeX parser library. This option has a cumulative action so \fB\-\-packages wasysym,pifont\fR is the same as \fB\-\-packages wasysym \-\-packages pifont\fR. +.Sp +You can find out the list of supported packages with +\&\fB\-\-list\-known\-packages\fR. +.IP "\fB\-\-custom\-packages\fR \fIlist\fR" 4 +.IX Item "--custom-packages list" +Instruct the TeX parser library to attempt to parse the +packages listed in \fIlist\fR. This is intended for simple custom +packages that don't contain complex code. .IP "\fB\-\-ignore\-packages\fR \fIlist\fR (or \fB\-k\fR \fIlist\fR)" 4 .IX Item "--ignore-packages list (or -k list)" Don't parse the log file for the packages listed in \fIlist\fR. Note that \fB\-\-packages\fR overrides this option, so if the same package is listed in both \fB\-\-ignore\-packages\fR and \fB\-\-packages\fR then the interpreter will check if it's supported. This option has a -cumulative action. (The \fBglossaries-extra\fR package can't be -included in the ignored \fIlist\fR.) +cumulative action. Only known packages may be included in +\&\fIlist\fR. +.IP "\fB\-\-list\-known\-packages\fR" 4 +.IX Item "--list-known-packages" +Lists all the packages that have are known to the TeX parser +library and then exits (with exit code 0). Any of the listed +packages may be used in \fB\-\-packages\fR or \fB\-\-ignore\-packages\fR. .IP "\fB\-\-mfirstuc\-protection\fR \fIfields\fR|\fBall\fR (or \fB\-u\fR \fIfields\fR|\fBall\fR)" 4 .IX Item "--mfirstuc-protection fields|all (or -u fields|all)" Insert an empty group if fields start with certain problematic diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf Binary files differindex fe8ac4ece60..5d17bbd70cd 100644 --- a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf Binary files differindex 76534290322..fe10f53a947 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf Binary files differindex 5a5584e01aa..49455ff3640 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf Binary files differindex 0475e6c3a75..856549f2d2a 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf Binary files differindex 71bb4a1e182..5efc443c095 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf Binary files differindex c1201374f86..074f4e34945 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf Binary files differindex 65f831f1e1b..6867cf63943 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf Binary files differindex c82a4893b2a..8ef2e531023 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf Binary files differindex 8c26e31452c..7eee95e4a49 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf Binary files differindex 7c959fd1b34..5c1c8bcb307 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf Binary files differindex 5b7694e8585..17bb6275e3d 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf Binary files differindex 2b51baa69d8..0e636887cad 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf Binary files differindex f3ed504f878..58a326a7c1f 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf Binary files differindex bf2bed2ec30..493f33c021d 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf Binary files differindex 2175683b701..af7bc696205 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf Binary files differindex 53f6af6c97f..da9f1ae4715 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf Binary files differindex e867646d135..0a1bbbac069 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf diff --git a/Master/texmf-dist/scripts/bib2gls/bib2gls.jar b/Master/texmf-dist/scripts/bib2gls/bib2gls.jar Binary files differindex dc534c7e0fa..4703f0d41ba 100755 --- a/Master/texmf-dist/scripts/bib2gls/bib2gls.jar +++ b/Master/texmf-dist/scripts/bib2gls/bib2gls.jar diff --git a/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar Binary files differindex 92a7cd9c549..50367615e17 100755 --- a/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar +++ b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar diff --git a/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml index ed928374730..0e65ff8855d 100644 --- a/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml +++ b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml @@ -37,6 +37,12 @@ See the manual for further details.</entry> <entry key="syntax.break.space">{0} Interpret tilde character as normal space.</entry> <entry key="syntax.no.break.space">{0} Interpret tilde character as a non-breaking space (default).</entry> +<entry key="syntax.cite.as.record">{0} Treat \citation as an ignored record.</entry> +<entry key="syntax.no.cite.as.record">{0} Don''t treat \citation as an ignored record (default).</entry> +<entry key="syntax.merge.wrglossary.records">{0} + Merge wrglossary counter records (default).</entry> +<entry key="syntax.no.merge.wrglossary.records">{0} + Don''t merge wrglossary counter records.</entry> <entry key="syntax.force.cross.resource.refs">{0} (or {1}) Force cross-resource referencing mode on.</entry> <entry key="syntax.no.force.cross.resource.refs">{0} @@ -126,11 +132,17 @@ See the manual for further details.</entry> <entry key="syntax.tex.encoding">{0} <name> Set the character encoding for the output files.</entry> <entry key="syntax.packages">{0} <list> or {1} <list> - Instruct interpreter to pretend the listed - packages have been used in the document.</entry> + Instruct interpreter to assume the listed + packages have been used in the document. + (The packages must be known by the interpreter.)</entry> <entry key="syntax.ignore.packages">{0} <list> or {1} <list> Don''t check the log file for the listed packages.</entry> +<entry key="syntax.custom.packages">{0} <list> + Instruct the interpreter to parse + the listed packages.</entry> +<entry key="syntax.list.known.packages"> + List the packages known to the interpreter.</entry> <entry key="message.reading">Reading {0}</entry> <entry key="message.writing">Writing {0}</entry> @@ -247,6 +259,9 @@ Defaulting to: {0}. <entry key="message.setting.entry.aliases">Setting entry type aliases.</entry> <entry key="message.removing.missing.parent">Stripping missing parent ''{0}'' from entry {1}</entry> <entry key="message.missing.sort.fallback">Entry ''{0}'' missing sort field ''{1}''. Falling back on field ''{2}''.</entry> +<entry key="message.list.known.packages.auto">Automatic support for: </entry> +<entry key="message.list.known.packages.extra">Support available for: </entry> +<entry key="message.created.missing.parent">Created missing parent ''{0}'' for entry ''{1}''</entry> <entry key="tag.page">Page</entry> <entry key="tag.pages">Pages</entry> @@ -405,6 +420,12 @@ Error occurred before: {3} <entry key="error.field.alias.trail">''field-aliases'' can''t contain both ''{0}={1}'' and ''{2}={0}'' (trails not permitted)</entry> <entry key="error.field.alias.identity">''field-aliases'' can''t contain identity mapping ''{0}={0}''</entry> <entry key="error.cyclic.sameas.type.category">Cyclic reference category='{'same as type'}' and type='{'same as category'}'</entry> +<entry key="error.unsupported.package">Package ''{0}'' doesn't have in-built support. +Use {1} {0} to allow the interpreter to parse {0}.sty if the package isn''t too complicated.</entry> +<entry key="error.supported.package">Package ''{0}'' has in-built support. +Use {1} {0} instead.</entry> +<entry key="error.create.missing.parent.failed">Attempt to create missing parent ''{0}'' for entry ''{1}'' caused a problem: +{2}</entry> <!-- The following messages are used by convertgls2bib @@ -483,8 +504,9 @@ converted to @dualabbreviationentry.)</entry> <entry key="bibtex.error.missing_value">Missing value</entry> <entry key="bibtex.error.expecting">Expecting ''{0}''</entry> <entry key="bibtex.error.expecting_or">Expecting ''{0}'' or ''{1}''</entry> -<entry key="bibtex.error.missing_field_part">Missing field part</entry> -<entry key="bibtex.error.missing_field_name">Missing field name</entry> +<entry key="bibtex.error.missing_id">Missing identifier</entry> +<entry key="bibtex.error.missing_field_part">Missing field value</entry> +<entry key="bibtex.error.missing_field_name">Missing field identifier</entry> <entry key="bibtex.error.unbalanced_braces">Unbalanced braces</entry> <entry key="bibtex.error.immediately_follows_entry_type">''{0}'' immediately follows entry type</entry> <entry key="bibtex.error.immediately_follows_field_name">''{0}'' immediately follows field name</entry> diff --git a/Master/texmf-dist/scripts/bib2gls/texparserlib.jar b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar Binary files differindex 2436eac873d..257655baedb 100755 --- a/Master/texmf-dist/scripts/bib2gls/texparserlib.jar +++ b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip Binary files differindex aa582b37b1b..9e7fa0e837b 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 6b2269114f8..32d6885d164 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -224,6 +224,21 @@ category={command} } +@dualindexentry{bibglsnewbibtexentry, + name={\csfmt{bib\-gls\-new\-bib\-tex\-entry}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with \gls[noindex]{dual.entry.bibtexentry}}, + category={command} +} + +@dualindexentry{bibglsnewcontributor, + name={\csfmt{bib\-gls\-new\-con\-trib\-u\-tor}}, + user1={\margm{label}\margm{options}\margm{name}\margm{description}}, + description={defines terms provided with + \gls[noindex]{dual.entry.contributor}}, + category={command} +} + @dualindexentry{bibglsuselongfont, name={\csfmt{bib\-gls\-use\-long\-font}}, user1={\margm{text}\margm{category}}, @@ -883,6 +898,26 @@ file by \gls{glsxtrresourcefile} category={command} } +@dualindexentry{glsxtr@wrglossarylocation, + name={\csfmt{gls\-xtr\-@wr\-glossary\-location}}, + user1={\margm{n}\margm{page}}, + description={This command simply expands to \meta{n}, the value of +the \counter{wrglossary} counter for the given page}, + note={internal command provided by + \styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@dualindexentry{GlsXtrIndexCounterLink, + name={\csfmt{Gls\-Xtr\-Index\-Counter\-Link}}, + user1={\margm{text}\margm{label}}, + description={Creates a hyperlink to the \counter{wrglossary} +location obtained from the \field{indexcounter} field}, + note={internal command provided by + \styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + @dualindexentry{glsxtrfmt, name={\csfmt{gls\-xtr\-fmt}}, user1={\oargm{options}\margm{label}\margm{text}}, @@ -961,6 +996,20 @@ file by \gls{glsxtrresourcefile} parent={resourceoptions} } +@dualindexentry{opt.missing-parents, + name={\csoptfmt{missing\dhyphen parents}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@dualindexentry{opt.missing-parent-category, + name={\csoptfmt{missing\dhyphen parent\dhyphen category}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.copy-alias-to-see, name={\csoptfmt{copy\dhyphen alias\dhyphen to\dhyphen see}}, user1={\meta{boolean}}, @@ -1363,7 +1412,7 @@ field\dhyphen locale}}, @dualindexentry{opt.group, name={\csoptfmt{group}}, - user1={\meta{value}}, + user1={\meta{label}}, category={resourceoption}, parent={resourceoptions} } @@ -1501,6 +1550,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.save-index-counter, + name={\csoptfmt{save\dhyphen index\dhyphen counter}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.supplemental-locations, name={\csoptfmt{supplemental\dhyphen locations}}, user1={\meta{basename}}, @@ -1564,6 +1620,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.bibtexentry-sort-fallback, + name={\csoptfmt{bibtexentry\dhyphen sort\dhyphen fallback}}, + user1={\meta{field}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.trim-sort, name={\csoptfmt{trim\dhyphen sort}}, user1={\meta{boolean}}, @@ -2698,6 +2761,54 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{booktabs, + name={\styfmt{booktabs}}, + category={package}, + parent={packages} +} + +@index{color, + name={\styfmt{color}}, + category={package}, + parent={packages} +} + +@index{graphics, + name={\styfmt{graphics}}, + category={package}, + parent={packages} +} + +@index{graphicx, + name={\styfmt{graphicx}}, + category={package}, + parent={packages} +} + +@index{ifthen, + name={\styfmt{ifthen}}, + category={package}, + parent={packages} +} + +@index{probsoln, + name={\styfmt{probsoln}}, + category={package}, + parent={packages} +} + +@index{shortvrb, + name={\styfmt{shortvrb}}, + category={package}, + parent={packages} +} + +@index{jmlrutils, + name={\styfmt{jmlrutils}}, + category={package}, + parent={packages} +} + @index{inputenc, name={\styfmt{inputenc}}, category={package}, @@ -2710,6 +2821,12 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{babel, + name={\styfmt{babel}}, + category={package}, + parent={packages} +} + @index{polyglossia, name={\styfmt{polyglossia}}, category={package}, @@ -3236,6 +3353,11 @@ cs}\margm{Glspl-like cs}}, category={counter} } +@index{ctr.wrglossary, + name={\counterfmt{wrglossary}}, + category={counter} +} + @index{labelprefixes, name={label prefixes}, text={label prefix}, @@ -3355,6 +3477,18 @@ cs}\margm{Glspl-like cs}}, parent={packageoptions} } +@index{styopt.counter, + name={\styoptfmt{counter}}, + category={packageoption}, + parent={packageoptions} +} + +@index{styopt.indexcounter, + name={\styoptfmt{index\-counter}}, + category={packageoption}, + parent={packageoptions} +} + @index{styopt.index, name={\styoptfmt{index}}, category={packageoption}, @@ -3786,6 +3920,15 @@ field.}, parent={internalfields} } +@dualindexentry{field.indexcounter, + name={\fieldfmt{index\-counter}}, + description={Stores the location corresponding to the matching +\counter{wrglossary} reference.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + @dualindexentry{field.counter, name={\fieldfmt{counter}}, description={The default counter used for indexing (assigned by @@ -3891,6 +4034,42 @@ field.}, parent={internalfields} } +@dualindexentry{field.bibtextype, + name={\fieldfmt{bib\-tex\-type}}, + description={Used by \bibgls\ as a substitution for \BibTeX's + \fieldfmt{type} field when parsing \atentry{bibtexentry}. Needs + to be defined or aliased to make it available in the document.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@dualindexentry{field.bibtexcontributor, + name={\fieldfmt{bib\-tex\-con\-trib\-u\-tor}}, + description={An internal list field provided when a + \atentry{contributor} entry is automatically + created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@dualindexentry{field.bibtexentry, + name={\fieldfmt{bib\-tex\-entry}}, + description={An internal list field created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + +@dualindexentry{field.bibtexentry@entrytype, + name={\fieldfmt{bib\-tex\-entry\-@\meta{entry-type}}}, + description={An internal list field created by \atentry{bibtexentry}.}, + note={internal field set by \bibgls}, + category={internalfield}, + parent={internalfields} +} + @dualindexentry{field.currcount, name={\fieldfmt{currcount}}, description={Used with entry counting to store the current total.}, @@ -4223,6 +4402,18 @@ field.}, parent={entrytypes} } +@dualindexentry{entry.bibtexentry, + name={\atentryfmt{bib\-tex\-entry}}, + category={entrytype}, + parent={entrytypes} +} + +@dualindexentry{entry.contributor, + name={\atentryfmt{contributor}}, + category={entrytype}, + parent={entrytypes} +} + @index{switches, name={switches}, text={switch}, @@ -4340,6 +4531,34 @@ field.}, parent={commandlineoptions} } +@dualindexentry{switch.cite-as-record, + name={\longargfmt{cite\dhyphen as\dhyphen record}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@dualindexentry{switch.no-cite-as-record, + name={\longargfmt{no\dhyphen cite\dhyphen as\dhyphen record}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@dualindexentry{switch.merge-wrglossary-records, + name={\longargfmt{merge\dhyphen wrglossary\dhyphen records}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@dualindexentry{switch.no-merge-wrglossary-records, + name={\longargfmt{no\dhyphen merge\dhyphen wrglossary\dhyphen records}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + @dualindexentry{switch.force-cross-resource-refs, name={\longargfmt{force\dhyphen cross\dhyphen resource\dhyphen refs}}, symbol={\shortargfmt{x}}, @@ -4385,6 +4604,19 @@ field.}, parent={commandlineoptions} } +@dualindexentry{switch.custom-packages, + name={\longargfmt{custom\dhyphen packages}}, + user1={\meta{list}}, + category={switch}, + parent={commandlineoptions} +} + +@dualindexentry{switch.list-known-packages, + name={\longargfmt{list\dhyphen known\dhyphen packages}}, + category={switch}, + parent={commandlineoptions} +} + @dualindexentry{switch.mfirstuc-protection, name={\longargfmt{mfirstuc\dhyphen protection}}, symbol={\shortargfmt{u}}, @@ -4570,6 +4802,10 @@ field.}, plural={ignored glossaries} } +@index{ignoredrecord, + name={ignored record} +} + @index{postlinkhook, name={post-link hook} } @@ -4708,6 +4944,10 @@ field.}, name={\filefmt{bib2gls.bat}} } +@index{file.xampl.bib, + name={\filefmt{xampl.bib}} +} + @index{file.sample-dual.tex, name={\filefmt{sample\dhyphen dual.tex}} } @@ -4895,7 +5135,8 @@ field.}, user1={\margm{label}\margm{field}\margm{handler}}, description={iterates over the items the given field, which contains an \styfmt{etoolbox} internal list, using the given handler}, - note={provided by \styfmt{glossaries-extra}}, + note={provided by \styfmt{glossaries-extra}, use at least v1.29 to +avoid a bug}, category={command} } @@ -5482,7 +5723,16 @@ label of the current entry}, @index{glsnumberformat, name={\csfmt{gls\-number\-format}}, user1={\margm{text}}, - description={default location format}, + description={default location format, uses \cs{glshypernumber} if +hyperlinks enabled otherwise just does \meta{text}}, + note={provided by \styfmt{glossaries}}, + category={command} +} + +@index{glshypernumber, + name={\csfmt{gls\-hyper\-number}}, + user1={\margm{text}}, + description={a location format that has a hyperlink (if enabled)}, note={provided by \styfmt{glossaries}}, category={command} } @@ -5538,7 +5788,7 @@ by \gls{makeindex} or \gls{xindy}}, name={\csfmt{glsignore}}, user1={\margm{text}}, description={does nothing but when used as a location format - \bibgls\ recognises it as an ignored location}, + \bibgls\ recognises it as an \idx{ignoredrecord}}, note={provided by \styfmt{glossaries}}, category={command} } @@ -5557,7 +5807,7 @@ by \gls{makeindex} or \gls{xindy}}, name={\csfmt{gls\-trigger\-record\-format}}, user1={\margm{text}}, description={does nothing but when used as a location format - \bibgls\ recognises it as an ignored location indexed by + \bibgls\ recognises it as an \idx{ignoredrecord} indexed by commands like \cs{rgls}}, note={provided by \styfmt{glossaries-extra} v1.21+}, category={command} @@ -5946,6 +6196,24 @@ defined}, category={command} } +@index{GlsXtrBibTeXEntryAliases, + name={\csfmt{Gls\-Xtr\-Bib\-TeX\-Entry\-Aliases}}, + user1={}, + description={expands to the set of common entry aliases for +\atentry{bibtexentry}}, + note={provided by \styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + +@index{GlsXtrProvideBibTeXFields, + name={\csfmt{Gls\-Xtr\-Provide\-Bib\-TeX\-Fields}}, + user1={}, + description={defines the standard \BibTeX\ fields using + \cs{glsaddstoragekey}}, + note={provided by \styfmt{glossaries-extra-bib2gls} v1.29+}, + category={command} +} + @index{glsxtrprovidecommand, name={\csfmt{glsxtrprovidecommand}}, user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, @@ -6679,6 +6947,55 @@ has three or more items}, category={command} } +@index{RequirePackage, + name={\csfmt{Require\-Pack\-age}}, + user1={\oargm{options}\margm{name}\oargm{min version}}, + description={loads the package identified by \meta{name} from + within another package}, + note={kernel command}, + category={command} +} + +@index{ProvidesPackage, + name={\csfmt{Provides\-Pack\-age}}, + user1={\margm{name}\oargm{version}}, + description={identifies a package}, + note={kernel command}, + category={command} +} + +@index{DeclareOption, + name={\csfmt{Declare\-Opt\-ions}}, + user1={\margm{name}\margm{code}}, + description={declares an option with the given \meta{name}}, + note={kernel command}, + category={command} +} + +@index{DeclareOption*, + name={\csfmt{Declare\-Opt\-ions*}}, + user1={\margm{code}}, + description={indicates what to do with unknown options}, + note={kernel command}, + category={command} +} + +@index{ProcessOptions, + name={\csfmt{Process\-Opt\-ions}}, + description={processes supplied options}, + note={kernel command}, + category={command} +} + +@index{PackageError, + name={\csfmt{Pack\-age\-Err\-or}}, + user1={\margm{name}\margm{code}\margm{help}}, + description={generates an error message for the package identified +by \meta{name}}, + note={kernel command}, + category={command} +} + @index{cjkname, name={\csfmt{cjkname}}, user1={\margm{CJK characters}}, @@ -6688,3 +7005,82 @@ has three or more items}, category={command} } +@index{citation, + name={\csfmt{citation}}, + user1={\margm{label}}, + description={written to the \ext{aux} file on each occurrence of + \gls[noindex]{cite}}, + note={kernel command}, + category={command} +} + +@index{cite, + name={\csfmt{cite}}, + user1={\margm{label}}, + description={cross-reference a bibliographic citation}, + note={kernel command}, + category={command} +} + +@index{bibliography, + name={\csfmt{bibliography}}, + user1={\margm{file list}}, + description={display bibliography created by \BibTeX}, + note={kernel command}, + category={command} +} + +@index{refstepcounter, + name={\csfmt{refstepcounter}}, + user1={\margm{counter name}}, + description={increments the given counter in a manner compatible + with the \cs{label} cross-referencing mechanism}, + note={kernel command}, + category={command} +} + +@index{label, + name={\csfmt{label}}, + user1={\margm{id}}, + description={creates a label that can be referenced with \ics{ref} +or \ics{pageref}}, + note={kernel command}, + category={command} +} + +@index{pageref, + name={\csfmt{pageref}}, + user1={\margm{id}}, + description={cross-reference the page where \cs{label}\margm{id} +occurred}, + note={kernel command}, + category={command} +} + +@index{ref, + name={\csfmt{ref}}, + user1={\margm{id}}, + description={cross-reference the location where \cs{label}\margm{id} +occurred}, + note={kernel command}, + category={command} +} + +@index{hyperlink, + name={\csfmt{hyperlink}}, + user1={\margm{target name}\margm{text}}, + description={create a hyperlink to \meta{target name} with the given +\meta{text}}, + note={provided by \styfmt{hyperref}}, + category={command} +} + +@index{hypertarget, + name={\csfmt{hypertarget}}, + user1={\margm{target name}\margm{text}}, + description={create a hypertarget with the given \meta{target +name} and the displayed \meta{text}}, + note={provided by \styfmt{hyperref}}, + category={command} +} + diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod index ae1485f9916..b45b4ca5e91 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod @@ -84,6 +84,23 @@ Interpret tilde character as a normal space. Interpret tilde as a non-breaking space (default). +=item B<--cite-as-record> + +Treat B<\citation> as an ignored record. + +=item B<--no-cite-as-record> + +Don't check for instances of B<\citation> in the B<.aux> file (default). + +=item B<--merge-wrglossary-records> + +Merge an entry's B<wrglossary> records for the same page locations. +(For use with the B<indexcounter> package option.) + +=item B<--no-merge-wrglossary-records> + +Don't merge an entry's B<wrglossary> records. + =item B<--force-cross-resource-refs> or B<-x> Force cross-resource referencing mode on. @@ -114,14 +131,29 @@ limited number of packages supported by the TeX parser library. This option has a cumulative action so B<--packages wasysym,pifont> is the same as B<--packages wasysym --packages pifont>. +You can find out the list of supported packages with +B<--list-known-packages>. + +=item B<--custom-packages> I<list> + +Instruct the TeX parser library to attempt to parse the +packages listed in I<list>. This is intended for simple custom +packages that don't contain complex code. + =item B<--ignore-packages> I<list> (or B<-k> I<list>) Don't parse the log file for the packages listed in I<list>. Note that B<--packages> overrides this option, so if the same package is listed in both B<--ignore-packages> and B<--packages> then the interpreter will check if it's supported. This option has a -cumulative action. (The B<glossaries-extra> package can't be -included in the ignored I<list>.) +cumulative action. Only known packages may be included in +I<list>. + +=item B<--list-known-packages> + +Lists all the packages that have are known to the TeX parser +library and then exits (with exit code 0). Any of the listed +packages may be used in B<--packages> or B<--ignore-packages>. =item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>) diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index a66a4125ae1..4f3dc88f5cf 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -347,6 +347,9 @@ \newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}} +\newcommand*{\postdeschook}[2][]{% + \glslink[#1]{idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#2}}} + \newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}% {% \let\csfmt\code @@ -521,6 +524,9 @@ {#2}% } +\newcommand*{\atentrypageref}[1]{% + \atentry{#1} (page~\glsxtrpageref{entry.#1})}% + \newcommand{\argsection}[2][\section]{% \def\switcharg{}% \def\switchalt{}% @@ -562,6 +568,9 @@ {\string-\string-#1}% } +\newcommand*{\longargpageref}[1]{% + \longarg{#1} (page~\glsxtrpageref{switch.#1})}% + \newcommand*{\longargorshort}[1]{% \texorpdfstring {\gls{switch.#1}\ifglshassymbol{switch.#1}{ or \glssymbol{switch.#1}}{}}% @@ -642,11 +651,11 @@ \newcommand*{\card}[1]{|\set{#1}|} \newcommand*{\imaginary}{i} -\newcommand{\addr}[1]{\\\url{#1}} +\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}} \title{\bibgls: a command line Java application to convert \filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource files} -\author{Nicola Talbot\addr{http://www.dickimaw-books.com/}} +\author{Nicola Talbot\addr{dickimaw-books.com}} \date{\DTMusedate{moddate}} \makeatletter @@ -684,7 +693,7 @@ files} \begin{abstract} The \bibgls\ command line application can be used to extract glossary information stored in a \ext{bib} file and convert it -into glossary entry definition commands that can be read using +into glossary entry definitions that can be read using \styfmt{glossaries-extra}'s \ics{GlsXtrLoadResources} command. When used in combination with the \styoptfmt{record} package option, \bibgls\ can select only those entries that have been used in the document, @@ -703,7 +712,7 @@ first \LaTeX\ run due to the unknown references being replaced with ?? which can be significantly shorter than the actual text produced when the reference is known. -Note that \bibgls\ is a Java application, and requires Java~7 +Note that \bibgls\ is a Java application, and requires at least Java~7 (although the latest version is recommended). Additionally, \sty{glossaries-extra} must be at least version 1.12. (Although again the latest version is recommended.) @@ -1461,21 +1470,8 @@ environments provided within the document. number of packages that the parser recognises. Note that in some cases there's only very limited support. For example, \isty{siunitx}'s \ics{si} command is recognised but other -commands aren't from that package aren't. \bibgls\ checks for the -following packages: -\isty{amsmath}, \isty{amssymb}, \isty{pifont}, \isty{textcase}, -\isty{wasysym}, \isty{lipsum}, \isty{natbib}, \isty{mhchem}, -\isty{bpchem}, \isty{stix}, \isty{textcomp}, \isty{MnSymbol}, -\isty{fourier}, \isty{upgreek}, \isty{xspace}, \isty{siunitx}, -\isty{fontenc} and \isty{tipa}. (You can omit checking for specific -packages with \longarg{ignore-packages}.) If you're wondering about the -selection, the \file{texparserlib.jar} library was originally written for -another application that required support for some of them. There -are a few other packages that the library supports (see -\url{https://github.com/nlct/texparser/tree/master/src/java/lib/latex}), but \bibgls\ -doesn't check for them as they're unlikely to be needed within -field values. (You can explicitly request them with -\longarg{packages} if required.) +commands aren't from that package aren't. See +\longargpageref{list-known-packages} for further details. Since the parser doesn't have a full set of commands available within the \LaTeX\ document, when it encounters \ics{renewcommand} it @@ -1932,6 +1928,37 @@ space (default). The interpreter treats a tilde character \idx{nbspchar} as a normal space. +\argsection{cite-as-record} + +Treat instances of \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{page}\marg{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{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 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 location list, +but they will link to different parts of the page. + \argsection{force-cross-resource-refs} Force \idx{crossresourceref} mode on (see @@ -1988,9 +2015,47 @@ this setting. For example, if \csfmt{superiortwo} is defined as then it will be interpreted as \hex{00B2} (superscript two) even if this setting is on. +\argsection{list-known-packages} + +This option will list all the packages supported by the \TeX\ parser +library and will then exit \bibgls. The results are divided into two +sections: those packages that are searched for in the \iext{log} +file and those packages that aren't searched for in the \iext{log} +file but have some support available. Some of the support is very +limited. Package options aren't detected. +The transcript file is always searched for \isty{glossaries-extra} +to ensure that the version is new enough to support \bibgls. + +Packages that fall into the first category are: +\isty{amsmath}, \isty{amssymb}, \isty{bpchem}, \isty{fontenc}, +\isty{fontspec}, \isty{fourier}, +\isty{hyperref}, \isty{lipsum}, \isty{MnSymbol}, \isty{mhchem}, \isty{natbib}, +\isty{pifont}, \isty{siunitx} (limited), \isty{stix}, +\isty{textcase}, \isty{textcomp}, \isty{tipa}, \isty{upgreek} and +\isty{wasysym}. (You can omit checking for specific packages with +\longarg{ignore-packages}.) These are packages that provide commands +that might be needed within entry fields. The check for +\isty{fontspec} is to simply determine whether or not UTF-8 +characters are allowed in labels (for \csopt{labelify} and +\csopt{labelify-list}). + +Packages that fall into the second category are: +\isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited), +\isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics}, +\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils}, \isty{probsoln}, \isty{shortvrb}, +and \isty{xspace}. These are less likely to be needed within fields +and so aren't checked for by default. If they are needed then you +can instruct \bibgls\ to support them with \longarg{packages}. + +(If you're wondering about the selection, the \file{texparserlib.jar} +library was originally written for another application that required +support for some of them.) + + + \argsection{packages} -Instruct the interpreter to pretend the packages listed +Instruct the interpreter to assume the packages listed in \meta{list} have been used by the document. This option has a cumulative action so \code{\longarg{packages} "wasysym,pifont"} is the same as \code{\longarg{packages} wasysym @@ -2000,7 +2065,21 @@ Note that there's only a limited number of packages supported by the \TeX\ parser library. This option is provided for cases where you're using a command from a package that the interpreter doesn't support but it happens to have the same name and meaning as a command from -a package that the interpreter does support. +a package that the interpreter does support. You can also use it to +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} @@ -2011,7 +2090,7 @@ listed in \meta{list}. Note that this option simply instructs 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 -\sty{glossaries-extra} can't be included in the ignored \meta{list}. +unknown packages can't be included in the ignored \meta{list}. \argsection{mfirstuc-protection} @@ -2501,7 +2580,7 @@ then \ics{rgls} writes a record to the \iext{aux} file with the \glsopt{format} set to \encap{glstriggerrecordformat}. This ensures that the record count is correct on the next run, but the record isn't added to the location list as -\bibgls\ recognises it as a special ignored location. +\bibgls\ recognises it as a special \idx{ignoredrecord}. Note that the entry will still appear in the usual glossary unless you assign it to a different one with \csopt{trigger-type}. @@ -2666,7 +2745,7 @@ by using commands like \ics{gls} or \ics{glsxtrp} in any of the recognised fields. These will automatically be selected if the \csopt{selection} setting includes dependencies, but you may need to rebuild the document to ensure the location lists are correct. Use -of the \ics{glssee} command will create an ignored location and the +of the \ics{glssee} command will create an \idx{ignoredrecord} and the \field{see} field will be set to the relevant information. If an entry has the \field{see} field already set, any instance of \ics{glssee} in the document for that entry will be appended to the @@ -3245,6 +3324,57 @@ The \atentry{acronym} entry type is like \atentry{abbreviation} except that the term is written to the output file using the command \csref{bibglsnewacronym}. +\entrysection{contributor} + +The \atentry{contributor} entry type is primarily provided for use +by the \atentry{bibtexentry} type. You may use it explicitly +if you want, but you need to take care that it doesn't clash with +\atentry{bibtexentry}. It behaves much like \atentry{index} except that the +term is written to the output file using the command +\csref{bibglsnewcontributor}. There are no required fields. As with +\atentry{index}, if the \field{name} field is missing, the fallback +value is the entry's label. When this entry type is automatically +created by \atentry{bibtexentry}, the \field{name} is set to +\begin{codeenv} +\ics{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix} +\end{codeenv} + +If you do explicitly use \atentry{contributor} you need to make sure it's +defined \emph{before} the first instance of \atentry{bibtexentry} that +tries to access it, but within the same resource set. If you ensure that +the label of \atentry{contributor} matches the contributor label generated by +\atentry{bibtexentry} then they can have their dependency lists +updated, and +the \field{bibtexentry} and \field{bibtexentry@entrytype} internal +fields can be set for the +\atentry{contributor} entry. For example: +\begin{verbatim} +@contributor{KnuthDonaldE, + name={\bibglscontributor{Donald E.}{}{Knuth}{}}, + description={Famous mathematician and computer scientist who + created \TeX} +} + +@book{texbook, + title = {The {\TeX book}}, + author = {Donald E. Knuth}, + publisher = {Addison-Wesley}, + year = 1986 +} +\end{verbatim} +The resource options then need to include: +\begin{codeenv} + \csopt[ + \ics{GlsXtrBibTeXEntryAliases} + ]{entry-type-aliases}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace} +\end{codeenv} + +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} \label{sec:dualentry} @@ -4426,6 +4556,214 @@ always defined immediately after the corresponding secondary entry. 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} +\label{sec:multientry} + +A multi-entry type is a primary entry that may spawn multiple +primary entries. This means that both the main entry and the +spawned entries are sorted together along with all the other primary +entries. + +\entrysection{bibtexentry} + +The \atentry{bibtexentry} type will typically need to be aliased +as it's designed for converting \BibTeX\ entries into \bibgls\ +entries. For example, to make \bibgls\ treat \atentryfmt{article} +and \atentryfmt{book} as though they were both +\atentry{bibtexentry}: +\begin{codeenv} +\csopt[ + article=bibtexentry, + book=bibtexentry +]{entry-type-aliases} +\end{codeenv} +For convenience, \isty{glossaries-extra-bib2gls} v1.29+ +provides \ics{GlsXtrBibTeXEntryAliases} which covers all the +standard \BibTeX\ entry types. If you use +\csopt[same as original entry]{category}, the \field{category} +field will be set to the original entry type (for example, +\code{article} or \code{book}). Similarly you can use +\csopt[same as original entry]{type} to set the \field{type} +field (but remember that the glossary types will need to be defined +in the document). + +There are no required fields. The fallback for the \field{sort} +field is given by \csopt{bibtexentry-sort-fallback}. If you want to +access any of the \BibTeX\ fields, you will need to alias or define +them. For example: +\begin{codeenv} +\csopt[ + title=name +]{field-aliases} +\end{codeenv} +Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's +\field{type} field, when \bibgls\ parses \atentry{bibtexentry} +if will convert \fieldfmt{type} to \field{bibtextype}, so you +must use \field{bibtextype} as the identifier when aliasing. + +Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which +uses \ics{glsaddstoragekey} to provided all the standard \BibTeX\ +fields. (Remember that new fields must be defined before the first +\idx{resourceset}.) + +The \atentry{bibtexentry} essentially creates an \atentry{index} +form of entry, but it additionally defines a \atentry{contributor} +entry for each listed author or editor +and updates the dependency lists: each \atentry{contributor} is +added to the main +\atentry{bibtexentry}'s list of dependencies (so if the +\atentry{bibtexentry} has a record then all its satellite +\atentry{contributor}s are selected with the default +\csopt[recorded and deps]{selection}), and +each \atentry{contributor} is treated as having a cross-reference to +the main \atentry{bibtexentry} (so if a \atentry{contributor} +has a record then all the linked \atentry{bibtexentry} terms will +be selected if \csopt[recorded and deps and see]{selection}). +You can instruct \bibgls\ to treat \ics{citation} as an +\idx{ignoredrecord} using \longarg{cite-as-record}. + +Each contributor is effectively defined as +\begin{codeenv} +\atentry{contributor}\marg{\meta{label}, + name=\marg{\ics{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}} +} +\end{codeenv} +The label is obtained by converting the \field{name} +to a label, using the same function as \csopt{labelify} (which +means it's governed by \csopt{labelify-replace}). + +The \fieldfmt{author} and \fieldfmt{editor} fields are always +checked, even if those fields aren't recognised by \bibgls, (which +they aren't by default). These checks are performed before field +aliases are applied. If neither field is present, no additional +entries are spawned. If the dependent \atentry{contributor} entry +has already been defined, it won't be redefined, but will have the +new \atentry{bibtexentry} added to its internal \field{bibtexentry} +field. + +The main \atentry{bibtexentry} is defined using +\ics{bibglsnewbibtexentry} and is followed by +\begin{codeenv} +\ics{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} +\end{codeenv} +where \meta{id} is the label identifying the main +\atentry{bibtexentry} and \meta{contributor-id} is the +label identifier the contributor, for each contributor that has +been selected. + +Each contributor is defined using \ics{bibglsnewcontributor}. The definition +is followed by +\begin{codeenv} +\ics{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id} +\ics{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id} +\end{codeenv} +for each selected \atentry{bibtexentry} associated with that contributor. The +second line provides the internal list field +\field{bibtexentry@entrytype}, where \meta{entry-type} is the +original entry type (before it was aliased to +\atentry{bibtexentry} and converted to lower case). +For example \code{article} or \code{book}. + +You can iterate over these internal list fields using +\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}. +For example: +\begin{codeenv} +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}} + +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\% + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\% + \marg{\% + \cs{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\% + \marg{\csfmt{contributorhandler}}\% + }% + \marg{\csfmt{par} No titles.}\% +} +\end{codeenv} +(where the resource option \csopt[title=name]{field-aliases} +has been used). + + +Here's an example that uses the test \file{xampl.bib} file that's +provided with \TeX\ distributions: +\begin{codeenv} +\csfmt{documentclass}\marg{article} + +\cs{usepackage}[record,nomain]\marg{glossaries-extra} + +\cs{newglossary*}\marg{contributors}\marg{Authors/Editors} +\cs{newglossary*}\marg{titles}\marg{Titles} + +\cs{newcommand}\marg{\ics{bibglsnewbibtexentry}}[4]\marg{\% + \cs{longnewglossaryentry}*\marg{\#1}\marg{name={\#3},\#2,type=\marg{titles}}\marg{\#4}\% +} + +\cs{GlsXtrLoadResources}[ + \csopt[xampl]{src}, + \csopt[false]{write-preamble}, + \csopt[ + \ics{GlsXtrBibTeXEntryAliases} + ]{entry-type-aliases}, + \csopt[ + title=name + ]{field-aliases}, + \csopt[ + note=name + ]{replicate-fields}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace}, + \csopt[contributors]{type}, + \csopt[same as original entry]{category}, + \csopt[category]{sort-field}, + \csopt[name]{sort-suffix} +] + +\ics{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\cs{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets} +\cs{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\cs{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters} +\cs{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous} + +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\#1} (\#1)} + +\cs{newcommand}\marg{\postdeschook{contributor}}{\% + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\% + \marg{\% + \ics{glsxtrfieldforlistloop} + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\% + \marg{\csfmt{contributorhandler}}\% + }\% + \marg{\csfmt{par} No titles.}\% +} + +\csfmt{begin}\marg{document} +Sample\idx!{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}. +Another sample\idx!{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}. + +\csfmt{bibliographystyle}\marg{plain} +\ics{bibliography}\marg{xampl} + +\cs{printunsrtglossary}[type=contributors,style=altlist] +\cs{printunsrtglossary*}[type=titles,style=indexgroup] +\marg{\% + \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}{category}\% + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\csfmt{emph}\marg{\#1}}\% + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\csfmt{textbf}\marg{\#1}}\% +} + +\csfmt{end}\marg{document} +\end{codeenv} +If the file is called \filefmt{myDoc.tex} then the document build +is: +\begin{codeenv} +pdflatex myDoc +bib2gls \longarg{cite-as-record} myDoc +bibtex myDoc +pdflatex myDoc +pdflatex myDoc +\end{codeenv} + \chapter{Resource File Options} \label{sec:resourceopts} @@ -5825,6 +6163,202 @@ supplementary resource files (omitting the primary \section{Field and Label Options} \label{sec:labelopts} +The options in this section may be used to set or adjust field +values or labels. Some field values are expected to be labels (such +as \field{group}). These labels must not contain special +characters or commands, but it's possible to convert a field value +into a valid label using options such as \csopt{labelify}. + +\optsection{group} + +The \csopt{group} option may only be used with the \longarg{group} switch. +This will set the \field{group} field to \meta{label} unless +\meta{label} is \optfmt{auto}, in which case the value is +set automatically during the sorting (see also +\csopt{group-formation}). +The corresponding title can be set +with \gls{glsxtrsetgrouptitle} if the title is different from the +label. The default behaviour is \csopt[auto]{group}. + +For example: +\begin{verbatim} +\GlsXtrLoadResources[sort=integer,group={Constants}, + src={entries-constants}% data in entries-constants.bib +] +\GlsXtrLoadResources[sort=letter-case,group={Variables}, + src={entries-variables}% data in entries-variables.bib +] +\end{verbatim} +In this case, if the \field{type} field hasn't been set in the \ext{bib} files, +these entries will be added to the same glossary, but will +be grouped according to each instance of \gls{GlsXtrLoadResources}, +with the provided group label. + + +\optsection{category} + +The selected entries may all have their \field{category} field +changed before writing their definitions to the \ext{glstex} file. +The \meta{value} may be: +\begin{itemize} +\item \optfmt{same as entry}: set the +\field{category} to the \ext{bib} entry type used to define it +(lower case and without the initial \code{@}) after any aliasing, +if applicable; + +\item \optfmt{same as original entry}: (new to v1.4) set the \field{category} +to the original entry type (lower case 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}: (new to v1.1) set the \field{category} +to the base name of the \ext{bib} file (without the extension) +that provided the entry definition; + +\item \optfmt{same as type}: set the \field{category} to the same +value as the \field{type} field (if that field has been provided +either in the \ext{bib} file or through the \csopt{type} option); + +\item \meta{label}: the \field{category} is set to +\meta{label} (which mustn't contain any special characters). +\end{itemize} +This will override any +\field{category} fields supplied in the \ext{bib} file. + +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{category} refers to the \emph{target} entry type whereas +\csopt[same as original entry]{category} refers to the +\emph{original} entry type given in the \ext{bib} file. In both +cases, the value is converted to lower case to ensure consistency. + +For example, if the \ext{bib} file contains: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@index{duck} + +@index{goose,plural="geese"} + +@dualentry{dog, + name={dog}, + description={chien} +} +\end{verbatim} +then if the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={same as entry},src={entries}] +\end{verbatim} +this will set the \field{category} of the \code{bird} term to +\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and +\code{goose} terms to \optfmt{index} (since they were defined +with \atentry{index}), and the \field{category} of the \code{dog} +term to \optfmt{dualentry} (since it was +defined with \atentry{dualentry}). Note that the dual entry +\code{dual.dog} doesn't have the category set, since that's +governed by \csopt{dual-category} instead. + +If, instead, the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then the \field{category} of all the primary selected entries will +be set to \optfmt{animals}. Again the dual entry \code{dual.dog} +doesn't have the \field{category} set. + +Note that the categories may be overridden by the commands, +such as \csref{bibglsnewindex}, that are used to actually define the +entries. + +For example, if the document contains +\begin{verbatim} +\newcommand{\bibglsnewdualentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% +} + +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then both the \code{dog} and \code{dual.dog} entries will +have their \field{category} field set to \optfmt{dual} since the +new definition of \gls{bibglsnewdualentry} has overridden +the \csopt[animals]{category} option. + +\optsection{type} + +The \meta{value} may be one of: +\begin{itemize} + \item \optfmt{same as entry} set the \field{type} field + to the entry type (lower case and without the initial \code{@}); + + \item \optfmt{same as original entry} set the \field{type} + to the original entry type (lower case and without + the initial \code{@}) before it was aliased (behaves like + \optfmt{same as entry} if the entry type wasn't aliased); + + \optfmt{same as base} set the \field{type} field + to the base name of the corresponding \ext{bib} file + (without the extension); + + \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 the glossary + identified by \meta{label}. +\end{itemize} +When used with \csopt{entry-type-aliases}, the option \csopt[same as +entry]{type} refers to the \emph{target} entry type and \csopt[same +as original entry]{type} refers to the \emph{original} entry type +given in the \ext{bib} file. It's not possible to have both +\csopt[same as type]{category} and \csopt[same as category]{type}. + +Note that this setting only changes the \field{type} field for +primary entries. Use \csopt{dual-type} for dual entries. + +For example: +\begin{verbatim} +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-symbols},type=symbols] +\end{verbatim} + +Make sure that the glossary type has already been defined +(see \sectionref{sec:newglossary}). In the above, the +\styopt{symbols} option defines the \code{symbols} glossary. +If you want to use a custom glossary, you need to provide it. For +example: +\begin{verbatim} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{dictionary}{Dictionary} + +\GlsXtrLoadResources[src={entries-symbols},type=dictionary] +\end{verbatim} +(The \styopt{nomain} option was added to suppress the +creation of the default \code{main} glossary.) + +\optsection{trigger-type} + +The record counting commands, such as \ics{rgls}, use the special +format \ics{glstriggerrecordformat}, which \bibgls\ also treats +as an \idx{ignoredrecord}. This means the entry will still be +identified as having a record for selection purposes, which is +necessary for the entry to be defined for use in the document, but +in order to prevent it from appearing in the glossary you need to +transfer the entry with \csopt[\meta{type}]{trigger-type}. +This will override the \csopt{type}, \csopt{dual-type}, +\csopt{tertiary-type} and the type specification in +\csopt{secondary}. + +The provided value \meta{type} must be a glossary label (not one of +the keywords allowed by \csopt{type}). +You can define the glossary before loading the resource, but +it's not required as \bibgls\ will write +\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file +(see \sectionref{sec:newglossary}). + \optsection{interpret-label-fields} This is a boolean option that determines whether or not the fields @@ -5832,10 +6366,12 @@ that may only contain labels should have their values interpreted (\field{parent}, \field{category}, \field{type}, \field{group}, \field{seealso} and \field{alias}). Although this option interprets commands within those fields, it doesn't strip any characters that -can't be used within a label. +can't be used within a label. The \field{see} field isn't included +as it may optionally start with \code{[\meta{tag}]} where \meta{tag} +may legitimately contain \LaTeX\ code that shouldn't be interpreted. The default setting is \csopt[false]{interpret-label-fields}. -Note that if this setting is on, cross-resource references aren't +Note that if this setting is on, \idxpl{crossresourceref} aren't permitted. This setting has no effect if the interpreter has been disabled. @@ -5850,7 +6386,7 @@ are performed before \csopt{interpret-label-fields}. This option should take a comma-separated list of recognised field names as the value. (If a field is present in both \csopt{labelify} and \csopt{labelify-list}, then \csopt{labelify-list} takes precedence.) -Note that if this setting is on, cross-resource references aren't +Note that if this setting is on, \idxpl{crossresourceref} aren't permitted. Each listed field will be converted into a string suitable @@ -5860,26 +6396,28 @@ name.) The conversion is performed in the following order: \begin{enumerate} -\item If the interpreter is on and the value contains -any of the characters \idx{escchar} (backslash), \idx{bgroupchar} -(begin group), \idx{egroupchar} (end group), \idx{nbspchar} -(non-breakable space) or \idx{mshiftchar} (maths shift), then the value is -be interpreted. +\item If the interpreter is on and the field value contains +any of the characters \idx{escchar}~(backslash), +\idx{bgroupchar}~(begin group), \idx{egroupchar}~(end group), +\idx{nbspchar}~(non-breakable space) or \idx{mshiftchar}~(maths shift), +then the value is interpreted. \item Any substitutions that have been specified with \csopt{labelify-replace} are performed. \item All characters that aren't alphanumeric or the space character - or the punctuation -characters \code{.} (full stop), \code{-} (hyphen), \code{+} (plus), -\code{:} (colon), \code{;} (semi-colon), \code{\string|} (pipe), -\code{/} (forward slash), \code{!} (exclamation mark), \code{?} -(question mark), \code{*} (asterisk), \code{<} (less than), \code{>} -(greater than), \code{\textasciigrave} (backtick), \code{'} -(apostrophe) or \code{@} (at-sign) are stripped. If you want to + or any of the following punctuation +characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus), +\code{:}~(colon), \code{;}~(semi-colon), \code{\string|}~(pipe), +\code{/}~(forward slash), \code{!}~(exclamation mark), +\code{?}~(question mark), \code{*}~(asterisk), \code{<}~(less than), +\code{>}~(greater than), \code{\textasciigrave}~(backtick), +\code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to retain commas, use \csopt{labelify-list} instead. If you want to strip any of the allowed punctuation, use \csopt{labelify-replace} to -remove the unwanted characters. +remove the unwanted characters. (Remember that \sty{babel} can make +some of these punctuation characters active, in which case they need +to be stripped.) \item If \bibgls\ hasn't detected \sty{fontspec} in the document's transcript file, the value is then decomposed and all non-ASCII @@ -6037,7 +6575,99 @@ typing mistake in the \field{parent} field. If you actually want missing parents to be stripped before sorting (but after the selection process) then use \csopt[true]{strip-missing-parents}. If you want all parents stripped then use \csopt{flatten} or -\csopt[parent]{ignore-fields} instead. +\csopt[parent]{ignore-fields} instead. As from version 1.4, if you +want \bibgls\ to create the missing parents, then you can use +\csopt[create]{missing-parents}. + +\optsection{missing-parents} + +As an alternative to \csopt{strip-missing-parents}, as from version +1.4 you can now use \csopt[\meta{value}]{missing-parents} where +\meta{value} may be one of: +\begin{itemize} +\item \optfmt{strip}: this is equivalent to +\csopt[true]{strip-missing-parents}; + +\item \optfmt{warn}: this is equivalent to the default +\csopt[false]{strip-missing-parents}; + +\item \optfmt{create}: this will create a new \atentry{index} +entry with the missing parent's label (after it's been processed by +options such as \csopt{labelify}) with the \field{name} obtained +from the \emph{original} value of the \field{parent} field (before being +processed by options like \csopt{labelify}). +If the child entry has the \field{type} field set, then the new +parent entry will be given the same value. The \field{category} for +the new parent entry can be assigned with +\csopt{missing-parent-category}. +\end{itemize} + +For example, consider the \exfile{books.bib} file which contains +entries like +\begin{verbatim} +@entry{ubik, + name={Ubik}, + description={novel by Philip K. Dick}, + identifier={book}, + author={\sortmediacreator{Philip K.}{Dick}}, + year={1969} +} +\end{verbatim} +then the field alias +\begin{codeenv} +\csopt[author=parent]{field-aliases} +\end{codeenv} +will treat +\begin{verbatim} + author={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +as though it had been defined as +\begin{verbatim} + parent={\sortmediacreator{Philip K.}{Dick}}, +\end{verbatim} +This can be converted into a label with the options: +\begin{codeenv} + \csopt[parent]{labelify}, + \csopt[ + \marg{[ \cs{cs.string}\csfmt{.}]}\marg{} + ]{labelify-replace} +\end{codeenv} +If the interpreter has been provided with the definition: +\begin{verbatim} +\providecommand*{\sortmediacreator}[2]{#2 #1} +\end{verbatim} +then the \field{parent} field for the \code{ubik} entry +will become \code{DickPhilipK} but the original value is stored +internally when \csopt[create]{missing-parents} is set so that it +can be used as the \field{name} if the parent needs to be created. +Once all the entries have been processed, if \code{ubik} has been +selected but no entry can be found with the label \code{DickPhilipK} +then a new entry will be added as though it had been defined with: +\begin{verbatim} +@index{DickPhilipK, + name={\sortmediacreator{Philip K.}{Dick}} +} +\end{verbatim} +This is an alternative approach to the \exfile{sample-authors.tex} +document from the \hyperref[sec:examples]{examples chapter}. + +\optsection{missing-parent-category} + +If a missing parent entry is created through the use of +\csopt[create]{missing-parents} then the \field{category} field can +be assigned to the new parent entry with this option. The +\meta{value} may be one of: +\begin{itemize} + \item \code{same as child}: the parent entry's \field{category} + field is set to the same value as the child's (if set); + \item \code{same as base}: the parent entry's \field{category} is + set to the base name of the \ext{bib} file that provided the + child entry's definition; + \item \code{no value}: don't set the \field{category} field; + \item \meta{label}: the parent entry's \field{category} field is set to + \meta{label} (which shouldn't contain any special characters). +\end{itemize} +The default setting is \csopt[no value]{missing-parent-category}. \optsection{abbreviation-name-fallback} @@ -6408,153 +7038,6 @@ The value is the locale used when parsing fields identified by \csopt{time-fields}. The \meta{value} is as for \csopt{date-sort-locale}. -\optsection{category} - -The selected entries may all have their \field{category} field -changed before writing their definitions to the \ext{glstex} file. -The \meta{value} may be: -\begin{itemize} -\item \optfmt{same as entry}: set the -\field{category} to the \ext{bib} entry type used to define it -(without the leading \code{@}); - -\item \optfmt{same as base}: set the \field{category} -to the base name of the \ext{bib} file (without the extension) -that provided the entry definition (new to v1.1); - -\item \optfmt{same as type}: set the \field{category} to the same -value as the \field{type} field (if that field has been provided -either in the \ext{bib} file or through the \csopt{type} option); - -\item \meta{label}: the \field{category} is set to -\meta{label} (which mustn't contain any special characters). -\end{itemize} -This will override any -\field{category} fields supplied in the \ext{bib} file. - -Note that if you've used \csopt{entry-type-aliases}, \optfmt{same as -entry} refers to the target entry type not the original entry type -provided in the \ext{bib} file. - -For example, if the \ext{bib} file contains: -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal} -} - -@index{duck} - -@index{goose,plural="geese"} - -@dualentry{dog, - name={dog}, - description={chien} -} -\end{verbatim} -then if the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={same as entry},src={entries}] -\end{verbatim} -this will set the \field{category} of the \code{bird} field to -\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and -\code{goose} entries to \optfmt{index} (since they were defined -with \atentry{index}), and the \field{category} of the \code{dog} -entry to \optfmt{dualentry} (since it was -defined with \atentry{dualentry}). Note that the dual entry -\code{dual.dog} doesn't have the category set, since that's -governed by \csopt{dual-category} instead. - -If, instead, the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -then the \field{category} of all the primary selected entries will -be set to \optfmt{animals}. Again the dual entry \code{dual.dog} -doesn't have the \field{category} set. - -Note that the categories may be overridden by the commands, -such as \csref{bibglsnewindex}, that are used to actually define the -entries. - -For example, if the document contains -\begin{verbatim} -\newcommand{\bibglsnewdualentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% -} - -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} -then both the \code{dog} and \code{dual.dog} entries will -have their \field{category} field set to \optfmt{dual} since the -new definition of \gls{bibglsnewdualentry} has overridden -the \csopt[animals]{category} option. - -\optsection{type} - -The \meta{value} may be one of: -\begin{itemize} - \item \optfmt{same as entry} set the \field{type} field - to the entry type (without the initial \code{@}); - \optfmt{same as base} set the \field{type} field - to the base name of the corresponding \ext{bib} file - (without the extension); - \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 the glossary - identified by \meta{label}. -\end{itemize} -If you've used \csopt{entry-type-aliases}, \optfmt{same as -entry} refers to the target entry type not the original entry type -provided in the \ext{bib} file. - - -Note that this setting only changes the \field{type} field for -primary entries. Use \csopt{dual-type} for dual entries. - -For example: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-symbols},type=symbols] -\end{verbatim} - -Make sure that the glossary type has already been defined -(see \sectionref{sec:newglossary}). In the above, the -\styopt{symbols} option defines the \code{symbols} glossary. -If you want to use a custom glossary, you need to provide it. For -example: -\begin{verbatim} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{dictionary}{Dictionary} - -\GlsXtrLoadResources[src={entries-symbols},type=dictionary] -\end{verbatim} -(The \styopt{nomain} option was added to suppress the -creation of the default \code{main} glossary.) - -\optsection{trigger-type} - -The record counting commands, such as \ics{rgls}, use the special -format \ics{glstriggerrecordformat}, which \bibgls\ also treats -as an ignored location. This means the entry will still be -identified as having a record for selection purposes, which is -necessary for the entry to be defined for use in the document, but -in order to prevent it from appearing in the glossary you need to -transfer the entry with \csopt[\meta{type}]{trigger-type}. -This will override the \csopt{type}, \csopt{dual-type}, -\csopt{tertiary-type} and the type specification in -\csopt{secondary}. - -The provided value \meta{type} must be a glossary label (not one of -the keywords allowed by \csopt{type}). -You can define the glossary before loading the resource, but -it's not required as \bibgls\ will write -\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file -(see \sectionref{sec:newglossary}). - \optsection{counter} The \csopt{counter} option assigns the default counter to use @@ -7173,27 +7656,6 @@ the field is defined (so \ics{GlsXtrIfFieldUndef} does the \meta{false} argument) but it's considered unset (so commands like \ics{ifglshasfield} do the \meta{false} argument). -\optsection{group} - -This option may only be used with the \longarg{group} switch. -This will set the \field{group} field to \meta{value} unless -\meta{value} is \optfmt{auto}, in which case the value is -set automatically during the sorting (see also -\csopt{group-formation}). For example: -\begin{verbatim} -\GlsXtrLoadResources[sort=integer,group={Constants}, - src={entries-constants}% data in entries-constants.bib -] -\GlsXtrLoadResources[sort=letter-case,group={Variables}, - src={entries-variables}% data in entries-variables.bib -] -\end{verbatim} -If the \field{type} field hasn't been set in the \ext{bib} files, -these entries will be added to the same glossary, but will -be grouped according to each instance of \gls{GlsXtrLoadResources}, -with the provided group label. -The default behaviour is \csopt[auto]{group}. - \optsection{copy-action-group-field} This option may only be used when invoking \bibgls\ with the @@ -7454,7 +7916,7 @@ The \styopt{record} package option automatically adds two new keys: the option \csopt[false]{save-locations} is used). The \field{loclist} field has the syntax of an \isty{etoolbox} internal list and includes every location (except for the discarded duplicates and -ignored formats). +\idxpl{ignoredrecord}). Each item in the list is provided in the form \begin{alltt} \ics{glsseeformat}\oargm{tag}\margm{label list}\marg{} @@ -7502,6 +7964,9 @@ for example \verb|\gls[format=textbf]{sample}| then it would cause a warning and be moved before the start of the range so that the location list would then be 1, \textbf{3}, 2--4. +An \idx{ignoredrecord} identifies a term that needs to be treated as +though it has a record for selection purposes, but the record +should not be included in the location list. The special format \glsaddopt[glsignore]{format} is provided by the \styfmt{glossaries} package for cases where the location should be ignored. (The command \ics{glsignore} simply ignores its @@ -7514,7 +7979,7 @@ will be selected but the record will be discarded. This means that the location list will be empty if the entry was only indexed with the special ignored format, but if the entry was also indexed with another format then the location list won't include the -ignored records. (This format is used by \ics{glsaddallunused} but +\idxpl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but remember that iterative commands like this don't work with \bibgls. Instead, just use \csopt[all]{selection} to select all entries. Those that don't have records won't have a location list.) @@ -7551,7 +8016,7 @@ this special format and is not recommended. The record counting commands, such as \ics{rgls}, use the special format \encap{glstriggerrecordformat}, which \bibgls\ also treats -as an ignored location and the same rules as for \encap{glsignore} apply. +as an \idx{ignoredrecord} and the same rules as for \encap{glsignore} apply. The locations are always listed in the order in which they were indexed, (except for the cross-reference which may be placed at the start or @@ -7607,12 +8072,14 @@ makes the following tests: range takes precedence. \item If one of the formats is \encap{glsnumberformat} (as in the -above example) or \encap{glsignore}, that format will be skipped. -So in the above example, the second record will be added to the -location list, but not the first. (A message will only be written to -the transcript if the \longarg{debug} switch is used.) The default -\encap{glsnumberformat} will take precedence over the ignored -format \encap{glsignore}. +above example) or an \idx{ignoredrecord} format such as +\encap{glsignore}, that format will be skipped. So in the above +example, the second record will be added to the location list, but +not the first. (A message will only be written to the transcript if +the \longarg{debug} switch is used.) The default +\encap{glsnumberformat} will take precedence over the +\idx{ignoredrecord} formats (\encap{glsignore} and +\encap{glstriggerrecordformat}). \item If a mapping has been set with the \longarg{map-format} switch that mapping will be checked. @@ -7983,7 +8450,7 @@ preamble providing an \ics{ifcase} condition: \end{alltt} \item \optfmt{comma}: -essentially equivalent to \csopt[\marg{,~}]{loc-prefix} but +essentially equivalent to \csopt[,~]{loc-prefix} but avoids confusion with the list format. \item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}. \item \optfmt{true}: equivalent to @@ -8135,6 +8602,163 @@ the locations are listed in the document order of use, or you can't form counter groups from \hyperref[sec:supplementalopts]{supplemental location lists}. +\optsection{save-index-counter} + +\emph{This option requires at least version 1.29 of +\isty{glossaries-extra}.} The \meta{value} may be one of: +\begin{itemize} +\item \optfmt{false}: don't create the \field{indexcounter} field +(default); +\item \optfmt{true}: create the \field{indexcounter} field with the +value set to the first \counter{wrglossary} location; +\item \meta{encap}: create the \field{indexcounter} field with the +value set to the first \counter{wrglossary} location +where the \glsopt{format} is \meta{encap}. +\end{itemize} +This setting will have no effect if the \styopt{indexcounter} package +option hasn't been used. In the case where the \meta{value} is +\meta{encap}, make sure that this format takes priority in the +location precedence rules (\longarg{map-format}). If the location +with that \meta{encap} format value is discarded then it can't be +saved. + +The \styopt{indexcounter} package option +(\sty{glossaries-extra} v1.29+) creates a new counter called +\counter{wrglossary} that's incremented every time a term is +indexed (recorded), except for cross-references such as \cs{glssee}. +The increment is performed using \ics{refstepcounter} and is +followed by \code{\ics{label}\marg{wrglossary.\meta{n}}} where +\meta{n} is the value of the \counter{wrglossary} counter. +This option is intended for use with the \sty{hyperref} package to +allow locations to link back to the particular part of the page where +the term was referenced rather than to the top of the page. + +The \styopt{indexcounter} package option also automatically +implements the option \styopt[wrglossary]{counter}, which means that +each instance of \code{\ics{gls}\margm{id}} writes the label +information to the \iext{aux} file: +\begin{alltt} +\csfmt{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}} +\end{alltt} +(where \meta{page} is the page number) followed by the record: +\begin{alltt} +\cs{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{glsnumberformat}\margm{n} +\end{alltt} +The location here is actually the value of the \counter{wrglossary} +counter not the page number, but \bibgls\ can pick up the +corresponding \meta{page} from the \csfmt{newlabel} command. It then +replaces the record's location \meta{n} with +\nosecdef{glsxtr@wrglossarylocation} +(but it only does this for records that have the \counter{wrglossary} +counter). + +The \sty{glossaries-extra} package (v1.29+) adjusts the definition +of \ics{glshypernumber} (which is internally used by +\cs{glsnumberformat}, \cs{hyperbf} etc when \sty{hyperref} has been +loaded) so that if the counter is \counter{wrglossary} then +\ics{pageref} is used instead of \ics{hyperlink}. This means that the +page number is displayed in the location list but it links back to +the place where the corresponding \cs{label} occurred. + +This method works partially with \appfmt{makeindex} and \appfmt{xindy} +but from their point of view the location is the value of the +\counter{wrglossary} counter, which interferes with their ability to +merge duplicate page numbers and form ranges. Since \bibgls\ is +designed specifically to work with \sty{glossaries-extra}, it's +aware of this special counter and will merge and collate the +locations according to the corresponding page number instead. + +With the default \longarg{merge-wrglossary-records} switch, if a +term has multiple \counter{wrglossary} records for a given page they +will be merged. The reference link will be the dominant record for +that page. + +The \csopt{save-index-counter} option allows you to save the first +of the \counter{wrglossary} locations for a given entry or the first +instance of a specific format of the \counter{wrglossary} locations +for a given entry. This location is stored in the +\field{indexcounter} internal field using: +\begin{codeenv} +\ics{GlsXtrSetField}\margm{id}\marg{indexcounter}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} +\end{codeenv} +Since \gls{glsxtr@wrglossarylocation} simply expands to its first +argument, the corresponding label can be obtained with +\begin{alltt} +wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page} +\end{alltt} +For convenience, \sty{glossaries-extra-bib2gls} provides +\nosecdef{GlsXtrIndexCounterLink} +which will do +\begin{alltt} +\csfmt{hyperref}\oarg{wrglossary.\meta{value}}\margm{text} +\end{alltt} +where \meta{value} is the value of the \field{indexcounter} field if +it has been set. If the \field{indexcounter} field hasn't been set +(or if \sty{hyperref} hasn't been loaded) then just \meta{text} is +done. + +This provides a convenient way of encapsulating the \field{name} in +the glossary so that it links back to the first \counter{wrglossary} +entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary} +entry. This encapsulation can be done by providing a new glossary +style or more simply by redefining \ics{glsnamefont}: +\begin{verbatim} +\renewcommand{\glsnamefont}[1]{% + \GlsXtrIndexCounterLink{#1}{\glscurrententrylabel}} +\end{verbatim} +Here's a complete example: +\begin{verbatim} +\documentclass{article} + +\usepackage{lipsum}% dummy filler text +\usepackage[colorlinks]{hyperref} +\usepackage[record,indexcounter]{glossaries-extra} + +\newcommand{\primary}[1]{\hyperbf{#1}} + +\GlsXtrLoadResources[ + src={entries},% terms defined in entries.bib + save-index-counter=primary +] + +\renewcommand{\glsnamefont}[1]{% + \GlsXtrIndexCounterLink{#1}{\glscurrententrylabel}} + +\begin{document} + +A \gls{sample}. \lipsum*[1] A \gls{duck}. + +An equation: +\begin{equation} +\gls[counter=equation]{pi} +\end{equation} + +\lipsum[2] + +Another \gls[format=primary]{sample}. \lipsum*[3] Another +\gls{duck}. + +\gls{pi}. \lipsum[4] + +A \gls{sample}. \lipsum*[5] A \gls{duck} and +\gls[format=primary]{pi}. + +\lipsum*[6] A \gls[format=primary]{duck}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Note that the \glsopt[equation]{counter} entry will have its own +independent location. In this example, it's difficult to tell the +difference between 1 (the equation reference) and 1 (the page +reference) in the location list for the \code{pi} entry. + +The \glsopt[primary]{format} instances indicate primary references. +They're displayed in bold (since \csfmt{primary} is defined to use +\csfmt{hyperbf}) and these are the locations saved in the +\field{indexcounter} field because that's the \meta{encap} +identified by the \csopt[primary]{save-index-counter} setting. + \section{Supplemental Locations} \label{sec:supplementalopts} @@ -9208,6 +9832,12 @@ The symbol-like entry types fallback on the field given by \csopt{symbol-sort-fallback} if the \field{sort} is missing. This is only used with \csopt[sort]{sort-field}. +Entries defined using \atentry{bibtexentry} fallback on the field +given by \csopt{bibtexentry-sort-fallback}, which defaults to the +\field{name} field. Note that this only applies to the main entry. +The spawned \atentry{contributor} entries behave like +\atentry{index}. + If no fallback field can be found, the entry's label will be used. \optsection{missing-sort-fallback} @@ -9231,6 +9861,10 @@ will fallback on the value given by \csopt{symbol-sort-fallback}. one of the abbreviation types, then \bibgls\ will fallback on the value given by \csopt{abbreviation-sort-fallback}. +\item If the entry was defined using \atentry{bibtexentry} (but not +the spawned \atentry{contributor} entries), then \bibgls\ will +fallback on the value given by +\csopt{bibtexentry-sort-fallback}. \end{itemize} If \meta{sort-field} is not \field{sort}, then there may not be a fallback, in which case the next condition applies: @@ -9272,6 +9906,16 @@ must be a known field label. Note that \csopt{missing-sort-fallback} overrides this setting. +\optsection{bibtexentry-sort-fallback} + +The main \atentry{bibtexentry} entry types will, by default, +fallback on the \field{name} if the +\field{sort} field is missing (assuming the default +\csopt[sort]{sort-field}). If you prefer to fallback on a different +field, then you can use this option to specify the field. + +Note that \csopt{missing-sort-fallback} overrides this setting. + \optsection{trim-sort} If the interpreter is used to determine the sort value, this setting @@ -9853,7 +10497,7 @@ different to using \begin{alltt} \ics{GlsXtrSetDefaultNumberFormat}\marg{glsignore} \end{alltt} -which creates an ignored record. Even though the record is ignored +which creates an \idx{ignoredrecord}. Even though the record is ignored (and so won't show in the location list) the record still influences the selection order and the record count. @@ -10659,13 +11303,19 @@ file (or created through a mapping). The \meta{value} is required. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{type} to the entry -type. For example, if the entry was defined with +type (lower case and without +the initial \code{@}). For example, if the entry was defined with \atentry{dualentry}, the \field{type} will be set to \optfmt{dualentry}. 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 (lower case 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 (new to v1.1); @@ -10711,13 +11361,19 @@ file (or created through a mapping). The \meta{value} may be empty. The \meta{value} may be: \begin{itemize} \item \optfmt{same as entry}: sets the \field{category} to the entry -type. For example, if the entry was defined with +type (lower case and without +the initial \code{@}). For example, if the entry was defined with \atentry{dualentry}, the \field{category} will be set to \optfmt{dualentry}. 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{category} field +to the original entry type (lower case 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{category} to the base name of the \ext{bib} file (without the extension) that provided the entry definition (new to v1.1); @@ -11648,6 +12304,19 @@ long form for the dual abbreviation. This will use \ics{glsuselongfont} if it's defined otherwise it will be defined to replicate that command. +\cssection{bibglsnewbibtexentry} + +\formatdef{bibglsnewbibtexentry} +This command is used to define the main term identified with +\atentry{bibtexentry}. + +\cssection{bibglsnewcontributor} + +\formatdef{bibglsnewcontributor} +This command is used to define terms identified with +\atentry{contributor} (typically implicitly created through +\atentry{bibtexentry}). + \section{Location Lists and Cross-References} \label{sec:loclistdefs} @@ -13437,7 +14106,7 @@ The contents of \filefmt{bacteria.bib} are as follows: The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries are all defined using the custom \atentryfmt{unit} entry type. This must be aliased with \csopt{entry-type-aliases} otherwise -\bibgls\ will ignored all the entries. For example +\bibgls\ will ignore all the entries. For example \begin{codeenv} \csopt[unit=symbol]{entry-type-aliases} \end{codeenv} @@ -13594,6 +14263,8 @@ There are other ways in which this data could be specified. For example, the \field{description} field could contain a brief summary (or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's syntax instead with \csopt{bibtex-contributor-fields} to convert it. +Alternatively, the entries could be defined using standard \BibTeX\ +entry types that are all aliased to \atentry{bibtexentry}. The contents of \filefmt{books.bib} are as follows: \lstinputlisting[firstline=5]{../examples/books.bib} @@ -13925,7 +14596,7 @@ This file uses a custom entry type \atentryfmt{icon}, which must be aliased to a recognised entry identifier otherwise the entries will all be ignored. For example: \begin{codeenv} -\csopt[unit=symbol]{entry-type-aliases} +\csopt[icon=symbol]{entry-type-aliases} \end{codeenv} There are three types of symbols defined: media controls, information diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip Binary files differindex 011dda8b4eb..a1c68c3145c 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip Binary files differindex 5b4b2b996cd..0852ab1d89a 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |