diff options
| author | Karl Berry <karl@freefriends.org> | 2021-11-06 20:40:33 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2021-11-06 20:40:33 +0000 |
| commit | 64faaa94313d41b577b70c12355e292b265426f0 (patch) | |
| tree | 82b7c301dd3e421e37e5b28f1bf05e2ca50085fc | |
| parent | 5c835cb7fc402dcaf0f66aad522767cb5d078237 (diff) | |
bib2gls (6nov21)
git-svn-id: svn://tug.org/texlive/trunk@60978 c570f23f-e606-0410-a88d-b1316a301751
38 files changed, 2654 insertions, 1324 deletions
diff --git a/Master/texmf-dist/doc/man/man1/bib2gls.1 b/Master/texmf-dist/doc/man/man1/bib2gls.1 index 37b4e6c0af8..61572af24b0 100644 --- a/Master/texmf-dist/doc/man/man1/bib2gls.1 +++ b/Master/texmf-dist/doc/man/man1/bib2gls.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "BIB2GLS 1" -.TH BIB2GLS 1 "2020-03-18" "perl v5.30.3" "bib2gls" +.TH BIB2GLS 1 "2021-11-05" "perl v5.32.1" "bib2gls" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -232,6 +232,21 @@ Merge an entry's \fBwrglossary\fR records for the same page locations. .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\-\-collapse\-same\-location\-range\fR" 4 +.IX Item "--collapse-same-location-range" +Collapse an explicit range that has a duplicate start and end +location into a normal record (default). +.IP "\fB\-\-no\-collapse\-same\-location\-range\fR" 4 +.IX Item "--no-collapse-same-location-range" +Don't collapse an explicit range that has a duplicate start and end +location into a normal record. +.IP "\fB\-\-retain\-formats\fR \fIlist\fR" 4 +.IX Item "--retain-formats list" +Indicates which location formats should always be retained even if +it causes a partial duplicate. Only exact duplicates will be merged. +.IP "\fB\-\-no\-retain\-formats\fR" 4 +.IX Item "--no-retain-formats" +Normal location merging rules apply (default). .IP "\fB\-\-merge\-nameref\-on\fR \fIrule\fR" 4 .IX Item "--merge-nameref-on rule" Rule for merging locations created with the \fBrecord=nameref\fR package option diff --git a/Master/texmf-dist/doc/man/man1/convertgls2bib.1 b/Master/texmf-dist/doc/man/man1/convertgls2bib.1 index 1b2b3016e0f..72eb20f3cb5 100644 --- a/Master/texmf-dist/doc/man/man1/convertgls2bib.1 +++ b/Master/texmf-dist/doc/man/man1/convertgls2bib.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "CONVERTGLS2BIB 1" -.TH CONVERTGLS2BIB 1 "2020-02-11" "perl v5.30.3" "convertgls2bib" +.TH CONVERTGLS2BIB 1 "2020-02-11" "perl v5.32.1" "convertgls2bib" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/Master/texmf-dist/doc/support/bib2gls/CHANGES b/Master/texmf-dist/doc/support/bib2gls/CHANGES index 78da3cb3798..36e8039ff4a 100644 --- a/Master/texmf-dist/doc/support/bib2gls/CHANGES +++ b/Master/texmf-dist/doc/support/bib2gls/CHANGES @@ -1,3 +1,65 @@ +v2.8 (2021-11-05): + + * Support for new features of mfirstuc v2.07: + + - sentence case (firstuc) and title case now recognise \MFUskippunc. + (This should be used to skip leading punctuation.) + + - title case now recognises \MFUwordbreak. + + * new dual field 'dualdescription' + + * new selection option 'selected before' + + * new resource options: + + - save-from-alias + - save-from-see + - save-from-seealso + - save-crossref-tail + - save-definition-index + - save-use-index + - format-integer-fields + - format-decimal-fields + - secondary-match-action + - secondary-match-op + - secondary-match + - secondary-not-match + - encapsulate-sort + - prefix-only-existing + - save-principal-locations (synonym for save-primary-locations) + - principal-location-formats (synonym for primary-location-formats) + + * issue #10: explicit ranges with identical start and end should + collapse to a normal location + https://github.com/nlct/bib2gls/issues/10 + + This has led to new switches: + + --collapse-same-location-range (default) + --no-collapse-same-location-range + + * issue #12 Primary locations need to be retained not merged (save-primary-locations=remove) + https://github.com/nlct/bib2gls/issues/12 + + This has led to new switches: + + --retain-formats + --no-retain-formats + + * bug fix: @entry missing required name/description results in "null" + saved in the field value. This has been changed to an empty + string (but the warning about the missing field remains). + + * bug fix: selection=all doesn't show see and seealso lists in + locations https://github.com/nlct/bib2gls/issues/9 + + * bug fix: integer sort method should cast to int + https://github.com/nlct/bib2gls/issues/11 + + * bug fix: indexplural default name incorrect when parent field set + https://github.com/nlct/bib2gls/issues/13 + v2.7 (2020-07-11): * save-original-entrytype option now allows the name of a field diff --git a/Master/texmf-dist/doc/support/bib2gls/README.md b/Master/texmf-dist/doc/support/bib2gls/README.md index ee84f7c8b09..0d1f8b13f97 100644 --- a/Master/texmf-dist/doc/support/bib2gls/README.md +++ b/Master/texmf-dist/doc/support/bib2gls/README.md @@ -9,7 +9,7 @@ Application Home Page: https://www.dickimaw-books.com/software/bib2gls # Licence -Copyright (C) 2017-2020 Nicola L. C. Talbot (www.dickimaw-books.com) +Copyright (C) 2017-2021 Nicola L. C. Talbot (www.dickimaw-books.com) License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html @@ -124,6 +124,17 @@ pdflatex myDoc (Replace `pdflatex` with `latex`, `xelatex` or `lualatex` as appropriate.) +# Related Resources + + - [bib2gls FAQ](https://www.dickimaw-books.com/faq.php?category=bib2gls). + - [bib2gls gallery](https://www.dickimaw-books.com/gallery/#bib2gls). + +TUGboat articles: + + - [Glossaries with bib2gls](http://tug.org/TUGboat/tb40-1/tb124talbot-bib2gls.pdf), issue [40:1, 2019](http://tug.org/TUGboat/Contents/contents40-1.html). + - [bib2gls: selection, cross-references and locations](http://tug.org/TUGboat/tb41-3/tb129talbot-bib2gls-more.pdf), issue [41:3, 2020](http://tug.org/TUGboat/Contents/contents41-3.html). + - bib2gls: sorting, issue [42:2, 2021](http://tug.org/TUGboat/Contents/contents42-2.html). + # Installation The files should be installed as follows where *TEXMF* indicates diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf Binary files differindex df6e596b1c7..c178684a171 100644 --- a/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf Binary files differindex c0d7b2843ff..05aefcaeac1 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 d40ca8cf46e..2a10f78927c 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 ad8ff4bda3c..de566d69c14 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 918483c6b8f..b381b12c759 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-citations.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf Binary files differindex c94eb54f6ef..90e5404aeff 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.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 92daecdfdee..ee514e61517 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-hierarchical.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf Binary files differindex c8deb3f5b33..366652cbd4a 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf Binary files differindex d93796579a7..a4b0ae09f6e 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.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 2f9fedbb6a9..2d7536bb36a 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 a28a071a60a..8198faa965b 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 bf2430cc1e7..58f79abc4d4 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 439094626bf..ef7feb79b1a 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 3548567094a..851f2ada1e3 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-multi2.tex b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.tex index bec2301f0c3..75733933b38 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.tex +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.tex @@ -300,7 +300,7 @@ \glsadd[format=hyperbf]{#1}% } -\newcommand{\unit}{\glssymbol} +\newcommand{\Unit}{\glssymbol} \newcommand{\measurement}{\gls} \glsxtrnewgls{film.}{\film} \glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} @@ -364,14 +364,14 @@ This section is about \idxpl{chemical}. \gls{Zr3PO44} (\glsdesc{Zr3PO44}), \gls{ZnF2} (\glsdesc{ZnF2}). \section{SI Units} -\Idxpl{baseunit}: \unit{ampere} (measures \measurement{ampere}), -\unit{kilogram} (measures \measurement{kilogram}), \unit{metre}, -\unit{second}, \unit{kelvin}, \unit{mole}, \unit{candela}. - -\Idxpl{derivedunit}: \unit{area}, \unit{volume}, -\unit{velocity}, -\unit{acceleration}, \unit{density}, \unit{luminance}, -\unit{specificvolume}, \unit{concentration}, \unit{wavenumber}. +\Idxpl{baseunit}: \Unit{ampere} (measures \measurement{ampere}), +\Unit{kilogram} (measures \measurement{kilogram}), \Unit{metre}, +\Unit{second}, \Unit{kelvin}, \Unit{mole}, \Unit{candela}. + +\Idxpl{derivedunit}: \Unit{area}, \Unit{volume}, +\Unit{velocity}, +\Unit{acceleration}, \Unit{density}, \Unit{luminance}, +\Unit{specificvolume}, \Unit{concentration}, \Unit{wavenumber}. \section{Books and Films} \Idxpl{book}: \gls{ataleoftwocities} (by \gls{dickens}), diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf Binary files differindex f61387651f3..a8f7e6120cd 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.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 a9e74241a2f..a03261b14f1 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 4f4af52d4bc..a38d38b85c6 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-textsymbols2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf Binary files differindex ba846037df2..ec8afd2eac5 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.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 fec5a07613e..0348d38a526 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 9f94f62e3d6..3db5447a91e 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 15947b9d508..e89abd84ef8 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 c946b1758fe..35debd6fa83 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 295a6d490da..4c325867986 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 1e6b2cb77b0..4ecd3ee2b72 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 978a6507b69..42846f9f2d7 100644 --- a/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml +++ b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml @@ -42,6 +42,10 @@ See the manual for further details.</entry> (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.collapse.same.location.range">{0} Collapse explicit location ranges with coincident end-points (default).</entry> +<entry key="syntax.no.collapse.same.location.range">{0} Don''t collapse explicit location ranges with coincident end-points.</entry> +<entry key="syntax.retain.formats">{0} Retain non-identical locations with the given formats even if a partial match exists.</entry> +<entry key="syntax.no.retain.formats">{0} Don''t override normal location merging rules (default).</entry> <entry key="syntax.merge.wrglossary.records">{0} Merge wrglossary counter records (default).</entry> <entry key="syntax.no.merge.wrglossary.records">{0} @@ -185,6 +189,7 @@ See the manual for further details.</entry> <entry key="message.crossref.found">Entry {0}: found cross-reference ({1}): {2}</entry> <entry key="message.crossref.by">Entry {0} cross-referenced by {1}</entry> <entry key="message.checking.crossrefs">Checking cross-references for: {0}</entry> +<entry key="message.crossref.tail">Cross-reference tail for ''{0}'': {1}</entry> <entry key="message.custom.dep.found">Entry {0}: found custom ''{1}'' dependency ({2}): {3}</entry> <entry key="message.field.not.set">Field {0} not set.</entry> <entry key="message.added.user.field">Adding internal user field: {0}</entry> @@ -192,6 +197,7 @@ See the manual for further details.</entry> <entry key="message.added.alias.dep">Adding alias {0} as dependency for {1}</entry> <entry key="message.added.dep">Added dependent: {0}</entry> <entry key="message.added.parent">Adding parent: {0}</entry> +<entry key="message.adding.child">Adding child {0} to parent {1}</entry> <entry key="message.selecting.all">Selecting all entries.</entry> <entry key="message.selecting.entry.records">Selecting entry {0} (has one or more records).</entry> <entry key="message.selecting.entry.record.match">Selecting entry {0} (matches record {1}).</entry> @@ -201,11 +207,15 @@ See the manual for further details.</entry> <entry key="message.selecting.entry.dualrecords">Selecting entry {0} (dual {1} has one or more records).</entry> <entry key="message.selecting.entry.dep">Selecting entry {0} (is dependency).</entry> <entry key="message.selecting.entry">Selecting entry {0}.</entry> +<entry key="message.selecting.entry.before">Selecting entry {0} (selected before).</entry> <entry key="message.datetime.field.check">Checking entry {0} field {1} for date/time data (date:{2}, time:{3}).</entry> <entry key="message.field.notset">Field {0} not set for entry {1}</entry> <entry key="message.selection.mode">Selection mode: {0}</entry> <entry key="message.ignore.fields">Ignoring fields:</entry> <entry key="message.ignore.field">Ignoring field ''{0}'' for entry ''{1}''</entry> +<entry key="message.add.secondary.entry.no_filter">Adding entry {0} to secondary list (no filter).</entry> +<entry key="message.add.secondary.entry">Adding entry {0} to secondary list.</entry> +<entry key="message.secondary.filter">Checking entry {0} admission to secondary list. Match action: {1}. Matches: {2}.</entry> <entry key="message.sort.mode">Sort mode: {0}</entry> <entry key="message.sort.field">Sort field: {0}</entry> <entry key="message.sort.date.locale">Date/time sort locale: {0}</entry> @@ -507,6 +517,7 @@ Use {1} {0} instead.</entry> {2}</entry> <entry key="error.option.requires.interpreter">Interpreter needed for setting {0}</entry> <entry key="error.sort.requires.switch">Sort method ''{0}'' requires {1} switch.</entry> +<entry key="error.selected_before.none_selected">Selection setting ''{0}'' requires previous selections from other resource sets.</entry> <!-- The following messages are used by convertgls2bib diff --git a/Master/texmf-dist/scripts/bib2gls/texparserlib.jar b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar Binary files differindex e31c5501bc8..5e6f7e8fe15 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 f76575706f1..7ab5687abf5 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-terms.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib new file mode 100644 index 00000000000..3416f55e1cc --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib @@ -0,0 +1,432 @@ +% Encoding: UTF-8 + +@entry{primaryentry, + name={primary entry}, + plural={primary entries}, + user1`={idx.primary}, + description={The original entry created from a dual-entry type + (such as \atentry{dualentry}) or the entry from single-entry + types (such as \atentry{entry}) or \glspl{spawnedentry}.} +} + +@entry{dualentry, + name={dual entry}, + plural={dual entries}, + user1={idx.dual}, + description={The duplicate entry created from a dual-entry type + (such as \atentry{dualentry}). This duplicate is based on the + \gls{primaryentry} with modifications made according to various + settings. With tertiary entry types, the dual entry represents + two entries: the \glsdisp{secondaryentry}{secondary} and + \glsdisp{tertiaryentry}{tertiary}. + See \sectionref{sec:dualentry}.} +} + +@entry{secondaryentry, + name={secondary entry}, + plural={secondary entries}, + user1={idx.secondary}, + description={For the tertiary entry types, such as + \atentry{tertiaryindexabbreviationentry}, there are only actually + two objects defined within \bibgls: the + \glsdisp{primaryentry}{primary} and the \glsdisp{dualentry}{dual}, + but the code that is written in the \ext{glstex} file for the + \gls{dualentry} actually defines two entries, which are the + secondary and tertiary entries. + This should not be confused with the \gls{secondaryglossary}. + See \sectionref{sec:tertiaryentry}.} +} + +@entry{tertiaryentry, + name={tertiary entry}, + plural={tertiary entries}, + user1={idx.tertiary}, + description={An entry that isn't defined as a separated object + within \bibgls, but is defined within the \ext{glstex} file + as a by-product of the dual definition code for tertiary entry + types.} +} + +@entry{mainentry, + name={main entry}, + plural={main entries}, + description={The originating entry from which + the \glspl{spawnedentry} are created. A main entry may + be a dual-entry type, consisting of a \gls{primaryentry} + and \gls{dualentry}. + (Not to be confused with the main glossary.)} +} + +@entry{progenitor, + name={progenitor}, + user1={idx.progenitor}, + description={The \gls{mainentry} for the \atentry{progenitor} + entry type.} +} + +@entry{progeny, + name={progeny}, + user1={idx.progeny}, + description={The \glspl{spawnedentry} for the \atentry{progenitor} + entry type.} +} + +@entry{multientrytype, + name={multi-entry type}, + description={An entry type that can spawn multiple + \glspl{primaryentry}. Some multi-entry types can also spawn a + \gls{dualentry}. See \sectionref{sec:multientry}.} +} + +@entry{spawnedentry, + name={spawned entry}, + plural={spawned entries}, + description={A duplicate entry created from a \gls{multientrytype} + (such as \atentry{spawnentry}).} +} + +@entry{principallocation, + name={principal (or primary) location}, + text={principal location}, + description={A special \gls{location} (\gls{record}) which indicates the principal + or primary place in the document where the entry is mentioned + or discussed. The \gls{location} is identified by the principal or + primary format (\csopt{principal-location-formats}).} +} + +@entry{mainglossary, + name={main glossary}, + description={The default glossary in the document identified by + \cs{glsdefaulttype} (which will have the label \code{main} unless + \styopt{nomain} is used). If \styopt{nomain} is used then + \cs{glsdefaulttype} will be set to the label of the first glossary + to be defined.} +} + +@entry{mainlist, + name={main (or primary) list}, + text={main list}, + description={The \bibgls\ list of \glspl{primaryentry}, which is sorted + according to the \csopt{sort} resource option. The entries may or + may not be assigned to the same glossary, and the list may only be + a subset of entries. If \csopt[combine]{dual-sort} is used, then + the main list will also contain all the \glspl{dualentry}.} +} + +@entry{duallist, + name={dual list}, + description={The \bibgls\ list of \glspl{dualentry}, which is sorted + according to the \csopt{dual-sort} resource option. The entries may or + may not be assigned to the same glossary, and the list may only be + a subset of entries. If \csopt[combine]{dual-sort} is used then + all entries will be in the \gls{mainlist} and there won't be a dual + list.} +} + +@entry{primaryglossary, + name={primary (or principal) glossary}, + text={primary glossary}, + plural={primary glossaries}, + description={A glossary that contains entries that have the \field{type} + field set to that glossary's label. Note that a primary glossary + may contain both \glsdisp{primaryentry}{primary} and + \glspl{dualentry}.} +} + +@entry{secondaryglossary, + name={secondary glossary}, + plural={secondary glossaries}, + description={A secondary glossary is one that contains labels of + entries that have been defined for another glossary. The actual + entry's \field{type} field will be set to the + \gls{primaryglossary}.} +} + +@entry{record, + name={record}, + description={Recording is \bibgls's equivalent of indexing. + When the \styopt{record} package option is set, each + time an entry is indexed in the document (using commands like + \cs{gls} or \cs{glstext}) a record is added to the \ext{aux} + file that makes a note of the entry label, the location, the + counter that was used to obtain the \gls{location}, and (optionally) + hyperlink information. A record may be \glsdisp{ignoredrecord}{ignored} + or \glsdisp{discardedrecord}{discarded} but, regardless of this, + if an entry has at least one record it will be considered for selection + for any of the \qt{recorded} selection options.} +} + +@entry{location, + name={location}, + description={The value of the indexing counter when an entry is + \glsdisp{record}{recorded}. By default, this is the \counter{page} + counter. Each location has an associated format or \idx{encap}, + which is the name of a formatting command that should be used to + encapsulate the location's value in the \gls{locationlist}. + The default is \encap{glsnumberformat}.} +} + +@entry{ignoredrecord, + name={ignored record}, + user1={idx.ignoredrecord}, + description={A record with the format \encap{glsignore} or + \encap{glstriggerrecordformat}. This record indicates that the + entry should be considered for selection + with any of the \qt{recorded} selection options, but the record + should not be added to the \gls{locationlist}.} +} + +@entry{discardedrecord, + name={discarded record}, + description={A record that is discarded because either it is + identical to another record or it conflicts with another record.} +} + +@entry{supplementalrecord, + name={supplemental record}, + description={A record obtained from another document. + See \sectionref{sec:supplementalopts}.} +} + +@entry{supplementaldocument, + name={supplemental (or supplementary) document}, + name={supplemental document}, + description={A related document from which + \glspl{supplementalrecord} are obtained.} +} + +@entry{maindocument, + name={main document}, + description={The principal document that has its own glossary but + the \glspl{locationlist} may also contain external + \glspl{location} obtained from a \gls{supplementaldocument}.} +} + +@entry{recordcount, + name={record count}, + description={An entry's record count is the total number of records + (including \glsdisp{discardedrecord}{discarded} and + \glsdisp{ignoredrecord}{ignored}) written to the \ext{aux} file + that are associated with the entry. It's also possible to have + sub-totals for each record counter.} +} + +@entry{recordedentry, + name={recorded entry}, + plural={recorded entries}, + description={An entry that has one or more \glspl{record}.} +} + +@entry{unrecordedentry, + name={unrecorded entry}, + plural={unrecorded entries}, + description={An entry that doesn't have any \glspl{record}.} +} + +@entry{locationlist, + name={location list}, + user1={idx.locationlist}, + description={Formatted list of \glspl{location} obtained from an entry's + \glspl{record}. This won't include \glsdisp{ignoredrecord}{ignored} + or \glsdisp{discardedrecord}{discarded} records, and a run of + \glspl{location} may be compressed into a range. See + \sectionref{sec:locationopts} and \sectionref{sec:loclistdefs}.} +} + +@entry{parententry, + name={parent entry}, + plural={parent entries}, + user1={idx.hierarchical-entry}, + description={An entry in a \gls{hierarchicalglossary} + that is linked to, but one level up from, its associated + \gls{childentry}. See \sectionref{sec:hierarchicalopts}.} +} + +@entry{childentry, + name={child entry}, + plural={child entries}, + user1={idx.hierarchical-entry}, + description={An entry in a \gls{hierarchicalglossary} + that is linked to, but one level down from, its associated + \gls{parententry}. See \sectionref{sec:hierarchicalopts}.} +} + +@entry{sub-entry, + name={sub-entry}, + plural={sub-entries}, + user1={idx.hierarchical-entry}, + description={A \gls{childentry}. More specifically, when + contrasted with sub-sub-entry etc, this may refer to level~1 entries + (which have a \glsdisp{parententry}{parent} that is a + \gls{top-levelentry}). See \sectionref{sec:hierarchicalopts}.} +} + +@entry{hierarchicalglossary, + name={hierarchical glossary}, + plural={hierarchical glossaries}, + user1={idx.hierarchical-entry}, + description={A glossary where the entries are ranked according to + some classification. Level~0 indicates \glspl{top-levelentry}, + level~1 indicates \glspl{childentry} that have a + level~0 \glsdisp{parententry}{parent}, level~2 indicates + \glspl{childentry} that have a + level~1 \glsdisp{parententry}{parent}, and so on. See \sectionref{sec:hierarchicalopts}.} +} + +@entry{flatglossary, + name={flat glossary}, + description={A glossary that has no \glsdisp{hierarchicalglossary}{hierarchy}. + That is, there are no \glspl{childentry}. See \sectionref{sec:hierarchicalopts}.} +} + +@entry{sibling, + name={sibling entry}, + text={sibling}, + description={Two or more \glspl{childentry} are siblings if + they all share the same \gls{parententry}. + See \sectionref{sec:hierarchicalopts}.} +} + +@entry{lonelychildentry, + name={lonely child entry}, + plural={lonely child entries}, + user1={idx.hierarchical-entry}, + description={A \gls{childentry} that has no selected \glspl{sibling}. + See \sectionref{sec:hierarchicalopts}.} +} + +@entry{ancestor, + name={ancestor}, + user1={idx.hierarchical-entry}, + description={An entry's \glsdisp{parententry}{parent} or an ancestor of + the \glsdisp{parententry}{parent}. See \sectionref{sec:hierarchicalopts}.} +} + +@entry{top-levelentry, + name={top-level entry}, + plural={top-level entries}, + user1={idx.hierarchical-entry}, + description={An entry that doesn't have a \gls{parententry}. + See \sectionref{sec:hierarchicalopts}.} +} + +@entry{masterdocument, + name={master document}, + description={A main or principal document that contains a glossary + with entries referenced by smaller documents that don't have their own + glossary. See \sectionref{sec:master}.} +} + +@entry{primarycollatorstrength, + name={primary collator strength}, + description={A collator strength value that indicates only primary + differences are considered significant during comparison. + This is locale dependant, but typically different base letters + are considered a primary difference.} +} + +@entry{secondarycollatorstrength, + name={secondary collator strength}, + description={A collator strength value that indicates only primary + and secondary differences are considered significant during comparison. + This is locale dependant. For example, in some languages different + accented forms of the same base letter may be considered a + secondary difference.} +} + +@entry{tertiarycollatorstrength, + name={tertiary collator strength}, + description={A collator strength value that indicates only + primary, secondary and tertiary differences are considered + significant during comparison. This is locale dependant. For + example, different cases of the same base letter may be considered a + tertiary difference.} +} + +@entry{identicalcollatorstrength, + name={identical collator strength}, + description={A collator strength value that indicates that all + differences are considered significant during comparison.} +} + +@entry{definitionindex, + name={definition index}, + description={An index (starting from 0) that's incremented + every time a new entry object is created within \bibgls. + This relates to the order of definitions within the \ext{bib} + files. Each \gls{dualentry} and \gls{spawnedentry} will increment + the underlying counter but only when they are created, which + may not happen until after all \ext{bib} files for the \gls{resourceset} have + been parsed.} +} + +@entry{orderofuseindex, + name={order of use index}, + description={The \gls{record} index is a value (starting from 0) that's incremented + every time a \gls{record} is created while parsing the \ext{aux} file. + The first time a non-\gls{ignoredrecord} is added to a given entry, the + \gls{record} index is assigned to that entry's order of use index. So the + index provides a relative order of use. So if entry1 is the first entry + to be indexed, it will have order of use index~0. If entry1 is + then indexed twice more and then entry2 is indexed, then entry2's + order of use index will be~3.} +} + +@entry{resourceset, + name={resource set}, + user1={idx.resourceset}, + description={The set of options and entries associated with a + \gls{resourcecommand}. See \sectionref{sec:resourcesets}.} +} + +@entry{resourcecommand, + name={resource command}, + description={\gls{glsxtrresourcefile} or \gls{GlsXtrLoadResources}.} +} + +@entry{crossresourceref, + name={cross-resource reference}, + user1={idx.crossresourceref}, + description={A reference from a \gls{recordedentry} provided in + one \gls{resourceset} to an \gls{unrecordedentry} in another + \gls{resourceset}. See \sectionref{sec:resourcesets}.} +} + +@entry{cross-referencefield, + name={cross-reference field}, + description={A field used for cross-referencing another entry: + \field{see}, \field{seealso} and \field{alias}. + Other fields can be identified as a list of dependent entry labels + with \csopt{dependency-fields}.} +} + +@entry{ignoredglossary, + name={ignored glossary}, + plural={ignored glossaries}, + user1={idx.ignoredglossary}, + description={A glossary defined with commands like + \cs{newignoredglossary}. An ignored glossary doesn't have an +associated title (so it one is required it needs to be explicitly +set), and isn't picked up by iterative commands such as + \cs{printunsrtglossaries}. See \sectionref{sec:newglossary}.} +} + +@entry{homograph, + name={homograph}, + user1={idx.homograph}, + description={Each word in a set of words that all have the same + spelling but different meanings. For example, lead (to guide + someone) and lead (metallic element) are homographs.} +} + +@entry{encoding, + name={encoding}, + user1={idx.encoding}, + description={A text format that maps a byte or sequence of bytes + to a character. See \sectionref{sec:bibencoding} and \longarg{tex-encoding} + for the \ext{bib} file encoding and \csopt{charset} for the \ext{glstex} + file encoding. See also the blog article +\href{https://dickimaw-books.com/blog/binary-files-text-files-and-file-encodings/}{Binary +Files, Text Files and File Encodings} for further information about + file encodings in general.} +} diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 6f4f6e5c4fe..5d8ed65bd39 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -1568,6 +1568,28 @@ name}, category={command} } +@bibglscommand{bibglsdefinitionindex, + name={\csfmt{bib\-gls\-definition\-index}}, + user1={\margm{label}}, + description={expands to the definition index of the entry + identified \meta{label} if \csopt{save-definition-index} is set + otherwise expands to empty}, + topics={fieldrefcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + +@bibglscommand{bibglsuseindex, + name={\csfmt{bib\-gls\-use\-index}}, + user1={\margm{label}}, + description={expands to the order of use index of the entry + identified \meta{label} if \csopt{save-use-index} is set and + the entry has records otherwise expands to empty}, + topics={fieldrefcommands}, + note={\bibgls\texparserdefnote}, + category={command} +} + @mainglscommand{glsexpandfields, name={\csfmt{gls\-expand\-fields}}, user1={}, @@ -2071,6 +2093,34 @@ starred version \csref{glsxtrfmt*}}, parent={resourceoptions} } +@resourceoption{opt.secondary-match, + name={\csoptfmt{secondary\dhyphen match}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-match-op, + name={\csoptfmt{secondary\dhyphen match\dhyphen op}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-match-action, + name={\csoptfmt{secondary\dhyphen match\dhyphen action}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.secondary-not-match, + name={\csoptfmt{secondary\dhyphen not\dhyphen match}}, + user1={\meta{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.limit, name={\csoptfmt{limit}}, user1={\meta{number}}, @@ -2303,6 +2353,34 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.save-definition-index, + name={\csoptfmt{save\dhyphen definition\dhyphen index}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-use-index, + name={\csoptfmt{save\dhyphen use\dhyphen index}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.format-integer-fields, + name={\csoptfmt{format\dhyphen integer\dhyphen fields}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.format-decimal-fields, + name={\csoptfmt{format\dhyphen decimal\dhyphen fields}}, + user1={\margm{\keyvallist}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.short-case-change, name={\csoptfmt{short\dhyphen case\dhyphen change}}, user1={\meta{value}}, @@ -2366,6 +2444,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.encapsulate-sort, + name={\csoptfmt{encapsulate\dhyphen sort}}, + user1={\marg{csname}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.prefix-fields, name={\csoptfmt{prefix\dhyphen fields}}, user1={\meta{list}}, @@ -2548,6 +2633,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.save-principal-locations, + name={\csoptfmt{save\dhyphen principal\dhyphen locations}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.primary-location-formats, name={\csoptfmt{primary\dhyphen location\dhyphen formats}}, user1={\meta{list}}, @@ -2555,6 +2647,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.principal-location-formats, + name={\csoptfmt{principal\dhyphen location\dhyphen formats}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.min-loc-range, name={\csoptfmt{min\dhyphen loc\dhyphen range}}, user1={\meta{value}}, @@ -2646,6 +2745,34 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.save-from-alias, + name={\csoptfmt{save\dhyphen from\dhyphen alias}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-from-seealso, + name={\csoptfmt{save\dhyphen from\dhyphen seealso}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-from-see, + name={\csoptfmt{save\dhyphen from\dhyphen see}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.save-crossref-tail, + name={\csoptfmt{save\dhyphen crossref\dhyphen tail}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.supplemental-locations, name={\csoptfmt{supplemental\dhyphen locations}}, user1={\meta{basename}}, @@ -3016,6 +3143,13 @@ format}}, parent={resourceoptions} } +@resourceoption{opt.prefix-only-existing, + name={\csoptfmt{prefix\dhyphen only\dhyphen existing}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.dual-prefix, name={\csoptfmt{dual\dhyphen prefix}}, user1={\meta{value}}, @@ -8237,6 +8371,14 @@ field.}, parent={fields} } +@field{field.dualdescription, + name={\fieldfmt{dual\-description}}, + description={May be used to identify a dual description}, + note={\appfmt{bib2gls}}, + category={bib2glsfield}, + parent={fields} +} + @field{field.access, name={\fieldfmt{access}}, description={The replacement text for the \field{name} field.}, @@ -8389,6 +8531,22 @@ field.}, parent={internalfields} } +@field{field.definitionindex, + name={\fieldfmt{definitionindex}}, + description={Stores the definition index.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + +@field{field.useindex, + name={\fieldfmt{useindex}}, + description={Stores the order of use index.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + @field{field.originalentrytype, name={\fieldfmt{original\-entry\-type}}, description={The original entry type before any aliasing was @@ -9177,6 +9335,20 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.collapse-same-location-range, + name={\longargfmt{collapse\dhyphen same\dhyphen location\dhyphen range}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-collapse-same-location-range, + name={\longargfmt{no\dhyphen collapse\dhyphen same\dhyphen location\dhyphen range}}, + user1={}, + category={switch}, + parent={commandlineoptions} +} + @switch{switch.merge-wrglossary-records, name={\longargfmt{merge\dhyphen wrglossary\dhyphen records}}, user1={}, @@ -9314,6 +9486,19 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.retain-formats, + name={\longargfmt{retain\dhyphen formats}}, + user1={\meta{list}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-retain-formats, + name={\longargfmt{no\dhyphen retain\dhyphen formats}}, + category={switch}, + parent={commandlineoptions} +} + @switch{switch.group, name={\longargfmt{group}}, symbol={\shortargfmt{g}}, @@ -10215,10 +10400,8 @@ primary formats, if enabled.}, name={\csfmt{gls\-see\-format}}, user1={\margm{tag}\margm{labels}\margm{location (ignored)}}, description={formats the entries identified in the comma separated - list of labels as a set of cross-references, where each - item in the list is encapsulated with \cs{glsseeitem} and - each element is separated with \cs{glsseesep} or - \cs{glsseelastsep}}, + list of labels as a set of cross-references. This just does + the tag (emphasized) followed by \cs{glsseelist}\margm{labels}}, topics={formattingcommands,crossrefcommands,loclistcommands}, note={\styfmt{glossaries}}, seealso={glsseeitem,glsseeitemformat,glsseesep,glsseelastsep}, @@ -10238,6 +10421,17 @@ primary formats, if enabled.}, category={command} } +@glscommand{glsseefirstitem, + name={\csfmt{gls\-see\-first\-item}}, + user1={\margm{label}}, + description={as \cs{glsseeitem} but is used for the first label in + the list. This just does \cs{glsseeitem} by default}, + topics={formattingcommands,crossrefcommands,loclistcommands,linkcommands}, + note={\styfmt{glossaries-extra} v1.47+}, + seealso={glsseeformat,glsseeitemformat}, + category={command} +} + @glscommand{glsseeitemformat, name={\csfmt{gls\-see\-item\-format}}, user1={\margm{label}}, @@ -10273,6 +10467,16 @@ primary formats, if enabled.}, category={command} } +@glscommand{glsseelastoxfordsep, + name={\csfmt{gls\-see\-last\-oxford\-sep}}, + description={used instead of \cs{glsseelastsep} if the list + contains three or more labels. This defaults to \cs{glsseelastsep}}, + topics={separatorcommands,crossrefcommands,loclistcommands}, + note={\styfmt{glossaries-extra} v1.47+}, + seealso={glsseeformat,glsseesep}, + category={command} +} + @glscommand{glsxtruseseeformat, name={\csfmt{gls\-xtr\-use\-see\-format}}, user1={\margm{tag}\margm{labels}}, @@ -11662,6 +11866,28 @@ field value}, category={command} } +@command{MFUwordbreak, + name={\csfmt{MFU\-word\-break}}, + user1={\margm{punctuation}}, + description={if \idx{capitalisewords} contains punctuation that + should be treated as a word break then \meta{punctuation} + should be encapsulated with this command to apply the case-change + to the following character}, + note={\styfmt{mfirstuc} v2.07+\texparserdefnote}, + category={command} +} + +@command{MFUskippunc, + name={\csfmt{MFU\-skip\-punc}}, + user1={\margm{punctuation}}, + description={if \idx{makefirstuc} starts with a punctuation + character it should be encapsulated with this command to skip + \meta{punctuation} and apply the case-change to the following + character}, + note={\styfmt{mfirstuc} v2.07+\texparserdefnote}, + category={command} +} + @glscommand{glsxtrusefield, name={\csfmt{gls\-xtr\-use\-field}}, user1={\margm{entry label}\margm{field label}}, @@ -11714,6 +11940,18 @@ field value}, category={command} } +@glscommand{glsxtrapptocsvfield, + name={\csfmt{gls\-xtr\-app\-to\-csv\-field}}, + user1={\margm{entry label}\margm{field label}\margm{value}}, + description={appends a comma followed by \meta{value} to the given + field for the given entry, it that field has already been set, + otherwise it sets the field to just \meta{value} (there's no check + for the existence of either the entry or the field)}, + topics={assigncommands}, + note={\styfmt{glossaries-extra} v1.47+}, + category={command} +} + @glscommand{glsxtrifhasfield, name={\csfmt{gls\-xtr\-if\-has\-field}}, user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, @@ -11722,7 +11960,7 @@ field value}, without testing if the entry exists and adds implicit scoping to \meta{true} and \meta{false}}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra} v1.19+}, + note={\styfmt{glossaries-extra} v1.19+\texparserdefnote}, seealso={GlsXtrIfFieldUndef}, category={command} } @@ -11735,7 +11973,7 @@ field value}, without testing if the entry exists and without introducing an implicit scope}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra} v1.19+}, + note={\styfmt{glossaries-extra} v1.19+\texparserdefnote}, seealso={GlsXtrIfFieldUndef}, category={command} } @@ -11758,7 +11996,7 @@ field value}, form adds implicit grouping. The starred form (new to v1.39) doesn't}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+\texparserdefnote}, category={command} } @@ -11770,7 +12008,7 @@ fully expands \meta{text} (but not the field value). The unstarred form adds implicit grouping. The starred form (new to v1.39) doesn't}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+\texparserdefnote}, category={command} } @@ -11782,7 +12020,7 @@ fully expands both the field value and \meta{text}. The unstarred form adds implicit grouping. The starred form (new to v1.39) doesn't}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+\texparserdefnote}, category={command} } @@ -11790,8 +12028,9 @@ doesn't}, name={\csfmt{if\-gls\-has\-field}}, user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, description={tests if the given entry, which must be defined, has the - given field set to a non-empty value}, - note={\styfmt{glossaries}}, + given field set to a non-empty value. This is implemented in + \bibgls\ in the same way as \cs{glsxtrifhasfield*}}, + note={\styfmt{glossaries}\texparserdefnote}, topics={conditional,fieldrefcommands}, seealso={glsxtrifhasfield,GlsXtrIfFieldUndef}, category={command} @@ -11804,7 +12043,7 @@ doesn't}, \field{symbol} field set to value that's not empty and not \csfmt{relax}}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, category={command} } @@ -11815,7 +12054,7 @@ doesn't}, description={tests if the given entry, which must be defined, has the \field{description} field set}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, seealso={ifglshassymbol,ifglshasdescsuppressed}, category={command} } @@ -11837,7 +12076,7 @@ doesn't}, description={tests if the given entry, which must be defined, has the \field{parent} field set}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, category={command} } @@ -11850,9 +12089,11 @@ doesn't}, have \meta{entry label} as the value of the \field{parent} field. With \bibgls, a more efficient approach is to use \csopt{save-child-count} and test the value of - the \field{childcount} field}, + the \field{childcount} field. The \TeX\ parser library recognises + this command and will simply use the child count (regardless of + whether or not the child count is saved)}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, category={command} } @@ -11862,7 +12103,7 @@ doesn't}, description={tests if the given entry, which must be defined, has the \field{short} field set}, topics={conditional,fieldrefcommands,abbreviationcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, category={command} } @@ -11872,7 +12113,7 @@ doesn't}, description={tests if the given entry, which must be defined, has the \field{long} field set}, topics={conditional,fieldrefcommands,abbreviationcommands}, - note={\styfmt{glossaries}}, + note={\styfmt{glossaries}\texparserdefnote}, category={command} } @@ -11928,7 +12169,7 @@ doesn't}, is the internal field label (not the key name). No expansion is performed in the test (which just uses \cs{ifcsstring})}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries} v4.16+}, + note={\styfmt{glossaries} v4.16+\texparserdefnote}, category={command} } @@ -12054,9 +12295,10 @@ doesn't}, option, this uses \cs{GlsXtrIfFieldNonZero} to test if the \field{childcount} field has a non-zero value. The value can be referenced in \meta{true} or \meta{false} with -\cs{glscurrentfieldvalue}}, +\cs{glscurrentfieldvalue}. The \TeX\ parser library recognises + this command regardless of whether or not the child count is saved}, topics={conditional,fieldrefcommands}, - note={\styfmt{glossaries-extra-bib2gls} v1.31+}, + note={\styfmt{glossaries-extra-bib2gls} v1.31+\texparserdefnote}, seealso={GlsXtrIfFieldNonZero}, category={command} } @@ -13694,6 +13936,23 @@ hasn't been defined}, category={command} } +@glscommand{glsseelist, + name={\csfmt{gls\-see\-list}}, + user1={\margm{label list}}, + description={iterates through the comma-separated list of entry + labels to produce a formatted list, where each + item in the list is encapsulated with \cs{glsseeitem} and + each element is separated with \cs{glsseesep} or + \cs{glsseelastsep}. This command was provided for + the use of \cs{glsseeformat} to format cross-reference lists + but may be used for any list of entry labels. This command is + redefined by \styfmt{glossaries-extra} (v1.47+) to additionally + use \cs{glsseefirstitem} and \cs{glsseelastoxfordsep}}, + topics={formattingcommands,crossrefcommands}, + note={\styfmt{glossaries}}, + category={command} +} + @glscommand{glsxtrsetaliasnoindex, name={\csfmt{gls\-xtr\-set\-alias\-noindex}}, user1={}, @@ -15569,7 +15828,7 @@ has three or more items}, } @command{MakeTextLowercase, - name={\csfmt{MakeTextLowercase}}, + name={\csfmt{Make\-Text\-Lower\-case}}, user1={\margm{text}}, description={converts \meta{text} to lower case}, note={\styfmt{textcase}\texparserdefnote}, @@ -15577,7 +15836,7 @@ has three or more items}, } @command{MakeTextUppercase, - name={\csfmt{MakeTextUppercase}}, + name={\csfmt{Make\-Text\-Upper\-case}}, user1={\margm{text}}, description={converts \meta{text} to \idx{uppercase}}, note={\styfmt{textcase}\texparserdefnote}, @@ -15585,7 +15844,7 @@ has three or more items}, } @command{NoCaseChange, - name={\csfmt{NoCaseChange}}, + name={\csfmt{No\-Case\-Change}}, user1={\margm{text}}, description={prevents \cs{MakeTextUppercase} and \cs{MakeTextLowercase} from converting \meta{text}}, @@ -15594,7 +15853,7 @@ has three or more items}, } @command{MakeUppercase, - name={\csfmt{MakeUppercase}}, + name={\csfmt{Make\-Upper\-case}}, user1={\margm{text}}, description={converts \meta{text} to \idx{uppercase}}, note={kernel command\texparserdefnote}, diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod index bf82acc2c2c..de6da0038b6 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod @@ -119,6 +119,25 @@ Merge an entry's B<wrglossary> records for the same page locations. Don't merge an entry's B<wrglossary> records. +=item B<--collapse-same-location-range> + +Collapse an explicit range that has a duplicate start and end +location into a normal record (default). + +=item B<--no-collapse-same-location-range> + +Don't collapse an explicit range that has a duplicate start and end +location into a normal record. + +=item B<--retain-formats> I<list> + +Indicates which location formats should always be retained even if +it causes a partial duplicate. Only exact duplicates will be merged. + +=item B<--no-retain-formats> + +Normal location merging rules apply (default). + =item B<--merge-nameref-on> I<rule> Rule for merging locations created with the B<record=nameref> package option diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index 30b252fd4a1..a18fcdfcfe3 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -4,7 +4,7 @@ % arara: lualatex if changed("glstex") || missing("toc") % arara: bib2gls: {group: on, packages: [mfirstuc-english]} % arara: lualatex -% arara: lualatex if found ("log", "Rerun") +% arara: lualatex \documentclass[titlepage=false,index=totoc,bibliography=totoc, fontsize=12pt,captions=tableheading]{scrreprt} @@ -46,7 +46,7 @@ \usepackage{scrhack} \usepackage[hidelinks]{hyperref} \usepackage{cleveref} -\usepackage[% v1.21+ +\usepackage[% v1.47+ record,% use bib2gls index,% create index glossary entrycounter,% enable entry counting @@ -186,6 +186,42 @@ save-child-count ] +\newglossary*{terms}{Glossary} +\GlsXtrLoadResources[src=bib2gls-terms,type=terms,save-locations=false,category=term] + +\newcommand{\igls}[2][]{% + \glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}% + \gls[#1]{#2}% +} +\newcommand{\iglspl}[2][]{% + \glsxtrifhasfield{useri}{#2}{\glsadd{\glscurrentfieldvalue}}{}% + \glspl[#1]{#2}% +} +\newcommand{\primary}{\glsdisp{primaryentry}{primary}} +\newcommand{\dual}{\glsdisp{dualentry}{dual}} +\newcommand{\parent}{\glsdisp{parententry}{parent}} +\newcommand{\child}{\glsdisp{childentry}{child}} +\newcommand{\children}{\glsdisp{childentry}{children}} +\newcommand{\hierarchicallevel}{\glsdisp{hierarchicalglossary}{hierarchical level}} +\newcommand{\hierarchical}{\glsdisp{hierarchicalglossary}{hierarchical}} +\newcommand{\hierarchically}{\glsdisp{hierarchicalglossary}{hierarchically}} +\newcommand{\hierarchy}{\glsdisp{hierarchicalglossary}{hierarchy}} +\newcommand{\mainglossary}{\glsdisp{mainglossary}{\code{main} glossary}} +\newcommand{\supplementallocation}{\glsdisp{supplementalrecord}{supplemental +location}} +\newcommand{\supplementallocations}{\glsdisp{supplementalrecord}{supplemental +locations}} +\newcommand{\supplementarylocation}{\glsdisp{supplementalrecord}{supplementary +location}} +\newcommand{\supplementarylocations}{\glsdisp{supplementalrecord}{supplementary +locations}} +\newcommand{\supplementarydocument}{\glsdisp{supplementaldocument}{supplementary +document}} +\newcommand{\supplementarydocuments}{\glsdisp{supplementaldocument}{supplementary +documents}} +\newcommand{\supplemental}{\glsdisp{supplementaldocument}{supplemental}} +\newcommand{\supplementary}{\glsdisp{supplementaldocument}{supplementary}} + \glsxtraddlabelprefix{} \glsxtraddlabelprefix{idx.} @@ -1317,13 +1353,13 @@ can select only those entries that have been used in the document, as well as any dependent entries, which reduces the \TeX\ resources required by not defining unnecessary commands. -Since \bibgls\ can also sort and collate the recorded locations +Since \bibgls\ can also sort and collate the recorded \glspl{location} present in the \ext{aux} file, it can simultaneously by-pass the need to use \idx!{makeindex} or \idx!{xindy}, although \bibgls\ can be used together with an external indexing application if required. (For example, if a custom \idx{xindy} rule is needed.) -An additional build may be required to ensure the locations are +An additional build may be required to ensure the \glspl{location} are up-to-date as the page-breaking may be slightly different on the first \LaTeX\ run due to the unknown references being replaced with ?? which can be significantly shorter than the actual text produced @@ -1352,11 +1388,39 @@ may prefer to start with if you are unfamiliar with the \sty{glossaries} and \sty{glossaries-extra} packages. \end{abstract} +Additional resources: +\begin{itemize} +\item +\href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}. +\item +\href{https://www.dickimaw-books.com/faq.php?category=bib2gls}{\bibgls\ FAQ} +\end{itemize} +TUGboat articles: +\begin{itemize} +\item +\href{http://tug.org/TUGboat/tb40-1/tb124talbot-bib2gls.pdf}{Glossaries +with \bibgls}, issue 40:1, 2019. +\item +\href{http://tug.org/TUGboat/tb41-3/tb129talbot-bib2gls-more.pdf}{\bibgls: +selection, cross-references and locations}, issue 41:3, 2020. +\item \bibgls: sorting, issue \href{http://tug.org/TUGboat/Contents/contents42-2.html}{42:2, 2021}. +\end{itemize} + \frontmatter \tableofcontents \listoftables \listoffigures +\printunsrtglossary*[type=terms,style=altlist,groups=false] +{% + \MFUhyphentrue + \glssetcategoryattribute{term}{glossname}{title}% + \renewcommand{\glslistitem}[1]{% + \item[\glsentryitem{#1}% + \glstarget{#1}{\glossentryname{#1}}]% + \glsxtrifhasfield{useri}{#1}{\glsadd{\glscurrentfieldvalue}}{}% + } +} \mainmatter \chapter{Introduction} @@ -1378,7 +1442,7 @@ can now be analogous to that used with \idx{bibtex} (or \appfmt{biber}), where only those entries that have been recorded in the document (and possibly their dependent entries) will be extracted from the \ext{bib} file. Since \bibgls\ can also perform -hierarchical sorting and can collate location lists, it doubles as +\hierarchical\ sorting and can collate \glspl{locationlist}, it doubles as an indexing application, which means that the \idx{makeglossaries} step can be skipped. Note that \bibgls\ doesn't warn you if an entry that's referenced @@ -1393,7 +1457,7 @@ by iterating over all defined entries and calling entries defined, so \ics{glsaddall} does nothing. If you want to select all entries, just use \csopt[all]{selection} instead (which has the advantage over \ics{glsaddall} in that it doesn't create a -redundant location for each entry). +redundant \gls{location} for each entry). Note that \bibgls\ requires the extension package \isty{glossaries-extra} and can't be used with just the base @@ -1523,7 +1587,7 @@ Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gl There are more examples provided in \sectionref{sec:examples}. Note that there's no need to called \idx!{xindy} or \idx!{makeindex} -since \bibgls\ automatically sorts the entries and collates the locations +since \bibgls\ automatically sorts the entries and collates the \glspl{location} after selecting the required entries from the \ext{bib} file and before writing the temporary file that's input with \gls{glsxtrresourcefile} (or the more convenient shortcut @@ -1544,7 +1608,7 @@ information that's used with the \ics{cs.makeglossaries} and \styfmt{glossaries} user manual~\cite{glossaries}). As from \styfmt{glossaries-extra} version 1.37, you can instead use \styopt[nameref]{record}, which saves some extra information for -each location that's not available for the other indexing methods. +each \gls{location} that's not available for the other indexing methods. See \longarg{merge-nameref-on} for further details. If you additionally want to use an indexing application, such @@ -1611,25 +1675,25 @@ assigned using \gls{glsxtrsetgrouptitle} within the document. \begin{important} \bibgls\ does not sort by group title. At most it can sort by the group label (by changing the \csopt{sort-field}) but this is usually -an indication that you actually have a hierarchical glossary and you +an indication that you actually have a \gls{hierarchicalglossary} and you ought to be using the \field{parent} field instead. (Compare \exfile{sample-textsymbols.tex} and \exfile{sample-textsymbols2.tex}.) \end{important} -\item[\field{parent}] An entry may have one or more sub-entries. -Most of the sort methods will produce a hierarchical ordering that -ensures that the sub-entries are listed immediately after their -parent entry. The parent entry is identified by the \field{parent} -field which should contain the parent's label. +\item[\field{parent}] An entry may have one or more \glspl{sub-entry}. +Most of the sort methods will produce a \hierarchical\ ordering that +ensures that the \glspl{sub-entry} are listed immediately after their +\gls{parententry}. The \gls{parententry} is identified by the \field{parent} +field which should contain the \glsdisp{parententry}{parent's} label. \begin{important} -\bibgls\ sorts the parent and child entries using the same -comparator. The sort methods listed -in \tableref{tab:sortoptionsnosort} disregard the hierarchical -level, which can result in child entries becoming detached from -their parent entry. The other methods sort hierarchically using -the same comparator but take the hierarchical level into account. +\bibgls\ sorts the \parent\ and \child\ entries using the same +comparator. The sort methods listed in +\tableref{tab:sortoptionsnosort} disregard the \hierarchicallevel, +which can result in \glspl{childentry} becoming detached from their +\gls{parententry}. The other methods sort \hierarchically\ using the +same comparator but take the \hierarchicallevel\ into account. \end{important} \end{description} @@ -1659,7 +1723,7 @@ Suppose that your list of symbols consists of pictographs, Latin characters and Greek characters and you want them grouped together in that order. Then you would use a separate \gls{GlsXtrLoadResources} for each block and assign your own custom -group. This means ensuring that each \idx{resourceset} only selects +group. This means ensuring that each \igls{resourceset} only selects the terms for that group. The simplest way of doing this is to have a separate \ext{bib} file for each set. For example: \begin{codeenv} @@ -1685,14 +1749,13 @@ have a separate \ext{bib} file for each set. For example: Suppose instead that you have many of these logical blocks and you want them ordered according to the block title. In this case you -have a hierarchical glossary and you need to use the \field{parent} +have a \gls{hierarchicalglossary} and you need to use the \field{parent} field. You then need to select an appropriate \idx{glossarystyle}. If you only want to have a single \ext{bib} file that contains all your entries and you want to share it across multiple documents then the most flexible approach is to use custom fields and entry types -that can be aliased according to the needs of the -\idxpl{resourceset}. +that can be aliased according to the needs of the \glspl{resourceset}. For example, the file \filefmt{entries.bib}: \begin{codeenv} @@ -1760,13 +1823,13 @@ This has a custom field \fieldfmt{identifier}. This will be ignored by \bibgls\ unless defined or aliased in the document. Here's an example document that creates three glossary types (the -default \code{main} glossary and the glossaries created with the +default \mainglossary\ and the glossaries created with the \styopt{abbreviations} and \styopt{symbols} options). They are listed in the order of \cs{printunsrtglossary} and their titles are added to the table of contents. The custom \fieldfmt{identifier} fields are ignored for the -main and abbreviation glossaries, but they are aliased for the +\glsdisp{mainglossary}{main} and abbreviation glossaries, but they are aliased for the symbols to the \field{group} field. Since I've split the symbols glossary into blocks with each block only containing entries that have the same \field{group} value, this isn't a problem. It also @@ -1813,7 +1876,7 @@ using \gls{glsxtrsetgrouptitle}. In the above example document, the symbols list is divided into three groups, listed in the order: Pictographs, Latin characters and Greek characters. If you want these titles ordered alphabetically -then you need a hierarchical structure instead. This can be obtained +then you need a \hierarchical\ structure instead. This can be obtained by aliasing the custom \fieldfmt{identifier} field to \field{parent}: \begin{codeenv} @@ -1852,7 +1915,7 @@ Greek characters, Latin characters and Pictographs. Some of the examples in this manual use \ics{newglossary*} to define a new glossary type and some use \ics{newignoredglossary} or \ics{newignoredglossary*}. Why the starred forms and why define an -\idx{ignoredglossary}? +\igls{ignoredglossary}? The base \styfmt{glossaries} package was originally designed to work with \idx!{makeindex}. Support for \idx!{xindy} was later added, but @@ -1873,7 +1936,7 @@ a hybrid method with \styopt[alsoindex]{record}.) Since some users wanted the ability to define entries that were common enough to not be worth including in any glossary lists, the -concept of an \idx{ignoredglossary} was introduced, defined with +concept of an \igls{ignoredglossary} was introduced, defined with \cs{newignoredglossary}. This only requires an internal control sequence to store the list of entry labels associated with that glossary\footnote{All entries must be assigned to a glossary. If you @@ -1890,7 +1953,7 @@ is still called, but because there's no associated file to write to, it has no effect. With \bibgls, the indexing is written to the \ext{aux} file and so does have an effect. -Although \idxpl{ignoredglossary} can't be used with +Although \iglspl{ignoredglossary} can't be used with \cs{printglossary}, they can be used with \cs{printunsrtglossary}, which is designed to work without any indexing, but you need to explicitly set the title in the optional argument to override the @@ -1908,7 +1971,7 @@ cases (see \exfile{sample-nested.tex} for an example). Since there is now the possibility of targets (created within \cs{printunsrtglossary} or \cs{printunsrtinnerglossary} or \cs{glsxtrglossentry}), it's convenient to -have an \idx{ignoredglossary} that doesn't suppress the hyperlinks, +have an \igls{ignoredglossary} that doesn't suppress the hyperlinks, which can be obtained with the starred form \ics{newignoredglossary*} provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}). @@ -1935,11 +1998,11 @@ used to test the existence of a glossary: \begin{codeenv} \ics{ifglossaryexists}\margm{label}\margm{true}\margm{false} \end{codeenv} -The unstarred version considers ignored glossaries as non-existent -(and so will do \meta{false} for an ignored glossary). As from +The unstarred version considers \glspl{ignoredglossary} as non-existent +(and so will do \meta{false} for an \gls{ignoredglossary}). As from v4.46, this command now has a starred version -\ics{ifglossaryexists*} that considers ignored glossaries as -existing (and so will do \meta{true} for an ignored glossary). In +\ics{ifglossaryexists*} that considers \glspl{ignoredglossary} as +existing (and so will do \meta{true} for an \gls{ignoredglossary}). In the event that you have an older version of \sty{glossaries}, the \sty{glossaries-extra} package (v1.44+) will provide the starred form if it hasn't been defined. (In general, it's best to have @@ -1950,12 +2013,12 @@ up-to-date versions of both \sty{glossaries} and \label{sec:resourcesets} Each instance of \gls{glsxtrresourcefile} or -\gls{GlsXtrLoadResources} in the document represents a \idx{resourceset}. Each -\idx{resourceset} has one or more associated \iext{bib} files +\gls{GlsXtrLoadResources} in the document represents a \igls{resourceset}. Each +\igls{resourceset} has one or more associated \iext{bib} files that provides the data for that set. Command line switches -(\sectionref{sec:switches}) are applied to all \idxpl{resourceset}. +(\sectionref{sec:switches}) are applied to all \iglspl{resourceset}. Resource options (\sectionref{sec:resourceopts}) are only applied to -that specific \idx{resourceset}. Each \idx{resourceset} is processed +that specific \igls{resourceset}. Each \igls{resourceset} is processed in stages: \begin{description} @@ -1969,11 +2032,11 @@ Initialising resource \meta{resource-name} at this point. \item[Stage 2 (Parsing)] All the \iext{bib} files associated with -the \idx{resourceset} are parsed. Entry aliases (identified by +the \igls{resourceset} are parsed. Entry aliases (identified by \csopt{entry-type-aliases}) are performed. The \hyperref[sec:multientry]{multi-entry types}, such as \atentry{bibtexentry} and \atentry{progenitor}, spawn their -associated primary entries. Preamble information (provided by +associated \glspl{primaryentry}. Preamble information (provided by \atentry{preamble}) is saved but is not interpreted at this stage. The transcript will show the message \begin{alltt} @@ -2073,8 +2136,8 @@ the corresponding set of \ext{bib} files: \item check for \field{nonumberlist}. \end{itemize} \item The dual version (if appropriate) is created. -\item Records are added to the entry's location list (or transferred -to the dual\slash primary according to \csopt{combine-dual-locations}). +\item \Glspl{record} are added to the entry's \igls{locationlist} (or transferred +to the \dual\slash\primary\ according to \csopt{combine-dual-locations}). \item The \field{type}, \field{category} and \field{counter} fields are set according to \csopt{type}, \csopt{dual-type}, \csopt{category}, \csopt{dual-category}, \csopt{counter} and @@ -2089,10 +2152,11 @@ see]{selection}). \csopt{date-time-fields}, \csopt{date-fields} or \csopt{time-fields} are converted. \end{itemize} -If \csopt[recorded and deps and see]{selection} then any recorded -entries that have been cross-referenced by an unrecorded entry, will -register a dependency with the unrecorded entry. Finally, -supplemental records are added to entries. +If \csopt[recorded and deps and see]{selection} then any +\glspl{recordedentry} that have been cross-referenced by an +\gls{unrecordedentry}, will register a dependency with the +\gls{unrecordedentry}. Finally, \glspl{supplementalrecord} are added to +entries. \item[Stage 4 (Selection, Sorting, Writing)] Entries are selected from the list according to the \csopt{selection} setting, sorting is @@ -2110,34 +2174,34 @@ at this point. \end{description} -Parent entries must always be in the same \idx{resourceset} as their -child entries. (They may be defined in different \ext{bib} files as +Parent entries must always be in the same \igls{resourceset} as their +\glspl{childentry}. (They may be defined in different \ext{bib} files as long as all those \ext{bib} files are listed in the same \csopt{src}.) Other forms of dependencies may be in a -different \idx{resourceset} under certain circumstances. These types +different \igls{resourceset} under certain circumstances. These types of dependencies are instances of commands such as \cs{gls} being found (for example, in the \field{description} field), or the -cross-reference fields (\field{see}, \field{seealso} or +\glspl{cross-referencefield} (\field{see}, \field{seealso} or \field{alias} or fields identified with \csopt{dependency-fields}) -in recorded entries that reference unrecorded entries. +in \glspl{recordedentry} that reference \glspl{unrecordedentry}. The \qt{cross-referenced by} dependencies enabled with -\csopt[recorded and deps and see]{selection} (where an unrecorded -entry references a recorded entry through the cross-reference -fields) \emph{aren't supported} across \idxpl{resourceset} (even with -\longarg{force-cross-resource-refs}). - -A \idx{crossresourceref} is a reference from a recorded entry provided in one -\idx{resourceset} to an unrecorded entry in another \idx{resourceset}. -Since -the contents of each \idx{resourceset}['s] preamble must be -processed before fields can be interpreted and one -\idx{resourceset}['s] preamble may contain definitions that override -another, \idxpl{crossresourceref} can't be supported if fields -containing cross-referencing information need to be interpreted. - -The \idx{crossresourceref} mode determines whether or not \bibgls\ -can support \idxpl{crossresourceref}. If enabled, the message +\csopt[recorded and deps and see]{selection} (where an +\gls{unrecordedentry} references a \gls{recordedentry} through the +\glspl{cross-referencefield}) \emph{aren't supported} across +\iglspl{resourceset} (even with \longarg{force-cross-resource-refs}). + +A \igls{crossresourceref} is a reference from a \gls{recordedentry} +provided in one \igls{resourceset} to an \gls{unrecordedentry} in +another \igls{resourceset}. Since the contents of each +\igls{resourceset}['s] preamble must be processed before fields can +be interpreted and one \igls{resourceset}['s] preamble may contain +definitions that override another, \iglspl{crossresourceref} can't +be supported if fields containing cross-referencing information need +to be interpreted. + +The \igls{crossresourceref} mode determines whether or not \bibgls\ +can support \iglspl{crossresourceref}. If enabled, the message \begin{verbatim} Cross-resource references allowed. \end{verbatim} @@ -2148,28 +2212,28 @@ Cross-resource references disabled. The mode can only be enabled if the following condition is satisfied: \begin{itemize} \item the interpreter is off (\longarg{no-interpret}), or -\item every \idx{resourceset} either doesn't have a preamble +\item every \igls{resourceset} either doesn't have a preamble (\atentry{preamble}) or has \csopt[false]{interpret-preamble} set. \end{itemize} If you know the preamble contents won't cause a problem, you -can force the \idxpl{crossresourceref} mode on with +can force the \iglspl{crossresourceref} mode on with \longarg{force-cross-resource-refs}. If you don't use either \csopt[recorded and deps]{selection} or \csopt[recorded and deps and see]{selection} -then the dependencies aren't picked up for that \idx{resourceset} -(and so can't be cross-referenced from another \idx{resourceset}). +then the dependencies aren't picked up for that \igls{resourceset} +(and so can't be cross-referenced from another \igls{resourceset}). -Trails don't work with \idxpl{crossresourceref}. For example, if +Trails don't work with \iglspl{crossresourceref}. For example, if entry $A$ has been recorded and depends on entry $B$ that hasn't been recorded, then $B$ can be picked up from a different -\idx{resourceset}, but if $A$ and $B$ are in the same -\idx{resourceset} and $B$ is dependent on $C$ which is in a -different \idx{resourceset} then $C$ won't be picked up if it hasn't +\igls{resourceset}, but if $A$ and $B$ are in the same +\igls{resourceset} and $B$ is dependent on $C$ which is in a +different \igls{resourceset} then $C$ won't be picked up if it hasn't been recorded because $B$ hasn't been recorded and is in a different -\idx{resourceset}. +\igls{resourceset}. -If the \idx{crossresourceref} mode is enabled then stage~3 and +If the \igls{crossresourceref} mode is enabled then stage~3 and stage~4 are processed in separate \idxpl{loop}, otherwise they are processed in the same \idx{loop}. @@ -2339,7 +2403,7 @@ parse the \meta{options} part in each instance of \gls{glsxtr@resource} for \csopt{src} and determine if the corresponding \ext{bib} file or files are newer than the \ext{tex} file. -It's not possible to determine if the location lists require +It's not possible to determine if the \glspl{locationlist} require updating, just as it's not possible to do this for the \idx{toc}, list of figures, list of tables etc. (Or, if it could be implemented, the required code would make the document build far @@ -2545,7 +2609,7 @@ glossary-related commands listed in \tableref{tab:bibglsdefs}. These may be overridden by custom packages provided with the \longarg{custom-packages} switch. Note that commands that reference an entry, such as \cs{glsentryname}, aren't guaranteed to work -across \idxpl{resourceset} and will only be able to look up field +across \iglspl{resourceset} and will only be able to look up field values that are known to \bibgls. (For example, the \field{name} field for abbreviations is typically set by the associated abbreviation style, which isn't available to \bibgls.) @@ -3089,17 +3153,27 @@ will issue a warning with this option set (default). This option will suppress the warning if an unknown entry types are found in the \ext{bib} file. +\argsection{collapse-same-location-range} + +Collapse any explicit \gls{location} range into a normal \gls{record} if +the \glspl{location} are the same (default). + +\argsection{no-collapse-same-location-range} + +Don't collapse any explicit \gls{location} range into a normal +\gls{record} if the \glspl{location} are the same. + \argsection{merge-wrglossary-records} For use with the \styopt{indexcounter} package option (\styfmt{glossaries-extra} v1.29+), this switch merges an entry's -\counter{wrglossary} records for the same page location. This is the +\counter{wrglossary} records for the same page \gls{location}. This is the default setting. (See also \csopt{save-index-counter}.) \argsection{no-merge-wrglossary-records} Don't merge an entry's \counter{wrglossary} records. This means that you -may end up with duplicate page numbers in the entry's location list, +may end up with duplicate page numbers in the entry's \gls{locationlist}, but they will link to different parts of the page. \argsection{merge-nameref-on} @@ -3119,7 +3193,7 @@ will always be empty. The most reliable target is given by associated counter name and \meta{hcounter} is obtained from \cs{theHentrycounter}, which is set to the hyper target command \csfmt{theH}\meta{counter} during indexing. Since -this information can't be included in the location when indexing +this information can't be included in the \gls{location} when indexing with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries} package tries to obtain a prefix from which the target name can be formed. This doesn't work if \csfmt{theH}\meta{counter} can't be @@ -3130,11 +3204,11 @@ the document to choose whether to use \meta{href} (to link to the nearest anchor) or \meta{hcounter} to link to the place where the indexing counter was incremented. -The \code{nameref} record will be written to the \idx{locationlist} using: +The \code{nameref} record will be written to the \igls{locationlist} using: \nosecdef{glsxtrdisplaylocnameref} -The \meta{file} part will be empty for normal internal locations, -and will be set to the corresponding file name for supplemental -locations. +The \meta{file} part will be empty for normal internal \glspl{location}, +and will be set to the corresponding file name for +\glsdisp{supplementalrecord}{supplemental locations}. With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be \code{Doc-Start} at the start of the document and is updated @@ -3168,12 +3242,12 @@ details. \argsection{force-cross-resource-refs} -Force \idx{crossresourceref} mode on (see +Force \igls{crossresourceref} mode on (see \sectionref{sec:resourcesets}). \argsection{no-force-cross-resource-refs} -Don't force \idx{crossresourceref} mode on (default). +Don't force \igls{crossresourceref} mode on (default). The mode will be enabled if applicable (see \sectionref{sec:resourcesets}). @@ -3402,7 +3476,7 @@ but in general there is little need to use this switch. \argsection{map-format} -This sets up the rule of precedence for partial location +This sets up the rule of precedence for partial \gls{location} matches (see \sectionref{sec:locationopts}). The argument may be a comma-separated list of \meta{map}\code{:}\meta{value} pairs. Alternatively, you can have multiple instances of @@ -3413,7 +3487,7 @@ For example, \begin{verbatim} bib2gls --map-format "emph:hyperbf" mydoc \end{verbatim} -This essentially means that if there's a record conflict +This essentially means that if there's a \gls{record} conflict involving \encap{emph}, try replacing \encap{emph} with \encap{hyperbf} and see if that resolves the conflict. @@ -3435,19 +3509,19 @@ or \begin{verbatim} bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc \end{verbatim} -then \bibgls\ will process these records as follows: +then \bibgls\ will process these \glspl{record} as follows: \begin{enumerate} -\item Accept the first record (\encap{emph}) since there's -currently no conflict. (This is the first record for page~3 for the +\item Accept the first \gls{record} (\encap{emph}) since there's +currently no conflict. (This is the first \gls{record} for page~3 for the entry given by \code{gls.sample}.) -\item The second record (\encap{hypersf}) conflicts -with the existing record (\encap{emph}). Neither has +\item The second \gls{record} (\encap{hypersf}) conflicts +with the existing \gls{record} (\encap{emph}). Neither has the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ consults the mappings provided by \longargfmt{map-format}. \begin{itemize} \item The \encap{hypersf} format (from the new record) is mapped to \encap{hyperit}, -so \bibgls\ checks if the existing record +so \bibgls\ checks if the existing \gls{record} has this format. In this case it doesn't (the format is \code{emph}). So \bibgls\ moves on to the next test: @@ -3461,19 +3535,19 @@ the new record is discarded with a warning. Note that there's no look ahead to the next record. (There may be other records for other entries also used on page~3 interspersed between these records.) \end{itemize} -\item The third record (\encap{hyperbf}) conflicts -with the existing record (\encap{emph}). Neither has +\item The third \gls{record} (\encap{hyperbf}) conflicts +with the existing \gls{record} (\encap{emph}). Neither has the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ again consults the mappings provided by \longargfmt{map-format}. \begin{itemize} -\item The new record's \encap{hyperbf} format has no mapping provided, +\item The new \gls{record}['s] \encap{hyperbf} format has no mapping provided, so \bibgls\ moves on to the next test: -\item The existing record's \encap{emph} format has a mapping -provided (\encap{hyperbf}). This matches the new record's format, -so the new record takes precedence. +\item The existing \gls{record}['s] \encap{emph} format has a mapping +provided (\encap{hyperbf}). This matches the new \gls{record}['s] format, +so the new \gls{record} takes precedence. -This means that the location list ends up with the \encap{hyperbf} +This means that the \gls{locationlist} ends up with the \encap{hyperbf} location for page~3. \end{itemize} \end{enumerate} @@ -3482,14 +3556,35 @@ If, on the other hand, the mappings are given as \begin{verbatim} --map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit" \end{verbatim} -then all the three conflicting records (\encap{emph}, +then all the three conflicting \glspl{record} (\encap{emph}, \encap{hypersf} and \encap{hyperbf}) will end up being replaced -by a single record with \encap{hyperit} as the format. +by a single \gls{record} with \encap{hyperit} as the format. Multiple conflicts will typically be rare as there's usually little -reason for more than two or three different location formats within +reason for more than two or three different \gls{location} formats within the same list. (For example, \encap{glsnumberformat} as the default -and \encap{hyperbf} or \encap{hyperit} for a primary reference.) +and \encap{hyperbf} or \encap{hyperit} for a +\gls{principallocation}.) + +\argsection{retain-formats} + +It's possible that you may not want to lose certain \gls{location} +formats, even if it means having duplicate \glspl{location}. For example, +if you want to move a \gls{principallocation} using +\csopt[remove]{save-principal-locations}. In which case, use this +switch with a comma-separated list of formats that should be +retained. Note that exact duplicates will still be merged. +This switch has a cumulative effect. + +Take care if you use this switch and you have an explicit range with +coincident start and end locations. If the +\glsdisp{principallocation}{principal record} is between +the start and end format markers then the range can't collapse +to an ordinary \gls{record}. + +\argsection{no-retain-formats} + +Normal \gls{location} merging rules apply (default). \argsection{group} @@ -3510,14 +3605,16 @@ switch doesn't automatically select an appropriate glossary style. \begin{important} The \field{group} field should typically not be set in the \ext{bib} file and will trigger a warning if found. The explicit use of the -\field{group} key will override \bibgls's normal group formation behaviour, -which can cause unexpected results. The custom use of the +\field{group} key will override \bibgls's normal group formation +behaviour, which can cause unexpected results. The custom use of the \field{group} field requires some care. As a general rule, if you -find yourself wanting to use the \field{group} field in the \ext{bib} file, -then the chances are that what you actually have is a hierarchical -glossary (list of topics) and what you really need is the \field{parent} field. -Compare the example files \exfile{sample-textsymbols.tex} and -\exfile{sample-textsymbols2.tex}. See also \sectionref{sec:logicaldivisions}. +find yourself wanting to use the \field{group} field in the +\ext{bib} file, then the chances are that what you actually have is +a \gls{hierarchicalglossary} (list of topics) and what you really +need is the \field{parent} field. Compare the example files +\exfile{sample-textsymbols.tex} and +\exfile{sample-textsymbols2.tex}. See also +\sectionref{sec:logicaldivisions}. \end{important} There are eight types of groups: \begin{description} @@ -3700,38 +3797,38 @@ group style, such as \glostyle{indexgroup}, is used (unless the \argsection{tex-encoding} -\bibgls\ tries to determine the character encoding to use for the +\bibgls\ tries to determine the character \igls{encoding} to use for the output files. If the document has loaded the \isty{inputenc} package then -\bibgls\ can obtain the value of the encoding from the +\bibgls\ can obtain the value of the \gls{encoding} from the \iext{aux} file. This is then converted to a name recognised by Java. For example, \code{utf8} will be mapped to \code{UTF-8}. If the \isty{fontspec} package has been loaded, -\styfmt{glossaries-extra} will assume the encoding is \code{utf8} and +\styfmt{glossaries-extra} will assume the \gls{encoding} is \code{utf8} and write that value to the \ext{aux} file. If neither package has been loaded, \bibgls\ will assume the \idx{JVM}['s] -default encoding (identified by the \code{file.encoding} property). If this is +default \gls{encoding} (identified by the \code{file.encoding} property). If this is incorrect or if \bibgls\ can't work out the appropriate mapping then you can -specify the correct encoding using \longargfmt{tex-encoding} \meta{name} where -\meta{name} is the encoding name (such as \code{UTF-8}). +specify the correct \gls{encoding} using \longargfmt{tex-encoding} \meta{name} where +\meta{name} is the \gls{encoding} name (such as \code{UTF-8}). If you have a problem with non-ASCII characters not displaying correctly in your document: \begin{itemize} -\item Check that the file encoding of your document \ext{tex} file (or files) +\item Check that the file \gls{encoding} of your document \ext{tex} file (or files) has been correctly set by your text editor. -\item Check that your document supports that encoding (for example, +\item Check that your document supports that \gls{encoding} (for example, through the \isty{inputenc} package). \item Check \bibgls's transcript file (\ext{glg}) for the line that starts \begin{verbatim} TeX character encoding: \end{verbatim} -This should be followed by the encoding used by \bibgls\ when +This should be followed by the \gls{encoding} used by \bibgls\ when creating the \ext{glstex} files. If this is incorrect use \longargfmt{tex-encoding}. -\item Check that the encoding of the \ext{bib} files (set by your -text editor or bibliographic management system) matches the encoding +\item Check that the \gls{encoding} of the \ext{bib} files (set by your +text editor or bibliographic management system) matches the \gls{encoding} line in the \ext{bib} file or the \csopt{charset} resource option. \end{itemize} @@ -3874,11 +3971,11 @@ it does \nosecdef{rglsformat} instead. If the use of \gls{rglsformat} is triggered in this way, -then \gls{rgls} writes a record to the \iext{aux} file +then \gls{rgls} writes a \gls{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 \idx{ignoredrecord}. +This ensures that the \gls{recordcount} is correct on the next run, +but the \gls{record} isn't added to the \gls{locationlist} as +\bibgls\ recognises it as a special \igls{ignoredrecord}. Note that the entry will still appear in the usual glossary unless you assign it to a different one with \csopt{trigger-type}. @@ -3956,7 +4053,7 @@ replaced by the value of the \csopt{dual-prefix} option. The different set of resources (loaded by another \gls{GlsXtrLoadResources} command). This prefix is replaced by the corresponding element of the list supplied by \csopt{ext-prefixes}, -but this is only supported if the \idx{crossresourceref} mode is enabled +but this is only supported if the \igls{crossresourceref} mode is enabled (see \sectionref{sec:resourcesets}). In the event that the \field{sort} value falls back on the label, @@ -3967,24 +4064,32 @@ prefixed label. \label{sec:bibencoding} Avoid \idx{non-ASCII} characters in the \meta{id} if your document uses the -\isty{inputenc} package. (This isn't a problem for \XeLaTeX\ or +\isty{inputenc} package. +(This isn't a problem for \XeLaTeX\ or \LuaLaTeX, but you still need to avoid special characters.) -You can set the character \idx{encoding} in the \ext{bib} file using: +You can set the character \igls{encoding} in the \ext{bib} file using: \begin{codeenv} \idx{commentchar} Encoding: \meta{encoding-name} \end{codeenv} -where \meta{encoding-name} is the name of the character encoding. +where \meta{encoding-name} is the name of the character \gls{encoding}. For example: \begin{verbatim} % Encoding: UTF-8 \end{verbatim} -You can also set the encoding using the \csopt{charset} option, +You can also set the \gls{encoding} using the \csopt{charset} option, but it's simpler to include the above comment on the first line of the \ext{bib} file. (This comment is also searched for by JabRef -to determine the encoding, so it works for both applications.) +to determine the \gls{encoding}, so it works for both applications.) If you don't use either method \bibgls\ will have to search the entire \ext{bib} file, which is inefficient and -you may end up with a mismatched encoding. +you may end up with a mismatched \gls{encoding}. + +Note that recent changes to the \LaTeX\ kernel now allow +\idx{non-ASCII} characters in labels when using commands such as +\cs{label} (with \sty{inputenc}). The commands used by the +\sty{glossaries} package are more complicated, but changes have been +made in \sty{glossaries} v4.47 and \sty{glossaries-extra} v1.46 to +help support this, however it hasn't been fully tested. \section{Comments} \label{sec:bibcomments} @@ -4008,13 +4113,9 @@ treated as a comment character and other unwanted material should be omitted. Avoid using comments within field values. Comments are best placed outside of entry definitions. -The most common type of comment is the encoding comment, described +The most common type of comment is the \gls{encoding} comment, described above. \BibTeX's \entrydef{comment} is also supported by \bibgls\ -for general comments, but not for the encoding. For example, JabRef -uses \atentryfmt{Comment} for metadata. -\begin{codeenv} -\atentryfmt{Comment}\marg{jabref-meta: databaseType:bib2gls;} -\end{codeenv} +for general comments, but not for the \gls{encoding}. \section{Fields} \label{sec:fields} @@ -4073,8 +4174,8 @@ Other entries can be cross-referenced using the \field{see}, 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 \idx{ignoredrecord} and the +rebuild the document to ensure the \glspl{locationlist} are correct. Use +of the \ics{glssee} command will create an \igls{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 @@ -4102,7 +4203,7 @@ You can identify an arbitrary field as containing a list of dependent entry labels with \csopt{dependency-fields}. This instructs \bibgls\ to parse the listed fields for dependencies in a similar manner to the \field{see} field, but it doesn't add any information to the cross-referencing part of the -location list. The option may be used in combination with the \field{see} or +\gls{locationlist}. The option may be used in combination with the \field{see} or \field{seealso} fields. \clearpage @@ -4506,9 +4607,9 @@ For example: If the \field{sort} field is missing the default is obtained from the \field{name} field (unless overridden by options like -\csopt{entry-sort-fallback}). For hierarchical entries, if the -\field{name} field is omitted it will be obtained from the parent's -\field{name}. +\csopt{entry-sort-fallback}). For \hierarchical\ entries, if the +\field{name} field is omitted it will be obtained from the +\glsdisp{parententry}{parent's} \field{name}. Terms defined using \atentry{entry} will be written to the output (\ext{glstex}) file using the command \gls!{bibglsnewentry}. @@ -4588,8 +4689,8 @@ The \atentry{index} entry type is designed for entries that don't have a description. Only the label is required. If \field{name} is omitted, it's assumed to be the same as the label, even if \field{parent} is present. (Note this is different to the fallback -behaviour of \atentry{entry}, which fetches the name from the parent -entry.) If the name contains any characters that can't be used in +behaviour of \atentry{entry}, which fetches the name from the +\gls{parententry}.) If the name contains any characters that can't be used in the label, you must use the \field{name} field. If the \field{sort} field is missing the default is obtained from the \field{name}. Note that the \atentry{index} entry type is \emph{not} governed by @@ -4822,17 +4923,20 @@ corresponding \atentry{bibtexentry} then you will end up with a label clash. The entry types described in this section create two separate (but related) \styfmt{glossaries-extra} entry definitions per \ext{bib} entry. The first of these entries is considered the -\idx{primary} entry, and the second is the \idx{dual} entry -(also referred to as the \idx{secondary} entry, but is not -related to the \csopt{secondary} option). The naming scheme is -\code{@dual}\meta{entry-type} where both the primary and dual are -considered to have the same type of entry (such as -\atentry{dualsymbol} where both the primary and dual are -functionally like \atentry{symbol}) or -\code{@dual}\meta{primary}\meta{dual} where the primary -is functionally like \code{@}\meta{primary} and the dual is +\igls{primaryentry}, and the second is the \igls{dualentry}. +The naming scheme is \code{@dual}\meta{entry-type} where both the +\primary\ and \dual\ are considered to have the same type of entry +(such as \atentry{dualsymbol} where both the \primary\ and \dual\ +are functionally like \atentry{symbol}) or +\code{@dual}\meta{primary}\meta{dual} where the \primary\ is +functionally like \code{@}\meta{primary} and the \dual\ is functionally like \code{@}\meta{dual}. +If you need a field to store the \glsdisp{dualentry}{dual} +description in (and you're not simply swapping known fields around), +then you can use the special \field{dualdescription} field and add +it to your map. + If the fields provided by the \isty{glossaries-prefix} are defined, there will be additional mappings for the special internal fields \field{dualprefix}, \field{dualprefixfirst}, @@ -4865,23 +4969,23 @@ and is analogous to: \field{description}=\marg{statistical pattern recognition technique}} \end{codeenv} but both entries are considered dependent on each other. This means -that if you only reference the primary entry (using \ics{gls} etc) -then the dual entry will still be selected if the \csopt{selection} +that if you only reference the \gls{primaryentry} (using \ics{gls} etc) +then the \gls{dualentry} will still be selected if the \csopt{selection} setting includes dependencies. -The creation of the dual entry involves mapping or copying fields -from the primary entry. Each dual entry type has a set of mappings. +The creation of the \gls{dualentry} involves mapping or copying fields +from the \gls{primaryentry}. Each \gls{dualentry} type has a set of mappings. If a field in the set of mappings is missing, its fallback value is used. Any fields that aren't listed in the mappings are simply copied, except for the \field{alias} field, which will never be copied to -the dual entry, nor can it be mapped. The alias will only apply to -the primary entry. The dual entry is given the label +the \gls{dualentry}, nor can it be mapped. The alias will only apply to +the \gls{primaryentry}. The \gls{dualentry} is given the label \meta{prefix}\meta{id} where \meta{prefix} is set by the \csopt{dual-prefix} option and \meta{id} is the label supplied in the \ext{bib} file. -If \csopt[combine]{dual-sort} then the dual entries will be sorted -along with the primary entries, otherwise the \csopt{dual-sort} +If \csopt[combine]{dual-sort} then the \glspl{dualentry} will be sorted +along with the \glspl{primaryentry}, otherwise the \csopt{dual-sort} indicates how to sort the dual entries and the dual entries will be appended to the end of the \ext{glstex} file. The \csopt{dual-sort-field} determines what field to use for the sort @@ -4891,7 +4995,7 @@ Take care if you have a mixture of entry types (such as \atentry{dualindexentry}, \atentry{dualindexsymbol} and \atentry{index}) and you're not using the default \csopt[combine]{dual-sort}. Remember that the -primary entries are all sorted together along with the single +\glspl{primaryentry} are all sorted together along with the single entries types described in \sectionref{sec:dualentry} (but they may be assigned to different glossary types), and then the dual entries are sorted together (but may be assigned to different glossary @@ -4900,8 +5004,8 @@ and some of the duals are assigned to the same glossary. For example, don't mix \atentry{dualindexabbreviation} (duals are abbreviations) with \atentry{dualabbreviationentry} (primaries are abbreviations) when you aren't using \csopt[combine]{dual-sort} -(unless you have two different glossaries for the primary vs dual -abbreviations). +(unless you have two different glossaries for the \primary\ vs +\dual\ abbreviations). Remember that \bibgls\ is designed to take advantage of \ics{printunsrtglossary}, which simply iterates over all defined @@ -4938,9 +5042,9 @@ For example, suppose the file \filefmt{entries.bib} contains: } \end{codeenv} This contains a mixture of entry types, including -\atentry{dualindexabbreviation} (where the dual is the +\atentry{dualindexabbreviation} (where the \dual\ is the abbreviation) and \atentry{dualabbreviationentry} (where the -primary is the abbreviation). +\primary\ is the abbreviation). Now consider the following document: \begin{codeenv} @@ -4974,35 +5078,35 @@ The \LaTeX\ code written to the \iext{glstex} file is essentially \comment{from \atentry{index}\marg{aardvark}:} \gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} \strut -\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} \gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\marg{text}=\marg{CSS}, \field{description}=\marg{a language that describes the style of an \cs{glsxtrshort}\marg{html} document}} \strut -\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} \gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} \strut -\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} \gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} \strut -\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} \gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} \strut \comment{from \atentry{index}\marg{mouse}:} \gls{newglossaryentry}\marg{mouse}{\marg{name}=\marg{mouse},\field{description}=\marg{}} \strut -\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} \gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages evaluated by the server}} \strut -\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} \gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} \strut -\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} \gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} \strut -\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} \gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} \strut \comment{from \atentry{index}\marg{zebra}:} @@ -5011,7 +5115,7 @@ The \LaTeX\ code written to the \iext{glstex} file is essentially Since the document uses the \styopt{abbreviations} package option, \gls{newabbreviation} automatically assigns the abbreviation to the \code{abbreviations} glossary (created through that package -option). This means that the \code{main} (default) glossary +option). This means that the \glsdisp{mainglossary}{\code{main} (default) glossary} contains the entries (in order): \begin{itemize} \item \code{aardvark} (name: aardvark), @@ -5035,17 +5139,17 @@ resulting glossaries are both ordered alphabetically (using \field{short} for the abbreviations and \field{name} for the rest), but note that you need to take care when referencing the abbreviations if you want to make use of the abbreviation style. You -need \verb|\gls{css}| and \verb|\gls{ssi}| for the primary +need \verb|\gls{css}| and \verb|\gls{ssi}| for the \primary\ abbreviations created with \atentry{dualabbreviationentry} and -\verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the dual +\verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the \dual\ abbreviations created with \atentry{dualindexabbreviation}. Also -the \field{name} of the primary\slash dual alternative of the +the \field{name} of the \primary\slash \dual\ alternative of the abbreviations is also inconsistent (short form for \code{html} and \code{xml} and long form for \code{dual.css} and \code{dual.ssi}), as different field mappings are used. -If the document is changed so that the dual entries are now -sorted and written after all the primary entries have been dealt +If the document is changed so that the \glspl{dualentry} are now +sorted and written after all the \glspl{primaryentry} have been dealt with: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ @@ -5054,7 +5158,7 @@ with: \csopt[all]{selection} } \end{codeenv} -then \bibgls\ first orders the primaries: +then \bibgls\ first orders the \glsdisp{primaryentry}{primaries}: \begin{itemize} \item \code{aardvark} (name: aardvark), \item \code{css} (short: CSS), @@ -5070,25 +5174,25 @@ and writes them to the \ext{glstex} file \comment{from \atentry{index}\marg{aardvark}:} \gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}} \strut -\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\comment{\primary\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} \gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} \strut -\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\comment{\primary\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} \gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}} \strut \comment{from \atentry{index}\marg{mouse}:} \gls{newglossaryentry}\marg{mouse}\marg{\field{name}=\marg{mouse},\field{description}=\marg{}} \strut -\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\comment{\primary\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} \gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} \strut -\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\comment{\primary\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} \gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} \strut \comment{from \atentry{index}\marg{zebra}:} \gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} \end{codeenv} -Then \bibgls\ orders the duals: +Then \bibgls\ orders the \glsdisp{dualentry}{duals}: \begin{itemize} \item \code{dual.css} (name: cascading stylesheets), \item \code{dual.html} (short: HTML), @@ -5098,20 +5202,20 @@ Then \bibgls\ orders the duals: and writes them to the \ext{glstex} file (functionally like): \begin{codeenv} -\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:} +\comment{\dual\ of \atentry{dualabbreviationentry}\marg{css,\ldots}:} \gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\field{text}=\marg{CSS}, \field{description}=\marg{a language that describes the style of an \cs{glsxtrshort}\marg{html} document}} \strut -\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:} +\comment{\dual\ of \atentry{dualindexabbreviation}\marg{html,\ldots}:} \gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} \strut -\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} +\comment{\dual\ of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:} \gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI}, \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages evaluated by the server}} \strut -\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} +\comment{\dual\ of \atentry{dualindexabbreviation}\marg{xml,\ldots}:} \gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language} \end{codeenv} When the \ext{glstex} file is input (during the next \LaTeX\ run) @@ -5129,7 +5233,7 @@ the entries are defined in the order: \item \code{dual.ssi} (type: \code{main}), \item \code{dual.xml} (type: \code{abbreviations}). \end{enumerate} -This means that the \code{main} glossary's internal list is in the +This means that the \glsdisp{mainglossary}{\code{main} glossary's} internal list is in the order: \begin{itemize} \item \code{aardvark} (aardvark), @@ -5148,7 +5252,7 @@ and the \code{abbreviations} glossary's internal list is in the order: \item \code{dual.xml} (XML). \end{itemize} The lists are no longer in alphabetical order as they have a mixture -of primary and dual entries that were separated before sorting. +of \primary\ and \dual\ entries that were separated before sorting. The above is a fairly contrived example as it wouldn't make sense in a real document to have glossary terms (that include a @@ -5162,7 +5266,7 @@ A better solution would be to use The \atentry{dualentry} entry type is similar to \atentry{entry} but actually defines two entries. -The dual entry contains the same information as the primary entry +The \gls{dualentry} contains the same information as the \gls{primaryentry} but some of the fields are swapped around. The default mappings are: \begin{itemize} @@ -5211,9 +5315,9 @@ is like: \end{codeenv} where \idprefix{dual} is replaced by the value of the \csopt{dual-prefix} option. However, instead of defining the entries -with \csfmt{bibglsnewentry} both the primary and dual entries are +with \csfmt{bibglsnewentry} both the \primary\ and \dual\ entries are defined using \gls!{bibglsnewdualentry}. The \field{category} -and \field{type} fields can be set for the dual entry using the +and \field{type} fields can be set for the \gls{dualentry} using the \csopt{dual-category} and \csopt{dual-type} options. For example: @@ -5223,19 +5327,35 @@ For example: \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[entries-dual]{src},\comment{data in entries-dual.bib} - \csopt[english]{type},\comment{put primary entries in glossary 'english'} - \csopt[french]{dual-type},\comment{put dual entries in glossary 'french'} - \csopt[dictionary]{category},\comment{set the primary category to 'dictionary'} - \csopt[dictionary]{dual-category},\comment{set the dual category to 'dictionary'} - \csopt[en]{sort},\comment{sort primary entries according to language 'en'} - \csopt[fr]{dual-sort}\comment{sort dual entries according to language 'fr'} + \csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'} + \csopt[french]{dual-type},\comment{put \glspl{dualentry} in glossary 'french'} + \csopt[dictionary]{category},\comment{set the \primary\ category to 'dictionary'} + \csopt[dictionary]{dual-category},\comment{set the \dual\ category to 'dictionary'} + \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} + \csopt[fr]{dual-sort}\comment{sort \glspl{dualentry} according to language 'fr'} } \end{codeenv} +If you need to keep the same name but have different descriptions +then you can use \field{dualdescription} and set up a mapping to use +it. For example: +\begin{codeenv} +\atentry{dualentry}\marg{sample, + \field{name}=\marg{sample}, + \field{description}=\marg{\primary\ sample description}, + \field{dualdescription}=\marg{\dual\ sample description} +} +\end{codeenv} +The mapping can then be: +\begin{codeenv} +\csopt[\marg{\field{description}}, + \marg{\field{dualdescription}}]{dual-entry-map} +\end{codeenv} + \entrysection{dualindexentry} -There are no required fields. The primary -entry behaves like \atentry{index} and the dual entry behaves +There are no required fields. The \gls{primaryentry} behaves like +\atentry{index} and the \gls{dualentry} behaves like \atentry{entry}. The default field mapping is: \begin{itemize} \item \field{name} $\mapsto$ \field{name} @@ -5254,13 +5374,13 @@ additionally include: \end{itemize} This doesn't actually perform any swapping of fields, but it provides the field used for backlinks (if -\csopt{dual-indexentry-backlink} is set). The reason that the primary -(rather than the dual) is like \atentry{index} is to allow the +\csopt{dual-indexentry-backlink} is set). The reason that the +\primary\ (rather than the \dual) is like \atentry{index} is to allow the primaries to merge with any \atentry{index} entries found in the resource set, since glossary entries with descriptions are likely to be a subset of all indexed entries. -If no \field{name} is given, the dual entry is assigned the +If no \field{name} is given, the \gls{dualentry} is assigned the (unprefixed) entry label. For example: \begin{codeenv} \atentry{dualindexentry}\marg{array, @@ -5276,11 +5396,11 @@ This is effectively like: \field{description}=\marg{ordered list of values} } \end{codeenv} -The primary entries are defined using +The \glspl{primaryentry} are defined using \gls!{bibglsnewdualindexentry}, which by default sets the \field{category} to \optfmt{index} (although this may be overridden, for example, by the \csopt{category} option). -The dual entries are defined with +The \glspl{dualentry} are defined with \gls!{bibglsnewdualindexentrysecondary}. This is the most convenient way of having an entry that's also @@ -5341,8 +5461,8 @@ index and a glossary: \cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[mcolindexgroup]{style}} \cmd{end}\marg{document} \end{codeenv} -This uses \csopt{combine-dual-locations} to combine the locations -for the primary and dual entries so that they only appear in the +This uses \csopt{combine-dual-locations} to combine the \glspl{location} +for the \primary\ and \dual\ entries so that they only appear in the index. To avoid the inconvenience of remembering which prefix to use, you can @@ -5370,7 +5490,7 @@ additionally include: \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} \end{itemize} However in this case the required fields are \field{short} and -\field{long}. The \field{name} for the primary entry defaults to +\field{long}. The \field{name} for the \gls{primaryentry} defaults to \field{short} if omitted. (This may be changed with the \csopt{abbreviation-name-fallback} option.) The fallback for the \field{sort} field is given by \csopt{abbreviation-sort-fallback}, @@ -5392,18 +5512,18 @@ is like: \field{long} = \marg{hypertext markup language} } \end{codeenv} -The primary term is defined using +The \primary\ term is defined using \gls!{bibglsnewdualindexabbreviation}, which encapsulates the \field{name} to match the font used by -the dual abbreviation. The encapsulation command depends +the \dual\ abbreviation. The encapsulation command depends on the \csopt{abbreviation-name-fallback} value. If it's the \field{short} field then \gls{bibglsuseabbrvfont} is used, otherwise \gls{bibglsuselongfont} is used. -The primary definition also +The \primary\ definition also by default sets the \field{category} to \optfmt{index} (although this again may be overridden). -The dual term is defined using +The \dual\ term is defined using \gls!{bibglsnewdualindexabbreviationsecondary}. \entrysection{dualindexsymbol} @@ -5430,12 +5550,12 @@ additionally include: \item \field{dualprefixfirstplural} $\mapsto$ \field{prefixfirstplural} \end{itemize} The required field is: \field{symbol}. -If the \field{name} field is omitted, the dual entry is assigned a +If the \field{name} field is omitted, the \dual\ entry is assigned a symbol from the original (unprefixed) label. -The primary entries are defined using +The \glspl{primaryentry} are defined using \gls!{bibglsnewdualindexsymbol}, which by default sets the \field{category} to \optfmt{index}, -and the dual entries are defined using +and the \glspl{dualentry} are defined using \gls!{bibglsnewdualindexsymbolsecondary}, which by default sets the \field{category} to \optfmt{symbol}. For example: @@ -5525,7 +5645,7 @@ a glossary and a list of symbols: \cmd{end}\marg{document} \end{codeenv} Here I've provided some convenient commands for referencing the -primary (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx} +\primary\ (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx} and \csfmt{Idxpl}). This means I don't need to worry about the label prefix and it also switches off the hyperlinks (with \code{\glsopt[false]{hyper}}). These custom @@ -5579,10 +5699,10 @@ further details. \entrysection{dualindexnumber} The \atentry{dualindexnumber} entry type is almost identical to -\atentry{dualindexsymbol}, but the primary entries are defined using +\atentry{dualindexsymbol}, but the \glspl{primaryentry} are defined using \gls!{bibglsnewdualindexnumber}, which by default sets the \field{category} to \optfmt{index}, -and the dual entries are defined using +and the \glspl{dualentry} are defined using \gls!{bibglsnewdualindexnumbersecondary}, which by default sets the \field{category} to \optfmt{number}. @@ -5618,7 +5738,7 @@ You may need to add a mapping from \field{shortplural} to The required fields are: \field{short}, \field{long} and \field{description}. This entry type is designed to emulate the example \gls{newdualentry} command given in the \sty{glossaries} -user manual~\cite{glossaries}. The primary entry is an abbreviation with the given +user manual~\cite{glossaries}. The \gls{primaryentry} is an abbreviation with the given \field{short} and \field{long} fields (but not the \field{description}) and the secondary entry is a regular entry with the \field{name} copied from the \field{long} field. @@ -5648,31 +5768,31 @@ is rather like doing: \end{codeenv} but \code{dual.svm} will automatically be selected if \code{svm} is indexed in the document. If \code{dual.svm} isn't explicitly -indexed, it won't have a location list. +indexed, it won't have a \gls{locationlist}. If the \field{sort} field is missing \bibgls\ by default falls back on the \field{name} field. If this is missing, this sort value will fallback on the \field{short} field. This means that if \field{name} isn't explicitly given in \atentry{dualabbreviationentry}, then the -primary entry will be sorted according to \field{short} but the dual -will be sorted according its \field{name} (which has been copied -from the primary \field{long}). +\gls{primaryentry} will be sorted according to \field{short} but the +\dual\ will be sorted according its \field{name} (which has been copied +from the \primary\ \field{long}). Entries provided using \atentry{dualabbreviationentry} will be defined with: \begin{codeenv} \gls{bibglsnewdualabbreviationentry} \end{codeenv} -(which uses \gls{newabbreviation}) for the primary entries and with : +(which uses \gls{newabbreviation}) for the \glspl{primaryentry} and with : \begin{codeenv} \gls{bibglsnewdualabbreviationentrysecondary} \end{codeenv} (which uses \gls{longnewglossaryentry}) for the secondary entries. -This means that if the \styopt{abbreviations} -package option is used, the primary entry will be put in the +This means that if the \styopt{abbreviations} package option is +used, the \gls{primaryentry} will be put in the \optfmt{abbreviations} glossary and the secondary entry in the -\optfmt{main} glossary. Use the \csopt{type} and -\csopt{dual-type} options to override this. +\mainglossary\. Use the \csopt{type} and \csopt{dual-type} options +to override this. \entrysection{dualentryabbreviation} @@ -5854,12 +5974,12 @@ If the abbreviation is in the file called \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[entries-dual-abbrv]{src},\comment{entries-dual-abbrv.bib} - \csopt[english]{type},\comment{put primary entries in glossary 'english'} - \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'} - \csopt[en.]{label-prefix},\comment{primary label prefix} - \csopt[de.]{dual-prefix},\comment{dual label prefix} - \csopt[en]{sort},\comment{sort primary entries according to language 'en'} - \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'} + \csopt[english]{type},\comment{put \primary\ entries in glossary 'english'} + \csopt[german]{dual-type},\comment{put \dual\ entries in glossary 'german'} + \csopt[en.]{label-prefix},\comment{\primary\ label prefix} + \csopt[de.]{dual-prefix},\comment{\dual\ label prefix} + \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} + \csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'} \comment{(German new orthography)} \csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry} } @@ -5887,7 +6007,7 @@ material: \begin{codeenv} \cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} \end{codeenv} -This means that the first use of the primary entry is displayed as +This means that the first use of the \gls{primaryentry} is displayed as \begin{quote} ribonucleic acid (RNA, Ribonukleins\"aure) \end{quote} @@ -5938,13 +6058,13 @@ mapping between the \field{description} and \field{user1} fields: \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[entries-dual-abbrv-desc]{src},\comment{entries-dual-abbrv-desc.bib} - \csopt[english]{type},\comment{put primary entries in glossary 'english'} - \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'} - \csopt[en.]{label-prefix},\comment{primary label prefix} - \csopt[de.]{dual-prefix},\comment{dual label prefix} - \csopt[en]{sort},\comment{sort primary entries according to language 'en'} + \csopt[english]{type},\comment{put \glspl{primaryentry} in glossary 'english'} + \csopt[german]{dual-type},\comment{put \glspl{dualentry} in glossary 'german'} + \csopt[en.]{label-prefix},\comment{\primary\ label prefix} + \csopt[de.]{dual-prefix},\comment{\dual\ label prefix} + \csopt[en]{sort},\comment{sort \glspl{primaryentry} according to language 'en'} \csopt[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field} - \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'} + \csopt[de-1996]{dual-sort},\comment{sort \glspl{dualentry} according to 'de-1996'} \comment{(German new orthography)} \csopt{dual-abbrv-backlink},\comment{add links in the glossary to the opposite entry} \comment{ dual key mappings:} @@ -6015,30 +6135,36 @@ As \atentry{dualabbreviation} but defines the entries with \section{Tertiary Entry Types} \label{sec:tertiaryentry} -A tertiary entry type is essentially a dual entry that creates three +A \igls{tertiaryentry} type is essentially a \gls{dualentry} that creates three separate (but related) \styfmt{glossaries-extra} entry definitions per -\ext{bib} entry. As with dual entries, the first and second of these -are the primary and secondary. The third of these is the -\idx{tertiary} which is effectively an appendage of the -secondary, and is defined by the same associated -\csfmt{bibglsnew\ldots secondary} command that defines the secondary -entry. Therefore the secondary and tertiary are both considered the -dual and are treated as a single entry for the purposes of sorting +\ext{bib} entry. As with \glspl{dualentry}, the first of these +is the \gls{primaryentry}. The second and third are referred to as the +\igls{secondaryentry} and \igls{tertiaryentry}. + +The \gls{tertiaryentry} is effectively an appendage of the +\gls{secondaryentry}{secondary}, and is defined by the same associated +\csfmt{bibglsnew\ldots secondary} command that defines the +\gls{secondaryentry}. Therefore the \glsdisp{secondaryentry}{secondary} +and \glsdisp{tertiaryentry}{tertiary} are both considered the +\dual\ and are treated as a single entry for the purposes of sorting and collating. -The tertiary entry will never have any locations. Any records found -will be assigned to the secondary (and may then be moved to the -primary with \csopt[primary]{combine-dual-locations}). The tertiary -will always have the same order as the secondary and will have the same -\field{group} value. You can set the \field{type} for the tertiary -with \csopt{tertiary-type} and the \field{category} with -\csopt{tertiary-category}. The label prefix defaults to -\idprefix{tertiary} and can be changed with \csopt{tertiary-prefix}. +The \gls{tertiaryentry} will never have any \glspl{location}. Any \glspl{record} +found will be assigned to the \glsdisp{secondaryentry}{secondary} +(and may then be moved to the \primary\ with +\csopt[primary]{combine-dual-locations}). The +\glsdisp{tertiaryentry}{tertiary} will always have the same order as +the \glsdisp{secondaryentry}{secondary} and will have the same +\field{group} value. You can set the \field{type} for the +\glsdisp{tertiaryentry}{tertiary} with \csopt{tertiary-type} and the +\field{category} with \csopt{tertiary-category}. The label prefix +defaults to \idprefix{tertiary} and can be changed with +\csopt{tertiary-prefix}. \entrysection{tertiaryindexabbreviationentry} This entry type is very similar to -\atentry{dualindexabbreviation} but creates a tertiary entry as +\atentry{dualindexabbreviation} but creates a \gls{tertiaryentry} as well. The required fields are: \field{short} and \field{long} (as for \atentry{dualindexabbreviation}) and also \field{description}. The mappings are shared by both entry types. For example: @@ -6063,11 +6189,11 @@ is analogous to: The last two are actually defined using one command: \begin{codeenv} \gls{bibglsnewtertiaryindexabbreviationentrysecondary} - \marg{dual.html}\comment{secondary label} - \marg{tertiary.html}\comment{tertiary label} - \marg{\ldots}\comment{secondary fields} - \marg{\ldots}\comment{tertiary fields} - \marg{HTML}\comment{primary name} + \marg{dual.html}\comment{\glsdisp{secondaryentry}{secondary} label} + \marg{tertiary.html}\comment{\glsdisp{tertiaryentry}{tertiary} label} + \marg{\ldots}\comment{\glsdisp{secondaryentry}{secondary} fields} + \marg{\ldots}\comment{\glsdisp{tertiaryentry}{tertiary} fields} + \marg{HTML}\comment{\primary\ name} \marg{HTML}\comment{short} \marg{hypertext markup language}\comment{long} \marg{a markup language for creating web pages}\comment{description} @@ -6082,22 +6208,24 @@ command is provided in the \iext{glstex} file as: \marg{\idx{param}8}\comment{} } \end{codeenv} -which defines the secondary as an abbreviation using -\csfmt{newabbreviation} and the tertiary as a regular entry using -\csfmt{longnewglossaryentry}. This means that the tertiary entry is -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. +which defines the \glsdisp{secondaryentry}{secondary} as an +abbreviation using \csfmt{newabbreviation} and the +\glsdisp{tertiaryentry}{tertiary} as a regular entry using +\csfmt{longnewglossaryentry}. This means that the +\gls{tertiaryentry} is always defined immediately after the +corresponding \gls{secondaryentry}. The \primary\ may be defined +earlier or later in the file depending on the way the entries are +sorted and on the \csopt{dual-sort} setting. \section{Multi-Entry Types} \label{sec:multientry} -A multi-entry type is an 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. In the case of \atentry{spawndualindexentry}, the main and -spawned entries are primary. The main entry's dual is created as per -\atentry{dualindexentry}. +A \gls{multientrytype} is an entry that may spawn multiple +\glspl{primaryentry}. This means that both the \gls{mainentry} and the +\glspl{spawnedentry} are sorted together along with all the other +\glspl{primaryentry}. In the case of \atentry{spawndualindexentry}, +the \glsdisp{mainentry}{main} and \glspl{spawnedentry} are \primary. +The \gls{mainentry}['s] \dual\ is created as per \atentry{dualindexentry}. \entrysection{bibtexentry} @@ -6141,23 +6269,23 @@ must use \field{bibtextype} as the identifier when aliasing. Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\ fields. (Remember that new fields must be defined before the first -\idx{resourceset}.) +\igls{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 +added to the \glsdisp{mainentry}{main} \atentry{bibtexentry}'s list of dependencies (so if the -\atentry{bibtexentry} has a record then all its satellite +\atentry{bibtexentry} has a \gls{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 +the \glsdisp{mainentry}{main} \atentry{bibtexentry} (so if a \atentry{contributor} +has a \gls{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}. +\igls{ignoredrecord} using \longarg{cite-as-record}. Each contributor is effectively defined as: \begin{codeenv} @@ -6178,12 +6306,12 @@ 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 +The \glsdisp{mainentry}{main} \atentry{bibtexentry} is defined using \gls{bibglsnewbibtexentry} and is followed by: \begin{codeenv} \gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} \end{codeenv} -where \meta{id} is the label identifying the main +where \meta{id} is the label identifying the \glsdisp{mainentry}{main} \atentry{bibtexentry} and \meta{contributor-id} is the label identifying the contributor, for each contributor that has been selected. @@ -6318,13 +6446,13 @@ takes place. However, if the \field{adoptparents} field isn't found, \bibgls\ will check for a simple mapping in both the \csopt{field-aliases} and \csopt{replicate-fields} settings. -This entry type creates a main \idx[textformat=emph]{progenitor} +This entry type creates a \glsdisp{mainentry}{main} \igls[textformat=emph]{progenitor} term (with all the given fields except \field{adoptparents}) -and $n$ spawned \idx[textformat=emph]{progeny} terms, where +and $n$ spawned \igls[textformat=emph]{progeny} terms, where $n$ is the number of elements in the \field{adoptparents} field, -that are dependent on the main term. +that are dependent on the \glsdisp{mainentry}{main term}. -Each of the spawned \idx{progeny} entries have the field identified by +Each of the spawned \gls{progeny} entries have the field identified by \csopt{adopted-parent-field} (\field{parent} by default) set to the corresponding element in the \field{adoptparents} field. @@ -6340,12 +6468,12 @@ The copied fields follow the same conditions as normal entries. (For example, unknown fields are ignored, case-changes are applied, if appropriate, and the \field{type} field must reference a valid glossary, if set.) If \csopt{progenitor-type} is set, then -this assignment is made after the \idx{progeny} are created -and only applies to the main \idx{progenitor} entry. The -type for the \idx{progeny} can be set with \csopt{progeny-type}. +this assignment is made after the \igls{progeny} are created +and only applies to the \glsdisp{mainentry}{main} \igls{progenitor} entry. The +type for the \gls{progeny} can be set with \csopt{progeny-type}. For example, \csopt[same as parent]{progeny-type} will ensure -that the \idx{progeny} are in the same glossary type as -their parent entry. +that the \igls{progeny} are in the same glossary type as +their \gls{parententry}. For example, an entry defined as: \begin{codeenv} @@ -6383,36 +6511,37 @@ is essentially like: \meta{field-name-n} = \margm{text} } \end{codeenv} -This creates the main (\idx{progenitor}) \meta{id} entry, which +This creates the \glsdisp{mainentry}{main} (\gls{progenitor}) \meta{id} entry, which contains all the fields (except for \field{adoptparents}) that were in the original \atentry{progenitor} definition and has the new -field \field{progeny} set to the comma-separated list of spawned -entry labels. The main entries are defined in the \ext{glstex} file +field \field{progeny} set to the comma-separated list of +\gls{spawnedentry} labels. The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewprogenitor}. -In addition to the main \meta{id} entry, the above also creates the -spawned \idx{progeny} entries \code{\meta{parent-1 id}.\meta{id}}, \ldots, -\code{\meta{parent-N id}.\meta{id}} that are dependent on the main -\meta{id} entry. +In addition to the \glsdisp{mainentry}{main} \meta{id} entry, the +above also creates the spawned \gls{progeny} entries +\code{\meta{parent-1 id}.\meta{id}}, \ldots, \code{\meta{parent-N +id}.\meta{id}} that are dependent on the \glsdisp{mainentry}{main} \meta{id} entry. -The spawned entries have the \field{parent} field set to the +The \glspl{spawnedentry} have the \field{parent} field set to the corresponding label obtained from the \field{adoptparents} list. -This parent entry must also be defined, as usual for the +This \gls{parententry} must also be defined, as usual for the \field{parent} field. (This restriction obviously doesn't apply if \csopt{adopted-parent-field} is changed from the default \field{parent}.) The spawned entries are defined in the \ext{glstex} file with \gls{bibglsnewspawnedindex} -If the main \idx{progenitor} entry is referenced in the document -then (assuming the default selection criteria) the spawned entries -will also be automatically selected. You can check for the existence -of the \field{progenitor} field using \cs{glsxtrifhasfield} and -fetch the \field{location} field from the main entry, if required. +If the \glsdisp{mainentry}{main} \gls{progenitor} entry is referenced in the document +then (assuming the default selection criteria) the +\glspl{spawnedentry} will also be automatically selected. You can +check for the existence of the \field{progenitor} field using +\cs{glsxtrifhasfield} and fetch the \field{location} field from the +\gls{mainentry}, if required. -Although the spawned entries are considered dependents of the main -entry, the reverse doesn't apply. If a spawned entry is referenced +Although the \glspl{spawnedentry} are considered dependents of the +\gls{mainentry}, the reverse doesn't apply. If a \gls{spawnedentry} is referenced in the document (with \code{\meta{parent-id}.\meta{id}}) then the -main entry and its other spawned entries aren't automatically +\gls{mainentry} and its other spawned entries aren't automatically selected. For example, suppose the file \filefmt{entries.bib} contains: @@ -6479,25 +6608,25 @@ parents. The following \atentryfmt{spawn\meta{single-type}} commands are all forms of \atentry{progenitor} that create the given -\atentryfmt{\meta{single-type}} of entry. The spawned entries are actually +\atentryfmt{\meta{single-type}} of entry. The \glspl{spawnedentry} are actually created with the private entry type \atentryfmt{spawned\meta{type}}. In the -case of \atentry{progenitor}, the spawned entries are defined as +case of \atentry{progenitor}, the \glspl{spawnedentry} are defined as a \atentryfmt{spawnedindex} entry. These special \atentryfmt{spawned\meta{type}} entry types aren't intended for use in the \ext{bib} file, but if you reference the entry type (for example, with \csopt[same as entry]{category}) you will get \atentryfmt{spawned\meta{type}} as the entry type. The -original entry type for the spawned entries is the same as -the original entry for the main \atentry{progenitor} entry. +original entry type for the \glspl{spawnedentry} is the same as +the original entry for the \glsdisp{mainentry}{main} \atentry{progenitor} entry. -There is currently only one form of dual \atentry{progenitor} entry and that's -\atentry{spawndualindexentry}. Only the main \idx{progenitor} entry -is a dual entry. The spawned \idx{progeny} are all \atentry{index} -primary entries. +There is currently only one form of \dual\ \atentry{progenitor} entry and that's +\atentry{spawndualindexentry}. Only the \glsdisp{mainentry}{main} \gls{progenitor} entry +is a \gls{dualentry}. The spawned \gls{progeny} are all \atentry{index} +\glspl{primaryentry}. \entrysection{spawnindex} -As \atentry{progenitor}, but the main entries are defined in the +As \atentry{progenitor}, but the \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnindex} and the spawned entries are defined with \gls{bibglsnewspawnedindex}. @@ -6509,9 +6638,9 @@ As with \atentry{indexplural}, if the \field{name} field isn't set, it's assigned to the same value as the \field{plural} field (or the fallback for the \field{plural}, if not defined). -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnindexplural} and the -spawned entries are defined with \gls{bibglsnewspawnedindexplural}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedindexplural}. \entrysection{spawnentry} @@ -6520,9 +6649,9 @@ As \atentry{progenitor}, except that it creates As with \atentry{entry}, the \field{description} field is required and either \field{name} or \field{parent}. -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnentry} and the -spawned entries are defined with \gls{bibglsnewspawnedentry}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedentry}. \entrysection{spawnabbreviation} @@ -6531,9 +6660,9 @@ As \atentry{progenitor}, except that it creates As with \atentry{abbreviation}, the \field{short} and \field{long} fields are required. -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the -spawned entries are defined with \gls{bibglsnewspawnedabbreviation}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedabbreviation}. \entrysection{spawnacronym} @@ -6542,9 +6671,9 @@ As \atentry{progenitor}, except that it creates As with \atentry{acronym}, the \field{short} and \field{long} fields are required. -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnacronym} and the -spawned entries are defined with \gls{bibglsnewspawnedacronym}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedacronym}. \entrysection{spawnsymbol} @@ -6554,9 +6683,9 @@ As with \atentry{symbol}, the required fields are \field{name} or \field{parent}, and the \field{description} field is required if the \field{name} field is missing. -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnsymbol} and the -spawned entries are defined with \gls{bibglsnewspawnedsymbol}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnedsymbol}. \entrysection{spawnnumber} @@ -6566,23 +6695,23 @@ As with \atentry{number}, the required fields are \field{name} or \field{parent}, and the \field{description} field is required if the \field{name} field is missing. -The main entries are defined in the +The \glspl{mainentry} are defined in the \ext{glstex} file with \gls{bibglsnewspawnnumber} and the -spawned entries are defined with \gls{bibglsnewspawnednumber}. +\glspl{spawnedentry} are defined with \gls{bibglsnewspawnednumber}. \entrysection{spawndualindexentry} -As \atentry{progenitor}, except that the main (\idx{progenitor}) +As \atentry{progenitor}, except that the \glsdisp{mainentry}{main} (\gls{progenitor}) entry behaves like \atentry{dualindexentry}. The spawned -\idx{progeny} behave like \atentry{index} are so are all considered primary -entries. The \field{adoptparents} field should therefore reference -primary entries with the default \csopt[parent]{adopted-parent-field}. +\gls{progeny} behave like \atentry{index} are so are all considered +\glspl{primaryentry}. The \field{adoptparents} field should therefore reference +\glspl{primaryentry} with the default \csopt[parent]{adopted-parent-field}. -The main primary and secondary (dual) entries are defined in the -\ext{glstex} file with -\gls{bibglsnewspawndualindexentry} and +The \glsdisp{mainentry}{main} \primary\ and +\glsdisp{secondaryentry}{secondary} (\dual) entries are defined in +the \ext{glstex} file with \gls{bibglsnewspawndualindexentry} and \gls{bibglsnewspawndualindexentrysecondary}. The spawned -\idx{progeny} are defined with \gls{bibglsnewspawnedindex}. +\gls{progeny} are defined with \gls{bibglsnewspawnedindex}. \chapter{Resource File Options} \label{sec:resourceopts} @@ -6599,7 +6728,7 @@ that there's no attempt to assign or process the \field{sort} key if it's omitted from \gls{newglossaryentry} (or similar commands). The \field{sort} key will be provided by \bibgls\ for informational purposes, but there's no need for \LaTeX\ to write it to any -external files (unless you use the hybrid \styopt[alsoindex]{record}, +external files (unless you use \styopt[hybrid]{record}, in which case you need to prevent \bibgls\ from sorting using the \csopt[none]{sort} resource option). @@ -6612,7 +6741,7 @@ You can have multiple \gls{glsxtrresourcefile} commands within your document, but each \meta{filename} must be unique, otherwise \LaTeX\ would attempt to input the same \ext{glstex} file multiple times (\bibgls\ checks for non-unique file names). The associated data for each -resource file is called the \idx{resourceset} (see +resource file is called the \igls{resourceset} (see \sectionref{sec:resourcesets}). There's a shortcut command that uses @@ -6647,7 +6776,7 @@ not carried over to the next instance of \gls{glsxtrresourcefile}. Only the definitions provided in \atentry{preamble} (if the interpreter is on and \csopt[true]{interpret-preamble}) are carried over to the next resource set and, possibly, -\idxpl{crossresourceref} if permitted (see +\iglspl{crossresourceref} if permitted (see \sectionref{sec:resourcesets}). The \sty{glossaries-extra} package doesn't parse the options, but just writes the information to the \ext{aux} file. This means that any invalid options will be reported @@ -6697,8 +6826,8 @@ Alternatively, if they have different settings: \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[use]{sort},\csopt[symbols]{type}} \end{codeenv} -Note that the sorting is applied to each \idx{resourceset} independently -of other \idxpl{resourceset}. This means that if you have multiple instances +Note that the sorting is applied to each \igls{resourceset} independently +of other \iglspl{resourceset}. This means that if you have multiple instances of \gls{glsxtrresourcefile} but only one glossary type, the glossary will effectively contain blocks of sorted entries. For example, if \filefmt{file1.bib} contains: @@ -6831,24 +6960,24 @@ also do: The \emph{contents} of \atentry{preamble} are only written to the associated \iext{glstex} file, but the definitions contained within the \atentry{preamble} are retained by the interpreter for subsequent -\idxpl{resourceset}. +\iglspl{resourceset}. \section{General Options} \label{sec:generalopts} \optsection{charset} -If the character \idx{encoding} hasn't been supplied in the \iext{bib} file -with the encoding comment +If the character \igls{encoding} hasn't been supplied in the \iext{bib} file +with the \gls{encoding} comment \begin{alltt} \idx{commentchar} Encoding: \meta{encoding-name} \end{alltt} -then you can supply the correct encoding using +then you can supply the correct \gls{encoding} using \csopt[encoding-name]{charset}. In general, it's better to include -the encoding in the \ext{bib} file where it can also be read by +the \gls{encoding} in the \ext{bib} file where it can also be read by a \ext{bib} managing systems, such as JabRef. -See \longarg{tex-encoding} for the encoding used to write the \ext{glstex} +See \longarg{tex-encoding} for the \gls{encoding} used to write the \ext{glstex} file. \optsection{interpret-preamble} @@ -6881,7 +7010,7 @@ that don't get seen by \LaTeX. \optsection{set-widest} The \glostyle{alttree} glossary style needs to know the widest -\field{name} (for each level, if hierarchical). This can be set +\field{name} (for each level, if \hierarchical). This can be set using \ics{glssetwidest} provided by the \isty{glossary-tree} package (or similar commands like \ics{glsupdatewidest} provided by \isty{glossaries-extra-stylemods}), but this requires knowing @@ -6891,11 +7020,11 @@ document build as it has to iterate over all defined entries. The \isty{glossary-longextra} package, provided with \sty{glossaries-extra} v1.37+, also needs to know the widest name, -but in this case only the top-level is needed. If this has already -been found through the commands provided with the \glostyle{alttree} -style then that value will be used as the default, but you can set another -value that's only used for the \sty{glossary-longextra} styles with -\ics{glslongextraSetWidest}. +but in this case only the \gls{top-levelentry}{top-level} is needed. +If this has already been found through the commands provided with +the \glostyle{alttree} style then that value will be used as the +default, but you can set another value that's only used for the +\sty{glossary-longextra} styles with \ics{glslongextraSetWidest}. The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest}, which sets the widest name for those styles that need it. As from version @@ -6904,7 +7033,7 @@ which sets the widest name for those styles that need it. As from version \sty{glossary-longextra} package. The boolean option \csopt[true]{set-widest} will try to calculate -the widest names for each hierarchical level to help remove the need +the widest names for each \hierarchicallevel\ to help remove the need to determine the correct value within the document. Since \bibgls\ doesn't know the fonts that will be used in the document or if there are any non-standard commands that @@ -6937,7 +7066,7 @@ selected. This will then be implemented as follows: empty string (that is the \field{name} fields all consist of unknown commands) then \begin{itemize} - \item if there are child entries \gls{bibglssetwidestfallback} + \item if there are \glspl{childentry} \gls{bibglssetwidestfallback} is used, \item otherwise \gls{bibglssetwidesttoplevelfallback} is used; \end{itemize} @@ -6949,7 +7078,7 @@ selected. This will then be implemented as follows: type to the empty string (that is the \field{name} fields all consist of unknown commands) then \begin{itemize} - \item if there are child entries \gls{bibglssetwidestfortypefallback} + \item if there are \glspl{childentry} \gls{bibglssetwidestfortypefallback} is used, \item otherwise \gls{bibglssetwidesttoplevelfortypefallback} is used; @@ -7099,7 +7228,10 @@ another method is to use \csopt[copy]{action} which simply writes instead of using one of the commands listed in \sectionref{sec:newentrydefs}. This copies the entries rather than defining them, which means the entries must already have been -defined. The \meta{type} is determined as follows: +defined. You can select entries that were selected in earlier +\iglspl{resourceset} with \csopt[selected before]{selection}. + +The \meta{type} is determined as follows: \begin{itemize} \item if the entry has the \field{type} field set, that's used; \item if the entry is a tertiary and \csopt{tertiary-type} is set, that's @@ -7259,7 +7391,7 @@ characters in filenames). For example: By default all entries that have records in the \iext{aux} file will be selected as well as all their dependent entries. The dependent entries that don't have corresponding records on the first \LaTeX\ -run, may need an additional build to ensure their location lists +run, may need an additional build to ensure their \glspl{locationlist} are updated. Remember that on the first \LaTeX\ run the \iext{glstex} files don't @@ -7287,32 +7419,49 @@ add unrecorded entries whose \field{see} or \field{alias} (but not \item \optfmt{recorded no deps}: add all recorded entries but not their dependencies. The dependencies include those referenced in the -\field{see} or \field{seealso} field or fields identified by -\csopt{dependency-fields}, \field{parent} entries and those found referenced -with commands like \ics{gls} in the field values that are parsed by -\bibgls. With this setting, parents will be omitted unless they've -been referenced in the document through commands like \ics{gls}. +\field{see} or \field{seealso} field or fields identified by +\csopt{dependency-fields}, \field{parent} entries and those found +referenced with commands like \ics{gls} in the field values that are +parsed by \bibgls. With this setting, \glsdisp{parententry}{parents} +will be omitted unless they've been referenced in the document +through commands like \ics{gls}. This setting won't add any +\field{see} or \field{seealso} lists to the \igls{locationlist}. The +given field will be set, so you can access the information, but +there's no guarantee that the cross-referenced entry will have been +selected. The \field{alias} cross-reference will be added to the +\igls{locationlist} but you will need to ensure that the target is +also selected (or use \csopt[omit]{alias} to suppress it). \item \optfmt{recorded and ancestors}: this is like the previous -setting but parents are added even if they haven't been referenced -in the document. The other dependent entries are omitted if they -haven't been referenced in the document. +setting but \glsdisp{parententry}{parents} are added even if they +haven't been referenced in the document. The other dependent entries +are omitted if they haven't been referenced in the document. The +above notes regarding the cross-reference lists also applies. \item \optfmt{deps but not recorded}: this first selects entries as though \optfmt{recorded and deps} had been used, but after all -ancestors and dependencies have been added it then removes all +\glspl{ancestor} and dependencies have been added it then removes all entries that have records. This means that you end up with only the unrecorded dependencies. (Recorded entries will need to be selected in a different resource set.) \item \optfmt{ancestors but not recorded}: this first selects entries as though \optfmt{recorded and ancestors} had been used, but -after all ancestors have been added it then removes all entries that +after all \glspl{ancestor} have been added it then removes all entries that have records. This means that you end up with only the unrecorded -ancestors. (Recorded entries will need to be selected +\glspl{ancestor}. (Recorded entries will need to be selected in a different resource set.) See the \exfile{sample-nested.tex} example document. +\item \optfmt{selected before}: select any entries that have been +selected in a previous \igls{resourceset}. This is intended +for use with \csopt[copy]{action} to copy entries to another +glossary as an alternative to (or in addition to) the +\csopt{secondary} option. Note that if you make any modifications to +the fields (such as case-changing) the modification won't be saved +to the \ext{glstex} file. This option can't be used in the first +\igls{resourceset}. + \item \optfmt{all}: add all entries found in the \ext{bib} files supplied in the \csopt{src} option. \end{itemize} @@ -7344,7 +7493,7 @@ selected. The above is just an example. The circuitous redirection of \qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and is best avoided (especially for an index where there are no accompanying -descriptions and no \idx{locationlist} for the intermediate \qt{sprint}). +descriptions and no \igls{locationlist} for the intermediate \qt{sprint}). A better method would be: \begin{codeenv} \atentry{index}\marg{run} @@ -7380,7 +7529,7 @@ and suppose the document only references \qt{dash} (for example, with will be selected because \qt{dash} requires it (for the cross-reference), and \qt{run} will be selected because \qt{sprint} requires it (for the cross-reference). In this case, neither \qt{sprint} nor \qt{run} -have a \idx{locationlist} but they do both provide additional information +have a \igls{locationlist} but they do both provide additional information for the reader in their descriptions. A better method here would be for each entry to have a cross-reference @@ -7531,28 +7680,47 @@ selecting at most \meta{number} entries. The default setting is \csopt[0]{limit} (no truncation). A negative value of \meta{number} is not permitted. -If you have any dual entries, then the truncation will be applied to -the combined list of primary and duals if \csopt[combine]{dual-sort} -otherwise each list will be truncated separately by \meta{number}, -which results in a maximum of $2 \times \meta{number}$. Remember -that tertiary entries are created when dual entries are defined in -the \ext{glstex} file, so this will increase the total number of +If you have any \glspl{dualentry}, then the truncation will be +applied to the combined list of \primary\ and +\glsdisp{dualentry}{duals} if \csopt[combine]{dual-sort} otherwise +each list will be truncated separately by \meta{number}, which +results in a maximum of $2 \times \meta{number}$. Remember that +\glspl{tertiaryentry} are created when \glspl{dualentry} are defined +in the \ext{glstex} file, so this will increase the total number of entries. \section{Hierarchical Options} \label{sec:hierarchicalopts} +Hierarchy is established by setting the \field{parent} field to the +label of the parent entry. The parent and child entries are +sorted together, but hierarchical comparators will place child +entries after their corresponding parent. + +The \sty{glossaries} package provides \ics{ifglshasparent} to +determine whether or not an entry has the \field{parent} field set. +If also provides \ics{ifglshaschildren}, but this command is +inefficient as it has to iterate over all entries to find an entry +with the \field{parent} field set to the relevant label. It's also +non-trivial to determine which child entries have been included in +the glossary with \idx!{makeindex} or \idx!{xindy}. \bibgls\ can +provide this information with some of the options described in this +section. + +It's also possible to \glsdisp{flatglossary}{flatten entries} (that is, remove the +hierarchical information) or just flatten \glspl{lonelychildentry}. + \optsection{save-child-count} This is a boolean option. The default setting is \csopt[false]{save-child-count}. -If \csopt[true]{save-child-count}, -each entry will be assigned a field called \field{childcount} with -the value equal to the number of child entries that have been -selected. As from version 1.5, this option also creates -the \field{childlist} field for entries that have children -selected. This field is in \sty{etoolbox}'s internal list -format and can be iterated over using \glsadd{idx.loop}\ics{glsxtrfieldforlistloop}. +If \csopt[true]{save-child-count}, each entry will be assigned a +field called \field{childcount} with the value equal to the number +of \glspl{childentry} that have been selected. As from version 1.5, +this option also creates the \field{childlist} field for entries +that have \glsdisp{childentry}{children} selected. This field is in +\sty{etoolbox}'s internal list format and can be iterated over using +\glsadd{idx.loop}\ics{glsxtrfieldforlistloop}. The assignment is done using \ics{GlsXtrSetField} so there's no associated key. You can test if the field is set and non-zero @@ -7608,13 +7776,13 @@ Then the \ext{glstex} file will contain: \cs{GlsXtrSetField}\marg{quartz}\marg{childcount}\marg{0} \gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{quartz} \end{codeenv} -Note that although \code{birds} has three children defined in the -\ext{bib} file, only two have been selected, so the child count is -set to~2. Similarly the \code{minerals} entry has five children +Note that although \code{birds} has three \children\ defined in the +\ext{bib} file, only two have been selected, so the \child\ count is +set to~2. Similarly the \code{minerals} entry has five \children\ defined in the \ext{bib} file, but only three have been selected, so -the child count is~3. +the \child\ count is~3. -The following uses the post-description hook to show the child count +The following uses the post-description hook to show the \child\ count in parentheses: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}} @@ -7638,22 +7806,24 @@ numerical test with \ics{GlsXtrIfFieldNonZero} or This is a boolean option. The default setting is \csopt[false]{save-sibling-count}. This is like -\csopt{save-child-count} but saves the sibling count in -\field{siblingcount} and the sibling list in \field{siblinglist}. -As with the child list, the sibling list is in \sty{etoolbox}['s] -internal list format. The sibling information is only saved for -entries that have a parent. +\csopt{save-child-count} but saves the \gls{sibling} count in +\field{siblingcount} and the \gls{sibling} list in +\field{siblinglist}. As with the \child list, the \gls{sibling} +list is in \sty{etoolbox}['s] internal list format. The +\gls{sibling} information is only saved for entries that have a +\parent. -The advantage with \field{siblinglist} over accessing the parent's -\field{childlist} is that the entry itself is excluded from the list. +The advantage with \field{siblinglist} over accessing the +\glsdisp{parententry}{parent's} \field{childlist} is that the entry +itself is excluded from the list. \optsection{flatten} This is a boolean option. The default value is \csopt[false]{flatten}. -If \csopt[true]{flatten}, the sorting will ignore hierarchy and +If \csopt[true]{flatten}, the sorting will ignore \hierarchy\ and the \field{parent} field will be omitted when writing -the definitions to the \ext{glstex} file, but the parent entries -will still be considered a dependent ancestor from the +the definitions to the \ext{glstex} file, but the \glspl{parententry} +will still be considered a dependent \gls{ancestor} from the \csopt{selection} point of view. Note the difference between this option and using @@ -7666,24 +7836,24 @@ This may take one of three values: \optfmt{false} (default), \optfmt{presort} and \optfmt{postsort}. The value must be supplied. Unlike the \csopt{flatten} option, which completely -removes the hierarchy, the \csopt{flatten-lonely} option can be used -to selectively alter the hierarchy. In this case only those entries -that have a parent but have no siblings are considered. This option +removes the \hierarchy, the \csopt{flatten-lonely} option can be used +to selectively alter the \hierarchy. In this case only those entries +that have a \parent\ but have no \glspl{sibling} are considered. This option is affected by the \csopt{flatten-lonely-rule} setting. The conditions for -moving a child up one hierarchical level are as follows: +moving a \child\ up one \hierarchicallevel\ are as follows: \begin{itemize} -\item The child must have a parent, and -\item the child can't have any selected siblings, and +\item The \child\ must have a \parent, and +\item the \child\ can't have any selected \glspl{sibling}, and \item if \csopt[only unrecorded parents]{flatten-lonely-rule} - then the parent can't have a location list, where the location list - includes records and \field{see} or \field{seealso} - cross-references (for the other rules the parent may have a location - list as long as it only has the one child selected). + then the \parent\ can't have a \gls{locationlist}, where the + \gls{locationlist} includes \glspl{record} and \field{see} or \field{seealso} + cross-references (for the other rules the \parent\ + may have a \gls{locationlist} as long as it only has the one \child\ selected). \end{itemize} -If the child is selected for hierarchical adjustment, the parent -will be removed if: +If the \child\ is selected for \hierarchical\ adjustment, +the \parent\ will be removed if: \begin{itemize} -\item The parent has no location list, and +\item The \parent\ has no \gls{locationlist}, and \item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}. \end{itemize} @@ -7735,13 +7905,14 @@ and suppose the document contains: \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -Although the \code{duck} entry has siblings in the -\filefmt{entries.bib} file, none of them have been recorded -(indexed) in the document, nor has the parent \code{birds} entry. +Although the \code{duck} entry has \glspl{sibling} in the +\filefmt{entries.bib} file, none of them have been +\glsdisp{recordedentry}{recorded} in the document, nor has the +\parent\ \code{birds} entry. This document hasn't used \csopt{flatten-lonely}, so the default \csopt[false]{flatten-lonely} is assumed. This results in the -hierarchical structure: +\hierarchical\ structure: \begin{description}\setlength\itemsep{0pt}% \item[A] \null \item[aardvark] 1 @@ -7776,15 +7947,16 @@ hierarchical structure: (The \qt{1} in the above indicates the page number.) There are some entries here that look a little odd: \code{duck}, \code{cabbage} and \code{subsubitem}. In each case they are a -lone child entry. It would look better if they could be compressed, -but I don't want to use the \csopt{flatten} option, as I still want -to keep the mineral hierarchy. +\glsdisp{lonelychildentry}{lone child entry}. It would look better +if they could be compressed, but I don't want to use the +\csopt{flatten} option, as I still want to keep the mineral +\hierarchy. If I now add \csopt[postsort]{flatten-lonely}: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}} \end{codeenv} -the hierarchy becomes: +the \hierarchy\ becomes: \begin{description}\setlength\itemsep{0pt}% \item[A] \null \item[aardvark] 1 @@ -7816,10 +7988,10 @@ the \field{text} field has been set to: \begin{codeenv} \field{text}=\marg{duck} \end{codeenv} -the \field{group} field is copied over from the parent entry (\qt{B}), +the \field{group} field is copied over from the \gls{parententry} (\qt{B}), and the \field{parent} field has been adjusted, moving \code{duck} -up one hierarchical level. -Finally, the former parent \code{birds} entry has been removed (the default +up one \hierarchicallevel. +Finally, the former \parent\ \code{birds} entry has been removed (the default \csopt[only unrecorded parents]{flatten-lonely-rule} is in effect). The default definition of \gls!{bibglsflattenedchildpostsort} @@ -7829,25 +8001,25 @@ in the original \atentry{index} definition of \text{duck}, it wouldn't have been altered. This adjustment ensures that in the document \code{\cs{gls}\marg{duck}} still produces \qt{duck} rather than \qt{birds, duck}. -(If the child and parent \field{name} fields are identical, -the terms are considered homographs. See below for further details.) +(If the \child\ and \parent\ \field{name} fields are identical, +the terms are considered \glspl{homograph}. See below for further details.) The \code{subsubitem} entry has also been adjusted. This was done in a multi-stage process, starting with sub-items and then moving down -the hierarchical levels: +the \hierarchical\ levels: \begin{itemize} \item The \code{subitem} entry was adjusted, moving it from a -sub-entry to a top-level entry. The \field{name} field was then +\gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then modified to: \begin{codeenv} \field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}} \end{codeenv} -This now means that the \code{subsubitem} entry is now a sub-entry +This now means that the \code{subsubitem} entry is now a \gls{sub-entry} (rather than a sub-sub-entry). The \code{subitem} entry now has no -parent, but at this stage the \code{subsubitem} entry still has -\code{subitem} as its parent. +\parent, but at this stage the \code{subsubitem} entry still has +\code{subitem} as its \parent. \item The \code{subsubitem} entry is then adjusted moving from a -sub-entry to a top-level entry. The \field{name} field was then +\gls{sub-entry} to a \gls{top-levelentry}. The \field{name} field was then modified to: \begin{codeenv} \field{name}= @@ -7861,22 +8033,22 @@ modified to: } \end{codeenv} The first argument of \gls!{bibglsflattenedchildpostsort} is -obtained from the \field{name} field of the entry's former parent -(which is removed from the child's set of ancestors). This field -value was changed in the previous step, and the change is -reflected here. +obtained from the \field{name} field of the entry's former \parent\ +(which is removed from the \glsdisp{childentry}{child's} set of +\glspl{ancestor}). This field value was changed in the previous +step, and the change is reflected here. This means that the name for \code{subitem} will be displayed as \qt{item, subitem} and the name for \code{subsubitem} will be displayed as \qt{item, subitem, subsubitem}. -\item The parent entries \code{item} and \code{subitem} -are removed from the selection as they have no location lists. +\item The \glspl{parententry} \code{item} and \code{subitem} +are removed from the selection as they have no \glspl{locationlist}. \end{itemize} -Note that the \code{cabbage} sub-entry hasn't been adjusted. It -doesn't have any siblings but its parent entry (\code{vegetable}) -has a location list so it can't be discarded. +Note that the \code{cabbage} \gls{sub-entry} hasn't been adjusted. It +doesn't have any \glspl{sibling} but its \gls{parententry} (\code{vegetable}) +has a \gls{locationlist} so it can't be discarded. If I change the rule: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, @@ -7885,7 +8057,7 @@ If I change the rule: } \end{codeenv} then this will move the \code{cabbage} entry up a level but the -original parent entry \code{vegetable} will remain: +original \gls{parententry} \code{vegetable} will remain: \begin{description}\setlength\itemsep{0pt}% \item[A] \null \item[aardvark] 1 @@ -7921,7 +8093,7 @@ the sorting is performed. For example, using: \csopt[presort]{flatten-lonely} } \end{codeenv} -the hierarchical order is now: +the \hierarchical\ order is now: \begin{description}\setlength\itemsep{0pt}% \item[A] \null \item[aardvark] 1 @@ -7966,17 +8138,17 @@ Note that the \field{text} field is only changed if not already set. This option may have unpredictable results for abbreviations as the \field{name} field (and sometimes the \field{text} field) is typically set by the abbreviation style. Remember that -if the parent entry doesn't have a \idx{locationlist} and the rule isn't -set to \optfmt{no discard} then the parent entry will be discarded +if the \gls{parententry} doesn't have a \igls{locationlist} and the rule isn't +set to \optfmt{no discard} then the \gls{parententry} will be discarded after all relevant entries and their dependencies have been -selected, so any cross-references within the parent entry (such as +selected, so any cross-references within the \gls{parententry} (such as \ics{gls} occurring in the description) may end up being selected -even if they wouldn't be selected if the parent entry didn't exist. +even if they wouldn't be selected if the \gls{parententry} didn't exist. -With both \optfmt{presort} and \optfmt{postsort}, -if the parent \field{name} is the same as the child's \field{name} -then the child is considered a homograph and -the child's name is set to: +With both \optfmt{presort} and \optfmt{postsort}, if the \parent\ \field{name} +is the same as the \glsdisp{childentry}{child's} \field{name} +then the \child\ is considered a \igls{homograph} and +the \glsdisp{childentry}{child's} name is set to: \begin{codeenv*} \format{bibglsflattenedhomograph} \end{codeenv*} @@ -7987,54 +8159,54 @@ This defaults to just \meta{name}. \optsection{flatten-lonely-rule} This option governs the rule used by \csopt{flatten-lonely} to -determine which sub-entries (that have no siblings) to adjust and -which parents to remove. The value may be one of the following: +determine which \glspl{sub-entry} (that have no \glspl{sibling}) to adjust and +which \glsdisp{parententry}{parents} to remove. The value may be one of the following: \begin{description} -\item[\optfmt{only unrecorded parents}] Only the sub-entries -that have a parent without a \idx{locationlist} will be altered. -The parent entry will be removed from the selection. +\item[\optfmt{only unrecorded parents}] Only the \glspl{sub-entry} +that have a \parent\ without a \igls{locationlist} will be altered. +The \gls{parententry} will be removed from the selection. This value is the default setting. \item[\optfmt{discard unrecorded}] This setting will adjust all -sub-entries that have no siblings regardless of whether or not the -parent has a \idx{locationlist}. -Only the parent entries that don't have a location list will be +\glspl{sub-entry} that have no \glspl{sibling} regardless of whether or not the +\parent\ has a \igls{locationlist}. +Only the \glspl{parententry} that don't have a \gls{locationlist} will be removed from the selection. \item[\optfmt{no discard}] This setting will adjust all -sub-entries that don't have siblings regardless of whether or not the -parent has a \idx{locationlist}. No entries will be discarded, so parent -entries that don't have a \idx{locationlist} will still appear in the +\glspl{sub-entry} that don't have \glspl{sibling} regardless of whether or not the +\parent\ has a \igls{locationlist}. No entries will be discarded, so +\glspl{parententry} that don't have a \igls{locationlist} will still appear in the glossary. \end{description} -In the above, the \idx{locationlist} includes records and +In the above, the \igls{locationlist} includes \glspl{record} and cross-references obtained from the \field{see} or \field{seealso} fields. See \csopt{flatten-lonely} for further details. \optsection{strip-missing-parents} -The \sty{glossaries} package requires that all child entries must be -defined after the parent entry. An error occurs otherwise, so +The \sty{glossaries} package requires that all \glspl{childentry} must be +defined after the \gls{parententry}. An error occurs otherwise, so \bibgls\ will omit the \field{parent} field if it can't be found in -the given \idx{resourceset}. However, when the default +the given \igls{resourceset}. However, when the default \csopt[false]{strip-missing-parents} is on, this omission only occurs while writing the definitions in the \ext{glstex} file (after selection and sorting). -Sorting is performed hierarchically and the \field{group} field is set -accordingly for the top-level entries (but not for child entries), -which means that an entry with a \field{parent} field will be -treated by the sort method as a child entry. This can lead to a -strange result, which \bibgls\ warns about: +Sorting is performed \hierarchically\ and the \field{group} field is +set accordingly for the \glspl{top-levelentry} (but not for +\glspl{childentry}), which means that an entry with a \field{parent} +field will be treated by the sort method as a \gls{childentry}. This can +lead to a strange result, which \bibgls\ warns about: \begin{alltt} Parent '\meta{parent id}' not found for entry \meta{child-id} \end{alltt} This is the default behaviour as it may simply be a result of a typing mistake in the \field{parent} field. If you actually want -missing parents to be stripped before sorting (but after the +missing \glsdisp{parententry}{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 +you want all \glsdisp{parententry}{parents} stripped then use \csopt{flatten} or \csopt[parent]{ignore-fields} instead. As from version 1.4, if you -want \bibgls\ to create the missing parents, then you can use +want \bibgls\ to create the missing \glsdisp{parententry}{parents}, then you can use \csopt[create]{missing-parents}. \optsection{missing-parents} @@ -8049,14 +8221,14 @@ As an alternative to \csopt{strip-missing-parents}, as from version \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 +\item \optfmt{create}: this will create a new \atentry{index} entry +with the missing \glsdisp{parententry}{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 \gls{childentry} has the \field{type} field +set, then the new \gls{parententry} will be given the same value. The +\field{category} for the new \gls{parententry} can be assigned with \csopt{missing-parent-category}. \end{itemize} @@ -8097,7 +8269,7 @@ If the interpreter has been provided with the definition: 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. +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: @@ -8111,18 +8283,18 @@ document from the \hyperref[sec:examples]{examples chapter}. \optsection{missing-parent-category} -If a missing parent entry is created through the use of +If a missing \gls{parententry} 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 +be assigned to the new \gls{parententry} 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 + \item \code{same as child}: the \gls{parententry}['s] \field{category} + field is set to the same value as the \glsdisp{childentry}{child's} (if set); + \item \code{same as base}: the \gls{parententry}['s] \field{category} is set to the base name of the \ext{bib} file that provided the - child entry's definition; + \gls{childentry}['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 + \item \meta{label}: the \gls{parententry}['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}. @@ -8174,9 +8346,9 @@ The other document \filefmt{myarticle.tex} might look like: \cs{gls}\marg{sample}. \cmd{end}\marg{document} \end{codeenv} -In this case the \optfmt{main} glossary isn't used, but the category +In this case the \mainglossary\ isn't used, but the category attributes allow a mixture of internal and external references, so -the \optfmt{main} glossary could be used for the internal +the \mainglossary\ could be used for the internal references. (In which case, \csfmt{makeglossaries} and \csfmt{printglossaries} would need to be added back to \filefmt{myarticle.tex}.) @@ -8240,7 +8412,7 @@ another possibility is to simply make \filefmt{myarticle.tex} input can work but it's not so convenient to set the label prefix, the type and the category. The \optfmt{master} option allows this, but it has limitations (see below), so in complex cases (in particular -different label prefixes combined with hierarchical entries or cross-references) you'll have to use +different label prefixes combined with \hierarchical\ entries or cross-references) you'll have to use the method shown in the example code above. \optsection{master} @@ -8258,8 +8430,8 @@ using commands like \ics{gls} in any of the other fields when the labels have been assigned prefixes. In this case you will need to use the method described in the example above. -The \meta{name} is the name of the \iext{aux} file for the master -document without the extension (in this case, \filefmt{mybook}). It +The \meta{name} is the name of the \iext{aux} file for the +\gls{masterdocument} without the extension (in this case, \filefmt{mybook}). It needs to be relative to the document referencing it or an absolute path using forward slashes as the directory divider. Remember that if it's a relative path, the PDF files (\filefmt{mybook.pdf} and @@ -8268,17 +8440,16 @@ relative position. When \bibgls\ detects the \csopt{master} option, it won't search for entries in any \ext{bib} files (for that particular resource set) -but will create a \iext{glstex} file that inputs the master -document's -\ext{glstex} files, but it will additionally temporarily -adjust the internal commands used to define entries so that -the prefix given by \csopt{label-prefix}, the glossary type and the -category type are all automatically inserted. If the \csopt{type} -or \csopt{category} options haven't been used, the corresponding -value will default to \optfmt{master}. The \catattr{targeturl} -and \catattr{targetname} category attributes will automatically be -set, and the glossary type will be provided using -\code{\ics{provideignoredglossary*}\margm{type}} (even if +but will create a \iext{glstex} file that inputs the +\gls{masterdocument}['s] \ext{glstex} files, but it will +additionally temporarily adjust the internal commands used to define +entries so that the prefix given by \csopt{label-prefix}, the +glossary type and the category type are all automatically inserted. +If the \csopt{type} or \csopt{category} options haven't been used, +the corresponding value will default to \optfmt{master}. The +\catattr{targeturl} and \catattr{targetname} category attributes +will automatically be set, and the glossary type will be provided +using \code{\ics{provideignoredglossary*}\margm{type}} (even if \longarg{no-provide-glossaries} is set). The above \filefmt{myarticle.tex} can be changed to: @@ -8294,13 +8465,13 @@ The above \filefmt{myarticle.tex} can be changed to: \cmd{end}\marg{document} \end{codeenv} -There are some settings from the master document that you +There are some settings from the \gls{masterdocument} that you still need to repeat in the other document. These include -the label prefixes set when the master document loaded -the resource files, and any settings in the master document -that relate to the master document's entries. +the label prefixes set when the \gls{masterdocument} loaded +the resource files, and any settings in the \gls{masterdocument} +that relate to the \gls{masterdocument}['s] entries. -For example, if the master document loaded a resource file +For example, if the \gls{masterdocument} loaded a resource file with \csopt[term.]{label-prefix} then you also need this prefix when you reference the entries in the dependent document in addition to the \optfmt{label-prefix} for the dependent document. @@ -8336,8 +8507,8 @@ but the category in the optional argument needs to be correct. \optsection{master-resources} -If the master document has multiple resource files -then by default all the master document's +If the \gls{masterdocument} has multiple resource files +then by default all the \gls{masterdocument}['s] \iext{glstex} files will be input. If you don't want them all you can use \optfmt{master-resources} to specify only those files that should be included. The value \meta{list} is @@ -8385,7 +8556,7 @@ as it may optionally start with \code{\oargm{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, \idxpl{crossresourceref} aren't +Note that if this setting is on, \iglspl{crossresourceref} aren't permitted. This setting has no effect if the interpreter has been disabled. @@ -8400,7 +8571,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, \idxpl{crossresourceref} aren't +Note that if this setting is on, \iglspl{crossresourceref} aren't permitted. The value is required for this key but may be empty, which indicates an empty set of fields (that is, the setting is switched off). @@ -8596,7 +8767,7 @@ start with \idprefix{dual} or \idprefix{tertiary} or \idprefix{extn} (where \meta{n} is an integer). Use \csopt{dual-prefix} to change the dual label prefixes and \csopt{ext-prefixes} to change the external label prefixes. -As from version 1.8, the primary label prefix is identified +As from version 1.8, the \primary\ label prefix is identified in the \ext{glstex} file with: \begin{codeenv} \format{bibglsprimaryprefixlabel} @@ -8645,8 +8816,8 @@ document with commands like \ics{gls}. The \sty{glossaries} package doesn't permit entries with duplicate labels (even if they're in different glossaries). If you -have multiple \idxpl{resourceset} and an entry that's selected -in one \idx{resourceset} is also selected in another, by +have multiple \iglspl{resourceset} and an entry that's selected +in one \igls{resourceset} is also selected in another, by default, \bibgls\ will issue a warning, but it will still write the entry definition to the \ext{glstex} file, which means you'll also get a warning from \sty{glossaries-extra} and the duplicate @@ -8702,7 +8873,7 @@ the \meta{label} will be converted as follows: \idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value; \item if \meta{label} starts with \idprefix{extn} then \idprefix{extn} will be replaced by the corresponding -\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is +\csopt{ext-prefixes} setting (if \igls{crossresourceref} mode is enabled, see \sectionref{sec:resourcesets}); \item if \meta{label} doesn't start with one of the above recognised prefixes then, if \csopt{cs-label-prefix} has been used the supplied @@ -8754,7 +8925,7 @@ substituted with the \meta{n}th tag listed in the comma-separated \meta{list}. If there aren't that many items in the list, the \idprefix{extn} will simply be removed. The default setting is an empty list, which will strip all \idprefix{extn} prefixes. -Remember that \idx{crossresourceref} mode needs to be enabled for +Remember that \igls{crossresourceref} mode needs to be enabled for this option to work (see \sectionref{sec:resourcesets}). As from version 1.8, the external label prefixes are identified @@ -8848,6 +9019,14 @@ start of the labels in the entry definitions and will replace the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the cross-references. +\optsection[\subsubsection]{prefix-only-existing} + +This is a boolean option. It's possible that a prefix can end up being +inserted when there's no entry in the current \igls{resourceset} that +matches the prefixed label. If this option is set then the prefix +won't be added if there's no matching entry. The default setting is +\csopt[false]{prefix-only-existing}. + \optsection[\subsubsection]{save-original-id} The \meta{value} may be the keywords \code{false} or \code{true} or @@ -8886,6 +9065,44 @@ has no associated key in \gls!{newglossaryentry} (such as will be set after field aliasing but before other options, such as \csopt{ignore-fields}. +\optsection[\subsubsection]{save-definition-index} + +This is a boolean option. If the value is omitted \code{true} is +assumed. The default setting is \csopt[false]{save-definition-index}. + +This setting will save the \gls{definitionindex} that's used by +\csopt[def]{identical-sort-action} to determine the order of +definition in the special internal field \field{definitionindex}. +This field is assigned when the entry is first created +and can be referenced with \gls{bibglsdefinitionindex}. +You can reference this field with certain resource options, such as +\csopt{format-integer-fields}, but you must place the +\csopt{save-definition-index} resource option first. + +Note that (unless you need to maintain \hierarchy) if you want to +order all entries by definition, it's better to use +\csopt[none]{sort}, which doesn't perform any sorting, so the order +will be by definition. + +\optsection[\subsubsection]{save-use-index} + +This is a boolean option. If the value is omitted \code{true} is +assumed. The default setting is \csopt[false]{save-use-index}. + +This setting will save the \gls{orderofuseindex} that's used by +\csopt[use]{identical-sort-action} in the special internal field +\field{useindex}. This field is assigned when the entry picks up +its first record and can be referenced with \gls{bibglsuseindex}. +You can't reference this field in resource options such as +\csopt{format-integer-fields}. + +Entries that don't have records won't have this field set. The order +of use corresponds to the first time the entry is recorded in the document. + +Note that (unless you need to maintain \hierarchy) if you want to +order all entries by use, it's better to use \csopt[use]{sort}, +which doesn't perform any sorting. + \optsection[\subsubsection]{dependency-fields} The \meta{list} should be a comma-separated list of fields that @@ -8896,7 +9113,7 @@ set of fields (that is, the setting is switched off). This setting makes those fields act like the \field{see} field by identifying the listed entries as dependencies, but the information -isn't added to the cross-reference part of the location list. This +isn't added to the cross-reference part of the \gls{locationlist}. This action is performed after \csopt{labelify-list}, if that's also set. For example, suppose the file \filefmt{entries-en.bib} contains: @@ -9122,8 +9339,8 @@ If, instead, the document contains: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} \end{codeenv} -then the \field{category} of all the primary selected entries will -be set to \optfmt{animals}. Again the dual entry \code{dual.dog} +then the \field{category} of all the \primary\ selected entries will +be set to \optfmt{animals}. Again the \gls{dualentry} \code{dual.dog} doesn't have the \field{category} set. Note that the categories may be overridden by the commands that are used to @@ -9163,11 +9380,11 @@ The \meta{value} may be one of: (\field{type} unchanged if \field{category} not set); \item \optfmt{same as parent}: sets the \field{type} to the same as -the entry's parent (new to v1.9). If the entry doesn't have a parent -or if the parent doesn't have the \field{type} field set, then +the entry's \parent\ (new to v1.9). If the entry doesn't have a +\parent\ or if the \parent\ doesn't have the \field{type} field set, then no change is made. Entries should always have the same type -as their parent, but it's possible for spawned entries to -pick up the \field{type} field from their \idx{progenitor} entry +as their \parent, but it's possible for spawned entries to +pick up the \field{type} field from their \igls{progenitor} entry (if it was explicitly set in the \ext{bib} file), which may be inappropriate. @@ -9190,7 +9407,7 @@ It's not possible to have both \end{important} Note that this setting only changes the \field{type} field for -primary entries. Use \csopt{dual-type} for dual entries. +\glspl{primaryentry}. Use \csopt{dual-type} for \glspl{dualentry}. For example: \begin{codeenv} @@ -9212,13 +9429,13 @@ example: \gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[dictionary]{type}} \end{codeenv} (The \styopt{nomain} option was added to suppress the -creation of the default \code{main} glossary.) +creation of the default \mainglossary.) \optsection[\subsubsection]{trigger-type} The record counting commands, such as \gls{rgls}, use the special format \ics{glstriggerrecordformat}, which \bibgls\ also treats -as an \idx{ignoredrecord}. This means the entry will still be +as an \igls{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 @@ -9237,25 +9454,25 @@ even if \longarg{no-provide-glossaries} is set \optsection[\subsubsection]{progenitor-type} -This sets the default \field{type} field for the main term defined by +This sets the default \field{type} field for the +\glsdisp{mainentry}{main term} defined by \atentry{progenitor}-like entries. The \meta{value} is as for \csopt{type}. This doesn't change the \field{type} for the spawned -\idx{progeny}. +\gls{progeny}. \optsection[\subsubsection]{progeny-type} -This sets the default \field{type} field for the \idx{progeny} term -spawned by -\atentry{progenitor}-like entries. The \meta{value} is as for -\csopt{type}. This doesn't change the \field{type} for the main -\idx{progenitor}. Remember that with the default -\csopt[parent]{adopted-parent-field} setting, the given type -should match the type of the parent entry. +This sets the default \field{type} field for the \gls{progeny} term +spawned by \atentry{progenitor}-like entries. The \meta{value} is as +for \csopt{type}. This doesn't change the \field{type} for the +\glsdisp{mainentry}{main} \gls{progenitor}. Remember that with the +default \csopt[parent]{adopted-parent-field} setting, the given type +should match the type of the \gls{parententry}. \optsection[\subsubsection]{adopted-parent-field} This identifies the target field to be set to the corresponding -value of the \field{adoptparents} list by the \idx{progeny} +value of the \field{adoptparents} list by the \gls{progeny} entries spawned by the \atentry{progenitor} type of entry. The default is \field{parent}. @@ -9306,7 +9523,7 @@ before determining the dependency lists. This means that \csopt[recorded and ancestors]{selection} won't pick up the label in the \field{parent} field. -If you want to maintain the dependency and ancestor relationship but +If you want to maintain the dependency and \gls{ancestor} relationship but omit the \field{parent} field when writing the entries to the \ext{glstex} file, you need to use \csopt{flatten} instead. @@ -9505,8 +9722,8 @@ the field given by \csopt{copy-action-group-field} set. Note that you may do \csopt[group]{copy-action-group-field} which will override the \field{group} field from the original definition. -This may be useful if you don't use grouping in the primary -glossary. That is, you use \code{nogroupskip} and a non-group +This may be useful if you don't use grouping in the +\gls{primaryglossary}. That is, you use \code{nogroupskip} and a non-group style. For example: \begin{codeenv} \cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}} @@ -9518,6 +9735,103 @@ style. For example: If set, the value of the \field{alias} field is copied to the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}. +\optsection[\subsubsection]{save-from-see} + +This option allows you to save a comma-separated list of entry +labels in a designated internal field of the target entry identified +by their \field{see} field. If the \meta{value} is omitted, +\csopt[from-see]{save-from-see} is assumed. The value may be the +keyword \code{false}, which switches off this setting, otherwise the +value should be the desired name of the internal field. +The default setting is \csopt[false]{save-from-see}. + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{index}\marg{gourd} +\atentry{index}{cucumber,\field{see}=\marg{gourd}} +\atentry{index}{pumpkin,\field{see}=\marg{gourd}} +\end{codeenv} +then the resource option \csopt[from-see]{save-from-see} will create +an internal field called \code{from-see} for the \code{gourd} entry +that contains the comma-separated list \code{cucumber,pumpkin}. + +Note that the given internal field isn't actually assigned within \bibgls, so it +can't be accessed via any resource options. Each item in this list is added using +\ics{glsxtrapptocsvfield} after the source entry (that is, the entry +containing the \field{see} field) is defined in the \ext{glstex} +file. This means that the list will be in the same order as the +entries. You can then pass the field value to \ics{glsseelist}. +For example: +\begin{codeenv} +\cs{glsdefpostdesc}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{from-see}\marg{\cs{glscurrententrylabel}} + {, related: \cs{glsseelist}\marg{\cs{glscurrentfieldvalue}}}{}% +} +\end{codeenv} + +This option has no effect with the \qt{no dependency} selection +criteria (such as \csopt[recorded no deps]{selection}). + +\optsection[\subsubsection]{save-from-seealso} + +As \csopt{save-from-see} but for the \field{seealso} field. If the +value is omitted, \csopt[from-seealso]{save-from-seealso} is assumed. + +\optsection[\subsubsection]{save-from-alias} + +As \csopt{save-from-see} but for the \field{alias} field. If the +value is omitted, \csopt[from-alias]{save-from-alias} is assumed. + +\optsection[\subsubsection]{save-crossref-tail} + +If you have a cross-reference trail where one entry references +another entry using \field{see}, \field{seealso} or \field{alias} +and the referenced entry also references another, and so on, then +you can save the tail end of the trail with this option. Note that +the trail only follows single-label lists (in \field{see} or +\field{seealso}). The trail is terminated if an entry doesn't have +one of those three fields set or if it cross-references multiple +entries or if the trail loops back on itself. + +If you have a loop, the tail for some entries may end prematurely +since the algorithm to obtain the tail saves the tail for each +sub-trail to avoid recalculating it. It's best to avoid +this setting if you have cross-reference loops. (Aside from two-way +cross-references, it's best to avoid loops in general.) + +The tail label is stored in the field identified by +the \meta{value} of this option. If the value is omitted, +\csopt[crossref-tail]{save-crossref-tail} is assumed. +The field won't be set if there's no tail. The tails are calculated +when writing the entry definitions to the \ext{glstex} file so the +value can't be referenced or otherwise accessed by \bibgls. + +Example: +\begin{codeenv} +\atentry{index}\marg{sample1,\field{see}=\marg{sample2}} +\atentry{index}\marg{sample2,\field{see}=\marg{sample3}} +\atentry{index}\marg{sample3,\field{see}=\marg{sample4}} +\atentry{index}\marg{sample4} +\end{codeenv} +The tail for \code{sample1} is \code{sample4}. As a by-product of +the recursion used in calculating the tail for \code{sample1}, the +tail for each element in the trail (\code{sample2} and +\code{sample3}) is also calculated. The tail is the same for each +entry in the trail. The final entry \code{sample4} doesn't have a +tail. + +If \code{sample4} is modified to cross-reference \code{sample1}: +\begin{codeenv} +\atentry{index}\marg{sample4,\field{see}=\marg{sample1}} +\end{codeenv} +then when the tail for \code{sample4} is calculated the tail for its +cross-reference (\code{sample1}) is consulted. This has already been +set to \code{sample4}. An entry can't have itself as a tail so the +tail for \code{sample4} is set to \code{sample3}. All the other +entries still have \code{sample4} as their tail because their tail +was determined while traversing the trail for \code{sample1}, which +had to stop when it wrapped round to its starting point. + \optsection[\subsubsection]{save-original-entrytype} The \meta{value} may be the keywords \code{false} or \code{true} or @@ -9750,13 +10064,13 @@ The final \code{:\meta{csname}} part may be omitted if no command need be applied. (That is, sort by label.) The value is required for this key but may be empty, which indicates the setting is switched off. -The sorting options are as those for the main list. For example, -for entries in the primary list the break point is obtained from the -\csopt{break-at} setting and for entries in the dual list the break -point is obtained from \csopt{dual-break-at}. (Remember that if -\csopt[combine]{dual-sort} then there is only one list that contains both -the primary and dual entries, which is governed by the primary -options only.) +The sorting options are as those for the \gls{mainlist}. For +example, for entries in the \glsdisp{mainlist}{primary list} the +break point is obtained from the \csopt{break-at} setting and for +entries in the \gls{duallist} the break point is obtained from +\csopt{dual-break-at}. (Remember that if \csopt[combine]{dual-sort} +then there is only one list that contains both the \primary\ and +\dual\ entries, which is governed by the \primary\ options only.) If the \meta{field-list} has more than one element take care to use braces \code{\marg{}} to avoid confusion for the @@ -9770,7 +10084,7 @@ list-parser. For example: Note that strange results may occur if this setting is used on any fields that don't simply contain a list of entry labels or if any of the referenced entries are processed in different -\idxpl{resourceset} (see \sectionref{sec:resourcesets}). +\iglspl{resourceset} (see \sectionref{sec:resourcesets}). After the main sorting of each set of selected entries is performed (as per \csopt{sort} or \csopt{dual-sort}), if this @@ -9803,8 +10117,8 @@ steps are performed: \end{enumerate} \end{enumerate} \end{enumerate} -Note that there is no hierarchical structure in the sorting of the field list -even if any of the referenced entries has a parent. +Note that there is no \hierarchical\ structure in the sorting of the field list +even if any of the referenced entries has a \parent. For example, suppose the file \filefmt{entries.bib} contains: \begin{codeenv} @@ -9892,11 +10206,11 @@ but in the \ext{glstex} file it's written as: \begin{codeenv} \field{seealso}=\marg{duckling,goose,parrot,swan} \end{codeenv} -Note that the hierarchical structure hasn't been maintained. The glossary -lists \qt{duckling} (a top-level entry) after \qt{swan} (a level~2 entry) +Note that the \hierarchical\ structure hasn't been maintained. The glossary +lists \qt{duckling} (a \gls{top-levelentry}) after \qt{swan} (a level~2 entry) but the \field{seealso} field has \code{duckling} first. -If you want to maintain the hierarchy you can use \ics{glsxtrhiername} instead +If you want to maintain the \hierarchy\ you can use \ics{glsxtrhiername} instead of \ics{glsentryname}: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ @@ -9927,11 +10241,11 @@ Therefore the \field{seealso} field for the \code{duck} entry ends up as: Now \code{swan} comes before \code{duckling} because the actual sort value started with a \qt{B} not \qt{S}. -This hierarchical information isn't shown in the cross-reference by +This \hierarchical\ information isn't shown in the cross-reference by default, so the \code{duck} cross-reference list appears in the document as: parrot, goose, swan \& duckling. -If you want the hierarchical information to appear to help assist +If you want the \hierarchical\ information to appear to help assist the reader, you can redefine \ics{glsseeitemformat} in the document to use \ics{glsxtrhiername}: \begin{codeenv} @@ -9970,8 +10284,8 @@ custom field is simply aliased to the \field{user1} field. The document has two glossaries for each set of terms. The English terms are sorted according to \csopt[en-GB]{sort} in one -\idx{resourceset} and the Portuguese terms are sorted according to -\csopt[pt-BR]{sort} in another \idx{resourceset}. This means that there +\igls{resourceset} and the Portuguese terms are sorted according to +\csopt[pt-BR]{sort} in another \igls{resourceset}. This means that there are cross-resource references, but since there are no instances of \atentry{preamble} it should be possible to resolve the references. @@ -10047,8 +10361,8 @@ texparserlib: {\glsentryname{gatinho}} -> gatinho The \code{kitten} entry has the same list, and the same process is repeated for that entry. The \longarg{verbose} mode will provide additional information. The \longarg{debug} mode will indicate whether the -referenced label was found in the current \idx{resourceset} or if it had -to be fetched from another \idx{resourceset}. So if the resulting +referenced label was found in the current \igls{resourceset} or if it had +to be fetched from another \igls{resourceset}. So if the resulting order isn't what you expect, check the transcript file for messages. \optsection[\subsubsection]{bibtex-contributor-fields} @@ -10180,9 +10494,9 @@ where \meta{value} was its previous value. An empty list switches off encapsulation (the default). This action overrides any previous use of \csopt{encapsulate-fields} -within the same \idx{resourceset} and is always performed before +within the same \igls{resourceset} and is always performed before \csopt{encapsulate-fields*}, regardless of the order in the -\idx{resourceset}['s] list of options. +\igls{resourceset}['s] list of options. \optsection[\subsubsection]{encapsulate-fields*} @@ -10203,14 +10517,65 @@ entry's label (including prefix, if appropriate). An empty list switches off encapsulation (the default). This action overrides any previous use of -\csopt{encapsulate-fields*} within the same \idx{resourceset}, and +\csopt{encapsulate-fields*} within the same \igls{resourceset}, and is always performed after \csopt{encapsulate-fields}, regardless of -the order in the \idx{resourceset}['s] list of options, so if the +the order in the \igls{resourceset}['s] list of options, so if the same field is listed in both settings, its value will end up as: \begin{codeenv} \cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label} \end{codeenv} +\optsection[\subsubsection]{format-integer-fields} + +This option should take a comma-separated list of +\optfmt{\meta{field}\dequals\meta{format}} values, where +\meta{format} is a +\href{https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax}{string +format pattern} that contains a single numeric specifier. +This will convert the value stored in the identified field to the +given format. If the field doesn't contain an integer value it won't +be changed. If the field contains a decimal value use +\csopt{format-decimal-fields} instead. This setting is performed +before field encapsulation. + +Since format patterns uses \idx{percentchar} as a placeholder, which +can be problematic in the resource command, you will need to use +\ics{cs.percent} instead. You may also use \ics{cs.hash}, +\ics{cs.dollar}, \ics{cs.amp}, \ics{cs.openbrace}, +\ics{cs.closebrace}, \ics{cs.underscore} and \ics{cs.backslash} to +indicate the corresponding literal character. You can use \cs{u}\meta{XXXX} to +indicate a character by its hexadecimal value, but remember that the +resource options will be expanded when they are written to the +resource file so use \cs{glshex} or \cs{cs.string}\cs{u}. + +If you want to format the \field{definitionindex} field you must use +\csopt{save-definition-index} first. For example, to save this field +and then zero-pad it to four digits: +\begin{codeenv} +\csopt{save-definition-index}, +\csopt[definitionindex=\ics{cs.percent}04d]{format-integer-fields} +\end{codeenv} +This option can't be used for the \field{useindex} field +created with \csopt{save-use-index} as that field isn't set until +after the field modifications are made. + +\optsection[\subsubsection]{format-decimal-fields} + +As \csopt{format-integer-fields} but for decimal values. If a field +contains an integer then: +\begin{itemize} +\item if \csopt{format-integer-fields} has also been used to set a +format for the given field, the integer format will take precedence; +\item otherwise the integer value will be treated as a decimal +number. +\end{itemize} +If you get an error like: +\begin{verbatim} +Error: d != java.lang.Double +\end{verbatim} +then it means you have used an invalid specifier. (The above error +results from using \verb|%d| instead of \verb|%f| or \verb|%g|.) + \optsection[\subsubsection]{interpret-fields} This option indicates that the listed fields should be replaced by @@ -10372,9 +10737,9 @@ to: \formatdef{bibglsdate} The fields are parsed according to \csopt{date-field-format} and -\csopt{date-field-locale} for primary entries and according to +\csopt{date-field-locale} for \glspl{primaryentry} and according to \csopt{dual-date-field-format} and -\csopt{dual-date-field-locale} for dual entries. +\csopt{dual-date-field-locale} for \glspl{dualentry}. \optsection[\subsubsection]{time-fields} @@ -10384,9 +10749,9 @@ to: \formatdef{bibglstime} The fields are parsed according to \csopt{time-field-format} and -\csopt{time-field-locale} for primary entries and according to +\csopt{time-field-locale} for \glspl{primaryentry} and according to \csopt{dual-time-field-format} and -\csopt{dual-time-field-locale} for dual entries. +\csopt{dual-time-field-locale} for \glspl{dualentry}. \optsection[\subsubsection]{date-time-field-format} @@ -10650,12 +11015,32 @@ in \TeX\ or by the \TeX\ parser library when interpreting field values). Only words in the exclusion list that start with an alphabetical character can be matched. Punctuation following a word-boundary is not considered part of the next word. +If you want to identify that a particular character forms a word +break, you can use \code{\ics{MFUwordbreak}\margm{char}}. For +example: +\begin{codeenv} +\field{name}=\marg{some word\cs{MFUwordbreak}\marg{/}phrase} +\end{codeenv} \end{itemize} The \optfmt{firstuc-cs} and \optfmt{firstuc} options are essentially a \idx{sentencecase} change, but there's no check for sentence-breaks within the value, so even if the value contains -multiple sentences, only the first is changed. +multiple sentences, only the first is changed. If the text to be +changed starts with a punctuation character it should be +encapsulated with \ics{MFUskippunc} to apply the case-change to the +following object. For example: +\begin{codeenv} +\field{name}=\marg{\cs{MFUskippunc}\marg{'}tis} +\end{codeenv} +If the \optfmt{firstuc} option is applied to the \field{name} field +this will be converted to: +\begin{codeenv} +\field{name}=\marg{\cs{MFUskippunc}\marg{'}Tis} +\end{codeenv} +Using \ics{NoCaseChange} (provided by \sty{textcase}) instead will have the +same effect, but this isn't consistent with the behaviour of +\ics{makefirstuc} so it's best to use \cs{MFUskippunc} instead. The \optfmt{\meta{option}-cs} settings defer the actual case-changing to \TeX, which means that the case-changing has to be applied every @@ -10663,8 +11048,6 @@ time the field is typeset (and it introduces non-expandable content to the field value). Be aware of the limitations of using any of the case-changing commands. See the \isty{textcase} and \isty{mfirstuc} package documentation for further details~\cite{textcase,mfirstuc}. -You may use \code{\ics{NoCaseChange}\margm{content}} (provided by -\sty{textcase}) to prevent any \idx{case-change} to \meta{content}. For the settings where \bibgls\ itself performs the \idx{case-change}, then \bibgls\ will iterate over each token of the field value and apply @@ -10707,7 +11090,8 @@ different). If the option is \optfmt{firstuc} then all the remaining tokens are skipped. If the option is \optfmt{title} then the subsequent tokens -are skipped until a word-boundary is found. +are skipped until a word-boundary is found. A word-boundary can be +marked up with \ics{MFUwordbreak}. \item If a control sequence \csfmt{}\meta{csname} is found, then: @@ -10715,6 +11099,12 @@ are skipped until a word-boundary is found. \item If the control sequence is \cs{protect}, this token is skipped for all options. + \item With \optfmt{firstuc} and \optfmt{title}, if + \code{\ics{MFUskippunc}\margm{text}} or \code{\ics{NoCaseChange}\margm{text}} + occurs at the start of a word, then \bibgls\ will act as though + the word hasn't started yet (so the next token will be considered + for a \idx{case-change}). + \item If the control sequence is one of: \ics{o}, \ics{O}, \ics{l}, \ics{L}, \ics{ae}, \ics{AE}, \ics{oe}, \ics{OE}, \ics{aa}, \ics{AA}, \ics{ss}, \ics{SS}, \ics{ng}, \ics{NG}, \ics{th}, \ics{TH}, @@ -10726,25 +11116,16 @@ are skipped until a word-boundary is found. skipped. If the option is \optfmt{title} then the subsequent tokens are skipped until a word-boundary is found. - \item If the control sequence is \ics{NoCaseChange} or is in the - \csopt{no-case-change-cs} list, then the - control sequence and its argument is ignored. With \optfmt{firstuc} - and \optfmt{title}, if \code{\ics{NoCaseChange}\margm{text}} - (but not any \csopt{no-case-change-cs} command) - occurs at the start of a word, then \bibgls\ will act as though - the word hasn't started yet (so the next token will be considered - for a \idx{case-change}). This is different to the way \ics{makefirstuc} - and \ics{capitalisewords} work. - - \item If the control sequence is \ics{ensuremath}, \ics{si} or if - \meta{csname} ends with \qtt{ref} (for example, \ics{ref} or - \ics{pageref}) then the control sequence and its argument is ignored. - In the case where \meta{csname} ends with \qtt{ref}, a following - star (\code{*}) or optional argument before the mandatory argument - will also be skipped. This allows for some common cross-referencing - commands, such as \sty{hyperref}['s] \ics{autoref}, which may have - a starred form, but does not allow for more complicated commands with - multiple arguments. + \item If the control sequence is in the \csopt{no-case-change-cs} + list or is \ics{ensuremath}, \ics{si} or if + \meta{csname} ends with \qtt{ref} (for example, \ics{ref} or + \ics{pageref}) then the control sequence and its argument is + ignored. In the case where \meta{csname} ends with \qtt{ref}, a + following star (\code{*}) or optional argument before the mandatory + argument will also be skipped. This allows for some common + cross-referencing commands, such as \sty{hyperref}['s] + \ics{autoref}, which may have a starred form, but does not allow for + more complicated commands with multiple arguments. If the option is \optfmt{firstuc} then all the remaining tokens are skipped (so no \idx{case-change} will be performed). If the option is @@ -10989,16 +11370,16 @@ A\cs{NoCaseChange}\marg{bc}D \end{codeenv} Note that with \optfmt{firstuc} and \optfmt{title}, if -\code{\ics{NoCaseChange}\margm{text}} occurs at the start of a word +\code{\ics{MFUskippunc}\margm{text}} occurs at the start of a word then it's skipped, and the case change is applied to the material following its argument. For example, suppose the \field{short} field is defined as: \begin{codeenv} -\field{short}=\marg{\cs{NoCaseChange}\marg{h}tml} +\field{short}=\marg{\cs{MFUskippunc}\marg{h}tml} \end{codeenv} then the result is: \begin{codeenv} -\cs{NoCaseChange}\marg{h}Tml +\cs{MFUskippunc}\marg{h}Tml \end{codeenv} whereas with: \begin{codeenv} @@ -11065,6 +11446,12 @@ The default setting is \csopt[white space,cs space]{word-boundaries}, which excludes non-breakable spaces and dashes. +Note that you can explicitly markup word-boundary punctuation using +\ics{MFUwordbreak}. For example: +\begin{codeenv*} +\field{name} = \marg{a book of rhyme\cs{MFUwordbreak}\marg{/}verse} +\end{codeenv*} + \optsection[\subsubsection]{short-case-change} Applies a case-change to the \field{short} field (if present). @@ -11132,7 +11519,7 @@ expandable \idx{titlecase} form that's suitable for the PDF bookmarks. This option isn't cumulative. If used multiple times in the same -\idx{resourceset}, the last instance will be the one used. If +\igls{resourceset}, the last instance will be the one used. If the \keyvallist\ is missing, no general case-changing is applied (the default). @@ -11243,7 +11630,7 @@ Now just make sure all the French abbreviations are have their \end{codeenv} The other approach is to use the options listed below for the given -\idx{resourceset}. For example: +\igls{resourceset}. For example: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}} \end{codeenv} @@ -11279,15 +11666,17 @@ The \styopt{record} package option automatically adds two new keys: \bibgls\ from the information supplied in the \iext{aux} file (unless the option \csopt[false]{save-locations} is used). The \field{location} field contains the code to typeset the formatted -\idx{locationlist}. - -The \field{loclist} field has the syntax of an \isty{etoolbox} internal list -and includes every location (except for the discarded duplicates and -\idxpl{ignoredrecord}) with no range formations. Any explicit range markup -is stripped from the \glsopt{format} information to leave just the \idx{encap} -name, so you just get the start and end locations added as individual -elements but they are still encapsulated with the associated formatting -command. Each item in the list is provided in one of the following forms: +\igls{locationlist}. + +The \field{loclist} field has the syntax of an \isty{etoolbox} +internal list and includes every \gls{location} (except for the +\glsdisp{discardedrecord}{discarded duplicates} and +\iglspl{ignoredrecord}) with no range formations. Any explicit range +markup is stripped from the \glsopt{format} information to leave +just the \idx{encap} name, so you just get the start and end +\glspl{location} added as individual elements but they are still +encapsulated with the associated formatting command. Each item in +the list is provided in one of the following forms: \begin{codeenv} \ics{glsseeformat}\oargm{tag}\margm{label list}\marg{} \end{codeenv} @@ -11297,16 +11686,16 @@ for the cross-reference supplied by the \field{see} field, \end{codeenv} for the cross-reference supplied by the \field{seealso} field, \nosecdef{glsnoidxdisplayloc} -for standard the internal locations, +for standard the internal \glspl{location}, \begin{codeenv} \format{glsxtrdisplaysupploc} \end{codeenv} -for supplemental (external) locations and +for \glsdisp{supplementalrecord}{supplemental (external) locations} and \begin{codeenv} \format{glsxtrdisplaylocnameref} \end{codeenv} -for \code{nameref} records. (See \sectionref{sec:supplementalopts} -for more information about supplemental locations and +for \code{nameref} \glspl{record}. (See \sectionref{sec:supplementalopts} +for more information about \glsdisp{supplementalrecord}{supplemental locations} and \longarg{merge-nameref-on} for more information about \code{nameref} records.) @@ -11323,21 +11712,21 @@ when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or default value is changed with \ics{GlsXtrSetDefaultNumberFormat}. The value of the \glsopt{format} key must be the name of a text-block command without the leading backslash that takes -a single argument (the location). The location +a single argument (the \gls{location}). The \gls{location} is encapsulated by that command. For example, \begin{codeenv} \cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample} \end{codeenv} -will display the corresponding location in bold, but note that this +will display the corresponding \gls{location} in bold, but note that this will no longer have a hyperlink if you've used \sty{hyperref}. -If you want to retain the hyperlink you need the location +If you want to retain the hyperlink you need the \gls{location} encapsulated with \cs{hyperbf} instead of \cs{textbf}: \begin{codeenv} \cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} \end{codeenv} The \csfmt{hyper}\meta{xx} set of commands all internally use \cs{glshypernumber} which adds the appropriate hyperlink to the -location. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries} +\gls{location}. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries} user manual for a list of all the \csfmt{hyper}\meta{xx} commands. Ranges can be explicitly formed using the parenthetical @@ -11348,53 +11737,55 @@ a text-block command without the initial backslash) in the optional argument of commands like \ics{gls} or \ics{glsadd}. These will always form a range, regardless of \csopt{min-loc-range}, and will be encapsulated by \gls!{bibglsrange}. (This command is not used with -ranges that are formed by collating consecutive locations.) The +ranges that are formed by collating consecutive \glspl{location}.) The initial marker is stripped from the \meta{format} argument of the -location formatting commands, such as \gls{glsnoidxdisplayloc}, to +\gls{location} formatting commands, such as \gls{glsnoidxdisplayloc}, to allow for easy conversion to the corresponding text-block command. -Explicit ranges don't merge with neighbouring locations, but will -absorb any single locations within the range that don't conflict. -(Conflicts will be moved to the start of the explicit range.) -For example, if \code{\cs{gls}\marg{sample}} is used on page~1, -\code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} is used on page~2, -\code{\cs{gls}\marg{sample}} is used on page~3, and -\code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} is used on page~4, then the location -list will be 1, 2--4. The entry on page~3 is absorbed into the -explicit range, but the range can't be expanded to include page~1. -If the entry on page~3 had a different format to the explicit range, -for example \code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}} +Explicit ranges don't merge with neighbouring \glspl{location}, but +will absorb any single \glspl{location} within the range that don't +conflict. (Conflicts will be moved to the start of the explicit +range.) For example, if \code{\cs{gls}\marg{sample}} is used on +page~1, +\code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} +is used on page~2, \code{\cs{gls}\marg{sample}} is used on page~3, and +\code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} +is used on page~4, then the \gls{locationlist} will be 1, 2--4. The +entry on page~3 is absorbed into the explicit range, but the range +can't be expanded to include page~1. If the entry on page~3 had a +different format to the explicit range, for example +\code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{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. +range so that the \gls{locationlist} 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. +An \igls{ignoredrecord} identifies a term that needs to be treated as +though it has a \gls{record} for selection purposes, but the +\gls{record} should not be included in the \gls{locationlist}. The special format \glsaddopt[\encap{glsignore}]{format} is provided -by the \styfmt{glossaries} package for cases where the location +by the \styfmt{glossaries} package for cases where the \gls{location} should be ignored. (The command \ics{glsignore} simply ignores its argument.) This works reasonably well if an entry only has the one -location, but if the entry happens to be indexed again, it can lead -to an odd empty gap in the location list with a spurious comma. If -\bibgls\ encounters a record with this special format, the entry -will be selected but the record will be discarded. +\gls{location}, but if the entry happens to be indexed again, it can lead +to an odd empty gap in the \gls{locationlist} with a spurious comma. If +\bibgls\ encounters a \gls{record} with this special format, the entry +will be selected but the \gls{record} will be discarded. -This means that the location list will be empty if the entry was +This means that the \gls{locationlist} 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 -\idxpl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but +indexed with another format then the \gls{locationlist} won't include the +\iglspl{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.) +Those that don't have \glspl{record} won't have a \gls{locationlist}.) -For example, suppose you only want main matter locations in the +For example, suppose you only want main matter \glspl{location} in the number list, but you want entries that only appear in the back matter -to still appear in the glossary (without a location list), then you could do: +to still appear in the glossary (without a \gls{locationlist}), then you could do: \begin{codeenv} \ics{backmatter} \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} -If you also want to drop front matter locations as well: +If you also want to drop front matter \glspl{location} as well: \begin{codeenv} \ics{frontmatter} \cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} @@ -11413,29 +11804,29 @@ Note that explicit range formations aren't discarded, so if \ldots \cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample} \end{codeenv} -then the range will be included in the location list (encapsulated +then the range will be included in the \gls{locationlist} (encapsulated with \ics{glsignore}), but this case would be a rather odd use of this special format and is not recommended. -The record counting commands, such as \gls{rgls}, use the special +The \gls{record} counting commands, such as \gls{rgls}, use the special format \encap{glstriggerrecordformat}, which \bibgls\ also treats -as an \idx{ignoredrecord} and the same rules as for \encap{glsignore} apply. +as an \igls{ignoredrecord} and the same rules as for \encap{glsignore} apply. -The locations are always listed in the order in which they were indexed, +The \glspl{location} are always listed in the order in which they were indexed, (except for the cross-reference which may be placed at the start or end of the list or omitted). This is different to \idx!{xindy} and \idx!{makeindex} where you can specify the ordering (such as \idx!{lowercase} Roman first, then digits, -etc), but unlike those applications, \bibgls\ allows any location, +etc), but unlike those applications, \bibgls\ allows any \gls{location}, although it may not be able to work out an integer representation. -(With \idx!{xindy}, you can define new location formats, but you need +(With \idx!{xindy}, you can define new \gls{location} formats, but you need to remember to add the appropriate code to the custom module.) It's possible to define a custom glossary style where -\ics{glossentry} (and the child form \ics{subglossentry}) ignore the +\ics{glossentry} (and the \child\ form \ics{subglossentry}) ignore the final argument (which will be the \field{location} field) and instead parse the \field{loclist} field and re-order the -locations or process them in some other way. Remember that you can +\glspl{location} or process them in some other way. Remember that you can also use \ics{glsnoidxloclist} provided by \styfmt{glossaries}. For example: \begin{codeenv} @@ -11443,12 +11834,12 @@ provided by \styfmt{glossaries}. For example: \cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations} \end{codeenv} This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler} -macro, which simply displays each location separated by \ics{delimN}. +macro, which simply displays each \gls{location} separated by \ics{delimN}. (See also \href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration Tips and Tricks}~\cite{iterationtips}.) -Each regular location is listed in the \iext{aux} file in the form: +Each regular \gls{location} is listed in the \iext{aux} file in the form: \nosecdef{glsxtr@record} (See \longarg{merge-nameref-on} for \code{nameref} records.) Exact duplicates are discarded. For example, if \code{cat} @@ -11457,8 +11848,8 @@ is indexed twice on page 1: \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} \end{codeenv} -then the second record is discarded. Only the first record is added -to the location list. +then the second \gls{record} is discarded. Only the first +\gls{record} is added to the \gls{locationlist}. Partial duplicates, where all arguments match except for \meta{format}, may be discarded depending on the value @@ -11470,30 +11861,30 @@ then the \ext{aux} file will contain: \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} \gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{1} \end{codeenv} -This is a partial record match. In this case, \bibgls\ +This is a partial \gls{record} match. In this case, \bibgls\ makes the following tests: \begin{itemize} \item If one of the formats includes a range formation, the range takes precedence. \item If one of the formats is \encap{glsnumberformat} (as in the -above example) or an \idx{ignoredrecord} format such as +above example) or an \igls{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 +example, the second \gls{record} will be added to the \gls{locationlist}, 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 +\igls{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. -\item Otherwise the duplicate record will be discarded with a +\item Otherwise the duplicate \gls{record} will be discarded with a warning. \end{itemize} -The \field{location} field is used to store the formatted location -list. The code for this list is generated by \bibgls\ based on the +The \field{location} field is used to store the formatted +\gls{locationlist}. The code for this list is generated by \bibgls\ based on the information provided in the \iext{aux} file, the presence of the \field{see} or \field{seealso} field and the various settings described in this chapter. When you display the glossary using \ics{printunsrtglossary}, @@ -11507,15 +11898,15 @@ For more information on adjusting the formatting see the \optsection{save-locations} -By default, the locations will be processed and stored in the +By default, the \glspl{location} will be processed and stored in the \field{location} and \field{loclist} fields. However, if you don't -want the location lists (for example, you are using the +want the \glspl{locationlist} (for example, you are using the \styopt{nonumberlist} option or you are using \idx!{xindy} with a -custom location rule), then there's no need for \bibgls\ to process -the locations. To switch this function off, just use +custom \gls{location} rule), then there's no need for \bibgls\ to process +the \glspl{location}. To switch this function off, just use \csopt[false]{save-locations}. Note that with this setting, if you're not additionally using \idx!{makeindex} or \idx!{xindy}, then -the locations won't be available even if you don't have the +the \glspl{location} won't be available even if you don't have the \styopt{nonumberlist} option set. The boolean \field{nonumberlist} key that may be used in @@ -11528,10 +11919,10 @@ The \field{nonumberlist} key provided by the base \sty{glossaries} package doesn't represent a real field. The value isn't saved but, if used, it will alter the indexing information that's written to the \idx!{makeindex} or \idx!{xindy} file. It's a little hack to -ensure that the location is hidden for a specific entry when used +ensure that the \gls{location} is hidden for a specific entry when used with \idx!{makeindex} and \idx!{xindy}. -\bibgls\ will look for this key to determine if the location should +\bibgls\ will look for this key to determine if the \gls{location} should be omitted for the given entry, but it won't write the key to the \ext{glstex} file. @@ -11543,50 +11934,64 @@ This can help to save resources and build time. \optsection{save-primary-locations} -It's sometimes useful to identify primary locations with a different +A synonym for \csopt{save-principal-locations}. + +\optsection{save-principal-locations} + +It's sometimes useful to identify a \igls{principallocation} with a different format, such as bold or italic. This helps the reader select which -location to try first in the event of a long location list. However, -you may prefer to store the primary location in a different field to +\gls{location} to try first in the event of a long \gls{locationlist}. However, +you may prefer to store the \glspl{principallocation} in a different field to give it a more prominent position. In order to do this you -need to specify the format (or formats) used to identify primary -locations with \csopt{primary-location-formats} and -use \csopt{save-primary-locations} to determine how to deal with -these locations. +need to specify the format (or formats) used to identify +\glspl{principallocation} with \csopt{principal-location-formats} and +use \csopt{save-principal-locations} to determine how to deal with +these \glspl{location}. This option may take one of the following values: \begin{itemize} -\item \optfmt{false}: don't save primary locations (default); -\item \optfmt{retain}: save primary locations in the +\item \optfmt{false}: don't save \glspl{principallocation} (default); + +\item \optfmt{retain}: save \glspl{principallocation} in the \field{primarylocations} field but don't remove from the usual -\idx{locationlist}; +\igls{locationlist}; + \item \optfmt{default format}: similar to \optfmt{retain} but the -format for the primary records in the \field{location} field is -converted to the default \encap{glsnumberformat} \idx{encap} (the records in the +format for the \glsdisp{principallocation}{principal records} in the +\field{location} field is converted to the default +\encap{glsnumberformat} \idx{encap} (the \glspl{record} in the \field{primarylocations} field retain their given format); -\item \optfmt{start}: save primary locations in the + +\item \optfmt{start}: save \glspl{principallocation} in the \field{primarylocations} field and also move to the start of the -usual \idx{locationlist}; -\item \optfmt{remove}: save primary locations in the +usual \igls{locationlist}; + +\item \optfmt{remove}: save \glspl{principallocation} in the \field{primarylocations} field and remove from the usual -\idx{locationlist}. +\igls{locationlist}. You may want to consider using the +\longswitch{retain-formats} switch with this setting if you don't +want to lose a partial \gls{location} match (for example, if the +\gls{principallocation} coincides with the start of an explicit range). + \end{itemize} -The primary locations are copied to the \field{primarylocations} +The \glspl{principallocation} are copied to the \field{primarylocations} field and encapsulated with \gls!{bibglsprimary}. -If you use \csopt[remove]{save-primary-locations}, the -\field{location} field will end up empty if the locations for the -associated entry were all identified as primary. If you use -\csopt[start]{save-primary-locations}, all primary locations will be -moved to the start of the \idx{locationlist} stored in the +If you use \csopt[remove]{save-principal-locations}, the +\field{location} field will end up empty if the \glspl{location} for the +associated entry were all identified as principal. If you use +\csopt[start]{save-principal-locations}, all +\glspl{principallocation} will be +moved to the start of the \igls{locationlist} stored in the \field{location} field, but there will be no additional markup (other than the given format) to identify them. If you need -additional markup, then use \csopt[remove]{save-primary-locations} -and adjust the \idx{locationlist} format to insert the primary -locations at the start. This can be done by modifying the glossary +additional markup, then use \csopt[remove]{save-principal-locations} +and adjust the \igls{locationlist} format to insert the +\glspl{principallocation} at the start. This can be done by modifying the glossary style. For example, the \glostyle{bookindex} style inserts -\ics{glsxtrbookindexprelocation} before the location, so you could +\ics{glsxtrbookindexprelocation} before the \gls{location}, so you could redefine this: \begin{codeenv} \cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} @@ -11601,8 +12006,8 @@ redefine this: } \end{codeenv} (Note that if \csopt{loc-prefix} is used, the prefix will be -in the \field{location} field and so will come after the primary -locations in the above example. Similarly for cross-references +in the \field{location} field and so will come after the +\glspl{principallocation} in the above example. Similarly for cross-references unless they've been omitted.) You can switch from using the \field{location} field to the @@ -11620,12 +12025,16 @@ consider using \csopt[false]{save-loclist} to prevent this. \optsection{primary-location-formats} +A synonym for \csopt{principal-location-formats}. + +\optsection{principal-location-formats} + This option will automatically set -\csopt[retain]{save-primary-locations} unless it has already been -changed from the default \csopt[false]{save-primary-locations} +\csopt[retain]{save-principal-locations} unless it has already been +changed from the default \csopt[false]{save-principal-locations} setting. The argument should be a comma-separated list of formats. If a record's format is contained in this list then it will -be considered a primary location and it will be included in the +be considered a \igls{principallocation} and it will be included in the associated entry's \field{primarylocations} field. For example, suppose the file \filefmt{entries.bib} contains: @@ -11660,8 +12069,8 @@ and the document \filefmt{test.tex} contains: \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[entries]{src}, - \csopt[hyperbf,hyperemph]{primary-location-formats}, - \csopt[remove]{save-primary-locations} + \csopt[hyperbf,hyperemph]{principal-location-formats}, + \csopt[remove]{save-principal-locations} } \strut \cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} @@ -11698,19 +12107,22 @@ and the document \filefmt{test.tex} contains: \cmd{end}\marg{document} \end{codeenv} -The \csopt[\encap{hyperbf},\encap{hyperemph}]{primary-location-formats} setting -in the above indicates that locations encapsulated with \ics{hyperbf} and -\ics{hyperemph} are primary records. In this case, the bold format is used to -indicate the primary location in the main document text and the emphasized -format is used to indicate the location in the main glossary. +The \csopt[\encap{hyperbf},\encap{hyperemph}]{principal-location-formats} +setting in the above indicates that \glspl{location} encapsulated with +\ics{hyperbf} and \ics{hyperemph} are +\glsdisp{principallocation}{principal records}. In this case, the +bold format is used to indicate the \gls{principallocation} in the +main document text and the emphasized format is used to indicate the +\gls{location} in the \gls{mainglossary}. -The primary records are removed from the \field{location} field -due to the \csopt[remove]{save-primary-locations} setting. This can -lead to a ragged location list. The option -\csopt[default format]{save-primary-locations} can allow the primary -location to be absorbed into a range. +The \glsdisp{principallocation}{principal records} are removed from +the \field{location} field due to the +\csopt[remove]{save-principal-locations} setting. This can lead to a +ragged \gls{locationlist}. The option \csopt[default +format]{save-principal-locations} can allow the +\gls{principallocation} to be absorbed into a range. -The main glossary records are added through the category-independent post-name +The \gls{mainglossary} records are added through the category-independent post-name hook with \cs{glsadd}. This won't be implemented until the entries are actually defined as the page number can't be determined until the glossary can be displayed. This means that the document build requires an extra \bibgls\ and @@ -11724,15 +12136,15 @@ pdflatex test \end{verbatim} For consistency, I've used \gls{glsxtrnewglslike} to provide commands -used to indicate a primary reference in the text. This means that if -I decide to change the optional arguments used for primary +used to indicate a principal reference in the text. This means that if +I decide to change the optional arguments used for principal references I only need to edit one line. For example, I might want to change the default counter: \begin{codeenv} \gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format},\glsopt[\counter{chapter}]{counter}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} \end{codeenv} -Here's another example that only has one primary format (\encap{hyperrm}) +Here's another example that only has one principal format (\encap{hyperrm}) that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets up a hook that automatically inserts: \begin{codeenv*} @@ -11756,8 +12168,8 @@ counter (from the \cs{glsadd} command in the hook), and then with the \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[topics]{src}, - \csopt[hyperrm]{primary-location-formats}, - \csopt[remove]{save-primary-locations}, + \csopt[hyperrm]{principal-location-formats}, + \csopt[remove]{save-principal-locations}, \csopt[false]{save-loclist} } \strut @@ -11789,20 +12201,24 @@ counter (from the \cs{glsadd} command in the hook), and then with the \cmd{end}\marg{document} \end{codeenv} -Note that in this case, from \bibgls' point of view, the primary format is -\encap{hyperrm} not \code{primaryfmt}. This picks out the records created with -the automated \ics{glsadd}, which have the counter set to \counter{chapter}. -The first glossary (with the title \qt{Summary}) switches the location field to -\field{primarylocations} so that only the primary records are listed. Since -\styopt[nameref]{record} has been used this means that the chapter title is -shown rather than the chapter number. - -The second glossary (\qt{Index}) shows the location lists that only -have the \counter{page} counter (because the automated \cs{glsadd} -records with the \counter{chapter} counter have been removed because -they were identified as primary records). These just show the page -number as that's the default display with \styopt[nameref]{record} -for records with the \counter{page} counter. +Note that in this case, from \bibgls' point of view, the principal +format is \encap{hyperrm} not \code{primaryfmt}. This picks out the +records created with the automated \ics{glsadd}, which have the +counter set to \counter{chapter}. The first glossary (with the +title \qt{Summary}) switches the location field to +\field{primarylocations} so that only the +\glsdisp{principallocation}{principal records} are listed. Since +\styopt[nameref]{record} has been used this means that the chapter +title is shown rather than the chapter number. + +The second glossary (\qt{Index}) shows the \glspl{locationlist} that +only have the \counter{page} counter (because the automated +\cs{glsadd} records with the \counter{chapter} counter have been +removed because they were identified as +\glsdisp{principallocation}{principal records}). These just show the +page number as that's the default display with +\styopt[nameref]{record} for records with the \counter{page} +counter. An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply define the custom commands as follows: @@ -11826,34 +12242,34 @@ define the custom commands as follows: \end{codeenv} This is more useful if you want to simply omit the \code{\glsopt[primaryfmt]{format}} option (just remove it from the above four -definitions), which makes it easier to merge the locations into +definitions), which makes it easier to merge the \glspl{location} into ranges in the index. \optsection{min-loc-range} -By default, three or more consecutive locations \meta{loc-1}, +By default, three or more consecutive \glspl{location} \meta{loc-1}, \meta{loc-2}, \ldots, \meta{loc-n} are compressed into the range \code{\meta{loc-1}\ics{delimR} \meta{loc-n}}. Otherwise -the locations are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}. +the \glspl{location} are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}. As mentioned above, these aren't merged with explicit range formations. You can change this with the \csopt{min-loc-range} setting where \meta{value} is either \optfmt{none} (don't form ranges) or an -integer greater than one indicating how many consecutive locations should be -converted into a range. +integer greater than one indicating how many consecutive +\glspl{location} should be converted into a range. -\bibgls\ determines if one location +\bibgls\ determines if one \gls{location} \code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}} -is one unit more than another location +is one unit more than another \gls{location} \code{\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} } according to the following: \begin{enumerate} \item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or \meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1} -is not equal to \meta{format-2}, then the locations aren't +is not equal to \meta{format-2}, then the \glspl{location} aren't considered consecutive. \item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty, -then the locations aren't considered consecutive. +then the \glspl{location} aren't considered consecutive. \item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}} used in the \idx{regex} will match any digits in the @@ -11866,9 +12282,9 @@ characters outside the Basic Latin set.} then: \begin{itemize} \item if the control sequence matched by group 2 isn't the same for - both locations, the locations aren't considered consecutive; + both \glspl{location}, the \glspl{location} aren't considered consecutive; \item if the argument of the control sequence (group 3) is the same for - both locations, then the test is retried with \meta{location-1} + both \glspl{location}, then the test is retried with \meta{location-1} set to group 1 of the first pattern match and \meta{location-2} set to group 1 of the second pattern match; \item otherwise the test is retried with \meta{location-1} set to @@ -11885,7 +12301,7 @@ then: \item\label{itm:decgrp3eq} if group 3 of both pattern matches are equal then: \begin{enumerate} - \item\label{itm:decgrp3nz} if group 3 isn't zero, the locations + \item\label{itm:decgrp3nz} if group 3 isn't zero, the \glspl{location} aren't considered consecutive; \item if the separators (group 2) are different the test is retried with \meta{location-1} set to the concatenation of the first @@ -11905,11 +12321,11 @@ and \meta{location-2} set to the first group or \meta{group-2} of the first pattern match (of \meta{location-1}) doesn't equal \meta{group-2} of the second pattern match (of \meta{location-2}) -then the locations aren't considered consecutive; +then the \glspl{location} aren't considered consecutive; \item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $ where $l_2$ is \meta{group 3} of the second pattern match, $l_1$ is \meta{group 3} of the first pattern match and -$d$ is the value of \optfmt{max-loc-diff} then the locations +$d$ is the value of \optfmt{max-loc-diff} then the \glspl{location} are consecutive otherwise they're not consecutive. \end{enumerate} \item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} @@ -11925,7 +12341,7 @@ where \meta{c} is either a \idx!{lowercase} letter from \code{a} to \code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}. The character is converted to its code point and the test is performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above. -\item\label{itm:nomatch} If none of the above, the locations aren't considered +\item\label{itm:nomatch} If none of the above, the \gls{location} aren't considered consecutive. \end{enumerate} @@ -11937,7 +12353,7 @@ Examples: \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2} \end{codeenv} These records are consecutive. The prefix, counter and format are -identical (so the test passes step~\ref{itm:pre}), the locations match +identical (so the test passes step~\ref{itm:pre}), the \glspl{location} match the \hyperref[itm:decmatch]{decimal pattern} and the test in step~\ref{itm:decgrp3} passes. @@ -11954,11 +12370,11 @@ These records aren't consecutive since the formats are different. \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.ii} \end{codeenv} These records are consecutive. The prefix, counter and format are -identical (so it passes step~\ref{itm:pre}). The locations match +identical (so it passes step~\ref{itm:pre}). The \glspl{location} match the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where \code{A} is considered a prefix and the dot is consider a separator. The Roman numerals i and ii are converted to decimal and -the test is retried with the locations set to 1 and 2, respectively. +the test is retried with the \glspl{location} set to 1 and 2, respectively. This now passes the decimal pattern test (step~\ref{itm:decgrp3}). \item @@ -11967,10 +12383,10 @@ This now passes the decimal pattern test (step~\ref{itm:decgrp3}). \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{ii.A} \end{codeenv} These records aren't consecutive. They match the -\hyperref[itm:alphmatch]{alpha pattern}. The first location is +\hyperref[itm:alphmatch]{alpha pattern}. The first \gls{location} is considered to consist of the prefix \code{i}, the separator \code{.}\ (dot) and the number given by the character code of A. -The second location is considered to consist of the prefix +The second \gls{location} is considered to consist of the prefix \code{ii}, the separator \code{.}\ (dot) and the number given by the character code of A. @@ -11985,8 +12401,8 @@ different. These records are consecutive. They match the \hyperref[itm:decmatch]{decimal pattern}, and then step~\ref{itm:decgrp3eq} followed by step~\ref{itm:decgrp3eqsepeq}. The \code{.0} part is discarded and -the test is retried with the first location set to 1 and the second -location set to 2. +the test is retried with the first \gls{location} set to 1 and the second +\gls{location} set to 2. \item \begin{codeenv} @@ -12001,26 +12417,26 @@ step~\ref{itm:decgrp3nz}. \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{1}} \gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{2}} \end{codeenv} -These records are consecutive. The locations match the +These records are consecutive. The \glspl{location} match the \hyperref[itm.csmatch]{control sequence pattern}. The control sequences are the same, so the test is retried with the first -location set to 1 and the second location set to 2. +\gls{location} set to 1 and the second \gls{location} set to 2. -In this example, the location has been written to the file as +In this example, the \gls{location} has been written to the file as \code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that \gls!{glsxtrresourcefile} changes the category code of \code{@} to allow for -internal commands in locations.) This unusual case is for illustrative purposes. +internal commands in \glspl{location}.) This unusual case is for illustrative purposes. \end{enumerate} \optsection{max-loc-diff} -This setting is used to determine whether two locations are +This setting is used to determine whether two \glspl{location} are considered consecutive. The value must be an integer greater than or equal to 1. (The default is \optfmt{1}.) -For two locations, \meta{location-1} and \meta{location-2}, +For two \glspl{location}, \meta{location-1} and \meta{location-2}, that have numeric values $n_1$ and $n_2$ (and identical prefix, counter and format), then the sequence \meta{location-1}, \meta{location-2} is considered consecutive if @@ -12034,33 +12450,33 @@ For example, if \meta{location-1} is \qt{B} and \meta{location-2} is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1= n_1+1$ then \meta{location-2} immediately follows \meta{location-1}. -This is used in the range formations within the location lists (as described +This is used in the range formations within the \glspl{locationlist} (as described in the above section). So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59, 61} becomes \qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}. The automatically indexing of commands like \ics{gls} means that -the location lists can become long and ragged. You could +the \glspl{locationlist} can become long and ragged. You could deal with this by switching off the automatic indexing and only explicitly index pertinent use or you can adjust the value of \optfmt{max-loc-diff} so that a range can be formed even if there are one or two gaps in it. -By default, any location ranges that have skipped gaps in this +By default, any \gls{location} ranges that have skipped gaps in this manner will be followed by \gls!{bibglspassim}. The default definition of this command is obtained from the resource file. For English, this is \verb*| passim| (space followed by \qt{passim}). -So with the above set of locations, if \csopt[2]{max-loc-diff} then +So with the above set of \glspl{location}, if \csopt[2]{max-loc-diff} then the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that there are two blocks within the document related to that term. \optsection{suffixF} -If set, a range consisting of two consecutive locations +If set, a range consisting of two consecutive \glspl{location} \meta{loc-1} and \meta{loc-2} will be -displayed in the location list as \meta{loc-1}\meta{value}. +displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}. Note that \csopt[\empty]{suffixF} sets the suffix to the empty string. To remove the suffix formation use @@ -12070,9 +12486,9 @@ The default is \csopt[none]{suffixF}. \optsection{suffixFF} -If set, a range consisting of three or more consecutive locations +If set, a range consisting of three or more consecutive \glspl{location} \meta{loc-1} and \meta{loc-2} will be -displayed in the location list as \meta{loc-1}\meta{value}. +displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}. Note that \csopt[\empty]{suffixFF} sets the suffix to the empty string. To remove the suffix formation use @@ -12087,14 +12503,14 @@ The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to \csopt[3]{compact-ranges}). If no \meta{value} is specified, \optfmt{true} is assumed. -This setting allows location ranges such as 184--189 to appear -more compactly as 184--9. The end location is encapsulated +This setting allows \gls{location} ranges such as 184--189 to appear +more compactly as 184--9. The end \gls{location} is encapsulated in the command \gls{bibglscompact}, so the range would actually become: \begin{codeenv} 184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9} \end{codeenv} -If the location is in the form \code{\meta{cs}\margm{loc}} +If the \gls{location} is in the form \code{\meta{cs}\margm{loc}} (where \meta{cs} is a command) then \gls{bibglscompact} will be inside the argument. For example, if the range would normally be: @@ -12106,7 +12522,7 @@ then it would become: \cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}} \end{codeenv} The numerical value given in \csopt[\meta{n}]{compact-ranges} -indicates that compaction should only occur if the actual location +indicates that compaction should only occur if the actual \gls{location} consists of at least \meta{n} characters, for $\meta{n} \geq 2$. Any value of \meta{n} less than 2 will switch off compaction. @@ -12117,7 +12533,7 @@ would only be compacted with \csopt[2]{compact-ranges} because \code{89} only consists of 2 characters. The compaction isn't limited to decimal digits but it will only -occur if both the start and end location have the same number of +occur if both the start and end \gls{location} have the same number of characters. For example, xvi--xviii can't be compacted because the start consists of three characters and the end consists of five characters, whereas xxv--xxx can be compacted to xxv--x, @@ -12128,21 +12544,23 @@ it only performs the compaction for digits. \optsection{see} If an entry has a \field{see} field, this can be placed before or -after the location list, or completely omitted (but the value will +after the \gls{locationlist}, or completely omitted (but the value will still be available in the \field{see} field for use with \ics{glsxtrusesee}). The required \meta{value} must be one of: \begin{itemize} -\item \optfmt{omit}: omit the see reference from the location -list. -\item \optfmt{before}: place the see reference before the location -list. -\item \optfmt{after}: place the see reference after the location -list (default). +\item \optfmt{omit}: omit the see reference from the +\gls{locationlist}. + +\item \optfmt{before}: place the see reference before the +\gls{locationlist}. + +\item \optfmt{after}: place the see reference after the +\gls{locationlist} (default). \end{itemize} -The separator between the location list and the cross-reference is +The separator between the \gls{locationlist} and the cross-reference is provided by \gls!{bibglsseesep}. This separator is omitted if the -location list is empty. The cross-reference is written to the +\gls{locationlist} is empty. The cross-reference is written to the \field{location} field using \code{\gls{bibglsusesee}\margm{label}}. \optsection{seealso} @@ -12156,20 +12574,20 @@ same as for \csopt{see} but the separator is given by \optsection{alias} -This is like \csopt{alias} but governs the location of the cross-references +This is like \csopt{see} but governs the location of the cross-references provided by the \field{alias} field. The separator is given by \gls!{bibglsaliassep}. The cross-reference is written to the \field{location} field using \code{\gls{bibglsusealias}\margm{label}}. \optsection{alias-loc} -If an entry has an \field{alias} field, the location list +If an entry has an \field{alias} field, the \gls{locationlist} may be retained or omitted or transferred to the target entry. The required \meta{value} must be one of: \begin{itemize} -\item\optfmt{keep}: keep the location list; -\item\optfmt{transfer}: transfer the location list; -\item\optfmt{omit}: omit the location list. +\item\optfmt{keep}: keep the \gls{locationlist}; +\item\optfmt{transfer}: transfer the \gls{locationlist}; +\item\optfmt{omit}: omit the \gls{locationlist}. \end{itemize} The default setting is \csopt[transfer]{alias-loc}. In all cases, the target entry will be added to the \field{see} @@ -12182,21 +12600,21 @@ entry and the target entry must be in the same resource set. (That is, both entries have been selected by the same instance of \gls!{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version~1.12, you may need to redefine \ics{glsxtrsetaliasnoindex} to do -nothing if the location lists aren't showing correctly +nothing if the \glspl{locationlist} aren't showing correctly with aliased entries. (This was corrected in version~1.13.) \optsection{loc-prefix} -The \csopt{loc-prefix} setting indicates that the location lists +The \csopt{loc-prefix} setting indicates that the \glspl{locationlist} should begin with \code{\gls!{bibglslocprefix}\margm{n}}. The \meta{value} may be one of the following: \begin{itemize} \item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the -start of the location lists (default). +start of the \glspl{locationlist} (default). \item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}: insert \code{\gls{bibglslocprefix}\margm{n}} (where \meta{n} is the number of -locations in the list) at the start of each location list and the +\glspl{location} in the list) at the start of each \gls{locationlist} and the definition of \gls{bibglslocprefix} will be appended to the glossary preamble providing an \ics{ifcase} condition: \begin{codeenv} @@ -12212,7 +12630,7 @@ preamble providing an \ics{ifcase} condition: \item \optfmt{comma}: equivalent to \csopt[\marg{,~}]{loc-prefix} but avoids confusion with the list syntax. That is, the prefix is a comma -followed by a space for non-empty locations. +followed by a space for non-empty \glspl{locationlist}. \item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}. @@ -12266,23 +12684,24 @@ have the location prefixes obtained from the language resource file. \optsection{loc-suffix} This is similar to \csopt{loc-prefix} but there are some subtle -differences. In this case \meta{value} may either be the keyword -\optfmt{false} (in which case the location suffix is omitted) -or a comma-separated list +differences. In this case \meta{value} may either be the keyword +\optfmt{false} (in which case the location suffix is omitted) or a +comma-separated list \optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}} -where \meta{suffix-0} is the suffix to use when the location list -only has a cross-reference with no locations, \meta{suffix-1} is the suffix to use -when the location list has one location (optionally with a +where \meta{suffix-0} is the suffix to use when the +\gls{locationlist} only has a cross-reference with no +\glspl{location}, \meta{suffix-1} is the suffix to use when the +\gls{locationlist} has one \gls{location} (optionally with a cross-reference), and so on. The final \meta{suffix-n} in the list -is the suffix when the location list has \meta{n} or more locations -(optionally with a cross-reference). +is the suffix when the \gls{locationlist} has \meta{n} or more +\glspl{location} (optionally with a cross-reference). -This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to location -lists that either have a cross-reference or have at least one location. -Unlike \gls{bibglslocprefix}, this command isn't used when the -location list is completely empty. Also, unlike -\gls{bibglslocprefix}, this suffix command doesn't have an equivalent -to \gls{bibglspostlocprefix}. +This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to +\glspl{locationlist} that either have a cross-reference or have at +least one \gls{location}. Unlike \gls{bibglslocprefix}, this +command isn't used when the \gls{locationlist} is completely empty. +Also, unlike \gls{bibglslocprefix}, this suffix command doesn't have +an equivalent to \gls{bibglspostlocprefix}. If \meta{value} omitted, \csopt[\ics{at}\idx{periodchar}]{loc-suffix} is assumed. The default is \csopt[false]{loc-suffix}. @@ -12293,7 +12712,7 @@ of \csopt{loc-suffix} for entries in the same glossary type. \optsection{loc-counters} Commands like \ics{gls} allow you to select a different -counter to use for the location for that specific instance +counter to use for the \gls{location} for that specific instance (overriding the default counter for the entry's glossary type). This is done with the \glsopt{counter} option. For example, consider the following document: @@ -12335,16 +12754,16 @@ consider the following document: \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -This results in the location list \qt{1, 1--3, 3--5}. This +This results in the \gls{locationlist} \qt{1, 1--3, 3--5}. This looks a little odd and it may seem as though the range formation -hasn't worked, but the locations are actually: page~1, equation~1, +hasn't worked, but the \glspl{location} are actually: page~1, equation~1, equation~2, equation~3, page~3, page~4 and page~5. Ranges can't be formed across different counters. The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\ -to group the locations according to the counters given in -the comma-separated \meta{list}. If a location has a counter -that's not listed in \meta{list}, then the location is discarded. +to group the \glspl{location} according to the counters given in +the comma-separated \meta{list}. If a \gls{location} has a counter +that's not listed in \meta{list}, then the \gls{location} is discarded. For example: \begin{codeenv} @@ -12353,16 +12772,16 @@ For example: \csopt[entries]{src}\comment{data in entries.bib} } \end{codeenv} -This will first list the locations for the \counter{equation} -counter and then the locations for the \counter{page} counter. -Each group of locations is encapsulated within the command +This will first list the \glspl{location} for the \counter{equation} +counter and then the \glspl{location} for the \counter{page} counter. +Each group of \glspl{location} is encapsulated within the command \gls!{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}. The groups are separated by \gls!{bibglslocationgroupsep}. The \meta{list} value must be non-empty. Use \csopt[as-use]{loc-counters} to restore the default behaviour, where -the locations are listed in the document order of use, or -\csopt[false]{save-locations} to omit the location lists. Note that +the \glspl{location} are listed in the document order of use, or +\csopt[false]{save-locations} to omit the \glspl{locationlist}. Note that you can't form counter groups from \hyperref[sec:supplementalopts]{supplemental location lists}. @@ -12374,17 +12793,17 @@ you can't form counter groups from \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; +value set to the first \counter{wrglossary} \gls{location}; \item \meta{encap}: create the \field{indexcounter} field with the -value set to the first \counter{wrglossary} location +value set to the first \counter{wrglossary} \gls{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. +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 +\gls{location} precedence rules (\longarg{map-format}). If the +\gls{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 @@ -12394,7 +12813,7 @@ 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 +allow \glspl{location} 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 @@ -12408,12 +12827,12 @@ information to the \iext{aux} file: \begin{codeenv} \gls{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{\encap{glsnumberformat}}\margm{n} \end{codeenv} -The location here is actually the value of the \counter{wrglossary} +The \gls{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: +replaces the \gls{record}['s] location \meta{n} with: \nosecdef{glsxtr@wrglossarylocation} -(but it only does this for records that have the \counter{wrglossary} +(but it only does this for \glspl{record} that have the \counter{wrglossary} counter). The \sty{glossaries-extra} package (v1.29+) adjusts the definition @@ -12421,16 +12840,16 @@ 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 +page number is displayed in the \gls{locationlist} but it links back to the place where the corresponding \cs{label} occurred. This method works partially with \idx!{makeindex} and \idx!{xindy} -but from their point of view the location is the value of the +but from their point of view the \gls{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. +\glspl{location} 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 @@ -12438,9 +12857,9 @@ 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 +of the \counter{wrglossary} \glspl{location} for a given entry or the first +instance of a specific format of the \counter{wrglossary} \glspl{location} +for a given entry. This \gls{location} is stored in the \field{indexcounter} internal field using: \begin{codeenv} \ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} @@ -12513,13 +12932,14 @@ A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and \cmd{end}\marg{document} \end{codeenv} Note that the \glsopt[\counter{equation}]{counter} entry will have its own -independent location. In this example, it's difficult to tell the +independent \gls{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. +reference) in the \gls{locationlist} for the \code{pi} entry. -The \glsopt[primary]{format} instances indicate primary references. +The \glsopt[primary]{format} instances indicate +\glsdisp{principallocation}{principal} references. They're displayed in bold (since \csfmt{primary} is defined to use -\csfmt{hyperbf}) and these are the locations saved in the +\csfmt{hyperbf}) and these are the \glspl{location} saved in the \field{indexcounter} field because that's the \meta{encap} identified by the \csopt[primary]{save-index-counter} setting. @@ -12527,21 +12947,21 @@ identified by the \csopt[primary]{save-index-counter} setting. \label{sec:supplementalopts} \emph{These options require at least version 1.14 of -\isty{glossaries-extra}.} If you require locations from multiple +\isty{glossaries-extra}.} If you require \glspl{location} from multiple external sources, then you need at least version 1.36 of \isty{glossaries-extra} (or, more specifically, \isty{glossaries-extra-bib2gls}, which is automatically loaded by the \styopt[only]{record} package option). The \sty{glossaries-extra} package (from v1.14) provides a way of -manually adding locations in supplemental documents through the use +manually adding \glspl{location} in \glspl{supplementaldocument} through the use of the \glsaddopt{thevalue} option in the optional argument of \ics{glsadd}. Setting values manually is inconvenient and can result in errors, so \bibgls\ provides a way of doing this automatically. -Both the main document and the supplementary document need to use +Both the \gls{maindocument} and the \supplementarydocument\ need to use the \styopt{record} option. The entries provided in the \csopt{src} -set must have the same labels as those used in the supplementary -document. (The simplest way to achieve this is to ensure that both +set must have the same labels as those used in the +\supplementarydocument. (The simplest way to achieve this is to ensure that both documents use the same \ext{bib} files and the same prefixes.) For example, suppose the file \filefmt{entries.bib} contains: @@ -12589,12 +13009,12 @@ Now suppose the supplementary document is contained in the file \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -This uses the \counter{section} counter for the locations and has a +This uses the \counter{section} counter for the \glspl{location} and has a prefix (\code{\csfmt{thepart}.})\ for the section hyperlinks. Now let's suppose I have another document called \filefmt{main.tex} that uses the \code{sample} entry, but also needs to include the -location (S1) from the supplementary document. The manual approached +\gls{location} (S1) from the \supplementarydocument. The manual approached offered by \styfmt{glossaries-extra} is quite cumbersome and requires setting the \catattr{externallocation} attribute and using \ics{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue} @@ -12604,17 +13024,17 @@ This can be simplified with \bibgls\ by using the \optfmt{supplemental-locations} option, described below. Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some -special location formatting commands that don't use the +special \gls{location} formatting commands that don't use the \catattr{externallocation} attribute, but instead have an extra argument that indicates the external reference. The additional argument means that it can't be used by the \glsaddopt{format} key, but with \bibgls\ you don't use \cs{glsadd} to record -the external locations. Instead it obtains the records from -the corresponding supplementary \ext{aux} file, and adjusts the -location encapsulator as appropriate. +the external \glspl{location}. Instead it obtains the \glspl{record} from +the corresponding \supplementary\ \ext{aux} file, and adjusts the +\gls{location} encapsulator as appropriate. If \bibgls\ detects an older version of \sty{glossaries-extra}, -it will only allow one external supplemental source, and +it will only allow one external \supplemental\ source, and will set the \catattr{externallocation} attribute and use the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\ will allow multiple sources and use the newer method. @@ -12622,10 +13042,10 @@ will allow multiple sources and use the newer method. \optsection{supplemental-locations} The value should be the base name (without the extension) of the -supplementary document (\optfmt{suppl} in the above example). +\supplementarydocument\ (\optfmt{suppl} in the above example). If you have at least version 1.36 of \sty{glossaries-extra}, the value may be a comma-separated list of base names (without the -extensions) of the supplementary documents. If an older version is +extensions) of the \supplementarydocuments. If an older version is detected, \bibgls\ will issue a warning and only accept the first element of the list. @@ -12646,17 +13066,17 @@ For example: \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -The location list for \code{sample} will now be \qt{1, S1} (page~1 -from the main document and S1 from the supplementary document). +The \gls{locationlist} for \code{sample} will now be \qt{1, S1} (page~1 +from the \gls{maindocument} and S1 from the \supplementarydocument). -With \sty{glossaries-extra} v1.36+, a regular location from the -supplementary document will be encapsulated with: +With \sty{glossaries-extra} v1.36+, a regular \gls{location} from the +\supplementarydocument\ will be encapsulated with: \nosecdef{glsxtrdisplaysupploc} By default, this simply creates an external hyperlink to the -supplementary document with the location as the hyperlink text. +\supplementarydocument\ with the \gls{location} as the hyperlink text. The hyperlink is created using \meta{src} as the target path with the fragment part (anchor) formed from the prefix and -location. The \catattr{externallocation} attribute is not set in +\gls{location}. The \catattr{externallocation} attribute is not set in this case. The actual formatting is done via: \nosecdef{glsxtrmultisupplocation} which ignores the \meta{format} argument by default. Its @@ -12671,7 +13091,7 @@ definition is simply: \end{codeenv} This locally sets the command \ics{glsxtrsupplocationurl}, which is checked by \ics{glshypernumber} to establish an external rather than internal link. -You can redefine the supplemental location command to retain the original +You can redefine the \supplementallocation\ command to retain the original \idx{encap} used in the target document: \begin{codeenv} \cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} @@ -12687,7 +13107,7 @@ uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you will lose the hyperlink. With older versions of \sty{glossaries-extra}, -the original location format from the supplementary document +the original \gls{location} format from the \supplementarydocument\ will be replaced by \encap{glsxtrsupphypernumber}, which again produces an external hyperlink. The \catattr{externallocation} attribute also needs to be set (this can be done automatically with @@ -12695,12 +13115,12 @@ attribute also needs to be set (this can be done automatically with The original format can't be accessed. In both cases, if the document hasn't loaded the \isty{hyperref} package, the -location will simply be displayed without a hyperlink. Even if both the main -and the supplementary documents have loaded \sty{hyperref}, note that not all +\gls{location} will simply be displayed without a hyperlink. Even if both the main +and the \supplementarydocuments\ have loaded \sty{hyperref}, note that not all PDF viewers can handle external hyperlinks, and some that can open the external PDF file may not recognise the destination within that file. -The special \code{nameref} locations (see +The special \code{nameref} \glspl{location} (see \longarg{merge-nameref-on}) are still identified with \gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now be set. @@ -12724,14 +13144,14 @@ skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf which will expand to \code{skr\'aarnafn.pdf}. -The supplementary locations lists are encapsulated within +The \supplementarylocation\ lists are encapsulated within \gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+, this command will encapsulate the sub-lists with \gls{bibglssupplementalsublist}. So the above example with an old version of \sty{glossaries-extra} -(pre 1.36) will set the supplemental location list (which only consists -of one location) to: +(pre 1.36) will set the \supplementallocation\ list (which only consists +of one \gls{location}) to: \begin{codeenv} \gls{bibglssupplemental} \marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}} @@ -12746,39 +13166,40 @@ Whereas with at least version 1.36, the list will be: \marg{\gls{glsxtrdisplaysupploc}\marg{I}\marg{\counter{section}}\marg{\encap{glsnumberformat}}\marg{suppl.pdf}\marg{S1}}} \end{codeenv} -If an entry has both a main location list and a supplementary -location list (such as the \code{sample} entry above), the lists +If an entry has both a main \gls{locationlist} and a +\supplementarylocation\ list (such as the \code{sample} entry above), the lists will be separated by \gls!{bibglssupplementalsep}. The sub-lists (when supported) are separated by \gls{bibglssupplementalsubsep}. \optsection{supplemental-selection} -In the above example, only the \code{sample} entry is listed in -the main document, even though the supplementary document also -references the \code{goose}, \code{html} and \code{ssi} -entries. By default, only those entries that are referenced in the -main document will have supplementary locations added (if found in -the supplementary document's \iext{aux} file). You can additionally -include other entries that are referenced in the supplementary -document but not in the main document using -\optfmt{supplemental-selection}. The \meta{value} may be one of the -following: +In the above example, only the \code{sample} entry is listed in the +\gls{maindocument}, even though the \supplementarydocument\ also +references the \code{goose}, \code{html} and \code{ssi} entries. By +default, only those entries that are referenced in the \gls{maindocument} +will have \supplementarylocations\ added (if found in the +\glsdisp{supplementaldocument}{supplementary document's} \iext{aux} +file). You can additionally include other entries that are +referenced in the \supplementarydocument\ but not in the main +document using \optfmt{supplemental-selection}. The \meta{value} may +be one of the following: \begin{itemize} -\item \optfmt{all}: add all the entries in the supplementary -document that have been defined in the \ext{bib} files listed in -\csopt{src} for this resource set in the main document. -\item \optfmt{selected}: only add supplemental locations for entries -that have already been selected by this resource set. +\item \optfmt{all}: add all the entries in the +\supplementarydocument\ that have been defined in the \ext{bib} files listed in +\csopt{src} for this resource set in the \gls{maindocument}. +\item \optfmt{selected}: only add \supplementallocations\ for entries +that have already been selected by this \gls{resourceset}. \item \meta{label-1},\ldots,\meta{label-2}: in addition to all those entries that have already been selected by this resource set, also add the entries identified in the comma-separated list. If a label -in this list doesn't have a record in the supplementary document's +in this list doesn't have a record in the +\glsdisp{supplementaldocument}{supplementary document's} \ext{aux} file, it will be ignored. \end{itemize} -Any records in the supplementary \ext{aux} file that aren't defined +Any records in the \supplementary\ \ext{aux} file that aren't defined by the current resource set (through the \ext{bib} files listed in \csopt{src}) will be ignored. Entry aliases aren't taken into -account when including supplementary locations. +account when including \supplementarylocations. For example: \begin{codeenv} @@ -12800,12 +13221,12 @@ For example: \end{codeenv} This will additionally add the \code{html} and \code{ssi} entries even though they haven't been used in this document. The -\code{goose} entry used in the supplementary document won't be +\code{goose} entry used in the \supplementarydocument\ won't be included. \optsection{supplemental-category} -The \field{category} field for entries containing supplemental location +The \field{category} field for entries containing \supplementallocation\ lists may be set using this option. If unset, \meta{value} defaults to the same as that given by the \csopt{category} option. The \meta{value} may either be a known @@ -12842,11 +13263,11 @@ contain the proof or solution. Therefore, somewhat unusually for an indexing application, \bibgls\ also provides the option to shuffle the entries instead of sorting them. -This section covers the resource options for sorting primary -entries. See \sectionref{sec:dualoptssort} for sorting dual entries -and also \csopt{sort-label-list} for sorting field values that -contain a comma-separated list of entry labels (such as the -\field{see} or \field{seealso} fields). +This section covers the resource options for sorting +\glspl{primaryentry}. See \sectionref{sec:dualoptssort} for sorting +\glspl{dualentry} and also \csopt{sort-label-list} for sorting field +values that contain a comma-separated list of entry labels (such as +the \field{see} or \field{seealso} fields). The sort methods that use a comparison function (that is, all the sort methods except those listed in \tableref{tab:sortoptionsnosort}) @@ -12943,7 +13364,7 @@ the redefinition occurring in the document with \csopt[false]{write-preamble}.) Alternatively both of these \ext{bib} files can be loaded in one -\idx{resourceset}: +\igls{resourceset}: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}} \end{codeenv} @@ -12954,7 +13375,7 @@ command definitions for the \bibgls\ interpreter and load it with \optsection{sort} -The \csopt{sort} key indicates how primary entries should be sorted. +The \csopt{sort} key indicates how \glspl{primaryentry} should be sorted. If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the \csopt{sort} option isn't used then \csopt[doc]{sort} is assumed if the document has a language that's been detected by \sty{tracklang}, @@ -12964,7 +13385,7 @@ The \optfmt{\meta{method}\dhyphen reverse} options reverse the result returned by the corresponding \meta{method} comparator. However \optfmt{\meta{method}\dhyphen reverse} may not produce a list that's the exact reverse of the underlying non-reversed -\meta{method} as the hierarchical structure or associated settings +\meta{method} as the \hierarchical\ structure or associated settings can affect the order. \begin{table}[p] @@ -13099,8 +13520,8 @@ sort\tabularnewline Most of the sort methods listed in \tableref{tab:sortoptionsnosort} don't actually perform any sorting. This may cause a problem for -hierarchical entries. In some cases this can lead to detached child -entries or an attempt to define a child entry before its parent. +\hierarchical\ entries. In some cases this can lead to detached +\glspl{childentry} or an attempt to define a \gls{childentry} before its \parent. The methods listed in this section all ignore the \csopt{sort-field} setting and all the various sort fallback settings, except where noted below. @@ -13110,43 +13531,57 @@ noted below. (The entries will be in the order they were processed when parsing the data.) +If you need to order by definition but also maintain \hierarchy\ then use: +\begin{codeenv} +\csopt{save-definition-index}, +\csopt[\field{definitionindex}]{sort-field}, +\csopt[integer]{sort} +\end{codeenv} + \item \optfmt{random}: shuffles rather than sorts the entries. -This won't work if there are hierarchical entries, so it's best +This won't work if there are \hierarchical\ entries, so it's best to use this option with \csopt{flatten}. The seed for the random generator can be set using \csopt{shuffle} (which also automatically sets \csopt[random]{sort} and \csopt{flatten}). \item \optfmt{use}: order of use. This order is determined -by the records written to the \iext{aux} file by the \styopt{record} +by the \glspl{record} written to the \iext{aux} file by the \styopt{record} package option. Dependencies and cross-references (including those -identified with \ics{glssee}) come after entries with records. +identified with \ics{glssee}) come after entries with \glspl{record}. Note that this is different from using the analogous option with \idx{makeindex} or \idx{xindy}, which does actually sort numerically, where each entry has an associated number set on the first use of that term that's used as the sort value. +If you need to order by use but also maintain \hierarchy\ then use: +\begin{codeenv} +\csopt{save-use-index}, +\csopt[\field{useindex}]{sort-field}, +\csopt[integer]{sort} +\end{codeenv} + \item \optfmt{use-reverse}: reverses the order that would be -obtained with \csopt[use]{sort} without reference to hierarchy. +obtained with \csopt[use]{sort} without reference to \hierarchy. -\item \optfmt{recordcount}: order of record count (starting from 0). This order is +\item \optfmt{recordcount}: order of \gls{recordcount} (starting from 0). This order is determined by the total number of records written to the \iext{aux} -file for each entry. Unlike the above methods, this performs a hierarchical sort. +file for each entry. Unlike the above methods, this performs a \hierarchical\ sort. If letter groups are enabled with \longarg{group}, this method will assign the entries to the \idx{numbergroup}. This option requires the \longarg{record-count} switch. Although -that switch makes \bibgls\ write the total record count to the +that switch makes \bibgls\ write the total \gls{recordcount} to the \ext{glstex} file in the \field{recordcount} internal field (so that it can be accessed in the document), \bibgls\ doesn't actually have a field itself that contains the information. So although this option behaves much like \csopt[integer]{sort} it's not possible to select a field containing the required value. In the event of two or more -entries having the same record count, the +entries having the same \gls{recordcount}, the \csopt{identical-sort-action} option is used to determine the relative ordering between them. -\item \optfmt{recordcount-reverse}: reverse order of record count +\item \optfmt{recordcount-reverse}: reverse order of \gls{recordcount} (ending with 0). All the above notes applying to \optfmt{recordcount} also apply here. @@ -13197,7 +13632,7 @@ Consider the following: This has a summary at the start of the document that only contains entries that have at least 10 records and is ordered according to the total number of records (starting with the most frequently used -entry). The main glossary at the end of the document is ordered +entry). The \gls{mainglossary} at the end of the document is ordered according to use and contains all selected entries. Compare this with the following: @@ -13221,10 +13656,10 @@ This again has a summary at the start of the document that only contains entries that have at least 10 records but is now ordered according to use. -Both examples assume there are no child entries as the filtering can -cause parent entries to be omitted. Both examples require +Both examples assume there are no \glspl{childentry} as the filtering can +cause \glspl{parententry} to be omitted. Both examples require \longarg{record-count} but only the first example sorts according to -the record count. +the \gls{recordcount}. \subsubsection{Alphabet} @@ -13811,7 +14246,7 @@ decimal sort values. \end{itemize} -In general, it doesn't make much sense to have hierarchical entries +In general, it doesn't make much sense to have \hierarchical\ entries that need to be sorted by a number, but it is possible as long as each level uses the same type of numbering. @@ -13876,7 +14311,7 @@ reversed). This has the by-product of providing a field that you can access within the document that can be more easily parsed by \LaTeX. -In general, it doesn't make much sense to have hierarchical entries +In general, it doesn't make much sense to have \hierarchical\ entries that need to be sorted by date, but it is possible as long as each level uses the same date format. @@ -14000,8 +14435,8 @@ given by \csopt{abbreviation-sort-fallback}. \item 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 +\field{name} field. Note that this only applies to the \gls{mainentry}. +The \glsdisp{spawnedentry}{spawned} \atentry{contributor} entries behave like \atentry{index}. \end{itemize} @@ -14164,14 +14599,14 @@ defined with \atentry{acronym} (\qt{laser}) will use the setting given by \csopt{abbreviation-sort-fallback} since \atentry{acronym} hasn't been identified in \csopt{custom-sort-fallbacks}. -This option also covers dual entries. For example: +This option also covers \glspl{dualentry}. For example: \begin{codeenv} \csopt[ \entryref{dualindexnumber}=\field{description}, \entryfmt{dualindexnumbersecondary}=\field{user1} ]{custom-sort-fallbacks} \end{codeenv} -Note that the entry type for the dual is in the form +Note that the entry type for the \dual\ is in the form \code{\meta{primary entry type}secondary}. \begin{important} @@ -14205,7 +14640,7 @@ where the separator is given by \csopt{field-concat-sep}. This setting doesn't affect the index type of entries, such as \atentry{index} or \atentry{indexplural}. This is useful if your -glossary contains homographs (terms with the same spelling) which +glossary contains \iglspl{homograph} (terms with the same spelling) which can't be distinguished by the sort comparators. For example, suppose my file \filefmt{entries.bib} contains: \begin{codeenv} @@ -14245,8 +14680,8 @@ The default behaviour for \atentry{entry} if the \field{sort} field is missing is to fallback on the \field{name} field. If the \field{name} field is missing (as with \code{glossarylist} and \code{glosscol}), then the value is obtained from the -\field{name} field from the parent entry. The parent entry for these -homographs is the \code{glossary} entry, which was defined with +\field{name} field from the \gls{parententry}. The \gls{parententry} for these +\glspl{homograph} is the \code{glossary} entry, which was defined with \atentry{index} and doesn't have the \field{name} field. For the \atentry{index} entries, if \field{name} is missing the value is obtained from the label. @@ -14352,7 +14787,7 @@ for sorting (\csopt{sort-field}). \optsection{bibtexentry-sort-fallback} -The main \atentry{bibtexentry} entry types will, by default, +The \glsdisp{mainentry}{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 @@ -14372,7 +14807,7 @@ Note that \csopt{missing-sort-fallback} and \begin{important} The \csopt{bibtexentry-sort-fallback} setting is only used when -\bibgls\ tries to access the \field{sort} field for a main entry +\bibgls\ tries to access the \field{sort} field for a \gls{mainentry} defined with \atentry{bibtexentry} and finds that the field hasn't been set. This means that this setting has no effect if you explicitly set the \field{sort} field or if you change the field used for @@ -14752,7 +15187,7 @@ This option automatically implements the dual and secondary settings \csopt[\meta{value}]{secondary-identical-sort-action}. This option determines what the comparator should do if -two entries at the same hierarchical level are considered +two entries at the same \hierarchicallevel\ are considered equal. The \meta{value} may be one of: \begin{itemize} \item\optfmt{none}: don't take any further action if sort values are @@ -14775,8 +15210,8 @@ and you also want a locale-sensitive sort used on the fallback, then you need to use \csopt{sort-suffix} instead. \bibgls\ allows duplicate sort values, but this can cause a problem -for hierarchical entries where parent entries with duplicate sort -fields are clumped together and their children follow. To prevent +for \hierarchical\ entries where \glspl{parententry} with duplicate sort +fields are clumped together and their \children\ follow. To prevent this from happening, the \csopt[id]{identical-sort-action} setting will fallback on comparing the labels. Since all labels must be unique, this means comparisons between two different entries @@ -14814,9 +15249,10 @@ types of sort methods (not including the no-sort options listed in \csopt{identical-sort-action} to prevent problems occurring with duplicate sort values. -In the case of \csopt[non-unique]{sort-suffix}, this will only append a -suffix to the duplicate sort values (within the same hierarchical -level). The first sort value to be encountered isn't given a suffix. +In the case of \csopt[non-unique]{sort-suffix}, this will only +append a suffix to the duplicate sort values (within the same +\hierarchicallevel). The first sort value to be encountered isn't +given a suffix. The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix if that field is set, but (if set) it will apply the suffix to all @@ -14827,14 +15263,14 @@ in the transcript when it appends a suffix to the sort value. The message: \begin{alltt} Sort value '\meta{sort}' (entry '\meta{id}') not unique for the entry's -hierarchical level. +\hierarchicallevel. \end{alltt} indicates that an entry with the given \meta{sort} value has already -been found within the same hierarchical level as the currently +been found within the same \hierarchicallevel\ as the currently processed entry (whose label is given by \meta{id}). The same -hierarchical level in this context means that either both entries -don't have a parent or both entries have the same parent. (That is, -the entries are considered siblings.) +\hierarchicallevel\ in this context means that either both entries +don't have a \parent\ or both entries have the same \parent. (That is, +the entries are considered \glspl{sibling}.) This message will then be followed by: \begin{alltt} @@ -15070,8 +15506,8 @@ different to using: \begin{codeenv} \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} -which creates an \idx{ignoredrecord}. Even though the record is ignored -(and so won't show in the location list) the record still influences +which creates an \igls{ignoredrecord}. Even though the record is ignored +(and so won't show in the \gls{locationlist}) the record still influences the selection order and the record count. \optsection{sort-suffix-marker} @@ -15092,16 +15528,28 @@ use the above hexadecimal markup. If you use \ics{cs.hash} it will be treated as a literal string containing a backslash followed by a hash character. +\optsection{encapsulate-sort} + +This option will encapsulate the sort value (after modifications such +as \csopt{sort-suffix} and \csopt{sort-number-pad}) with +\csfmt{\meta{csname}}\marg{value}\marg{entry-id} where \meta{value} +is the sort value that would otherwise have been used and +\meta{entry-id} is the entry's label. It will then be interpreted +(if enabled). Note that \meta{value} may already have been +interpreted in a previous step. + \optsection{strength} This option automatically implements \csopt[\meta{value}]{dual-strength} and \csopt[\meta{value}]{secondary-strength}. -The collation strength used by the alphabet sort methods -(\tableref{tab:sortoptionsrule}) can be set -to the following values: \optfmt{primary} (default), -\optfmt{secondary}, \optfmt{tertiary} or \optfmt{identical}. These +The collation strength used by the alphabet sort methods +(\tableref{tab:sortoptionsrule}) can be set to the following values: +\glsdisp{primarycollatorstrength}{\optfmt{primary}} (default), +\glsdisp{secondarycollatorstrength}{\optfmt{secondary}}, +\glsdisp{tertiarycollatorstrength}{\optfmt{tertiary}} or +\glsdisp{identicalcollatorstrength}{\optfmt{identical}}. These indicate the difference between two characters, but the exact assignment is locale dependent. See the documentation for Java's \href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator} @@ -15518,7 +15966,7 @@ See also \sectionref{sec:logicaldivisions}. \section{Secondary Glossary} \label{sec:secondaryopts} -The secondary glossary may only be used with \csopt[define]{action} +The \gls{secondaryglossary} may only be used with \csopt[define]{action} (within the same resource set) since it's incompatible with the copy actions. You may use \csopt{secondary} in the first resource set and a copy action in a subsequent resource set. @@ -15546,16 +15994,18 @@ or \meta{sort}:\meta{type} \end{definition} If the \meta{field} is omitted, the value of \csopt{sort-field} is -used. Remember that when the primary entries are sorted, the +used. Remember that when the \glspl{primaryentry} are sorted, the \field{sort} field will be set, which means that the fallback field -(such as \field{name}) won't be used in the secondary sort. In +(such as \field{name}) won't be used in the +\glsdisp{secondaryglossary}{secondary} sort. In general it's best to supply the field unless one type is sorted and the -other isn't. (The actual sort value obtained by the secondary sort +other isn't. (The actual sort value obtained by the +\glsdisp{secondaryglossary}{secondary} sort will be saved in the \field{secondarysort} field in case you require it.) The value of \meta{sort} is as for \csopt{sort}, but note that in this case the sort value \optfmt{unsrt} or \optfmt{none} -means to use the same ordering as the primary entries. For +means to use the same ordering as the \glspl{primaryentry}. For example, with \csopt[de-CH-1996]{sort}, \csopt[none:copies]{secondary} the \code{copies} list will be ordered according to \code{de-CH-1996} and not according to the @@ -15566,21 +16016,21 @@ provided with \csopt{secondary-sort-rule}. This option will copy all the selected entries into the glossary labelled \meta{type} sorted according to \meta{sort} (using \meta{field} as the sort value). Note that this \emph{just copies the entry's label} -to the second glossary list rather than creating a duplicate entry, +to the \gls{secondaryglossary} list rather than creating a duplicate entry, which saves resources but it means that all the fields will be identical. If you want groups in your glossary, the group -information for the secondary glossary will be stored in the +information for the \glspl{secondaryglossary} will be stored in the internal \field{secondarygroup} field. The \field{group} field will -contain the group for the primary glossary. +contain the group for the \gls{primaryglossary}. In order to switch fields in \ics{printunsrtglossary}, you need at least v1.21 of \sty{glossaries-extra} which provides \ics{glsxtrgroupfield} to keep track of the appropriate field label. -If this command is defined, the preamble for the secondary glossary +If this command is defined, the preamble for the \gls{secondaryglossary} will be adjusted to locally change the field to \field{secondarygroup}. With older versions, the group information -in the secondary glossary will be the same as for the primary -glossary. +in the \gls{secondaryglossary} will be the same as for the +\gls{primaryglossary}. (If the glossary \meta{type} doesn't exist, it will be defined with \ics{provideignoredglossary*}\margm{type} @@ -15615,14 +16065,14 @@ and the document preamble contains: \csopt[en-GB:category:topic]{secondary} } \end{codeenv} -This sorts the primary entries according to the default +This sorts the \glspl{primaryentry} according to the default \csopt{sort-field} and then sorts the entries according to the \field{category} field and copies this list to the \code{topic} glossary (which will be provided if not defined.) -The secondary list can be displayed with the hypertargets switched -off to prevent duplicates. The cross-references will link to the -original glossary. +The \glsdisp{secondaryglossary}{secondary list} can be displayed +with the hypertargets switched off to prevent duplicates. The +cross-references will link to the \glsdisp{primaryglossary}{original glossary}. For example: \begin{codeenv*} @@ -15669,91 +16119,122 @@ For example, if the entries are stored in \filefmt{entries.bib}: } \end{codeenv} +\optsection{secondary-match} + +Similar to \csopt{match} but determines whether or not to include a +\gls{primaryentry} in the \glsdisp{secondaryglossary}{secondary +list}. The syntax is the same but this option is governed by +\csopt{secondary-match-op} and \csopt{secondary-match-action}. Note +that if an entry hasn't been selected for the +\glsdisp{primaryglossary}{primary list} then it won't be added to +the \glsdisp{secondaryglossary}{secondary list}, regardless of this +setting. + +\optsection{secondary-not-match} + +Similar to \csopt{not-match} but determines whether or not to +include a \gls{primaryentry} in the +\glsdisp{secondaryglossary}{secondary list}. The syntax is the same +but this option is governed by \csopt{secondary-match-op} and +\csopt{secondary-match-action}. Note that if an entry hasn't been +selected for the \glsdisp{primaryglossary}{primary list} then it +won't be added to the \glsdisp{secondaryglossary}{secondary list}, +regardless of this setting. + +\optsection{secondary-match-op} + +As \csopt{match-op} but for the \glsdisp{secondaryglossary}{secondary list} selection. + +\optsection{secondary-match-action} + +As \csopt{match-action} but for the \glsdisp{secondaryglossary}{secondary list} selection. + \optsection{secondary-missing-sort-fallback} -As \csopt{missing-sort-fallback} but for secondary sorting. +As \csopt{missing-sort-fallback} but for +\glsdisp{secondaryglossary}{secondary} sorting. \optsection{secondary-trim-sort} -As \csopt{trim-sort} but for secondary sorting. +As \csopt{trim-sort} but for \glsdisp{secondaryglossary}{secondary} sorting. \optsection{secondary-sort-replace} -As \csopt{sort-replace} but for secondary sorting. +As \csopt{sort-replace} but for \glsdisp{secondaryglossary}{secondary} sorting. \optsection{secondary-sort-rule} -As \csopt{sort-rule} but for secondary custom sorting. +As \csopt{sort-rule} but for \glsdisp{secondaryglossary}{secondary} custom sorting. \optsection{secondary-break-at} -As \csopt{break-at} but for secondary entries. +As \csopt{break-at} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-break-marker} -As \csopt{break-marker} but for secondary entries. +As \csopt{break-marker} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-sort-number-pad} -As \csopt{sort-number-pad} but for secondary entries. +As \csopt{sort-number-pad} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-sort-pad-plus} -As \csopt{sort-pad-plus} but for secondary entries. +As \csopt{sort-pad-plus} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-sort-pad-minus} -As \csopt{sort-pad-minus} but for secondary entries. +As \csopt{sort-pad-minus} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-identical-sort-action} -As \csopt{identical-sort-action} but for secondary entries. +As \csopt{identical-sort-action} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-sort-suffix} -As \csopt{sort-suffix} but for secondary entries. +As \csopt{sort-suffix} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-sort-suffix-marker} -As \csopt{sort-suffix-marker} but for secondary entries. +As \csopt{sort-suffix-marker} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-strength} -As \csopt{strength} but for secondary entries. +As \csopt{strength} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-decomposition} -As \csopt{decomposition} but for secondary entries. +As \csopt{decomposition} but for \glsdisp{secondaryglossary}{secondary} entries. \optsection{secondary-letter-number-rule} -As \csopt{letter-number-rule} but for secondary letter-number sorting. +As \csopt{letter-number-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting. \optsection{secondary-letter-number-punc-rule} -As \csopt{letter-number-punc-rule} but for secondary letter-number sorting. +As \csopt{letter-number-punc-rule} but for \glsdisp{secondaryglossary}{secondary} letter-number sorting. \optsection{secondary-numeric-sort-pattern} -As \csopt{numeric-sort-pattern} but for secondary +As \csopt{numeric-sort-pattern} but for \glsdisp{secondaryglossary}{secondary} locale-sensitive numeric sorting. \optsection{secondary-numeric-locale} -As \csopt{numeric-locale} but for secondary +As \csopt{numeric-locale} but for \glsdisp{secondaryglossary}{secondary} locale-sensitive numeric sorting. \optsection{secondary-date-sort-locale} -As \csopt{date-sort-locale} but for secondary date-time sorting. +As \csopt{date-sort-locale} but for \glsdisp{secondaryglossary}{secondary} date-time sorting. \optsection{secondary-date-sort-format} -As \csopt{date-sort-format} but for secondary date-time sorting. +As \csopt{date-sort-format} but for \glsdisp{secondaryglossary}{secondary} date-time sorting. \optsection{secondary-group-formation} -As \csopt{group-formation} but for secondary sorting. +As \csopt{group-formation} but for \glsdisp{secondaryglossary}{secondary} sorting. \section{Dual Entries} \label{sec:dualopts} @@ -15763,7 +16244,7 @@ As \csopt{group-formation} but for secondary sorting. \optsection[\subsubsection]{dual-prefix} -This option indicates the prefix to use for the dual entries. The +This option indicates the prefix to use for the \glspl{dualentry}. The default value is \idprefix{dual} (including the terminating period). Any references to dual entries within the \ext{bib} file should use the prefix \idprefix{dual} which will be replaced by \meta{value} @@ -15777,10 +16258,10 @@ in the \ext{glstex} file with: \optsection[\subsubsection]{primary-dual-dependency} -This is a boolean setting that determines whether or not primary and -dual entries should be considered mutual dependencies. The default value is -\csopt[true]{primary-dual-dependency}, which means that if a primary -has records then the dual is added as a dependency and vice versa. +This is a boolean setting that determines whether or not \primary\ and +\dual\ entries should be considered mutual dependencies. The default value is +\csopt[true]{primary-dual-dependency}, which means that if a +\primary\ has records then the \dual\ is added as a dependency and vice versa. The setting \csopt[false]{primary-dual-dependency} can't be used with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or @@ -15788,18 +16269,29 @@ used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or \optsection[\subsubsection]{combine-dual-locations} -This setting allows the location lists for each primary entry -to be merged with that of the corresponding dual entry. +This setting allows the \glspl{locationlist} for each \gls{primaryentry} +to be merged with that of the corresponding \gls{dualentry}. The \meta{value} may be one of: \begin{itemize} -\item\optfmt{false} This is the default setting. The location lists -aren't combined. -\item\optfmt{both} Both the primary and dual are given the combined -location list. -\item\optfmt{dual} Only the dual is given the combined location -list. The primary's location list is emptied. -\item\optfmt{primary} Only the primary is given the combined -location list. The dual's location list is emptied. +\item\optfmt{false} This is the default setting. The +\glspl{locationlist} aren't combined. + +\item\optfmt{both} Both the \primary\ and \dual\ are given the combined +\gls{locationlist}. + +\item\optfmt{dual} Only the \dual\ is given the combined +\gls{locationlist}. The \glsdisp{primaryentry}{primary's} location list is emptied. + +\item\optfmt{primary} Only the \primary\ is given the combined +\gls{locationlist}. The \glsdisp{dualentry}{dual's} +\gls{locationlist} is emptied. + +\item\optfmt{dual retain principal} Like \optfmt{dual} but any +\glspl{principallocation} for \glspl{primaryentry} will have a copy left in the +\gls{primaryentry}['s] \igls{locationlist}. +\item\optfmt{primary retain principal} Like \optfmt{primary} but any +\glspl{principallocation} for \glspl{dualentry} will have a copy left in the +\gls{dualentry}['s] \igls{locationlist}. \end{itemize} For example, suppose the file \filefmt{entries.bib} contains: @@ -15849,33 +16341,33 @@ and the document contains: \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -In this case, the primary entries are placed in the \code{index} +In this case, the \glspl{primaryentry} are placed in the \code{index} glossary type and are assigned the prefix \idprefixfmt{idx} but only -two of the primary entries have been used in the document (both on +two of the \glspl{primaryentry} have been used in the document (both on page~2). -The dual entries are assigned the prefix \idprefixfmt{gls} and are -placed in the \code{main} glossary. The \code{gls.array} +The \glspl{dualentry} are assigned the prefix \idprefixfmt{gls} and are +placed in the \mainglossary. The \code{gls.array} and \code{gls.matrix} entries have been indexed on pages~1, 2 and~3. The \code{gls.vector} and \code{gls.set} entries have been indexed on pages~1 and~3. -With the default setting, some of the locations are in the -\code{main} glossary (corresponding to \code{\cs{gls}\marg{gls.array}}, +With the default setting, some of the \glspl{location} are in the +\mainglossary\ (corresponding to \code{\cs{gls}\marg{gls.array}}, \code{\cs{gls}\marg{gls.vector}}, \code{\cs{gls}\marg{gls.set}} and -\code{\cs{gls}\marg{gls.matrix}}) and some of the locations are in the +\code{\cs{gls}\marg{gls.matrix}}) and some of the \glspl{location} are in the \code{index} glossary (corresponding to \code{\cs{gls}\marg{idx.vector}} and \code{\cs{gls}\marg{idx.set}}). If the option \csopt[primary]{combine-dual-locations} is added to -the resource set, then all the locations are moved to the -\code{index} glossary. The entries in the \code{main} glossary no -longer have locations. This is actually preferable for this type -of document and it's best not to reference the primary (index) +the resource set, then all the \glspl{location} are moved to the +\code{index} glossary. The entries in the \mainglossary\ no longer +have \glspl{location}. This is actually preferable for this type of +document and it's best not to reference the \primary\ (index) entries as the hyperlink created by \ics{gls} will point to the index, but these entries don't have descriptions, so it's less -useful than referencing the dual (main) entries as then the -hyperlink can point to the definition in the \code{main} glossary. +useful than referencing the \dual\ (\code{main}) entries as then the +hyperlink can point to the definition in the \mainglossary. \subsection{Dual Fields} @@ -15883,8 +16375,8 @@ hyperlink can point to the definition in the \code{main} glossary. \optsection[\subsubsection]{dual-type} -This option sets the \field{type} field for all dual -entries. (The primary entries obey the \csopt{type} option.) This +This option sets the \field{type} field for all \glspl{dualentry}. +(The \glspl{primaryentry} obey the \csopt{type} option.) This will override any value of \field{type} provided in the \ext{bib} file (or created through a mapping). The \meta{value} is required and should be one of: @@ -15908,15 +16400,15 @@ of the \ext{bib} file (without the extension) that provided the entry definition (new to v1.1); \item \optfmt{same as primary}: sets the \field{type} to the same as -the corresponding primary entry's \field{type} (which may have been -set with \csopt{type}). If the primary entry doesn't have the -\field{type} field set, the dual's \field{type} will remain +the corresponding \gls{primaryentry}['s] \field{type} (which may have been +set with \csopt{type}). If the \gls{primaryentry} doesn't have the +\field{type} field set, the \glsdisp{dualentry}{dual's} \field{type} will remain unchanged. \item \optfmt{same as parent}: sets the \field{type} to the same as -the entry's parent (new to v1.9). If the entry doesn't have a parent -or if the parent doesn't have the \field{type} field set, then -no change is made. +the entry's \parent\ (new to v1.9). If the entry doesn't have a +\parent\ or if the \parent\ doesn't have the \field{type} field set, +then no change is made. \item \meta{label}: sets the \field{type} field to \meta{label}. \end{itemize} @@ -15943,8 +16435,8 @@ Alternatively: \optsection[\subsubsection]{dual-category} -This option sets the \field{category} field for all dual -entries. (The primary entries obey the \csopt{category} option.) This +This option sets the \field{category} field for all +\glspl{dualentry}. (The \glspl{primaryentry} obey the \csopt{category} option.) This will override any value of \field{category} provided in the \ext{bib} file (or created through a mapping). The \meta{value} may be empty or one of: @@ -15968,9 +16460,9 @@ name of the \ext{bib} file (without the extension) that provided the entry definition (new to v1.1); \item \optfmt{same as primary}: sets the \field{category} to the -same as the corresponding primary entry's \field{category} (which -may have been set with \csopt{category}). If the primary entry -doesn't have the \field{category} field set, the dual's +same as the corresponding \gls{primaryentry}['s] \field{category} (which +may have been set with \csopt{category}). If the \gls{primaryentry} +doesn't have the \field{category} field set, the \glsdisp{dualentry}{dual's} \field{category} will remain unchanged. \item \optfmt{same as type}: sets the \field{category} to the same @@ -15983,10 +16475,10 @@ set with \csopt{dual-type}). If the entry doesn't have the \optsection[\subsubsection]{dual-counter} -As \csopt{counter} but for the dual entries. In this case +As \csopt{counter} but for the \glspl{dualentry}. In this case \meta{value} may be the name of the counter or -\optfmt{same as primary} which uses the counter for the primary -entry. +\optfmt{same as primary} which uses the counter for the +\gls{primaryentry}. \optsection[\subsubsection]{dual-short-case-change} @@ -16026,11 +16518,11 @@ at the start of the file and will include the line: \begin{codeenv*} \field{dual}=\marg{dual.child}, \end{codeenv*} -for the primary entry (\code{child}) and the line: +for the \gls{primaryentry} (\code{child}) and the line: \begin{codeenv} \field{dual}=\marg{child}, \end{codeenv} -for the dual entry (\code{dual.child}). It's then possible to +for the \gls{dualentry} (\code{dual.child}). It's then possible to reference one entry from the other. For example, the post-description hook could contain: \begin{codeenv} @@ -16047,46 +16539,46 @@ before \gls!{glsxtrresourcefile}). \optsection[\subsubsection]{dual-date-time-field-format} -As \csopt{date-time-field-format} but is used for dual entries. +As \csopt{date-time-field-format} but is used for \glspl{dualentry}. \optsection[\subsubsection]{dual-date-field-format} -As \csopt{date-field-format} but is used for dual entries. +As \csopt{date-field-format} but is used for \glspl{dualentry}. \optsection[\subsubsection]{dual-time-field-format} -As \csopt{time-field-format} but is used for dual entries. +As \csopt{time-field-format} but is used for \glspl{dualentry}. \optsection[\subsubsection]{dual-date-time-field-locale} -As \csopt{date-time-field-locale} but is used for dual entries. +As \csopt{date-time-field-locale} but is used for \glspl{dualentry}. \optsection[\subsubsection]{dual-date-field-locale} -As \csopt{date-field-locale} but is used for dual entries. +As \csopt{date-field-locale} but is used for \glspl{dualentry}. \optsection[\subsubsection]{dual-time-field-locale} -As \csopt{time-field-locale} but is used for dual entries. +As \csopt{time-field-locale} but is used for \glspl{dualentry}. \subsection{Dual Sorting} \label{sec:dualoptssort} \optsection[\subsubsection]{dual-sort} -This option indicates how to sort the dual entries. The primary -entries are sorted with the normal entries according to -\csopt{sort}, and the dual entries are sorted according to -\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the dual -entries will be combined with the primary entries and all the -entries will sorted together according to the \csopt{sort} option. +This option indicates how to sort the \glspl{dualentry}. +The \glspl{primaryentry} are sorted with the normal entries according to +\csopt{sort}, and the \glspl{dualentry} are sorted according to +\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the +\glspl{dualentry} will be combined with the \glspl{primaryentry} and all the +entries will be sorted together according to the \csopt{sort} option. -If \meta{value} isn't set to \optfmt{combine} then the dual -entries are sorted separately according to \meta{value} (as per -\csopt{sort}) and the dual entries will be appended at the end of +If \meta{value} isn't set to \optfmt{combine} then the +\glspl{dualentry} are sorted separately according to \meta{value} (as per +\csopt{sort}) and the \glspl{dualentry} will be appended at the end of the \iext{glstex} file. The field used by the comparator is given by \csopt{dual-sort-field}. -If \csopt[custom]{dual-sort}, then the dual entries are sorted according to the +If \csopt[custom]{dual-sort}, then the \glspl{dualentry} are sorted according to the rule provided by \csopt{dual-sort-rule}. For example: @@ -16097,8 +16589,8 @@ For example: \csopt[de-CH-1996]{dual-sort} } \end{codeenv} -This will sort the primary entries according to \optfmt{en} -(English) and the secondary entries according to \optfmt{de-CH-1996} +This will sort the \glspl{primaryentry} according to \optfmt{en} +(English) and the \glspl{secondaryentry} according to \optfmt{de-CH-1996} (Swiss German new orthography) whereas: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ @@ -16107,7 +16599,7 @@ This will sort the primary entries according to \optfmt{en} \csopt[combine]{dual-sort} } \end{codeenv} -will combine the dual entries with the primary entries and sort them +will combine the dual entries with the \glspl{primaryentry} and sort them all according to the \optfmt{en-GB} locale (British English). If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If @@ -16116,20 +16608,20 @@ If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If \optsection[\subsubsection]{dual-sort-field} This option indicates the field to use when sorting dual entries -(when they haven't been combined with the primary entries). The +(when they haven't been combined with the \glspl{primaryentry}). The default value is the same as the \csopt{sort-field} value. \optsection[\subsubsection]{dual-missing-sort-fallback} -As \csopt{missing-sort-fallback} but for dual sorting. +As \csopt{missing-sort-fallback} but for \dual\ sorting. \optsection[\subsubsection]{dual-trim-sort} -As \csopt{trim-sort} but for dual sorting. +As \csopt{trim-sort} but for \dual\ sorting. \optsection[\subsubsection]{dual-sort-replace} -As \csopt{sort-replace} but for dual sorting. +As \csopt{sort-replace} but for \dual\ sorting. \optsection[\subsubsection]{dual-sort-rule} @@ -16137,77 +16629,77 @@ As \csopt{sort-rule} but for \csopt[custom]{dual-sort}. \optsection[\subsubsection]{dual-break-at} -As \csopt{break-at} but for dual entries. +As \csopt{break-at} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-break-marker} -As \csopt{break-marker} but for dual entries. +As \csopt{break-marker} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-sort-number-pad} -As \csopt{sort-number-pad} but for dual entries. +As \csopt{sort-number-pad} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-sort-pad-plus} -As \csopt{sort-pad-plus} but for dual entries. +As \csopt{sort-pad-plus} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-sort-pad-minus} -As \csopt{sort-pad-minus} but for dual entries. +As \csopt{sort-pad-minus} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-identical-sort-action} -As \csopt{identical-sort-action} but for dual entries. +As \csopt{identical-sort-action} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-sort-suffix} -As \csopt{sort-suffix} but for dual entries. +As \csopt{sort-suffix} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-sort-suffix-marker} -As \csopt{sort-suffix-marker} but for dual entries. +As \csopt{sort-suffix-marker} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-strength} -As \csopt{strength} but for dual entries. +As \csopt{strength} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-decomposition} -As \csopt{decomposition} but for dual entries. +As \csopt{decomposition} but for \glspl{dualentry}. \optsection[\subsubsection]{dual-letter-number-rule} -As \csopt{letter-number-rule} but for dual entries that use a +As \csopt{letter-number-rule} but for \glspl{dualentry} that use a letter-number sort. \optsection[\subsubsection]{dual-letter-number-punc-rule} -As \csopt{letter-number-punc-rule} but for dual entries that use a +As \csopt{letter-number-punc-rule} but for \glspl{dualentry} that use a letter-number sort. \optsection[\subsubsection]{dual-numeric-sort-pattern} -As \csopt{numeric-sort-pattern} but for dual entries that use a +As \csopt{numeric-sort-pattern} but for \glspl{dualentry} that use a locale-sensitive numeric sort. \optsection[\subsubsection]{dual-numeric-locale} -As \csopt{numeric-locale} but for dual entries that use a +As \csopt{numeric-locale} but for \glspl{dualentry} that use a locale-sensitive numeric sort. \optsection[\subsubsection]{dual-date-sort-locale} -As \csopt{date-sort-locale} but for dual entries that +As \csopt{date-sort-locale} but for \glspl{dualentry} that use a date/time sort. \optsection[\subsubsection]{dual-date-sort-format} -As \csopt{date-sort-format} but for dual entries that +As \csopt{date-sort-format} but for \glspl{dualentry} that use a date/time sort. \optsection[\subsubsection]{dual-group-formation} -As \csopt{group-formation} but for dual sorting. +As \csopt{group-formation} but for \dual\ sorting. \subsection{Dual Mappings} @@ -16217,8 +16709,8 @@ As \csopt{group-formation} but for dual sorting. This setting governs the behaviour of \atentry{dualentry} definitions. The value consists of two comma-separated lists of -equal length identifying the field mapping used to create the dual -entry from the primary one. Note that the \field{alias} field +equal length identifying the field mapping used to create the +\gls{dualentry} from the \primary\ one. Note that the \field{alias} field can't be mapped. The default setting is: @@ -16228,7 +16720,7 @@ The default setting is: \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} ]{dual-entry-map} \end{codeenv} -The dual entry is created by copying the value of the field in the +The \gls{dualentry} is created by copying the value of the field in the first list \meta{list1} to the field in the corresponding place in the second list \meta{list2}. Any additional fields are copied over to the same field. @@ -16240,7 +16732,7 @@ For example: \field{see}=\marg{dog} } \end{codeenv} -defines two entries. The primary entry is essentially like: +defines two entries. The \gls{primaryentry} is essentially like: \begin{codeenv} \atentry{entry}\marg{cat, \field{name}=\marg{cat}, @@ -16250,7 +16742,7 @@ defines two entries. The primary entry is essentially like: \field{see}=\marg{dog} } \end{codeenv} -and the dual entry is essentially like: +and the \gls{dualentry} is essentially like: \begin{codeenv} \atentry{entry}\marg{dual.cat, \field{description}=\marg{cat}, @@ -16396,12 +16888,12 @@ and if the \ext{bib} file contains: \field{description}=\marg{enfant} } \end{codeenv} -Then the definition of the primary entry (\code{child}) in the +Then the definition of the \gls{primaryentry} (\code{child}) in the \ext{glstex} file will set the \field{description} field to: \begin{codeenv} \gls{bibglshyperlink}\marg{enfant}\marg{dual.child} \end{codeenv} -and the dual entry (\code{dual.child}) will have the +and the \gls{dualentry} (\code{dual.child}) will have the \field{description} field set to: \begin{codeenv} \gls{bibglshyperlink}\marg{child}\marg{child} @@ -16415,13 +16907,13 @@ The reason the \field{description} field is chosen for the modification is because the first field listed in \meta{list1} of \csopt{dual-entry-map} is the \field{name} field which maps to \field{description} (the first field in the second list \meta{list2}). This means that the hyperlink for -the dual entry should be put in the \field{description} field. +the \gls{dualentry} should be put in the \field{description} field. -For the primary entry, the \field{name} field is looked up in the +For the \gls{primaryentry}, the \field{name} field is looked up in the second list from the \csopt{dual-entry-map} setting. This is the third item in this second list, so the third item in the first list is selected, which also happens to be the \field{description} field, -so the hyperlink for the primary entry is put in the +so the hyperlink for the \gls{primaryentry} is put in the \field{description} field. \optsection[\subsubsection]{dual-abbrv-backlink} @@ -16450,9 +16942,9 @@ use a style that checks for this field and adds the backlink. With \sty{glossaries-extra} v1.30+ you can use: \nosecdef{GlsXtrDualBackLink} -which encapsulates \meta{text} with a hyperlink to the dual. +which encapsulates \meta{text} with a hyperlink to the \dual. The \meta{label} identifies the entry that requires a backlink. -The dual's label is obtained from the field given by: +The \glsdisp{dualentry}{dual's} label is obtained from the field given by: \nosecdef{GlsXtrDualField} which defaults to \field{dual}. Note that if you assign a different field label with \csopt{dual-field}, then you will @@ -16508,10 +17000,10 @@ Shortcut for: \optsection{tertiary-prefix} -This option indicates the prefix to use for the tertiary entries. The +This option indicates the prefix to use for the \glspl{tertiaryentry}. The default value is \idprefix{tertiary} (including the terminating period). -As from version 1.8, the tertiary label prefix is identified +As from version 1.8, the \glsdisp{tertiaryentry}{tertiary} label prefix is identified in the \ext{glstex} file with: \begin{codeenv} \format{bibglstertiaryprefixlabel} @@ -16519,7 +17011,7 @@ in the \ext{glstex} file with: \optsection{tertiary-type} -This option indicates that the tertiary entries should have +This option indicates that the \glspl{tertiaryentry} should have their \field{type} field set to \meta{value}. If \meta{value} is empty the \field{type} is left unchanged. Unlike the \csopt{type} and \csopt{dual-type} options, there are no @@ -16527,7 +17019,7 @@ recognised keywords. \optsection{tertiary-category} -This option indicates that the tertiary entries should have +This option indicates that the \glspl{tertiaryentry} should have their \field{category} field set to \meta{value}. If \meta{value} is empty the \field{category} is left unchanged. Unlike the \csopt{category} and \csopt{dual-category} options, there are no @@ -16550,7 +17042,7 @@ will generate a warning instead of an error. Since many of the commands are actually used within the \ext{glstex} file, it's best to use \cs{newcommand} before the first -\idx{resourceset} and \cs{renewcommand} between \idxpl{resourceset} +\igls{resourceset} and \cs{renewcommand} between \iglspl{resourceset} if adjustments are necessary. @@ -16569,11 +17061,12 @@ provided. The \field{sort} key may be set within the \ext{glstex} entry definition, but its value is usually not required in the document -unless you are using a hybrid method with \styopt[alsoindex]{record}. +unless you are using a hybrid method with \styopt[hybrid]{record} +(in which case, it's redundant to get \bibgls\ to sort). -After each entry is defined, if it has any associated locations and +After each entry is defined, if it has any associated \glspl{location} and the default \csopt[true]{save-loclist} is set, then the -locations are added using: +\glspl{location} are added using: \nosecformatdef{glsxtrfieldlistadd} Any additional fields that don't have associated keys are then set (if required) with \ics{GlsXtrSetField}. @@ -16714,7 +17207,7 @@ file is: \cssection{bibglsnewdualindexentry} \formatdef{bibglsnewdualindexentry} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the \atentry{dualindexentry} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16727,7 +17220,7 @@ Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexentrysecondary} \formatdef{bibglsnewdualindexentrysecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the \atentry{dualindexentry} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16739,7 +17232,7 @@ file is: \cssection{bibglsnewdualindexsymbol} \formatdef{bibglsnewdualindexsymbol} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16752,7 +17245,7 @@ Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexsymbolsecondary} \formatdef{bibglsnewdualindexsymbolsecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16764,7 +17257,7 @@ file is: \cssection{bibglsnewdualindexnumber} \formatdef{bibglsnewdualindexnumber} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the \atentry{dualindexnumber} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16777,7 +17270,7 @@ Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexnumbersecondary} \formatdef{bibglsnewdualindexnumbersecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the \atentry{dualindexnumber} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16789,7 +17282,7 @@ file is: \cssection{bibglsnewdualindexabbreviation} \formatdef{bibglsnewdualindexabbreviation} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the \atentry{dualindexabbreviation} type. The default definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16799,7 +17292,7 @@ the \ext{glstex} file is: \field{category}=\marg{index},\idx{param}3}\marg{}\comment{} } \end{codeenv} -In this case \meta{dual-label} is the dual entry's label, which is used +In this case \meta{dual-label} is the \gls{dualentry}['s] label, which is used to fetch the category label in \gls{bibglsuseabbrvfont}. (The \field{category} field for the dual isn't used since a custom definition of @@ -16810,18 +17303,18 @@ Note that (as shown above) with the default \csopt[short]{abbreviation-name-fallback} the \field{name} uses: \nosecformatdef{bibglsuseabbrvfont} to format the name, which ensures that it uses the same font as the -short form for the dual abbreviation. This will use +short form for the \dual\ abbreviation. This will use \ics{glsuseabbrvfont} if it's defined otherwise it will be defined to replicate that command. If \csopt{abbreviation-name-fallback} is set to some other field then the \field{name} uses: \nosecformatdef{bibglsuselongfont} instead, which ensures that it uses the same font as the -long form for the dual abbreviation. +long form for the \dual\ abbreviation. \cssection{bibglsnewdualindexabbreviationsecondary} \formatdef{bibglsnewdualindexabbreviationsecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the \atentry{dualindexabbreviation} entry type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16837,7 +17330,7 @@ interfere with the abbreviation style. \cssection{bibglsnewdualabbreviationentry} \formatdef{bibglsnewdualabbreviationentry} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16850,7 +17343,7 @@ Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualabbreviationentrysecondary} \formatdef{bibglsnewdualabbreviationentrysecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} file is: \begin{codeenv} @@ -16865,7 +17358,7 @@ are changed). \cssection{bibglsnewdualentryabbreviation} \formatdef{bibglsnewdualentryabbreviation} -This command is used to define primary terms identified with the +This command is used to define \primary\ terms identified with the (now deprecated) entry type \atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} file is: @@ -16879,7 +17372,7 @@ Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualentryabbreviationsecondary} \formatdef{bibglsnewdualentryabbreviationsecondary} -This command is used to define secondary terms identified with the +This command is used to define \glsdisp{dualentry}{secondary} terms identified with the (now deprecated) entry type \atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} file is: @@ -16948,7 +17441,7 @@ set to \ics{acronymtype} and the default \field{category} set to \cssection{bibglsnewtertiaryindexabbreviationentry} \formatdef{bibglsnewtertiaryindexabbreviationentry} -This is used to define primary terms identified with the +This is used to define \primary\ terms identified with the \atentry{tertiaryindexabbreviationentry} type. It's essentially the same as \gls!{bibglsnewdualindexabbreviation}. The definition provided in the \ext{glstex} file is: @@ -16963,10 +17456,13 @@ The definition provided in the \ext{glstex} file is: \cssection{bibglsnewtertiaryindexabbreviationentrysecondary} \formatdef{bibglsnewtertiaryindexabbreviationentrysecondary} -This command is used to define both the secondary and tertiary terms identified with the -\atentry{tertiaryindexabbreviationentry} type. The secondary -term is an abbreviation and the tertiary term is a regular entry. -The definition written to the \ext{glstex} file is: +This command is used to define both the +\glsdisp{secondaryentry}{secondary} and +\glsdisp{tertiaryentry}{tertiary} terms identified with the +\atentry{tertiaryindexabbreviationentry} type. The +\glsdisp{secondaryentry}{secondary} term is +an abbreviation and the \glsdisp{tertiaryentry}{tertiary} term is a regular entry. The +definition written to the \ext{glstex} file is: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{} \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{} @@ -16975,21 +17471,22 @@ The definition written to the \ext{glstex} file is: \marg{\idx{param}8}\comment{} } \end{codeenv} -The \meta{label} is the label for the secondary (abbreviation) entry -and \meta{tertiary-label} is the label for the tertiary (regular) -entry. The fifth argument (\meta{primary name}) isn't used but is -provided if required for a custom redefinition. -The \field{name} field for the tertiary is obtained from -the \meta{long} argument encapsulated by \gls{bibglsuselongfont} -to format the name, which ensures that it uses the same font as the -long form for the dual abbreviation. This will use -\ics{glsuselongfont} if it's defined otherwise it will be defined to -replicate that command. +The \meta{label} is the label for the +\glsdisp{secondaryentry}{secondary} (abbreviation) entry and +\meta{tertiary-label} is the label for the +\glsdisp{tertiaryentry}{tertiary} (regular) entry. The fifth +argument (\meta{primary name}) isn't used but is provided if +required for a custom redefinition. The \field{name} field for the +\glsdisp{tertiaryentry}{tertiary} is obtained from the \meta{long} +argument encapsulated by \gls{bibglsuselongfont} to format the name, +which ensures that it uses the same font as the 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 +This command is used to define the \glsdisp{mainentry}{main term} identified with \atentry{bibtexentry}. The definition written to the \ext{glstex} file is: \begin{codeenv} @@ -17014,7 +17511,7 @@ The definition written to the \ext{glstex} file is: \cssection{bibglsnewprogenitor} \formatdef{bibglsnewprogenitor} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{progenitor}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17026,7 +17523,7 @@ file as: \cssection{bibglsnewspawnindex} \formatdef{bibglsnewspawnindex} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnindex}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17038,7 +17535,7 @@ file as: \cssection{bibglsnewspawnedindex} \formatdef{bibglsnewspawnedindex} -This command is used to define the terms spawned by +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{progenitor} or \atentry{spawnindex}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17050,7 +17547,7 @@ to the \ext{glstex} file as: \cssection{bibglsnewspawnindexplural} \formatdef{bibglsnewspawnindexplural} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnindexplural}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17062,7 +17559,7 @@ file as: \cssection{bibglsnewspawnedindexplural} \formatdef{bibglsnewspawnedindexplural} -This command is used to define the terms spawned by +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnindexplural}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17074,7 +17571,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawnentry} \formatdef{bibglsnewspawnentry} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnentry}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17086,7 +17583,7 @@ file as: \cssection{bibglsnewspawnedentry} \formatdef{bibglsnewspawnedentry} -This command is used to define the terms spawned by \atentry{spawnentry}. +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnentry}. The definition is written to the \ext{glstex} file as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{} @@ -17097,7 +17594,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawnabbreviation} \formatdef{bibglsnewspawnabbreviation} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnabbreviation}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17109,7 +17606,7 @@ file as: \cssection{bibglsnewspawnedabbreviation} \formatdef{bibglsnewspawnedabbreviation} -This command is used to define the terms spawned by \atentry{spawnabbreviation}. +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnabbreviation}. The definition is written to the \ext{glstex} file as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{} @@ -17120,7 +17617,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawnacronym} \formatdef{bibglsnewspawnacronym} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnacronym}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17132,7 +17629,7 @@ file as: \cssection{bibglsnewspawnedacronym} \formatdef{bibglsnewspawnedacronym} -This command is used to define the terms spawned by \atentry{spawnacronym}. +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnacronym}. The definition is written to the \ext{glstex} file as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{} @@ -17143,7 +17640,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawnsymbol} \formatdef{bibglsnewspawnsymbol} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnsymbol}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17155,7 +17652,7 @@ file as: \cssection{bibglsnewspawnedsymbol} \formatdef{bibglsnewspawnedsymbol} -This command is used to define the terms spawned by \atentry{spawnsymbol}. +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnsymbol}. The definition is written to the \ext{glstex} file as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{} @@ -17165,7 +17662,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawnnumber} \formatdef{bibglsnewspawnnumber} -This command is used to define the main terms created by +This command is used to define the \glsdisp{mainentry}{main terms} created by \atentry{spawnnumber}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17177,7 +17674,7 @@ file as: \cssection{bibglsnewspawnednumber} \formatdef{bibglsnewspawnednumber} -This command is used to define the terms spawned by \atentry{spawnnumber}. +This command is used to define the \glsdisp{spawnedentry}{terms spawned} by \atentry{spawnnumber}. The definition is written to the \ext{glstex} file as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{} @@ -17187,7 +17684,7 @@ The definition is written to the \ext{glstex} file as: \cssection{bibglsnewspawndualindexentry} \formatdef{bibglsnewspawndualindexentry} -This command is used to define the \idx{progenitor}['s] primary term created by +This command is used to define the \gls{progenitor}['s] \primary\ term created by \atentry{spawndualindexentry}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17200,8 +17697,8 @@ The \meta{description} argument is ignored. \cssection{bibglsnewspawndualindexentrysecondary} \formatdef{bibglsnewspawndualindexentrysecondary} -This command is used to define the \idx{progenitor}['s] secondary -(dual) term created by +This command is used to define the \gls{progenitor}['s] +\glsdisp{dualentry}{secondary} (dual) term created by \atentry{spawndualindexentry}. The definition is written to the \ext{glstex} file as: \begin{codeenv} @@ -17213,8 +17710,8 @@ The definition is written to the \ext{glstex} file as: \section{Location Lists and Cross-References} \label{sec:loclistdefs} -These commands deal with the way the location lists and cross -references are formatted. The commands typically aren't used until +These commands deal with the way the \iglspl{locationlist} and +cross references are formatted. The commands typically aren't used until the entry information is displayed in the glossary, so you may redefine these commands after the resource file has been loaded. @@ -17222,9 +17719,9 @@ redefine these commands after the resource file has been loaded. \formatdef{bibglsseesep} Any entries that provide a \field{see} field (and that field hasn't -be omitted from the location list with \csopt[omit]{see}) will +be omitted from the \gls{locationlist} with \csopt[omit]{see}) will have \gls{bibglsseesep} inserted between the \field{see} part and the -location list (unless there are no locations, in which case just +\gls{locationlist} (unless there are no \glspl{location}, in which case just the \field{see} part is displayed without \gls{bibglsseesep}). This command is provided with: @@ -17278,25 +17775,25 @@ Displays the formatted cross-reference stored in the \cssection{bibglsdelimN} \formatdef{bibglsdelimN} -Separator between individual locations, except for the last. +Separator between individual \glspl{location}, except for the last. This defaults to \ics{delimN}. \cssection{bibglslastDelimN} \formatdef{bibglslastDelimN} -Separator between penultimate and final individual locations. -This defaults to \code{,\idx{nbspchar}} to discourage lonely locations. +Separator between penultimate and final individual \glspl{location}. +This defaults to \code{,\idx{nbspchar}} to discourage lonely \glspl{location}. \cssection{bibglscompact} \formatdef{bibglscompact} -The first argument \meta{pattern} indicates the location pattern: +The first argument \meta{pattern} indicates the \gls{location} pattern: \code{digit} for digits, \code{roman} for \idx!{lowercase} Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman -numerals and \code{alpha} for alphabetical locations. The actual -location is split into two parts, \meta{part1} and \meta{part2}. +numerals and \code{alpha} for alphabetical \glspl{location}. The actual +\gls{location} is split into two parts, \meta{part1} and \meta{part2}. The string concatenation \meta{part1}\meta{part2} forms the -actual location. +actual \gls{location}. This just does \meta{part2} by default. @@ -17339,7 +17836,7 @@ text-block command without the initial backslash) in the optional argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within the argument of \gls{bibglsrange}. By default this simply does its argument. This command is not used with ranges that are formed by collating -consecutive locations. +consecutive \glspl{location}. \cssection{bibglsinterloper} @@ -17381,13 +17878,13 @@ discard the conflicting entries.) \formatdef{bibglspostlocprefix} If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will -be inserted at the start of location lists, and its default +be inserted at the start of \glspl{locationlist}, and its default definition includes \gls{bibglspostlocprefix} placed after the prefix text. This command is provided with: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglspostlocprefix}}\marg{\cs{cs.space}} \end{codeenv} -which puts a space between the prefix text and the location list. +which puts a space between the prefix text and the \gls{locationlist}. You can define this before you load the \ext{bib} file: \begin{codeenv} \cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } @@ -17404,14 +17901,14 @@ Or you can redefine it afterwards: \formatdef{bibglslocprefix} If the \csopt{loc-prefix} option is on, this command will be provided. If the glossary type has been provided by \csopt{type} -(and \csopt{dual-type} if there are any dual entries) then the +(and \csopt{dual-type} if there are any \glspl{dualentry}) then the definition of \gls{bibglslocprefix} will be appended to the glossary -preamble for the given type (or types if there are dual entries). +preamble for the given type (or types if there are \glspl{dualentry}). For example, if the document has: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[p.,pp.]{loc-prefix},\csopt[entries]{src}} \end{codeenv} -and there are no dual entries, then the following will be added to +and there are no \glspl{dualentry}, then the following will be added to the \ext{glstex} file: \begin{codeenv} \cs{apptoglossarypreamble}\oarg{main}\marg{\comment{} @@ -17459,9 +17956,9 @@ using the value of \idx{tag.pages} from the \langxml. For example with \file{bib \formatdef{bibglslocsuffix} If the \csopt{loc-suffix} option is on, this command will be provided. If the glossary type has been provided by \csopt{type} -(and \csopt{dual-type} if there are any dual entries) then the +(and \csopt{dual-type} if there are any \glspl{dualentry}) then the definition of \gls{bibglslocsuffix} will be appended to the glossary -preamble for the given type (or types if there are dual entries). +preamble for the given type (or types if there are \glspl{dualentry}). This commands definition depends on the value provided by \csopt{loc-suffix}. For example, with @@ -17480,29 +17977,29 @@ the command is defined as: Note that this is slightly different from \gls{bibglslocprefix} as it includes the 0 case, which in this instance means that there were -no locations but there was a cross-reference. This command isn't -added when the location list is empty. +no \glspl{location} but there was a cross-reference. This command isn't +added when the \gls{locationlist} is empty. \cssection{bibglsprimary} \formatdef{bibglsprimary} -When the \csopt{save-primary-locations} option is used, the primary -locations are stored in the \field{primarylocations} field +When the \csopt{save-principal-locations} option is used, the +\glspl{principallocation} are stored in the \field{primarylocations} field encapsulated with this command. The first argument is the number of -locations in the list. The second argument is the list of locations +\glspl{location} in the list. The second argument is the list of \glspl{location} formatted in the usual way. The default definition is to ignore the first argument and simply do the second. \cssection{bibglslocationgroup} \formatdef{bibglslocationgroup} -When the \csopt{loc-counters} option is used, the locations +When the \csopt{loc-counters} option is used, the \glspl{location} for each entry are grouped together according to the counter (in the order specified in the value of \csopt{loc-counters}). -Each group of locations is encapsulated within +Each group of \glspl{location} is encapsulated within \gls{bibglslocationgroup}, where \meta{n} is the number -of locations within the group, \meta{counter} is the -counter name and \meta{list} is the formatted location sub-list. +of \glspl{location} within the group, \meta{counter} is the +counter name and \meta{list} is the formatted \gls{location} sub-list. By default, this simply does \meta{list}, but may be defined (before the resources are loaded) or redefined (after the resources are loaded) as required. @@ -17524,8 +18021,8 @@ For example: } \end{codeenv} This will prefix each group with the counter name, if there's -only one location, or the counter name followed by \qt{s}, -if there are multiple locations within the group. +only one \gls{location}, or the counter name followed by \qt{s}, +if there are multiple \glspl{location} within the group. There are various ways to adapt this to translate the counter name to a different textual label, such as: @@ -17549,7 +18046,7 @@ name to a different textual label, such as: \formatdef{bibglslocationgroupsep} When the \csopt{loc-counters} option is set, this command -is used to separate each location sub-group. It may be defined +is used to separate each \gls{location} sub-group. It may be defined before the resources are loaded: \begin{codeenv} \cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } @@ -17572,12 +18069,13 @@ or redefined after the resources are loaded: \cssection{bibglssupplemental} \formatdef{bibglssupplemental} -When the \csopt{supplemental-locations} option is used, the locations -from a supplementary document are encapsulated within the \meta{list} -part of \gls{bibglssupplemental}. The first argument \meta{n} -(ignored by default) is the number of supplementary locations. +When the \csopt{supplemental-locations} option is used, the +\glspl{location} from a \supplementarydocument\ are encapsulated +within the \meta{list} part of \gls{bibglssupplemental}. The first +argument \meta{n} (ignored by default) is the number of +\supplementarylocations. -If multiple supplemental sources are permitted (that is, +If multiple \supplemental\ sources are permitted (that is, \bibgls\ has detected that the document is using at least version 1.36 of \sty{glossaries-extra}), then the \meta{list} part will consist of sub-lists for each external source. In this @@ -17587,17 +18085,17 @@ all the sub-lists. \cssection{bibglssupplementalsublist} \formatdef{bibglssupplementalsublist} -If multiple supplemental sources are permitted, this will be used +If multiple \supplemental\ sources are permitted, this will be used to format each sub-list, where \meta{n} (ignored by default) is the number of elements in the sub-list, \meta{external document} (ignored by default) is the external source and \meta{list} -is the list of supplementary locations in \meta{external document}. +is the list of \supplementarylocations\ in \meta{external document}. \cssection{bibglssupplementalsep} \formatdef{bibglssupplementalsep} -The separator between the main location list and the supplementary -location list. By default this is just \gls!{bibglsdelimN}. This may be +The separator between the main \gls{locationlist} and the supplementary +\gls{locationlist}. By default this is just \gls!{bibglsdelimN}. This may be defined before the resources are loaded: \begin{codeenv} \cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } @@ -17619,7 +18117,7 @@ or redefined after the resources are loaded: \formatdef{bibglssupplementalsubsep} The separator between the supplementary -location sub-lists. By default this is just \gls!{bibglsdelimN}. +\gls{location} sub-lists. By default this is just \gls!{bibglsdelimN}. \cssection{bibglshrefchar} @@ -17709,7 +18207,7 @@ the original rule. The problem is now how to make the indexing application use the desired label in the argument of \gls{glsgroupheading} instead of selecting the heading based on the first character of each sort value for each -top-level entry in that group. This can't be done with +\gls{top-levelentry} in that group. This can't be done with \idx!{makeindex}, and with \idx!{xindy} it requires a custom language module, which isn't a trivial task. @@ -17795,7 +18293,7 @@ then the last group is identified with: In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs} are the arguments for that command. If you want \gls{bibglssetlastgrouptitle} to change the group title then you need to define it before the -\idx{resourceset}. For example: +\igls{resourceset}. For example: \begin{codeenv} \cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{} \cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}} @@ -17913,10 +18411,10 @@ and the document contains: \strut \gls{GlsXtrLoadResources}\oarg{ \csopt[testcjk]{src},\comment{bib file} - \csopt[ja-JP]{sort},\comment{locale used to sort primary entries} - \csopt[en-GB]{dual-sort},\comment{locale used to sort secondary entries} - \csopt[japanese]{type},\comment{put the primary entries in the 'japanese' glossary} - \csopt[english]{dual-type},\comment{put the dual entries in the 'english' glossary} + \csopt[ja-JP]{sort},\comment{locale used to sort \glspl{primaryentry}} + \csopt[en-GB]{dual-sort},\comment{locale used to sort \glspl{dualentry}} + \csopt[japanese]{type},\comment{put the \gls{primaryentry} in the 'japanese' glossary} + \csopt[english]{dual-type},\comment{put the \gls{dualentry} in the 'english' glossary} \csopt[en.]{dual-prefix} } \end{codeenv} @@ -18211,7 +18709,7 @@ converted to \idx{lowercase}) not \hex{C5}. \formatdef{bibglsunicodegrouptitle} The title for Unicode group formations is simply defined as \code{\cs{unexpanded}\margm{label}} so you will need to change it to -something more appropriate. For example (before the \idx{resourceset}): +something more appropriate. For example (before the \igls{resourceset}): \begin{codeenv} \cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{} \ifnumhex{\idx{param}3}>64 @@ -18255,7 +18753,7 @@ as \glostyle{indexhypergroup}. \label{sec:flattendefs} These commands relate to the way the \field{name} field is altered -when flattening lonely child entries with the \csopt{flatten-lonely} +when flattening \glspl{lonelychildentry} with the \csopt{flatten-lonely} option. \cssection{bibglsflattenedhomograph} @@ -18263,7 +18761,7 @@ option. \formatdef{bibglsflattenedhomograph} The default definition simply does \meta{name}. -This command is used if the child and parent name's are identical. +This command is used if the \child\ and \parent\ names are identical. For example, suppose the \ext{bib} file contains: \begin{codeenv} \atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}} @@ -18278,9 +18776,9 @@ For example, suppose the \ext{bib} file contains: \field{description}=\marg{list of technical words} } \end{codeenv} -The child entries don't have a \field{name} field, so the value is assumed -to be the same as the parent's \field{name} field. Here's an example -document where both child entries are used: +The \glspl{childentry} don't have a \field{name} field, so the value is assumed +to be the same as the \glsdisp{parententry}{parent's} \field{name} field. +Here's an example document where both \glspl{childentry} are used: \begin{codeenv} \cmd{documentclass}\marg{article} \strut @@ -18294,21 +18792,21 @@ document where both child entries are used: \cs{printunsrtglossary} \cmd{end}\marg{document} \end{codeenv} -This uses one of the glossary styles designed for homographs and the +This uses one of the glossary styles designed for \iglspl{homograph} and the glossary has the structure: \begin{flushleft} \textbf{glossary}\par \quad 1) collection of glosses 1\par \quad 2) list of technical words 1 \end{flushleft} -If only one child entry is selected, then the result looks a little +If \glsdisp{lonelychildentry}{only one child entry} is selected, then the result looks a little odd. For example: \begin{flushleft} \textbf{glossary}\par \quad 1) collection of glosses 1 \end{flushleft} -With the \csopt{flatten-lonely} option, the parent is removed and -the child is moved up a hierarchical level. With +With the \csopt{flatten-lonely} option, the \parent\ is removed and +the \child\ is moved up a \hierarchicallevel. With \csopt[postsort]{flatten-lonely} this would normally adjust the name so that it appears as \meta{parent name}, \meta{child name} but in this case it would look a little odd for the name to @@ -18318,14 +18816,14 @@ set to: \gls{bibglsflattenedhomograph}\marg{glossary}\marg{super.glossary} \end{codeenv} (where the first argument is the original name and the second argument is the -label of the parent entry). +label of the \gls{parententry}). This means that the name simply appears as \qt{glossary}, even if the \csopt[postsort]{flatten-lonely} option is used. Note that if -the parent entry is removed, the parent label won't be of much use. -You can test for existence using \ics{ifglsentryexists} in case you -want to vary the way the name is displayed according to whether or -not the parent is still present. +the \gls{parententry} is removed, the \parent\ label won't be of +much use. You can test for existence using \ics{ifglsentryexists} +in case you want to vary the way the name is displayed according to +whether or not the \parent\ is still present. \cssection{bibglsflattenedchildpresort} @@ -18372,7 +18870,7 @@ this just defaults to: \formatdef{bibglssetwidest} This is used by \csopt{set-widest} to set the widest name for the -given hierarchical level where the glossary type can't be determined. +given \hierarchicallevel\ where the glossary type can't be determined. This is defined as: \begin{codeenv} \cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}} @@ -18394,7 +18892,7 @@ set the \field{type} using options like \csopt{type}. \formatdef{bibglssetwidestfortype} This is used by \csopt{set-widest} to set the widest name for the -given hierarchical level where the glossary type is known. This +given \hierarchicallevel\ where the glossary type is known. This is defined as: \begin{codeenv} \cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} @@ -18429,8 +18927,8 @@ will use: \ics{glsxtrSetWidestFallback}\marg{2}\margm{glossary list} \end{codeenv} if defined otherwise it will use \ics{glsFindWidestLevelTwo}, which -sets the widest name for the top-level and first two sub-levels -across all the listed glossaries. +sets the widest name for the \glsdisp{top-levelentry}{top-level} and +first two sub-levels across all the listed glossaries. \cssection{bibglssetwidestfortypefallback} @@ -18455,7 +18953,7 @@ will use: \ics{glsxtrSetWidestFallback}\marg{0}\margm{glossary list} \end{codeenv} if defined otherwise it will use \ics{glsFindWidestTopLevelName}, -which sets the widest name for the top-level. +which sets the widest name for the \glsdisp{top-levelentry}{top-level}. \cssection{bibglssetwidesttoplevelfortypefallback} @@ -18545,26 +19043,26 @@ The default definition is: \cssection{bibglsprimaryprefixlabel} \formatdef{bibglsprimaryprefixlabel} -A hook to pick up the primary prefix label (identified with +A hook to pick up the \primary\ prefix label (identified with \csopt{label-prefix}) if required. This does nothing by default. If required, this command should be defined before the -\idx{resourceset} is loaded. +\igls{resourceset} is loaded. \cssection{bibglsdualprefixlabel} \formatdef{bibglsdualprefixlabel} -A hook to pick up the dual prefix label (identified with +A hook to pick up the \dual\ prefix label (identified with \csopt{dual-prefix}) if required. This does nothing by default. If required, this command should be defined before the -\idx{resourceset} is loaded. +\igls{resourceset} is loaded. \cssection{bibglstertiaryprefixlabel} \formatdef{bibglstertiaryprefixlabel} -A hook to pick up the tertiary prefix label (identified with +A hook to pick up the \glsdisp{tertiaryentry}{tertiary} prefix label (identified with \csopt{tertiary-prefix}) if required. This does nothing by default. If required, this command should be defined before the -\idx{resourceset} is loaded. +\igls{resourceset} is loaded. \cssection{bibglsexternalprefixlabel} @@ -18572,7 +19070,7 @@ required, this command should be defined before the A hook to pick up the \meta{n}th external prefix label (identified with \csopt{ext-prefixes}) if required. This does nothing by default and won't be used if the list of external prefixes is empty. If required, -this command should be defined before the \idx{resourceset} is +this command should be defined before the \igls{resourceset} is loaded. \cssection{bibglshashchar} @@ -18624,6 +19122,28 @@ Converts \meta{text} to \idx{titlecase}. This just uses Converts the first letter of \meta{text} to \idx{uppercase}. This just uses \ics{makefirstuc} by default. +\cssection{bibglsdefinitionindex} + +\formatdef{bibglsdefinitionindex} +If \csopt{save-definition-index} has been set this command expands to the +\gls{definitionindex} of the entry identified by \meta{label}. This +command will only be provided in the \ext{glstex} file if +\csopt{save-definition-index} has been set. However, the command is +always defined by the \hyperref[sec:texparserlib]{\TeX\ parser library} +but will expand to empty if the associated resource option hasn't +been set. + +\cssection{bibglsuseindex} + +\formatdef{bibglsuseindex} +If \csopt{save-use-index} has been set this command expands to the +\gls{orderofuseindex} of the entry identified by \meta{label}. This +command will only be provided in the \ext{glstex} file if +\csopt{save-use-index} has been set. However, the command is +always defined by the \hyperref[sec:texparserlib]{\TeX\ parser library} +but will expand to empty if the associated resource option hasn't +been set. + \chapter{Converting Existing \iext{tex} to \iext{bib}} \label{sec:gls2bib} \setsecdepth{1} @@ -18652,14 +19172,14 @@ The \meta{options} recognised by \idx{convertgls2bib} are described below. \convertglsbibarg{texenc} -The character encoding of the \ext{tex} file. If omitted, the -operating system's default encoding is assumed (or the +The character \igls{encoding} of the \ext{tex} file. If omitted, the +operating system's default \gls{encoding} is assumed (or the \idx{JVM}['s]). \convertglsbibarg{bibenc} -The character encoding of the \ext{bib} file. If omitted, the same -encoding as the \ext{tex} file is assumed. +The character \igls{encoding} of the \ext{bib} file. If omitted, the same +\gls{encoding} as the \ext{tex} file is assumed. \convertglsbibarg{space-sub} @@ -19243,7 +19763,8 @@ These files are just examples of how to use \bibgls. There are other ways of defining similar entries and sometimes alternatives are suggested. Use the code here as a starting point if you need data like this and adapt it to a format appropriate for your -requirements. +requirements. There are also some example documents in the +\href{https://www.dickimaw-books.com/gallery}{Dickimaw Books gallery}. \filesection{no-interpret-preamble.bib} @@ -19287,7 +19808,7 @@ example of \csopt{bibtex-contributor-fields}, see the way the \fieldfmt{cast} field in \exfile{films.bib} is dealt with. Although the file only contains ASCII characters, it starts with -an encoding line to prevent \bibgls\ from searching the entire file +an \gls{encoding} line to prevent \bibgls\ from searching the entire file for it. (That's not so much of an issue with a short file, but may cause an unnecessary delay for much longer files.) @@ -19387,7 +19908,7 @@ is in the \fieldfmt{constantsymbol} field in both cases) and \code{imaginary} I've provided some commands in the \atentry{preamble} for constants that are represented by Latin and Greek letters. -These can be defined in the document before the \idx{resourceset} +These can be defined in the document before the \igls{resourceset} if different notation is required. The upright Greek commands require the \isty{upgreek} package. @@ -19608,10 +20129,10 @@ An alternative approach would be to format the names using \csopt[name]{bibtex-contributor-fields} to convert them. There are also some synonyms provided with \atentry{index} entry -types that have the \field{alias} field to redirect to the main -entry. These don't include a \field{description} or any of the other +types that have the \field{alias} field to redirect to the +\gls{mainentry}. These don't include a \field{description} or any of the other fields as that would be redundant. All the information can be found -in the main entry. +in the \gls{mainentry}. Except for the aliases, the entries have a custom field \fieldfmt{identifier} set to \code{person}. This will be ignored by @@ -19678,7 +20199,7 @@ the \fieldfmt{director} field could use \BibTeX's contributor syntax (as the \fieldfmt{cast} field does). Some of the films actually had more than one director but only one is listed per film in this sample file for simplicity. Similarly, the -\fieldfmt{cast} field only contains the principle actors rather than the +\fieldfmt{cast} field only contains the principal actors rather than the complete list. The book on which the film is based could be contained in a cross-reference field or a custom \fieldfmt{basedon} field. @@ -20343,7 +20864,7 @@ The contents of \filefmt{topics.bib} are as follows: This example uses the \exfile{terms.bib}, \exfile{animals.bib}, \exfile{minerals.bib} and \exfile{vegetables.bib} files to create a -hierarchical glossary. These are specified with the resource option: +\gls{hierarchicalglossary}. These are specified with the resource option: \begin{codeenv} \csopt[{terms,animals,minerals,vegetables}]{src} \end{codeenv} @@ -20356,19 +20877,19 @@ the labels of the animal, mineral and vegetable entries in the \end{codeenv} The default \csopt{selection} setting means that only those terms referenced in the document and their dependencies are selected. The -referenced entries simply have \qt{1} in the \idx{locationlist} as +referenced entries simply have \qt{1} in the \igls{locationlist} as it's only a trivial single-paged example. The dependencies that haven't actually been referenced in the -document don't have a \idx{locationlist}. (The \qt{seal} entry is a +document don't have a \igls{locationlist}. (The \qt{seal} entry is a dependency, but it's also been referenced in the document, so it has a -\idx{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow} +\igls{locationlist}.) The \qt{quartz}, \qt{beryl} and \qt{marrow} entries are dependencies because they occur in the description of some of the referenced entries. Normally this would mean that they -have no \idx{locationlist} after the first \LaTeX+\bibgls+\LaTeX\ +have no \igls{locationlist} after the first \LaTeX+\bibgls+\LaTeX\ build but once the glossary has been created the references to those dependent entries in the descriptions will create records and so on -the next \bibgls+\LaTeX\ they will also have \idxpl{locationlist}. +the next \bibgls+\LaTeX\ they will also have \iglspl{locationlist}. This would make the complete document build: \begin{verbatim} pdflatex sample-hierarchical @@ -20377,8 +20898,8 @@ pdflatex sample-hierarchical bib2gls --group sample-hierarchical pdflatex sample-hierarchical \end{verbatim} -However, in this example I've decided to ignore any records created -in the glossary: +However, in this example I've decided to \glsdisp{ignoredrecord}{ignore} any records +created in the glossary: \begin{codeenv} \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} @@ -20386,7 +20907,7 @@ This means that the document build is the usual \LaTeX+\bibgls+\LaTeX. I've used the \glostyle{treegroup} style so I need to invoke \bibgls\ with the \longarg{group} switch. This creates letter groups -for the top-level entries. Note that sub-entries never have letter groups. +for the \glspl{top-levelentry}. Note that \glspl{sub-entry} never have letter groups. The complete code is listed below. The document build is: \begin{verbatim} @@ -20412,15 +20933,15 @@ The complete document is shown in \figureref{fig:sample-hierarchical.pdf}. As discussed in \sectionref{sec:logicaldivisions} there are three ways of creating logical divisions when displaying the entries through the use of the \field{type}, \field{group} and \field{parent} fields. -In general, hierarchical glossaries are created with +In general, \glspl{hierarchicalglossary} are created with the \field{parent} field and an appropriate glossary style (as in the previous \exfile{sample-hierarchical.tex} example). -This example creates a hierarchical effect but the entries don't -actually have a hierarchical structure as none of them have the -\field{parent} field set. Instead, what were the child entries in +This example creates a \hierarchical\ effect but the entries don't +actually have a \hierarchical\ structure as none of them have the +\field{parent} field set. Instead, what were the \glspl{childentry} in \exfile{sample-hierarchical.tex} now have the \field{type} field -set. The hierarchical effect is achieved with +set. The \hierarchical\ effect is achieved with \ics{printunsrtinnerglossary} (which requires at least \sty{glossaries-extra} v1.44). @@ -20428,10 +20949,10 @@ set. The hierarchical effect is achieved with The \ics{printunsrtinnerglossary} command is unsuitable for use with tabular-like styles, such as \glostyle{long}, and can be problematic with \glostyle{list} styles. However, those styles -aren't suitable for hierarchical glossaries anyway. +aren't suitable for \glspl{hierarchicalglossary} anyway. \end{important} -Normally, hierarchy is achieve through definitions like: +Normally, \hierarchy\ is achieve through definitions like: \begin{codeenv} \atentry{index}\marg{animal} \atentry{entry}\marg{duck,\field{name}=\marg{duck}, @@ -20451,11 +20972,11 @@ definitions behave like: \field{type}=\marg{animal} } \end{codeenv} -The aim here is for the \code{animal} entry to be placed in the main -glossary so that it's listed with \cs{printunsrtglossary}. The +The aim here is for the \code{animal} entry to be placed in the +\gls{mainglossary} so that it's listed with \cs{printunsrtglossary}. The \code{duck} entry is placed in a glossary that has a label (\code{animal}) that matches the label of the \qt{parent} entry -(even though it's technically not a parent). This new glossary +(even though it's technically not a \parent). This new glossary (\code{animal}) can be automatically defined by invoking \bibgls\ with the \longarg{provide-glossaries} switch. @@ -20478,14 +20999,14 @@ existence check. If the glossary exists, it's then displayed using } \end{codeenv} The \printglossopt{leveloffset} option is required to achieve a -hierarchical effect (provided the glossary style supports it) and +\hierarchical\ effect (provided the glossary style supports it) and the \printglossopt[false]{groups} option is needed to prevent letter groups showing for the nested glossary, which would otherwise create a strange effect. (This example uses the \glostyle{treegroup} style, -which provides a hierarchical glossary with letter groups.) +which provides a \gls{hierarchicalglossary} with letter groups.) The \cs{printunsrtglossary} handler macro then needs to be set to -this custom macro when the main glossary is displayed: +this custom macro when the \gls{mainglossary} is displayed: \begin{codeenv} \cs{printunsrtglossary*}\marg{\cs{let}\cs{printunsrtglossaryhandler}\csfmt{nestedhandler}} \end{codeenv} @@ -20495,9 +21016,9 @@ field has been aliased to \field{type} rather than \field{parent}, the \code{animal} entry is no longer considered a dependent. The \code{duck} entry has been referenced in the document with \cs{gls} but the \code{animal} entry hasn't. The previous example ensured -that the \code{animal} entry was selected because it was a parent of +that the \code{animal} entry was selected because it was a \parent\ of a selected entry. If the same resource options are used in this -example, the main glossary will be empty, which means that the +example, the \gls{mainglossary} will be empty, which means that the nested glossaries won't be displayed either. One way to ensure that the \code{animal}, \code{mineral} and @@ -20512,7 +21033,7 @@ field as a dependency field: This will achieve the same effect as the \exfile{sample-hierarchical.tex} document, but it's a far more convoluted method. The reason this example document is listed here -is to demonstrate a sightly modified hierarchical effect that can't +is to demonstrate a sightly modified \hierarchical\ effect that can't be achieved through the normal method. Suppose that, for some strange reason, I want the \qt{animal}, @@ -20521,7 +21042,7 @@ order (say, reverse alphabetical). The other entries (\qt{duck} etc) need to be sorted in normal alphabetical order. The \csopt{sort} option applies the same sort method to all -hierarchical levels. The sort \emph{value} chosen for particular entries +\hierarchical\ levels. The sort \emph{value} chosen for particular entries can be altered through the use of fallbacks (such as the \csopt{entry-sort-fallback} or \csopt{symbol-sort-fallback} options) and a letter comparator may be used to resolve identical sort @@ -20531,7 +21052,7 @@ within the same resource set). The only way to apply different sort methods is to separate the entries into different resource sets (or use dual or secondary sorting). -This can be achieved by having one resource set for the main entries +This can be achieved by having one resource set for the \glspl{mainentry} with one sort method and another resource set for all the other entries with a different sort method: \begin{codeenv} @@ -20998,7 +21519,7 @@ use labels: \begin{codeenv} \csopt[baseunits]{group} \end{codeenv} -for the first \idx{resourceset} and +for the first \igls{resourceset} and \begin{codeenv} \csopt[derivedunits]{group} \end{codeenv} @@ -21032,8 +21553,8 @@ so I've changed it to use \field{name} instead: An alternative approach would be to alias \atentryfmt{unit} and \atentryfmt{measurement} to \atentry{entry} instead. -Since there's no \csopt{type} set, all entries end up in the main -glossary, but since there are two resource commands the glossary +Since there's no \csopt{type} set, all entries end up in the +\gls{mainglossary}, but since there are two resource commands the glossary ends up with sorted blocks. The document doesn't include any commands like \cs{gls}, so @@ -21087,14 +21608,14 @@ sorted blocks this example has two glossaries: I've used the \styopt{section} package option to use \ics{section*} for the glossary titles. This overrides the default \ics{chapter*} which is used with book or report type of classes. I've also used the -\styopt{nomain} option to suppress the creation of the main glossary +\styopt{nomain} option to suppress the creation of the \gls{mainglossary} as I want to define my own glossary types instead. As before the custom entry types need to be aliased: \begin{codeenv} \csopt[unit=symbol]{entry-type-aliases} \end{codeenv} -for the first \idx{resourceset} and +for the first \igls{resourceset} and \begin{codeenv} \csopt[measurement=symbol]{entry-type-aliases} \end{codeenv} @@ -21211,10 +21732,10 @@ the column headers) and the way each row is formatted: }\comment{} } \end{codeenv} -There are no sub-entries in this document so I haven't bothered to +There are no \glspl{sub-entry} in this document so I haven't bothered to redefine \ics{subglossentry}. (The tabular styles aren't appropriate -for hierarchical glossaries.) This puts the symbol into the third -column (rather than the location list, which is ignored). +for \glspl{hierarchicalglossary}.) This puts the symbol into the third +column (rather than the \gls{locationlist}, which is ignored). This style supports the letter group separator (although it doesn't title the groups), so if I want this I need to use the \longarg{group} switch. @@ -21382,10 +21903,10 @@ be revert back to being suppressed for entries containing I haven't referenced any of the entries in the main body of the document, so I've used \csopt[all]{selection} to select all entries. This means that there are no number lists on the first document -build (\LaTeX+\bibgls+\LaTeX) but the next build would show locations for +build (\LaTeX+\bibgls+\LaTeX) but the next build would show \glspl{location} for the books that have been referenced by the film entries. Since this looks a bit odd, I've added \csopt[false]{save-locations} to -prevent \bibgls\ from saving the locations. +prevent \bibgls\ from saving the \glspl{location}. I've used a style that shows letter group headings so I need to use the \longarg{group} switch. @@ -21832,9 +22353,9 @@ There are no glossary reference commands, such as \cs{gls}, but \bibgls\ can be run with \longarg{cite-as-record} to treat the \ics{citation} commands (written to the \ext{aux} file by \ics{cite}) as ignored records. Since \cs{cite} doesn't record the page number, -there are no associated locations. +there are no associated \glspl{location}. -The \code{main} glossary isn't required, so I've used +The \mainglossary\ isn't required, so I've used \styopt{nomain} to suppress its creation. I want to use both the \glostyle{altlist} and \glostyle{indexgroup} styles but none of the other styles, so I've used \styopt{nostyles} to prevent the @@ -22114,7 +22635,7 @@ need to remember to redefine \ics{GlsXtrFmtField} to match. As with \exfile{sample-msymbols.tex} I'm sorting by the \field{category} label and this value is copied to the \field{group} -field, but again I don't have a hierarchical glossary as the logical +field, but again I don't have a \gls{hierarchicalglossary} as the logical blocks don't have titles. In this document I only want to select entries that have been @@ -22254,7 +22775,7 @@ titles as they're in the document, so it's only able to sort by the label. While this might work for English, it can become a problem for other languages that use extended Latin or non-Latin characters in their alphabet. A much better method is to treat this as a -hierarchical glossary with topic titles as the top-level entries. +\gls{hierarchicalglossary} with topic titles as the \glspl{top-levelentry}. This is covered in the next example \exfile{sample-textsymbols2.tex}. The complete document code is listed below. The document build is: @@ -22293,7 +22814,7 @@ The \exfile{topics.bib} file contains terms with labels that match the custom \fieldfmt{identifier} fields used in the \exfile{miscsymbols.bib} file. So both files are loaded and the \fieldfmt{identifier} field is now aliased to \field{parent}. These -parent entries represent the topics and unlike the previous example +\glspl{parententry} represent the topics and unlike the previous example it's now possible to sort by the topic title (obtained from the \field{name} field) instead of by the label. \begin{codeenv} @@ -22428,9 +22949,9 @@ records into ignored records: \begin{codeenv} \ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} -This means that some of the entries won't have location lists, so +This means that some of the entries won't have \glspl{locationlist}, so I've defined a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the -\field{description} if there's no location otherwise it inserts a +\field{description} if there's no \gls{location} otherwise it inserts a comma: \begin{codeenv} \cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{} @@ -22440,7 +22961,7 @@ comma: } \end{codeenv} I've used \csopt{loc-suffix} to append a \idx{full-stop} after the -location lists. This doesn't affect the entries that haven't been +\glspl{locationlist}. This doesn't affect the entries that haven't been indexed. I decided to convert the first letter of the \field{name} field to @@ -22746,7 +23267,7 @@ xelatex sample-usergroups \end{verbatim} The two pages of the document are shown in \figureref{fig:sample-usergroups.pdf}. Since the entries have all -been referenced on page~1, the location lists are all simply~\qt{1}. +been referenced on page~1, the \glspl{locationlist} are all simply~\qt{1}. %\lstinputlisting[firstline=5]{../examples/sample-usergroups.tex} \begin{lstlisting}[escapechar=|] @@ -22908,7 +23429,7 @@ cross-reference term as been indexed. This requires: \end{codeenv} to ensure the aliased entries are selected. -Since I don't need the default \code{main} glossary (I'm providing +Since I don't need the default \mainglossary\ (I'm providing my own custom glossaries) I've used the \styopt{nomain} option to suppress its automatic creation, but I do want the \code{index} glossary so I've used the \styopt{index} package option. As with the @@ -23173,7 +23694,7 @@ fixed with: \begin{codeenv} \csopt[primary]{combine-dual-locations} \end{codeenv} -Which transfers the dual entry locations to the corresponding +Which transfers the dual entry \glspl{location} to the corresponding primary. The other problem is the cross-references in the \field{description} @@ -23277,7 +23798,7 @@ to avoid the redundant index record: \cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{} \end{codeenv} Remember that if any records are added within a glossary, an extra -\LaTeX\ and \bibgls\ call are required to ensure that the location list +\LaTeX\ and \bibgls\ call are required to ensure that the \gls{locationlist} is correct, so the document build is: \begin{verbatim} pdflatex sample-multi1 @@ -23569,7 +24090,7 @@ Instead I've used \cs{glsFindWidestTopLevelName} to find it: \end{codeenv} The text symbols from \exfile{miscsymbols.bib} are all loaded in a -single \idx{resourceset}, where the \field{type} field can be +single \igls{resourceset}, where the \field{type} field can be obtained from the \field{category}, which in turns is obtained from the custom \fieldfmt{identifier} field. Since \bibgls\ doesn't recognise any of the symbol commands, I'm sorting according to the @@ -23594,7 +24115,7 @@ makes more sense in this case.) Finally, all recorded and cross-referenced terms are needed for the index. This includes entries that have already been defined in the -earlier \idxpl{resourceset} (so a guard against duplicates is +earlier \iglspl{resourceset} (so a guard against duplicates is necessary) but it also includes entries from the \exfile{terms.bib} file that haven't yet been dealt with. I'd like the index to start with a \idx{symbolgroup} containing the icons from @@ -23616,9 +24137,9 @@ the rest of the index to keep them together in a single group: \csopt[glssymbols]{group} } \end{codeenv} -Since I know that there are no parents or cross-references in this +Since I know that there are no \glsdisp{parententry}{parents} or cross-references in this set of entries I've used \csopt[recorded no deps]{selection} to skip -the dependency checks. In this \idx{resourceset}, the \field{name} +the dependency checks. In this \igls{resourceset}, the \field{name} field has the symbol command (obtained from the custom \fieldfmt{icon} field), and the \field{symbol} field has the symbol description (obtained from the custom \fieldfmt{icondescription} @@ -23627,7 +24148,7 @@ label to \code{glssymbols}, which keeps all these entries in a single group and the title will be obtained from \ics{glssymbolsgroupname}. -Before loading the final \idx{resourceset} \ics{glsxtrlongshortdescname} needs +Before loading the final \igls{resourceset} \ics{glsxtrlongshortdescname} needs to be changed so that the abbreviations using the \abbrstyle{long-short-desc} style (that is, the abbreviations with the \field{category} set to @@ -23683,7 +24204,7 @@ the \field{name} field is suitable for alphabetical sorting. I've aliased \atentryfmt{unit} to \atentry{dualentry} rather than \atentry{symbol} as I want both the unit name and the -measurement in the index and I've combined their location lists: +measurement in the index and I've combined their \glspl{locationlist}: \begin{codeenv} \csopt[both]{combine-dual-locations} \end{codeenv} @@ -23694,7 +24215,7 @@ glossary: \csopt[index]{dual-type} \end{codeenv} -All \ext{bib} files used in the previous \idxpl{resourceset} are needed +All \ext{bib} files used in the previous \iglspl{resourceset} are needed as well as the \exfile{terms.bib} file: \begin{codeenv} \csopt[terms,bacteria,markuplanguages,vegetables,minerals, @@ -23729,7 +24250,7 @@ entries except for those in the \exfile{terms.bib} file will link to the relevant glossary. Those in the \exfile{terms.bib} file will link to the index. It's possible to disable the hyperlinks for those entries, but the reader may find it useful to jump to the index to -look up other locations for that entry in the document. +look up other \glspl{location} for that entry in the document. To deal with the identical book and film titles, I'm again using the \field{category} to resolve identical sort values: 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 a5cc4072729..e0fef509d98 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 a09583725cb..9b49d2321cd 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |