texlive[47413] Master/texmf-dist: bib2gls (9apr18)
commits+karl at tug.org
commits+karl at tug.org
Mon Apr 9 23:19:32 CEST 2018
Revision: 47413
http://tug.org/svn/texlive?view=revision&revision=47413
Author: karl
Date: 2018-04-09 23:19:32 +0200 (Mon, 09 Apr 2018)
Log Message:
-----------
bib2gls (9apr18)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES
trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1
trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
trunk/Master/texmf-dist/scripts/bib2gls/bib2gls.jar
trunk/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar
trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml
trunk/Master/texmf-dist/scripts/bib2gls/texparserlib.jar
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
trunk/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
trunk/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES 2018-04-09 21:19:32 UTC (rev 47413)
@@ -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)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 2018-04-09 21:19:32 UTC (rev 47413)
@@ -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 @@
.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,6 +243,14 @@
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
@@ -236,8 +257,13 @@
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
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/bib2gls.jar
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml
===================================================================
--- trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml 2018-04-09 21:19:32 UTC (rev 47413)
@@ -37,6 +37,12 @@
<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 @@
<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 @@
<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 @@
<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 @@
<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>
Modified: trunk/Master/texmf-dist/scripts/bib2gls/texparserlib.jar
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib 2018-04-09 21:19:32 UTC (rev 47413)
@@ -224,6 +224,21 @@
category={command}
}
+ at 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}
+}
+
+ at 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 @@
category={command}
}
+ at dualindexentry{glsxtr at wrglossarylocation,
+ name={\csfmt{gls\-xtr\- at 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}
+}
+
+ at 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 @@
parent={resourceoptions}
}
+ at dualindexentry{opt.missing-parents,
+ name={\csoptfmt{missing\dhyphen parents}},
+ user1={\meta{value}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+ at 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 @@
@dualindexentry{opt.group,
name={\csoptfmt{group}},
- user1={\meta{value}},
+ user1={\meta{label}},
category={resourceoption},
parent={resourceoptions}
}
@@ -1501,6 +1550,13 @@
parent={resourceoptions}
}
+ at 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 @@
parent={resourceoptions}
}
+ at 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 @@
parent={packages}
}
+ at index{booktabs,
+ name={\styfmt{booktabs}},
+ category={package},
+ parent={packages}
+}
+
+ at index{color,
+ name={\styfmt{color}},
+ category={package},
+ parent={packages}
+}
+
+ at index{graphics,
+ name={\styfmt{graphics}},
+ category={package},
+ parent={packages}
+}
+
+ at index{graphicx,
+ name={\styfmt{graphicx}},
+ category={package},
+ parent={packages}
+}
+
+ at index{ifthen,
+ name={\styfmt{ifthen}},
+ category={package},
+ parent={packages}
+}
+
+ at index{probsoln,
+ name={\styfmt{probsoln}},
+ category={package},
+ parent={packages}
+}
+
+ at index{shortvrb,
+ name={\styfmt{shortvrb}},
+ category={package},
+ parent={packages}
+}
+
+ at index{jmlrutils,
+ name={\styfmt{jmlrutils}},
+ category={package},
+ parent={packages}
+}
+
@index{inputenc,
name={\styfmt{inputenc}},
category={package},
@@ -2710,6 +2821,12 @@
parent={packages}
}
+ at index{babel,
+ name={\styfmt{babel}},
+ category={package},
+ parent={packages}
+}
+
@index{polyglossia,
name={\styfmt{polyglossia}},
category={package},
@@ -3236,6 +3353,11 @@
category={counter}
}
+ at index{ctr.wrglossary,
+ name={\counterfmt{wrglossary}},
+ category={counter}
+}
+
@index{labelprefixes,
name={label prefixes},
text={label prefix},
@@ -3355,6 +3477,18 @@
parent={packageoptions}
}
+ at index{styopt.counter,
+ name={\styoptfmt{counter}},
+ category={packageoption},
+ parent={packageoptions}
+}
+
+ at index{styopt.indexcounter,
+ name={\styoptfmt{index\-counter}},
+ category={packageoption},
+ parent={packageoptions}
+}
+
@index{styopt.index,
name={\styoptfmt{index}},
category={packageoption},
@@ -3786,6 +3920,15 @@
parent={internalfields}
}
+ at 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 @@
parent={internalfields}
}
+ at 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}
+}
+
+ at 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}
+}
+
+ at 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}
+}
+
+ at dualindexentry{field.bibtexentry at 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 @@
parent={entrytypes}
}
+ at dualindexentry{entry.bibtexentry,
+ name={\atentryfmt{bib\-tex\-entry}},
+ category={entrytype},
+ parent={entrytypes}
+}
+
+ at dualindexentry{entry.contributor,
+ name={\atentryfmt{contributor}},
+ category={entrytype},
+ parent={entrytypes}
+}
+
@index{switches,
name={switches},
text={switch},
@@ -4340,6 +4531,34 @@
parent={commandlineoptions}
}
+ at dualindexentry{switch.cite-as-record,
+ name={\longargfmt{cite\dhyphen as\dhyphen record}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+ at dualindexentry{switch.no-cite-as-record,
+ name={\longargfmt{no\dhyphen cite\dhyphen as\dhyphen record}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+ at dualindexentry{switch.merge-wrglossary-records,
+ name={\longargfmt{merge\dhyphen wrglossary\dhyphen records}},
+ user1={},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+ at 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 @@
parent={commandlineoptions}
}
+ at dualindexentry{switch.custom-packages,
+ name={\longargfmt{custom\dhyphen packages}},
+ user1={\meta{list}},
+ category={switch},
+ parent={commandlineoptions}
+}
+
+ at 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 @@
plural={ignored glossaries}
}
+ at index{ignoredrecord,
+ name={ignored record}
+}
+
@index{postlinkhook,
name={post-link hook}
}
@@ -4708,6 +4944,10 @@
name={\filefmt{bib2gls.bat}}
}
+ at index{file.xampl.bib,
+ name={\filefmt{xampl.bib}}
+}
+
@index{file.sample-dual.tex,
name={\filefmt{sample\dhyphen dual.tex}}
}
@@ -4895,7 +5135,8 @@
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,11 +5723,20 @@
@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}
}
+ at 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}
+}
+
@index{hypersf,
name={\csfmt{hypersf}},
user1={\margm{text}},
@@ -5538,7 +5788,7 @@
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 @@
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 @@
category={command}
}
+ at 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}
+}
+
+ at 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 @@
category={command}
}
+ at 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}
+}
+
+ at index{ProvidesPackage,
+ name={\csfmt{Provides\-Pack\-age}},
+ user1={\margm{name}\oargm{version}},
+ description={identifies a package},
+ note={kernel command},
+ category={command}
+}
+
+ at 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}
+}
+
+ at index{DeclareOption*,
+ name={\csfmt{Declare\-Opt\-ions*}},
+ user1={\margm{code}},
+ description={indicates what to do with unknown options},
+ note={kernel command},
+ category={command}
+}
+
+ at index{ProcessOptions,
+ name={\csfmt{Process\-Opt\-ions}},
+ description={processes supplied options},
+ note={kernel command},
+ category={command}
+}
+
+ at 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 @@
category={command}
}
+ at 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}
+}
+
+ at index{cite,
+ name={\csfmt{cite}},
+ user1={\margm{label}},
+ description={cross-reference a bibliographic citation},
+ note={kernel command},
+ category={command}
+}
+
+ at index{bibliography,
+ name={\csfmt{bibliography}},
+ user1={\margm{file list}},
+ description={display bibliography created by \BibTeX},
+ note={kernel command},
+ category={command}
+}
+
+ at 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}
+}
+
+ at 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}
+}
+
+ at index{pageref,
+ name={\csfmt{pageref}},
+ user1={\margm{id}},
+ description={cross-reference the page where \cs{label}\margm{id}
+occurred},
+ note={kernel command},
+ category={command}
+}
+
+ at index{ref,
+ name={\csfmt{ref}},
+ user1={\margm{id}},
+ description={cross-reference the location where \cs{label}\margm{id}
+occurred},
+ note={kernel command},
+ category={command}
+}
+
+ at 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}
+}
+
+ at 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}
+}
+
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod 2018-04-09 21:19:32 UTC (rev 47413)
@@ -84,6 +84,23 @@
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,6 +131,15 @@
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
@@ -120,9 +146,15 @@
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>)
Insert an empty group if fields start with certain problematic
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex 2018-04-09 21:18:59 UTC (rev 47412)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex 2018-04-09 21:19:32 UTC (rev 47413)
@@ -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 @@
\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 @@
?? 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 @@
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 @@
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 at 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 @@
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,8 +2065,22 @@
\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}
This option is cumulative. When the document \iext{log} file is
@@ -2011,7 +2090,7 @@
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 @@
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 @@
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 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 at entrytype} internal
+fields can be set for the
+\atentry{contributor} entry. For example:
+\begin{verbatim}
+ at contributor{KnuthDonaldE,
+ name={\bibglscontributor{Donald E.}{}{Knuth}{}},
+ description={Famous mathematician and computer scientist who
+ created \TeX}
+}
+
+ at 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 @@
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 at 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 @@
\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}
+ at entry{bird,
+ name={bird},
+ description = {feathered animal}
+}
+
+ at index{duck}
+
+ at index{goose,plural="geese"}
+
+ at 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 @@
(\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 @@
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 @@
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,8 +6575,100 @@
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}
+ at 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}
+ at 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}
The entry types that define abbreviations (such as
@@ -6408,153 +7038,6 @@
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}
- at entry{bird,
- name={bird},
- description = {feathered animal}
-}
-
- at index{duck}
-
- at index{goose,plural="geese"}
-
- at 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 @@
\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 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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
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 at 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 at 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 at wrglossarylocation}\margm{n}\margm{page}}
+\end{codeenv}
+Since \gls{glsxtr at wrglossarylocation} simply expands to its first
+argument, the corresponding label can be obtained with
+\begin{alltt}
+wrglossary.\gls{glsxtr at 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 @@
\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 @@
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 @@
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 @@
\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,7 +11303,8 @@
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
@@ -10666,6 +11311,11 @@
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,7 +11361,8 @@
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
@@ -10718,6 +11369,11 @@
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 @@
\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 \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 @@
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 @@
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
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
===================================================================
(Binary files differ)
More information about the tex-live-commits
mailing list