diff options
Diffstat (limited to 'Master')
38 files changed, 10281 insertions, 6066 deletions
diff --git a/Master/texmf-dist/doc/support/bib2gls/CHANGES b/Master/texmf-dist/doc/support/bib2gls/CHANGES index a59744d0601..d90c4cd5e75 100644 --- a/Master/texmf-dist/doc/support/bib2gls/CHANGES +++ b/Master/texmf-dist/doc/support/bib2gls/CHANGES @@ -1,3 +1,57 @@ +v1.8 (2018-11-30): + + * new resource options: + + --save-primary-locations + --primary-location-formats + --long-case-change + --dual-long-case-change + --word-boundaries + --sort-label-list + --dependency-fields + + * added support for the new glossaries-extra package option + record=nameref (introduced to glossaries-extra v1.37). + + * normal locations are now written to the location field as + \glsnoidxdisplayloc{<prefix>}{<counter>}{<format>}{<location>} + instead of explicitly using + \setentrycounter[<prefix>]{<counter>}\<format>{<location>} + This matches the way the record is added to the loclist field + and makes it easier to adjust the record formatting. + + * bib2gls now always parses the .log file even if the interpreter + setting is off. (It still needs to know version details and + whether hyperlinks and Unicode are supported by the document.) + + * Underscores now allowed in bib labels. + + * Hooks added to pick up label prefixes if needed: + + \bibglsprimaryprefixlabel + \bibglsdualprefixlabel + \bibglstertiaryprefixlabel + \bibglsexternalprefixlabel + + * bug fix: corrected default sort=doc + + * bug fix: corrected letternumber-upperlower and + letternumber-lowerupper sort methods. + + * bug fix: corrected invalid datetime pattern that threw + InvalidArgumentException + + * bug fix: https://github.com/nlct/bib2gls/issues/3 + Files located in local texmf path are not determined correctly + on Windows. + (actual bug was in texparserlib.jar rather than bib2gls.jar) + + * \@glsnavhypertarget will now fallback on original definition + (which requires an extra LaTeX call) if the type is unknown. + + * Renamed example file sample-languages.tex to + sample-markuplanguages.tex + v1.7 (2018-08-18): * added support for multiple supplementary sources 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 10567d7ab4d..1b56f3d9b33 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.1 b/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 index 7cb3ab10c3f..60060770700 100644 --- a/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 +++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -54,16 +54,20 @@ .\" Avoid warning from groff about undefined register 'F'. .de IX .. -.if !\nF .nr F 0 -.if \nF>0 \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} . \} .\} +.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "BIB2GLS 1" -.TH BIB2GLS 1 "2018-04-07" "perl v5.26.1" "bib2gls" +.TH BIB2GLS 1 "2018-08-25" "perl v5.28.0" "bib2gls" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -214,6 +218,11 @@ 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\-\-merge\-nameref\-on\fR \fIrule\fR" 4 +.IX Item "--merge-nameref-on rule" +Rule for merging locations created with the record=nameref package option +(requires glossaries\-extra.sty version 1.37+). The \fIrule\fR may be +one of: \fBhcounter\fR, \fBhref\fR, \fBtitle\fR or \fBlocation\fR. .IP "\fB\-\-force\-cross\-resource\-refs\fR or \fB\-x\fR" 4 .IX Item "--force-cross-resource-refs or -x" Force cross-resource referencing mode on. diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf Binary files differindex e5b5ca22f51..43d21de48ce 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/markuplanguages.bib b/Master/texmf-dist/doc/support/bib2gls/examples/markuplanguages.bib index a9026843b72..8c46af7fa95 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/markuplanguages.bib +++ b/Master/texmf-dist/doc/support/bib2gls/examples/markuplanguages.bib @@ -46,7 +46,7 @@ @abbreviation{mathml, short={MathML}, long={\abbrvtag{m\NoCaseChange{ath}}ematical }#markuplang, - description={the standard markup language for creating web pages}, + description={markup language for describing mathematical notation}, identifier={markuplanguage} } 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 de3315dbf0b..7e637a9e649 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 880723b51c6..37088bf4823 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 9ad4de19184..ba5cafb6d1d 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 9377006f8d6..70bb61b0470 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 7e2c4d483de..616370e70e7 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf Binary files differindex d8835b6e975..bf7cb76b55d 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.tex b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.tex index d394c1b0212..aba4cbf2194 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.tex +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.tex @@ -26,7 +26,8 @@ \GlsXtrLoadResources[ src=markuplanguages,% data in markuplanguages.bib loc-suffix, - category=markuplanguage + category=markuplanguage, + description-case-change=firstuc ] \newcommand{\glsxtrpostdescmarkuplanguage}{% 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 516c47d6c62..9f1849fe1ac 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 e35915ee954..2ecee98595b 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 c283f2f91ac..2a8cf08a99f 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 45756e713d0..bca3e987feb 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 ce890362f42..e61b207d5ec 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 433a56cc1ec..bec2301f0c3 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.tex +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.tex @@ -439,7 +439,7 @@ and \film{thereturnoftheking} (adapted from the \renewcommand{\glsxtralttreeSymbolDescLocation}[2]{% \glossentrydesc{#1}% \ifglshassymbol{#1}{\space(\glossentrysymbol{#1})}{}% - \glspostdescription\glstreeprelocation + \glspostdescription \glsxtrAltTreePar }% } 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 9059cf5198a..1490ac1b029 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 4a8b92b4f46..239503ceb43 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf +++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf Binary files differindex f9d46361409..b3a5176fdba 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 4174e51e7fb..db752bfcd20 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 498b3e0adef..799ee650f30 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 a0d80a70269..2cefbd0b1ec 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/doc/support/bib2gls/examples/usergroups.bib b/Master/texmf-dist/doc/support/bib2gls/examples/usergroups.bib index 95fa3163a50..2f3b654c28b 100644 --- a/Master/texmf-dist/doc/support/bib2gls/examples/usergroups.bib +++ b/Master/texmf-dist/doc/support/bib2gls/examples/usergroups.bib @@ -117,7 +117,7 @@ @abbreviation{ITALIC, short={ITALIC}, long={Irish \TeX\ and \LaTeX\ In-print Community}, - language={en-GB,en-IE}, + language={en-IE,en-GB}, identifier={texusergroup} } diff --git a/Master/texmf-dist/scripts/bib2gls/bib2gls.jar b/Master/texmf-dist/scripts/bib2gls/bib2gls.jar Binary files differindex 5d3db439d82..2141ce3e14c 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/bib2gls.sh b/Master/texmf-dist/scripts/bib2gls/bib2gls.sh index 124091e7f3b..2e720ffb545 100755 --- a/Master/texmf-dist/scripts/bib2gls/bib2gls.sh +++ b/Master/texmf-dist/scripts/bib2gls/bib2gls.sh @@ -1,12 +1,22 @@ #!/bin/sh +# Adapted from tlcockpit.sh to ensure the script works with cygwin -kernel=`uname -s` -if test "${kernel#*CYGWIN}" != "$kernel" -then - jarpath=`cygpath -w $(kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar)` -else - jarpath=`kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar` +scriptname=`basename "$0" .sh` +jar="$scriptname.jar" +jarpath=`kpsewhich --progname="$scriptname" --format=texmfscripts "$jar"` + +kernel=`uname -s 2>/dev/null` +if echo "$kernel" | grep CYGWIN >/dev/null; then + CYGWIN_ROOT=`cygpath -w /` + export CYGWIN_ROOT + jarpath=`cygpath -w "$jarpath"` fi -java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" +# User may have globally set their locale provider preference in +# $JAVA_TOOL_OPTIONS so don't override it. +if [ -z "$JAVA_TOOL_OPTIONS" ]; then + exec java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" +else + exec java -jar "$jarpath" "$@" +fi diff --git a/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar Binary files differindex 4fb33e1a006..a5b5e1dfe19 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 9e77be67c94..223c3e6b891 100644 --- a/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml +++ b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml @@ -50,6 +50,12 @@ See the manual for further details.</entry> Don''t force cross-resource referencing mode on (default).</entry> +<entry key="syntax.merge.nameref.on">{0} <rule> + Rule for merging locations with record=nameref + (requires glossaries-extra version 1.37+). + <rule> may be one of: ''hcounter'', ''href'', ''title'' + or ''location''.</entry> + <entry key="syntax.support.unicode.script">{0} Text superscripts or subscripts will use Unicode superscript or subscript characters if possible @@ -156,6 +162,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.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.dual.dep">Dual found: {0} (primary {1})</entry> <entry key="message.added.alias.dep">Adding alias {0} as dependency for {1}</entry> @@ -181,6 +188,7 @@ See the manual for further details.</entry> <entry key="message.sort.numeric.locale">Numeric sort locale: {0}</entry> <entry key="message.sort.numeric.format">Numeric sort format: {0}</entry> <entry key="message.no.sort.required">No sorting required.</entry> +<entry key="message.sort.labels">Label list sort method ''{0}'' on {1,choice,1#field|1<fields}: {2}</entry> <entry key="message.label.prefix">Label prefix: {0}</entry> <entry key="message.dual.label.prefix">Dual label prefix: {0}</entry> <entry key="message.tertiary.label.prefix">Tertiary label prefix: {0}</entry> @@ -247,6 +255,7 @@ Defaulting to: {0}. <entry key="message.detected.charset">Detected encoding: {0}</entry> <entry key="message.default.charset">Default encoding: {0}</entry> <entry key="message.null">not set</entry> +<entry key="message.detected.fontenc">Detected font encoding: {0}</entry> <entry key="message.missing.id">id missing</entry> <entry key="message.default.locale">Default document locale: {0} {1}</entry> <entry key="message.adding.record">Adding record {0} to entry {1}''s record list.</entry> @@ -268,7 +277,9 @@ Defaulting to: {0}. <entry key="message.missing.sort.fallback">Entry ''{0}'' missing sort field ''{1}''. Falling back on field ''{2}''.</entry> <entry key="message.list.known.packages.auto">Automatic support for: </entry> <entry key="message.list.known.packages.extra">Support available for: </entry> +<entry key="message.list.known.packages.info">Support may be quite limited in some cases.</entry> <entry key="message.created.missing.parent">Created missing parent ''{0}'' for entry ''{1}''</entry> +<entry key="message.found_entry_in_resource">Found entry ''{0}'' in resource set: {1}</entry> <entry key="tag.page">Page</entry> <entry key="tag.pages">Pages</entry> @@ -291,6 +302,8 @@ Defaulting to: {0}. <entry key="warning.title">Warning: {0}</entry> <entry key="warning.substituting">Substituting {0} with {1}</entry> <entry key="warning.removing">Removing {0}</entry> +<entry key="warning.cant.parse.file">Can''t parse {0} +{1}</entry> <entry key="warning.ignoring.unknown.entry.type">Ignoring unknown entry type: {0}</entry> <entry key="warning.ignoring.unknown.encoding">Ignoring unknown encoding: {0}</entry> <entry key="warning.ignoring.unknown.field">Ignoring unknown field: {0}</entry> @@ -306,6 +319,7 @@ Falling back on ID.</entry> <entry key="warning.cant.parse.datetime.pattern">Can''t parse {0} value ''{1}'' (pattern: ''{2}'')</entry> <entry key="warning.deprecated.type">Entry type ''{0}'' deprecated. Use ''{1}'' instead.</entry> <entry key="warning.deprecated.option">Option ''{0}'' deprecated. Use ''{1}'' instead.</entry> +<entry key="warning.deprecated.cs">Command ''{0}'' deprecated. Use ''{1}'' instead.</entry> <entry key="warning.missing.field">Entry ''{0}'' missing required field: {1}</entry> <entry key="warning.potential.nested.link">Entry ''{0}'' has potentially nested link text in field: {1} Consider using \glsps'{'{3}'}' or \glspt'{'{3}'}' instead of {2}'{'{3}'}'</entry> @@ -358,6 +372,8 @@ Aliased entries must be in the same resource set as their target entries with op <entry key="warning.invalid.locale">Unrecognised locale: {0}. Using {1} instead.</entry> <entry key="warning.interpreter.needed.fallback">Interpreter needed to obtain fallback contents for field {0} (entry {1})</entry> <entry key="warning.multi_supp_unsupported">Multiple supplemental locations not supported with glossaries-extra {1}. Restricting selection to just {0}. Update to at least glossaries-extra version {2} to support multiple supplementary sources.</entry> +<entry key="warning.unknown_entry">Unknown entry: {0}</entry> +<entry key="warning.unknown_entry_in_current_resource">Unknown entry ''{0}'' in current resource set: {1}</entry> <entry key="error.title">Error: {0}</entry> <entry key="error.alias.map.forbidden">The 'alias' field can't be mapped.</entry> diff --git a/Master/texmf-dist/scripts/bib2gls/texparserlib.jar b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar Binary files differindex ee969c62616..89c1d8fbf70 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-begin.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex index 1c82b8a2319..df2ef53ae03 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex @@ -1,10 +1,10 @@ -% arara: xelatex -% arara: bib2gls: {group: on} +% arara: lualatex +% arara: bib2gls: {group: on} if missing("glstex") || changed(toFile("bib2gls.bib")) || found("log", "Warning: Glossary entry") % arara: bibtex -% arara: xelatex -% arara: bib2gls if found ("log", "has not been defined") -% arara: xelatex if found ("log", "has not been defined") -% arara: xelatex if found ("log", "Rerun") +% arara: lualatex if changed("glstex") || missing("toc") +% arara: bib2gls: {group: on} +% arara: lualatex +% arara: lualatex if found ("log", "Rerun") \documentclass[titlepage=false,fontsize=12pt,captions=tableheading]{scrreprt} \usepackage[no-math]{fontspec} @@ -20,7 +20,7 @@ \usepackage{graphicx} \usepackage{datetime2} \usepackage{siunitx} -\usepackage{mhchem} +\usepackage[version=4]{mhchem} \usepackage{xr-hyper} \usepackage[hidelinks]{hyperref} @@ -76,6 +76,8 @@ {\string\\#1}% } +\newcommand*{\csref}{\gls} + \GlsXtrLoadResources[ src={bib2gls}, max-loc-diff=3, @@ -208,7 +210,7 @@ \newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}} \newenvironment{codeenv} {% - \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% \def\cmd{\char`\\}% \def\comment##1{\textcolor{comment}{\%\ ##1}}% \renewcommand*{\styfmt}[1]{##1}% @@ -236,10 +238,10 @@ \newcommand{\Idx}{\Gls} \newcommand{\Idxpl}{\Glspl} -\newcommand{\ext}{\gls} +\glsxtrnewgls{ext.}{\ext} \newcommand*{\iext}[1]{% - \glsxtrtitleorpdforheading{\idx{#1}}{.#1}{\extfmt{#1}}% + \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}% } \newcommand{\sty}{\gls} @@ -291,7 +293,7 @@ \newcommand*{\cs}{\gls} -\newcommand*{\ics}{\cs} +\newcommand*{\ics}[1][]{\cs[noindex=false,#1]} \newcommand*{\icswithargs}[2][]{\cs{#2}\glsentryuseri{#2}} @@ -491,7 +493,7 @@ Here's a simple example: \begin{codeenv} \cmd{documentclass}\marg{article} \strut -\cmd{usepackage}\marg{glossaries} +\ics{usepackage}\marg{glossaries} \strut \gls{newglossaryentry}\marg{duck}\comment{label} \marg{\comment{ information about this term:} @@ -813,7 +815,7 @@ which does \meta{true} if either the entry hasn't been defined or hasn't been marked as used, otherwise it does \meta{false}. Neither \gls{ifglsused} nor \gls{GlsXtrIfUnusedOrUndefined} should -occur in the \idx{postlinkhook} as the entry will have already +occur in the \idx{postlinkhook} (described later) as the entry will have already been used by that point. Instead, you need \gls{glsxtrifwasfirstuse} (see \sectionref{sec:postlinkhooks}). @@ -965,7 +967,7 @@ cs} but converts the first letter to \idx{uppercase} (analogous to letter to \idx{uppercase} and \meta{link allcaps cs} converts the entire value to \idx{uppercase}. -The new keys must be defined before the entries are defined (and +The new keys must be provided before the entries are defined (and the key definitions must come before the first \idx{resourceset} if you use \bibgls). For example: \begin{codeenv} @@ -994,8 +996,9 @@ below, the field label is the \emph{internal} label. In some cases, this is the same as the key, but there are a few that have a different internal label. See Table~\ref*{tab:internalfields} in the \bibgls\ user manual or Table~4.1 in the \sty{glossaries} user -manual. Custom fields provided with \gls{glsaddkey} or \gls{glsaddstoragekey} -have matching key and internal field labels. +manual~\cite{glossaries}. Custom fields provided with +\gls{glsaddkey} or \gls{glsaddstoragekey} have matching key and +internal field labels. The \sty{glossaries-extra} package provides a generic way of accessing a field, analogous to commands like \gls{glsentryname}: @@ -1028,7 +1031,7 @@ If you additionally need the field value (protected) fully expanded before comparison, use: \nosecformatdef{GlsXtrIfXpFieldEqXpStr} For a complete list of field commands, see the -\sty{glossaries-extra} user manual. +\sty{glossaries-extra} user manual~\cite{glossaries-extra}. The earlier \code{duck} and \code{goose} examples from \sectionref{sec:firstuse} can be rewritten to move the parenthetical @@ -1055,13 +1058,13 @@ material into separate keys: The \idx{postlinkhook} and glossary style can then be modified to include the additional information. For example: \begin{codeenv} -\gls[noindex=false]{glsdefpostlink}\marg{general}\marg{\comment{} +\gls[noindex=false]{glsdefpostlink}\marg{general}\marg{\comment{post-link hook} \gls[noindex=false]{glsxtrifwasfirstuse}\marg{\cmd{space}(\gls{glsentryuserii}\marg{\gls{glslabel}})}{}\comment{} } \strut \gls[noindex=false]{glssetcategoryattribute}\marg{general}\marg{glossname}\marg{firstuc} \strut -\gls[noindex=false]{glsdefpostname}\marg{general}\marg{\comment{} +\gls[noindex=false]{glsdefpostname}\marg{general}\marg{\comment{post-name hook} \cmd{space} (\gls{glsentryuseri}\marg{\gls[noindex=false]{glscurrententrylabel}}\comment{} \gls{GlsXtrIfXpFieldEqXpStr}\marg{plural}\marg{\gls{glscurrententrylabel}}\comment{} @@ -1072,13 +1075,14 @@ include the additional information. For example: \end{codeenv} The \idx{postlinkhook} appends the value of the \field{user2} field after the \idx{firstuse} of \gls{gls} (or its \idxpl{variant}). -The \catattr{glossname} attribute converts the first letter of the -\field{name} field to \idx{uppercase} when it's displayed in the -glossary. The \idx{postnamehook} appends (in parentheses) the value -of the \field{user1} field and then checks if the plural form is the -same as the singular form with \qt{s} appended, and only displays -the plural if they are different. See \sectionref{sec:glsformats} -and \sectionref{sec:displaygloss} for further details. +The \catattr{glossname} attribute is set to \code{firstuc}, which +converts the first letter of the \field{name} field to +\idx{uppercase} when it's displayed in the glossary. The +\idx{postnamehook} appends (in parentheses) the value of the +\field{user1} field and then checks if the plural form is the same +as the singular form with \qt{s} appended, and only displays the +plural if they are different. See \sectionref{sec:glsformats} and +\sectionref{sec:displaygloss} for further details. \section{Accessibility Support} \label{sec:accsupp} @@ -1213,8 +1217,8 @@ the \idx{firstuse} or subsequent use. For example, if the \idx{firstuse} starts with a vowel (or vowel sound), you may need \qt{an \gls{gls}\margm{label}} but if the subsequent use starts with a constant, you may need \qt{a \gls{gls}\margm{label}}. The prefix for -the \idx{firstuse} form specified in the \field{prefixfirst} field -and the prefix for the subsequent use form is specified in the +the \idx{firstuse} form is specified in the \field{prefixfirst} +field, and the prefix for the subsequent use form is specified in the \field{prefix} field. If a space is required between the prefix and \gls{gls}, this needs to be included, as the prefixing system allows for prefixes like l' which shouldn't be followed by a space. @@ -2254,7 +2258,7 @@ closest known \sty{babel} dialect label with: \nosecformatdef{IfTrackedDialectHasMapping} If true, you can fetch the corresponding \sty{babel} label with: \nosecformatdef{GetTrackedDialectToMapping} -If false, can try the root language label instead, which can be +If false, you can try the root language label instead, which can be obtained with: \nosecformatdef{TrackedLanguageFromDialect} For example: @@ -2401,8 +2405,8 @@ For example: }\marg{din}\marg{DIN}\marg{German Institute for Standardization} \strut \cmd{renewcommand}*\marg{\gls{glsxtruserparen}}[2]\marg{\comment{} - \gls{glsxtrfullsep}\marg{\gls{param}2}\comment{} - \gls{glsxtrparen} + \gls[noindex=false]{glsxtrfullsep}\marg{\gls{param}2}\comment{} + \gls[noindex=false]{glsxtrparen} \marg{\gls{param}1\comment{} \gls{ifglshasfield}\marg{\gls{glsxtruserfield}}\marg{\gls{param}2}\comment{} \marg{, \gls{emph}\marg{\gls{GlsXtrForeignText}\marg{\gls{param}2}\marg{\gls{glscurrentfieldvalue}}}}\comment{} @@ -2658,7 +2662,7 @@ following: \nosecformatdef{glsxtrfmt*} which internally use \gls{glslink} or: \nosecformatdef{glsxtrentryfmt} -which doesn't (as so is more like using \gls{glsentryname}). +which doesn't (and so is more like using \gls{glsentryname}). So an alternative approach is: \begin{codeenv} @@ -2718,6 +2722,12 @@ Now to obtain $g'(x_i)$: \begin{codeenv} \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{[g]\marg{x\gls{sbchar}i}}\gls{mshiftchar} \end{codeenv} +Note that for this simplistic helper macro, the mandatory inner +argument needs extra braces if it consists of more than a single +token. For example: +\begin{codeenv} +\gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{\marg{x\gls{sbchar}i}}\gls{mshiftchar} +\end{codeenv} \section{Dealing with Automated Case-Changing} \label{sec:symfirstuc} @@ -2878,6 +2888,14 @@ include the \field{symbol} field. (Table~15.1 in the \sty{glossaries} user manual~\cite{glossaries} gives an overview of the features supported by the predefined styles.) +The \glostyle{bookindex} style is provided by the +\isty{glossary-bookindex} package, which is distributed with +\sty{glossaries-extra}. This style is designed for indexes +and omits both the description and the symbol by default. It's +customized specifically for use with \bibgls. Without the +\idxpl{locationlist} obtained by \bibgls, this simply becomes a list +of the \field{name} values for each term. + The glossary is sub-divided into letter groups. By default, these sub-groups are separated with a vertical gap (for example, between duck and goose above). In the above example, the letter group is @@ -2888,9 +2906,10 @@ field (which is used by \idx{makeindex}) is set to the value of the \field{name} field (unless explicitly set) and then sanitized. When using \gls{printunsrtglossary}, the \field{sort} field is -irrelevant except to determine the letter group. The sub-group +irrelevant except to determine the letter group (unless the +\field{group} field has been defined). The sub-group heading is displayed by some styles, such as the -\glostyle{indexgroup} style. For example, with: +\glostyle{indexgroup} and \glostyle{bookindex} styles. For example, with: \begin{codeenv} \gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} \end{codeenv} @@ -3047,7 +3066,7 @@ information. \label{sec:parent} An entry may be assigned a parent with the \field{parent} key. The -value must be the label of a entry that's already defined. You can +value must be the label of an entry that's already defined. You can test if an entry has the \field{parent} field set with: \nosecformatdef{ifglshasparent} If the \field{name} key is omitted, the value is assumed to be the same as @@ -3436,7 +3455,7 @@ suppress the hyperlinks. Although \gls{printunsrtglossaries} skips \idxpl{ignoredglossary}, it's still possible to display an \idx{ignoredglossary} with \gls{printunsrtglossary} but you'll need to use the -\printglossopt{title} setting to override the default title. +\printglossopt{title} option to override the default title. \subsection{Redisplaying or Filtering a Glossary} \label{sec:printglossagain} @@ -4012,7 +4031,7 @@ a level~1 entry (\code{quartz}) and a level~2 entry (\code{amethyst}). A reference to \gls{gls}\marg{mineral}. A reference to \gls{gls}\oarg{\printglossopt{prefix}={main.}}\marg{amethyst}. \strut -\cmd{renewcommand}\marg{\gls{GlsEntryCounterLabelPrefix}}\marg{main.glsentry-} +\cmd{renewcommand}\marg{\gls[noindex=false]{GlsEntryCounterLabelPrefix}}\marg{main.glsentry-} \gls{glsresetentrycounter} \gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{main.},\printglossopt{style}=tree} \cmd{end}\marg{document} @@ -4962,7 +4981,7 @@ It's best not to use these in entry definitions. Instead use the full command name. The main problem comes when the shortcuts aren't enabled until the start of the \envfmt{document} environment. For example, the \code{ngerman} language setting in -\sty{babel} makes the double quote character (\idx{doublequotechar}) +\sty{babel} makes the double quote character (\idx{doublequoteactivechar}) active and it becomes a shortcut for \gls{umlaut} (the umlaut accent command): \begin{codeenv} @@ -4994,7 +5013,7 @@ uses those entries must ensure that the appropriate shortcut commands are set up before use. Also, when using \bibgls, it recognises commands like \gls{umlaut} but not \sty{babel} shorthands, so the sorting will be adversely affected if you simply -use \idx{doublequotechar} instead of \gls{umlaut}. +use \idx{doublequoteactivechar} instead of \gls{umlaut}. For large files that are written once (with minor subsequent edits), but reused many times for multiple documents, it's better to use the @@ -5231,7 +5250,7 @@ be simplified to: \cmd{documentclass}\marg{scrartcl} \cmd{usepackage}\marg{mhchem} \cmd{usepackage}[ - \styopt{record},\comment{create \field{group} field} + \styopt{record},\comment{create \field{group} field and other stuff} \styopt[dot]{postpunc},\comment{full stop after description} \styopt{nostyles},\comment{don't load default style packages} \styopt[tree]{stylemods}\comment{load glossary-tree.sty and patch styles} diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib index 6aefd534d51..7acb27da90b 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib @@ -14,6 +14,20 @@ year = 2018 } +@misc{mfirstuc, + author = "Nicola Talbot", + title = "The \sty{mfirstuc} package", + note = {\url{https://ctan.org/pkg/mfirstuc}}, + year = 2017 +} + +@misc{textcase, + author = "David Carlisle", + title = "The \sty{textcase} package", + note = {\url{https://ctan.org/pkg/textcase}}, + year = 2004 +} + @misc{tracklang, author = "Nicola Talbot", title = "The \sty{tracklang} package", @@ -92,6 +106,13 @@ System Property}, year = 2018 } +@misc{javaoptions, + author={Oracle}, + title = {The JAVA\_TOOL\_OPTIONS Environment Variable}, + note={\url{https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/envvars002.html}}, + year = 2018 +} + @misc{gallery, author = {Nicola Talbot}, title = {{Dickimaw Books} Gallery}, @@ -106,6 +127,14 @@ System Property}, year = 2018 } +@misc{buildglossaries, + author = {Nicola Talbot}, + title = {Incorporating \idx{makeglossaries} or + \idx{makeglossaries-lite} or \bibgls\ into the document build}, + note = {\url{https://www.dickimaw-books.com/latex/buildglossaries}}, + year = 2018 +} + @inbook{iterationtips, author = "Nicola L. C. Talbot", title = "{\LaTeX} for Administrative Work", 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 6302e2da730..3b3a0b4129d 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 0696be2b875..a9a463f98a0 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -42,59 +42,70 @@ category={common} } +@abbreviation{CJK, + short = {CJK}, + long = {Chinese, Japanese, Korean languages}, + category={common} +} + +@abbreviation{encap, + short = {encap}, + long = {encapsulating command} +} + @dualindexentry{bibglsnewentry, name={\csfmt{bib\-gls\-new\-entry}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.entry}}, + description={defines terms provided with \atentry{entry}}, category={command} } @dualindexentry{bibglsnewsymbol, name={\csfmt{bib\-gls\-new\-symbol}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.symbol}}, + description={defines terms provided with \atentry{symbol}}, category={command} } @dualindexentry{bibglsnewnumber, name={\csfmt{bib\-gls\-new\-number}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.number}}, + description={defines terms provided with \atentry{number}}, category={command} } @dualindexentry{bibglsnewindex, name={\csfmt{bib\-gls\-new\-index}}, user1={\margm{label}\margm{options}}, - description={defines terms provided with \gls[noindex]{dual.entry.index}}, + description={defines terms provided with \atentry{index}}, category={command} } @dualindexentry{bibglsnewindexplural, name={\csfmt{bib\-gls\-new\-index\-plural}}, user1={\margm{label}\margm{options}\margm{name}}, - description={defines terms provided with \gls[noindex]{dual.entry.index}}, + description={defines terms provided with \atentry{index}}, category={command} } @dualindexentry{bibglsnewabbreviation, name={\csfmt{bib\-gls\-new\-abbreviation}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}}, - description={defines terms provided with \gls[noindex]{dual.entry.abbreviation}}, + description={defines terms provided with \atentry{abbreviation}}, category={command} } @dualindexentry{bibglsnewacronym, name={\csfmt{bib\-gls\-new\-acronym}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}}, - description={defines terms provided with \gls[noindex]{dual.entry.acronym}}, + description={defines terms provided with \atentry{acronym}}, category={command} } @dualindexentry{bibglsnewdualentry, name={\csfmt{bib\-gls\-new\-dual\-entry}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.dualentry}}, + description={defines terms provided with \atentry{dualentry}}, category={command} } @@ -102,7 +113,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-entry}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.dualindexentry}}, +\atentry{dualindexentry}}, category={command} } @@ -110,7 +121,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-entry\-secondary}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, description={defines secondary terms provided with -\gls[noindex]{dual.entry.dualindexentry}}, +\atentry{dualindexentry}}, category={command} } @@ -118,7 +129,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-symbol}}, user1={\margm{label}\margm{options}\margm{name}\margm{symbol}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.dualindexsymbol}}, +\atentry{dualindexsymbol}}, category={command} } @@ -126,7 +137,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-symbol\-secondary}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, description={defines secondary terms provided with -\gls[noindex]{dual.entry.dualindexsymbol}}, +\atentry{dualindexsymbol}}, category={command} } @@ -134,7 +145,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-number}}, user1={\margm{label}\margm{options}\margm{name}\margm{symbol}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.dualindexnumber}}, +\atentry{dualindexnumber}}, category={command} } @@ -142,7 +153,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-number\-secondary}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, description={defines secondary terms provided with -\gls[noindex]{dual.entry.dualindexnumber}}, +\atentry{dualindexnumber}}, category={command} } @@ -150,7 +161,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-abbre\-via\-tion}}, user1={\margm{label}\margm{dual-label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.dualindexabbreviation}}, +\atentry{dualindexabbreviation}}, category={command} } @@ -158,7 +169,7 @@ name={\csfmt{bib\-gls\-new\-dual\-index\-abbre\-via\-tion\-sec\-ond\-ary}}, user1={\margm{label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, description={defines secondary terms provided with -\gls[noindex]{dual.entry.dualindexabbreviation}}, +\atentry{dualindexabbreviation}}, category={command} } @@ -166,7 +177,7 @@ name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion\-entry}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.dualabbreviationentry}}, +\atentry{dualabbreviationentry}}, category={command} } @@ -174,7 +185,7 @@ name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion\-entry\-sec\-ond\-ary}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, description={defines secondary terms provided with -\gls[noindex]{dual.entry.dualabbreviationentry}}, +\atentry{dualabbreviationentry}}, category={command} } @@ -182,7 +193,7 @@ name={\csfmt{bib\-gls\-new\-dual\-entry\-abbre\-via\-tion}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, description={defines primary terms provided with (deprecated) -\gls[noindex]{dual.entry.dualentryabbreviation}}, +\atentry{dualentryabbreviation}}, category={command} } @@ -190,21 +201,21 @@ name={\csfmt{bib\-gls\-new\-dual\-entry\-abbre\-via\-tion\-sec\-ond\-ary}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}\margm{description}}, description={defines secondary terms provided with (deprecated) -\gls[noindex]{dual.entry.dualentryabbreviation}}, +\atentry{dualentryabbreviation}}, category={command} } @dualindexentry{bibglsnewdualsymbol, name={\csfmt{bib\-gls\-new\-dual\-symbol}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.dualsymbol}}, + description={defines terms provided with \atentry{dualsymbol}}, category={command} } @dualindexentry{bibglsnewdualnumber, name={\csfmt{bib\-gls\-new\-dual\-number}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.dualnumber}}, + description={defines terms provided with \atentry{dualnumber}}, category={command} } @@ -212,14 +223,14 @@ name={\csfmt{bib\-gls\-new\-dual\-abbre\-via\-tion}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}}, description={defines terms provided with -\gls[noindex]{dual.entry.dualabbreviation}}, +\atentry{dualabbreviation}}, category={command} } @dualindexentry{bibglsnewdualacronym, name={\csfmt{bib\-gls\-new\-dual\-acronym}}, user1={\margm{label}\margm{options}\margm{short}\margm{long}}, - description={defines terms provided with \gls[noindex]{dual.entry.dualacronym}}, + description={defines terms provided with \atentry{dualacronym}}, category={command} } @@ -227,7 +238,7 @@ name={\csfmt{bib\-gls\-new\-tert\-iary\-index\-abbre\-via\-tion\-entry}}, user1={\margm{label}\margm{dual-label}\margm{options}\margm{name}\margm{short}\margm{long}\margm{description}}, description={defines primary terms provided with -\gls[noindex]{dual.entry.tertiaryindexabbreviationentry}}, +\atentry{tertiaryindexabbreviationentry}}, category={command} } @@ -235,14 +246,14 @@ name={\csfmt{bib\-gls\-new\-tert\-iary\-index\-abbre\-via\-tion\-entry\-sec\-ond\-ary}}, user1={\margm{label}\margm{tertiary-label}\margm{options}\margm{tertiary-opts}\margm{primary-name}\margm{short}\margm{long}\margm{description}}, description={defines secondary and tertiary terms provided with -\gls[noindex]{dual.entry.tertiaryindexabbreviationentry}}, +\atentry{tertiaryindexabbreviationentry}}, category={command} } @dualindexentry{bibglsnewbibtexentry, name={\csfmt{bib\-gls\-new\-bib\-tex\-entry}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, - description={defines terms provided with \gls[noindex]{dual.entry.bibtexentry}}, + description={defines terms provided with \atentry{bibtexentry}}, category={command} } @@ -250,7 +261,7 @@ name={\csfmt{bib\-gls\-new\-con\-trib\-u\-tor}}, user1={\margm{label}\margm{options}\margm{name}\margm{description}}, description={defines terms provided with - \gls[noindex]{dual.entry.contributor}}, + \atentry{contributor}}, category={command} } @@ -267,7 +278,20 @@ user1={\margm{text}\margm{category}}, description={applies the formatting command used for the long form for the abbreviation style associated with the given category}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, + category={command} +} + +@index{GlsXtrAutoAddOnFormat, + name={\csfmt{GlsXtrAutoAddOnFormat}}, + user1={\oargm{label}\margm{format list}\margm{glsadd options}}, + description={makes commands like \cs{gls} and \cs{glslink} + (but not \cs{glsadd}) automatically insert \cs{glsadd}\oargm{glsadd + options}\margm{label} if the format (supplied in the optional + argument of the invoking \cs{gls}, \cs{glslink} etc) matches any in the given + comma-separated elements of \meta{format list}. The format isn't automatically + applied to the \cs{glsadd} options}, + note={\styfmt{glossaries-extra} v1.37+}, category={command} } @@ -284,7 +308,7 @@ user1={\margm{text}\margm{category}}, description={applies the formatting command used for the short form for the abbreviation style associated with the given category}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -363,7 +387,7 @@ @dualindexentry{bibglsrange, name={\csfmt{bib\-gls\-range}}, - user1={\marg{\meta{start}\gls{delimR} \meta{end}}}, + user1={\marg{\meta{start}\cs{delimR} \meta{end}}}, description={Explicit range format}, category={command} } @@ -389,6 +413,14 @@ category={command} } +@dualindexentry{bibglsprimary, + name={\csfmt{bib\-gls\-primary}}, + user1={\margm{n}\margm{locations}}, + description={location list encapsulator used in the +\field{primarylocations} field}, + category={command} +} + @dualindexentry{bibglspagename, name={\csfmt{bib\-gls\-page\-name}}, user1={}, @@ -465,13 +497,13 @@ user1={\margm{label}}, description={formats the heading for the group identified by the given label}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @dualindexentry{bibglssetlastgrouptitle, name={\csfmt{bib\-gls\-set\-last\-group\-title}}, - user1={\margm{cs}\margm{group specs}}, + user1={\margm{cs}\margm{specs}}, description={sets the last group title}, category={command} } @@ -487,7 +519,7 @@ given label}, name={\csfmt{gls\-xtr\-set\-group\-title}}, user1={\margm{group label}\margm{group title}}, description={globally sets the title for the group identified by the given label}, - note={provided by \styfmt{glossaries-extra} version 1.14+}, + note={\styfmt{glossaries-extra} v1.14+}, category={command} } @@ -495,7 +527,7 @@ given label}, name={\csfmt{gls\-xtr\-local\-set\-group\-title}}, user1={\margm{group label}\margm{group title}}, description={locally sets the title for the group identified by the given label}, - note={provided by \styfmt{glossaries-extra} version 1.24+}, + note={\styfmt{glossaries-extra} v1.24+}, category={command} } @@ -600,6 +632,13 @@ character code}, category={command} } +@dualindexentry{bibglssetdatetimegrouptitle, + name={\csfmt{bib\-gls\-set\-date\-time\-group\-title}}, + user1={\marg{\margm{YYYY}\margm{MM}\margm{DD}\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the date-time group title}, + category={command} +} + @dualindexentry{bibglsdatetimegroup, name={\csfmt{bib\-gls\-date\-time\-group}}, user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, @@ -614,6 +653,13 @@ character code}, category={command} } +@dualindexentry{bibglssetdategrouptitle, + name={\csfmt{bib\-gls\-set\-date\-group\-title}}, + user1={\marg{\margm{YYYY}\margm{MM}\margm{DD}\margm{G}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the date (no time) group title}, + category={command} +} + @dualindexentry{bibglsdategroup, name={\csfmt{bib\-gls\-date\-group}}, user1={\margm{YYYY}\margm{MM}\margm{DD}\margm{G}\margm{title}\margm{group\dhyphen id}\margm{type}}, @@ -628,6 +674,13 @@ character code}, category={command} } +@dualindexentry{bibglssettimegrouptitle, + name={\csfmt{bib\-gls\-set\-time\-group\-title}}, + user1={\marg{\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}}, + description={sets the time (no date) group title}, + category={command} +} + @dualindexentry{bibglstimegroup, name={\csfmt{bib\-gls\-time\-group}}, user1={\margm{hh}\margm{mm}\margm{ss}\margm{zone}\margm{title}\margm{group\dhyphen id}\margm{type}}, @@ -688,24 +741,28 @@ name}, @dualindexentry{bibglssetwidesttoplevelfallback, name={\csfmt{bib\-gls\-set\-widest\-top\-level\-fallback}}, user1={\margm{glossary list}}, - description={fallback used instead of \gls{bibglssetwidest} + description={fallback used instead of \csref{bibglssetwidest} in the event that \bibgls\ can't determine the widest name - where there are only top level entries}, + where there are only top level entries, + where \meta{glossary list} is a comma-separated list + of glossary labels}, category={command} } @dualindexentry{bibglssetwidestfallback, name={\csfmt{bib\-gls\-set\-widest\-fallback}}, user1={\margm{glossary list}}, - description={fallback used instead of \gls{bibglssetwidest} - in the event that \bibgls\ can't determine the widest name}, + description={fallback used instead of \csref{bibglssetwidest} + in the event that \bibgls\ can't determine the widest name, + where \meta{glossary list} is a comma-separated list + of glossary labels}, category={command} } @dualindexentry{bibglssetwidestfortypefallback, name={\csfmt{bib\-gls\-set\-widest\-for\-type\-fallback}}, user1={\margm{type}}, - description={fallback used instead of \gls{bibglssetwidestfortype} + description={fallback used instead of \csref{bibglssetwidestfortype} in the event that \bibgls\ can't determine the widest name}, category={command} } @@ -713,7 +770,7 @@ name}, @dualindexentry{bibglssetwidesttoplevelfortypefallback, name={\csfmt{bib\-gls\-set\-widest\-top\-level\-for\-type\-fallback}}, user1={\margm{type}}, - description={fallback used instead of \gls{bibglssetwidestfortype} + description={fallback used instead of \csref{bibglssetwidestfortype} in the event that \bibgls\ can't determine the widest name where there are only top-level entries}, category={command} @@ -738,29 +795,29 @@ name}, @dualindexentry{bibglsdate, name={\csfmt{bib\-gls\-date}}, - user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\marg{original}}, + user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\margm{original}}, description={used to markup a date converted from a field value}, category={command} } @dualindexentry{bibglsdatetime, name={\csfmt{bib\-gls\-date\-time}}, - user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\marg{original}}, + user1={\margm{year}\margm{month}\margm{day-of-month}\margm{day-of-week}\margm{day-of-year}\margm{era}\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, description={used to markup a date-time instance converted from a field value}, category={command} } @dualindexentry{bibglsdatetimeremainder, name={\csfmt{bib\-gls\-date\-time\-remainder}}, - user1={\margm{millisec}\margm{dst}\margm{zone}\marg{original}}, + user1={\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, description={used internally to pick up the final four arguments of - \gls{bibglsdatetime}}, + \csref{bibglsdatetime}}, category={command} } @dualindexentry{bibglstime, name={\csfmt{bib\-gls\-time}}, - user1={\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\marg{original}}, + user1={\margm{hour}\margm{minute}\margm{second}\margm{millisec}\margm{dst}\margm{zone}\margm{original}}, description={used to markup a time converted from a field value}, category={command} } @@ -800,11 +857,86 @@ name}, category={command} } +@dualindexentry{bibglshrefchar, + name={\csfmt{bib\-gls\-href\-char}}, + user1={\margm{hex}\margm{char}}, + description={expands to a literal percent character followed by +\meta{hex}}, + category={command} +} + +@dualindexentry{bibglshrefunicode, + name={\csfmt{bib\-gls\-href\-unicode}}, + user1={\margm{hex}\margm{char}}, + description={expands to \meta{char} by default}, + category={command} +} + +@dualindexentry{bibglsprimaryprefixlabel, + name={\csfmt{bib\-gls\-primary\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the primary prefix, if + required}, + category={command} +} + +@dualindexentry{bibglsdualprefixlabel, + name={\csfmt{bib\-gls\-dual\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the dual prefix, if + required}, + category={command} +} + +@dualindexentry{bibglstertiaryprefixlabel, + name={\csfmt{bib\-gls\-tertiary\-prefix\-label}}, + user1={\margm{prefix}}, + description={hook provided to pick up the tertiary prefix, if + required}, + category={command} +} + +@dualindexentry{bibglsexternalprefixlabel, + name={\csfmt{bib\-gls\-external\-prefix\-label}}, + user1={\margm{n}\margm{prefix}}, + description={hook provided to pick up the \meta{n}th external prefix, if + required}, + category={command} +} + +@dualindexentry{bibglsuppercase, + name={\csfmt{bib\-gls\-upper\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{uppercase}}, + category={command} +} + +@dualindexentry{bibglslowercase, + name={\csfmt{bib\-gls\-lower\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{lowercase}}, + category={command} +} + +@dualindexentry{bibglstitlecase, + name={\csfmt{bib\-gls\-title\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{titlecase}}, + category={command} +} + +@dualindexentry{bibglsfirstuc, + name={\csfmt{bib\-gls\-first\-uc}}, + user1={\margm{text}}, + description={converts the first letter of \meta{text} to \idx{uppercase}}, + category={command} +} + @dualindexentry{glsexpandfields, name={\csfmt{gls\-expand\-fields}}, user1={}, description={switches on field expansion}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -812,7 +944,7 @@ name}, name={\csfmt{gls\-no\-expand\-fields}}, user1={}, description={switches off field expansion}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -820,7 +952,7 @@ name}, name={\csfmt{gls\-set\-expand\-field}}, user1={\margm{field}}, description={switches on field expansion for the given field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -828,7 +960,7 @@ name}, name={\csfmt{gls\-set\-no\-expand\-field}}, user1={\margm{field}}, description={switches off field expansion for the given field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -836,7 +968,7 @@ name}, name={\csfmt{new\-glossary\-entry}}, user1={\margm{label}\margm{\keyvallist}}, description={defines a new glossary entry}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -844,9 +976,9 @@ name}, name={\csfmt{long\-new\-glossary\-entry}}, user1={\margm{label}\margm{\keyvallist}\margm{description}}, description={defines a new glossary entry and appends - \csfmt{leavemode}\csfmt{unskip}\gls{nopostdesc} at the end of + \csfmt{leavemode}\csfmt{unskip}\cs{nopostdesc} at the end of \meta{description}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -855,7 +987,7 @@ name}, user1={\margm{label}\margm{\keyvallist}\margm{description}}, description={defines a new glossary entry without appending any extra code to the end of \meta{description}}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -864,7 +996,7 @@ extra code to the end of \meta{description}}, user1={\margm{label}\margm{\keyvallist}}, description={defines a new glossary entry if one doesn't already exist with the given label}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -873,7 +1005,7 @@ extra code to the end of \meta{description}}, user1={\margm{label}\margm{\keyvallist}\margm{description}}, description={defines a new glossary entry if one doesn't already exist with the given label}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -882,25 +1014,27 @@ extra code to the end of \meta{description}}, user1={\oargm{\keyvallist}\margm{label}}, description={defines a new glossary entry where the \field{description} field defaults to empty}, - note={provided by the \styfmt{glossaries}'s \styopt{index} package + note={the \styfmt{glossaries}'s \styopt{index} package option}, category={command} } @dualindexentry{newabbreviation, - name={\csfmt{new\-abbreviation}}, + name={\csfmt{new\-abbre\-vi\-a\-tion}}, user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}}, description={defines a new abbreviation}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @dualindexentry{newacronym, name={\csfmt{new\-acronym}}, user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}}, - description={defines a new abbreviation with the - \field{category} set to \code{acronym}}, - note={provided by \styfmt{glossaries}}, + description={defines a new abbreviation. The + \styfmt{glossaries-extra} package redefines this to use + \csref{newabbreviation} with the \field{category} set to + \code{acronym}}, + note={\styfmt{glossaries}}, category={command} } @@ -908,8 +1042,7 @@ option}, name={\csfmt{gls\-xtr\-new\-symbol}}, user1={\oargm{\keyvallist}\margm{label}\margm{symbol}}, description={defines a new symbol}, - note={provided by \styfmt{glossaries-extra}'s \styopt{symbols} -package option}, + note={\styfmt{glossaries-extra} \styopt{symbols}}, category={command} } @@ -917,8 +1050,7 @@ package option}, name={\csfmt{gls\-xtr\-new\-number}}, user1={\oargm{\keyvallist}\margm{label}}, description={defines a new number}, - note={provided by \styfmt{glossaries-extra}'s \styopt{numbers} -package option}, + note={\styfmt{glossaries-extra} \styopt{numbers}}, category={command} } @@ -932,9 +1064,9 @@ package option}, @dualindexentry{@gls@hypergroup, name={\csfmt{@gls@hypergroup}}, user1={\margm{type}\margm{group id}}, - description={identifies that the given group was used in the + description={command written to the \ext{aux} file that identifies that the given group was used in the glossary on the previous run}, - note={internal command provided by \styfmt{glossary-hypernav}}, + note={\styfmt{glossary-hypernav}}, category={command} } @@ -942,9 +1074,9 @@ package option}, name={\csfmt{glsxtr@resource}}, user1={\margm{options}\margm{filename}}, description={this internal command is written to the \ext{aux} -file by \gls{glsxtrresourcefile} +file by \csref{glsxtrresourcefile} to provide \bibgls\ with the resource information}, - note={internal command provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.08+}, category={command} } @@ -953,8 +1085,7 @@ file by \gls{glsxtrresourcefile} user1={\margm{n}\margm{page}}, description={This command simply expands to \meta{n}, the value of the \counter{wrglossary} counter for the given page}, - note={internal command provided by - \styfmt{glossaries-extra-bib2gls} v1.29+}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, category={command} } @@ -963,8 +1094,7 @@ the \counter{wrglossary} counter for the given page}, user1={\margm{text}\margm{label}}, description={Creates a hyperlink to the \counter{wrglossary} location obtained from the \field{indexcounter} field}, - note={internal command provided by - \styfmt{glossaries-extra-bib2gls} v1.29+}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, category={command} } @@ -972,9 +1102,8 @@ location obtained from the \field{indexcounter} field}, name={\csfmt{Gls\-Xtr\-Dual\-Back\-Link}}, user1={\margm{text}\margm{label}}, description={Creates a hyperlink to the dual entry whose label is - obtained from the field given by \gls{GlsXtrDualField}}, - note={internal command provided by - \styfmt{glossaries-extra-bib2gls} v1.30+}, + obtained from the field given by \csref{GlsXtrDualField}}, + note={\styfmt{glossaries-extra-bib2gls} v1.30+}, category={command} } @@ -982,10 +1111,9 @@ location obtained from the \field{indexcounter} field}, name={\csfmt{Gls\-Xtr\-Dual\-Field}}, user1={}, description={The field used to store the dual label. This defaults - to \gls{field.dual} but will need to be redefined if a different + to \field{dual} but will need to be redefined if a different value is given by \csopt{dual-field}}, - note={internal command provided by - \styfmt{glossaries-extra-bib2gls} v1.30+}, + note={\styfmt{glossaries-extra-bib2gls} v1.30+}, category={command} } @@ -995,37 +1123,37 @@ location obtained from the \field{indexcounter} field}, description={formats the given text according to the formatting command identified by the value of the field obtained from \cs{GlsXtrFmtField}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @dualindexentry{glsxtrfmt*, name={\csfmt{gls\-xtr\-fmt*}}, user1={\oargm{options}\margm{label}\margm{text}\oargm{insert}}, - description={like \cs{glsxtrfmt} but inserts extra + description={like \csref{glsxtrfmt} but inserts extra material into the link text but outside of the formatting command}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.23+}, category={command} } @dualindexentry{glsxtrentryfmt, name={\csfmt{gls\-xtr\-entry\-fmt}}, user1={\margm{label}\margm{text}}, - description={alternative to \cs{glsxtrfmt} for use in + description={alternative to \csref{glsxtrfmt} for use in section headings}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @index{glsxtrfmtdisplay, name={\csfmt{gls\-xtr\-fmt\-display}}, - user1={\margm{cs-name}\margm{text}\oargm{insert}}, - description={used by \cs{glsxtrfmt} to format the given + user1={\margm{cs-name}\margm{text}\margm{insert}}, + description={used by \csref{glsxtrfmt} to format the given \meta{text} where \meta{cs-name} is obtained from the field identified by \cs{GlsXtrFmtField} and \meta{insert} is empty for the -unstarred \gls{glsxtrfmt} and the final optional argument of the -starred version \gls{glsxtrfmt*}}, - note={provided by \styfmt{glossaries-extra}}, +unstarred \csref{glsxtrfmt} and the final optional argument of the +starred version \csref{glsxtrfmt*}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -1034,11 +1162,12 @@ starred version \gls{glsxtrfmt*}}, user1={\oargm{options}\margm{filename}}, description={input the \ext{glstex} file created by \bibgls\ and write resource instructions to the \ext{aux} file}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.08+}, seealso={resourceoptions,GlsXtrLoadResources}, category={command} } + @index{resourceoptions, name={resource options}, text={resource option} @@ -1163,6 +1292,13 @@ starred version \gls{glsxtrfmt*}}, parent={resourceoptions} } +@dualindexentry{opt.dependency-fields, + name={\csoptfmt{dependency\dhyphen fields}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.labelify-replace, name={\csoptfmt{labelify\dhyphen replace}}, user1={\meta{list}}, @@ -1479,6 +1615,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.long-case-change, + name={\csoptfmt{long\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.name-case-change, name={\csoptfmt{name\dhyphen case\dhyphen change}}, user1={\meta{value}}, @@ -1493,6 +1636,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.word-boundaries, + name={\csoptfmt{word\dhyphen boundaries}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.post-description-dot, name={\csoptfmt{post\dhyphen description\dhyphen dot}}, user1={\meta{value}}, @@ -1502,7 +1652,7 @@ field\dhyphen locale}}, @dualindexentry{opt.strip-trailing-nopost, name={\csoptfmt{strip\dhyphen trailing\dhyphen nopost}}, - user1={\meta{value}}, + user1={\meta{boolean}}, category={resourceoption}, parent={resourceoptions} } @@ -1514,6 +1664,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.sort-label-list, + name={\csoptfmt{sort\dhyphen label\dhyphen list}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.group, name={\csoptfmt{group}}, user1={\meta{label}}, @@ -1577,6 +1734,20 @@ field\dhyphen locale}}, parent={resourceoptions} } +@dualindexentry{opt.save-primary-locations, + name={\csoptfmt{save\dhyphen primary\dhyphen locations}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + +@dualindexentry{opt.primary-location-formats, + name={\csoptfmt{primary\dhyphen location\dhyphen formats}}, + user1={\meta{list}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.min-loc-range, name={\csoptfmt{min\dhyphen loc\dhyphen range}}, user1={\meta{value}}, @@ -2031,6 +2202,13 @@ format}}, parent={resourceoptions} } +@dualindexentry{opt.dual-long-case-change, + name={\csoptfmt{dual\dhyphen long\dhyphen case\dhyphen change}}, + user1={\meta{value}}, + category={resourceoption}, + parent={resourceoptions} +} + @dualindexentry{opt.dual-field, name={\csoptfmt{dual\dhyphen field}}, user1={\meta{value}}, @@ -2350,8 +2528,8 @@ pattern}}, @dualindexentry{GlsXtrLoadResources, name={\csfmt{Gls\-Xtr\-Load\-Resources}}, user1={\oargm{options}}, - description={a shortcut command that uses \gls[noindex]{glsxtrresourcefile}}, - note={provided by \styfmt{glossaries-extra}}, + description={a shortcut command that uses \csref{glsxtrresourcefile}}, + note={\styfmt{glossaries-extra} v1.11+}, seealso={resourceoptions,glsxtrresourcefile}, category={command} } @@ -2361,7 +2539,7 @@ pattern}}, user1={\margm{label}\margm{type}}, description={copies the entry given by \meta{label} to the glossary given by \meta{type}}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -2372,7 +2550,7 @@ cs}\margm{glspl-like cs}\margm{Gls-like cs}\margm{Glspl-like cs}}, description={defines commands to behave like \ics{gls}, \ics{glspl}, \ics{Gls} and \ics{Glspl} with the given label prefix}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, seealso={glsxtrnewgls}, category={command} } @@ -2382,7 +2560,7 @@ cs}\margm{Glspl-like cs}}, user1={\oargm{options}\margm{prefix}\margm{cs}}, description={defines the command \meta{cs} to behave like \ics{gls} with the given label prefix}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, seealso={gls}, category={command} } @@ -2390,9 +2568,18 @@ cs}\margm{Glspl-like cs}}, @dualindexentry{glsnoidxdisplayloc, name={\csfmt{gls\-no\-idx\-display\-loc}}, user1={\margm{prefix}\margm{counter}\margm{format}\margm{location}}, - description={handler used to display the number list stored in - the \field{loclist} field}, - note={provided by \styfmt{glossaries}}, + description={used to display a regular location in the + \field{location} field}, + note={\styfmt{glossaries} v4.04+}, + category={command} +} + +@dualindexentry{glsxtrdisplaylocnameref, + name={\csfmt{gls\-xtr\-display\-loc\-name\-ref}}, + user1={\margm{prefix}\margm{counter}\margm{format}\margm{location}\margm{title}\margm{href}\margm{hcounter}\margm{file}}, + description={used to display a \code{nameref} location in the + \field{location} field}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, category={command} } @@ -2401,16 +2588,50 @@ cs}\margm{Glspl-like cs}}, user1={\margm{prefix}\margm{counter}\margm{format}\margm{src}\margm{location}}, description={used to display an external location in the supplementary list}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.36+}, + note={\styfmt{glossaries-extra-bib2gls} v1.36+}, category={command} } @dualindexentry{glsxtrmultisupplocation, name={\csfmt{gls\-xtr\-multi\-supp\-location}}, user1={\margm{location}\margm{src}\margm{format}}, - description={used by \gls{glsxtrdisplaysupploc} to format the + description={used by \csref{glsxtrdisplaysupploc} to format the external location}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.36+}, + note={\styfmt{glossaries-extra-bib2gls} v1.36+}, + category={command} +} + +@index{glsxtrsupplocationurl, + name={\csfmt{gls\-xtr\-supp\-loc\-a\-tion\-url}}, + description={set by \cs{glsxtrsupphypernumber} + and \csref{glsxtrmultisupplocation} to the + URL of the supplemental document for use by + \cs{glshypernumber}}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glshypernumber,glsxtrsupphypernumber,glsxtrmultisupplocation,glsxtrlocationhyperlink}, + category={command} +} + +@index{glsxtrlocationhyperlink, + name={\csfmt{gls\-xtr\-loc\-a\-tion\-hyper\-link}}, + user1={\margm{counter}\margm{prefix}\margm{location}}, + description={used to create the location hyperlink, + this tests if an internal or external link is required + depending on the definition of \cs{glsxtrsupplocationurl}}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glsxtrsupphypernumber,glsxtrsupplocationurl}, + category={command} +} + +@index{glsxtrsupphypernumber, + name={\csfmt{gls\-xtr\-supp\-hyper\-num\-ber}}, + user1={\margm{location}}, + description={uses \cs{glshypernumber} to create a hyperlink + to the given location (if hyperlinks are supported) but + first checks the \catattr{externallocation} attribute to determine + if an external link is required}, + note={\styfmt{glossaries-extra} v1.14+}, + seealso={glsxtrlocationhyperlink,glsxtrsupplocationurl}, category={command} } @@ -2419,7 +2640,16 @@ cs}\margm{Glspl-like cs}}, user1={\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location}}, description={this command is written to the \ext{aux} file each time an entry is indexed to provide \bibgls\ with the record information}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries-extra} v1.08+}, + category={command} +} + +@dualindexentry{glsxtr@record@nameref, + name={\csfmt{glsxtr@record@name\-ref}}, + user1={\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location}\margm{title}\margm{href}\margm{hcounter}}, + description={used instead of \csref{glsxtr@record} when the + \styopt[nameref]{record} option is used}, + note={\styfmt{glossaries-extra} v1.37+}, category={command} } @@ -2428,7 +2658,7 @@ cs}\margm{Glspl-like cs}}, user1={\margm{label}\margm{field}\margm{item}}, description={adds the given item to the given field that contains an \styfmt{etoolbox} internal list}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, seealso={glsxtrfieldifinlist,glsxtrfieldforlistloop,glsxtrfielddolistloop}, category={command} } @@ -2438,7 +2668,7 @@ cs}\margm{Glspl-like cs}}, user1={\margm{label}\margm{field}\margm{item}\margm{true}\margm{false}}, description={tests if the given item is in the given field that contains an \styfmt{etoolbox} internal list}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, seealso={glsxtrfieldxifinlist,glsxtrfieldlistadd,glsxtrfieldforlistloop,glsxtrfielddolistloop}, category={command} } @@ -2448,16 +2678,210 @@ cs}\margm{Glspl-like cs}}, user1={\margm{label}\margm{field}\margm{item}\margm{true}\margm{false}}, description={tests if the expansion of the given item is in the given field that contains an \styfmt{etoolbox} internal list}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, seealso={glsxtrfieldifinlist}, category={command} } +@index{glsxtrcontrolrules, + name={\csfmt{gls\-xtr\-control\-rules}}, + user1={}, + description={collation sub-rule for control characters usually +placed at the start of a rule in the \qt{ignored characters} section +(although there typically won't be any control codes in sort fields)}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrspacerules, + name={\csfmt{gls\-xtr\-space\-rules}}, + user1={}, + description={collation sub-rule for space characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrnonprintablerules, + name={\csfmt{gls\-xtr\-non\-printable\-rules}}, + user1={}, + description={collation sub-rule for non-printable characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrcombiningdiacriticrules, + name={\csfmt{gls\-xtr\-combining\-diacritic\-rules}}, + user1={}, + description={collation sub-rule for combining diacritic characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrhyphenrules, + name={\csfmt{gls\-xtr\-hyphen\-rules}}, + user1={}, + description={collation sub-rule for hyphen characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrgeneralpuncrules, + name={\csfmt{gls\-xtr\-general\-punc\-rules}}, + user1={}, + description={collation sub-rule for general punctuation characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrdigitrules, + name={\csfmt{gls\-xtr\-digit\-rules}}, + user1={}, + description={collation sub-rule for digits from the basic Latin +set (0, \ldots, 9) as well as their subscript and superscript variants}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrfractionrules, + name={\csfmt{gls\-xtr\-fraction\-rules}}, + user1={}, + description={collation sub-rule for vulgar fraction characters}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrMathItalicGreekIrules, + name={\csfmt{gls\-xtr\-Math\-Italic\-Greek\-I\-rules}}, + user1={}, + description={collation sub-rule for math-Greek characters +(includes upright digamma between epsilon and zeta)}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-I\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(basic Latin set plus subscript and superscript Latin +characters)}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + seealso={glsxtrGeneralLatinIIrules,glsxtrGeneralLatinIIIrules,glsxtrGeneralLatinIVrules,glsxtrGeneralLatinVrules,glsxtrGeneralLatinVIrules,glsxtrGeneralLatinVIIrules,glsxtrGeneralLatinVIIIrules}, + category={command} +} + +@index{glsxtrGeneralLatinIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-II\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \ss\ treated as \qt{ss})}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinIIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-III\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \ss\ treated as \qt{sz})}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinIVrules, + name={\csfmt{gls\-xtr\-General\-Latin\-IV\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \AE/\ae\ treated as AE/ae, \OE/\oe\ treated +as OE/oe, \TH/\th\ treated as TH/th and \ss\ treated as \qt{ss})}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinVrules, + name={\csfmt{gls\-xtr\-General\-Latin\-V\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \TH/\th\ treated as TH/th and \ss\ treated as \qt{ss})}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinVIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VI\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \DH/\dh\ between D/d +and E/e +and \TH/\th\ treated as TH/th and \ss\ treated as \qt{sz})}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinVIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VII\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \AE/\ae\ between A/a +and B/b, +\DH/\dh\ between D/d and E/e, \insularG/\insularg\ (insular G) as +G/g, \OE/\oe\ +between O/o and P/p, \longs\ (long S) +equivalent to S/s, \TH/\th\ between T/t and U/u and \char"01F7/\char"01BF\ +(wynn) as W/w}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrGeneralLatinVIIIrules, + name={\csfmt{gls\-xtr\-General\-Latin\-VIII\-rules}}, + user1={}, + description={collation sub-rule for Latin characters +(as \cs{glsxtrGeneralLatinIrules} but includes \AE/\ae\ treated as +A/a, \OE/\oe\ treated as OE/oe, \TH/\th\ treated as TH/th, \ss\ +treated as \qt{ss}, \DH/\dh\ treated as D/d, \O/\o\ treated as O/o +and \L/\l\ treated as L/l}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrLatinAA, + name={\csfmt{gls\-xtr\-Latin\-AA}}, + user1={}, + description={collation sub-rule for \AA/\aa}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsxtrLatinOslash, + name={\csfmt{gls\-xtr\-Latin\-O\-slash}}, + user1={}, + description={collation sub-rule for \O/\o}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + @index{alpha, name={\csfmt{alpha}}, user1={}, description={Greek letter alpha $\alpha$}, - note={kernel command (maths mode only)}, + note={kernel command (maths mode)}, + category={command} +} + +@index{pi, + name={\csfmt{pi}}, + user1={}, + description={Greek letter pi $\pi$}, + note={kernel command (maths mode)}, category={command} } @@ -2465,7 +2889,7 @@ cs}\margm{Glspl-like cs}}, name={\csfmt{omicron}}, user1={}, description={Greek letter omicron $\omicron$}, - note={provided by \styfmt{glossaries-extra-bib2gls}}, + note={\styfmt{glossaries-extra-bib2gls}}, category={command} } @@ -2473,21 +2897,61 @@ cs}\margm{Glspl-like cs}}, name={\csfmt{Alpha}}, user1={}, description={Greek letter alpha $\Alpha$}, - note={provided by \styfmt{glossaries-extra-bib2gls}}, + note={\styfmt{glossaries-extra-bib2gls}}, + category={command} +} + +@index{approx, + name={\csfmt{approx}}, + user1={}, + description={approximate symbol $\approx$}, + note={kernel command (maths mode)}, + category={command} +} + +@index{surd, + name={\csfmt{surd}}, + user1={}, + description={surd symbol $\surd$}, + note={kernel command (maths mode)}, + category={command} +} + +@index{triangleright, + name={\csfmt{triangle\-right}}, + user1={}, + description={right-pointing triangle $\triangleright$}, + note={kernel command (maths mode)}, + category={command} +} + +@index{textstyle, + name={\csfmt{text\-style}}, + user1={}, + description={switch to in-line maths style (vertically compact)}, + note={kernel command (maths mode)}, category={command} } -@index{bigoperatornamefmt, - name={\csfmt{bigoperatornamefmt}}, +@index{displaystyle, + name={\csfmt{display\-style}}, + user1={}, + description={switch to display maths style}, + note={kernel command (maths mode)}, + category={command} +} + +@dualindexentry{bigoperatornamefmt, + name={\csfmt{big\-operator\-name\-fmt}}, user1={\margm{text}}, - description={custom command}, + description={example command}, category={command} } -@index{nary, +@dualindexentry{nary, name={\csfmt{nary}}, user1={\margm{text}}, - description={custom command}, + description={example command}, category={command} } @@ -2498,6 +2962,13 @@ cs}\margm{Glspl-like cs}}, category={command} } +@dualindexentry{parenswap, + name={\csfmt{parenswap}}, + user1={\margm{text1}\margm{text2}}, + description={example command}, + category={command} +} + @dualindexentry{sortop, name={\csfmt{sortop}}, user1={\margm{text1}\margm{text2}}, @@ -2608,73 +3079,79 @@ cs}\margm{Glspl-like cs}}, text={file format} } -@index{tex, +@index{ext.tex, name={\extfmt{tex}}, category={fileformat}, parent={fileformats} } -@index{bib, +@index{ext.bib, name={\extfmt{bib}}, category={fileformat}, parent={fileformats} } -@index{aux, +@index{ext.aux, name={\extfmt{aux}}, category={fileformat}, parent={fileformats} } -@index{out, +@index{ext.out, name={\extfmt{out}}, category={fileformat}, parent={fileformats} } -@index{sh, +@index{ext.sh, name={\extfmt{sh}}, category={fileformat}, parent={fileformats} } -@index{bat, +@index{ext.bat, name={\extfmt{bat}}, category={fileformat}, parent={fileformats} } -@index{jar, +@index{ext.jar, name={\extfmt{jar}}, category={fileformat}, parent={fileformats} } -@index{glg, +@index{ext.glg, name={\extfmt{glg}}, category={fileformat}, parent={fileformats} } -@index{log, +@index{ext.log, name={\extfmt{log}}, category={fileformat}, parent={fileformats} } -@index{toc, +@index{ext.toc, name={\extfmt{toc}}, category={fileformat}, parent={fileformats} } -@index{glstex, +@index{ext.glstex, name={\extfmt{glstex}}, category={fileformat}, parent={fileformats} } -@index{bbl, +@index{ext.gls, + name={\extfmt{gls}}, + category={fileformat}, + parent={fileformats} +} + +@index{ext.bbl, name={\extfmt{bbl}}, category={fileformat}, parent={fileformats} @@ -2698,7 +3175,7 @@ cs}\margm{Glspl-like cs}}, } @index{makeindex, - name={\appfmt{makeindex}}, + name={\appfmt{make\-index}}, category={application}, parent={applications} } @@ -2852,6 +3329,12 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{mfirstuc-english, + name={\styfmt{mfirstuc-english}}, + category={package}, + parent={packages} +} + @index{hyperref, name={\styfmt{hyperref}}, category={package}, @@ -2924,6 +3407,12 @@ cs}\margm{Glspl-like cs}}, parent={packages} } +@index{glossary-longextra, + name={\styfmt{glossary\dhyphen longextra}}, + category={package}, + parent={packages} +} + @index{booktabs, name={\styfmt{booktabs}}, category={package}, @@ -3089,7 +3578,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.hash, - name={\csfmt{\#}} + name={\csfmt{\#}}, + description={produces the hash symbol \#}, + note={kernel command}, + category={command} } @index{colsep, @@ -3103,7 +3595,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.amp, - name={\csfmt{\&}} + name={\csfmt{\&}}, + description={produces the ampersand symbol \&}, + note={kernel command}, + category={command} } @index{bgroupchar, @@ -3117,7 +3612,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.openbrace, - name={\csfmt{\{}} + name={\csfmt{\{}}, + description={produces the open brace symbol \{}, + note={kernel command}, + category={command} } @index{egroupchar, @@ -3131,7 +3629,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.closebrace, - name={\csfmt{\}}} + name={\csfmt{\}}}, + description={produces the close brace symbol \}}, + note={kernel command}, + category={command} } @index{commentchar, @@ -3145,7 +3646,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.percent, - name={\csfmt{\%}} + name={\csfmt{\%}}, + description={produces the percent symbol \%}, + note={kernel command}, + category={command} } @index{sbchar, @@ -3159,7 +3663,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.underscore, - name={\csfmt{\_}} + name={\csfmt{\_}}, + description={produces the underscore symbol \_}, + note={kernel command}, + category={command} } @index{spchar, @@ -3191,7 +3698,10 @@ cs}\margm{Glspl-like cs}}, } @index{cs.dollar, - name={\csfmt{\$}} + name={\csfmt{\$}}, + description={produces the dollar symbol \_}, + note={kernel command}, + category={command} } @index{escchar, @@ -3208,6 +3718,14 @@ cs}\margm{Glspl-like cs}}, name={\csfmt{\glsbackslash}} } +@index{tabularnewline, + name={\csfmt{tabular\-new\-line}}, + description={tabular version of \idx{cs.backslash} (avoids conflict +with forced line breaks in paragraph column formats)}, + note={kernel command}, + category={command} +} + @index{nbspchar, name={\code{\glstildechar} (non-breakable space)}, text={\code{\glstildechar}} @@ -3218,8 +3736,34 @@ cs}\margm{Glspl-like cs}}, text={\code{\glstildechar}} } +@index{doublequotechardelim, + name = {\code{"} (delimiter)}, + text = {\code{"}} +} + +@index{doublequotecharhex, + name = {\code{"} (hexadecimal identifier)}, + text = {\code{"}} +} + +@index{doublequoteactivechar, + name = {\code{"} (active)}, + text = {\code{"}} +} + @index{doublequotechar, - name = {\code{"}} + name = {\code{"} (literal)}, + text = {\code{"}} +} + +@index{openrange, + name = {\code{(} (start range)}, + text = {\code{(}} +} + +@index{closerange, + name = {\code{)} (end range)}, + text = {\code{)}} } @index{cs.tilde, @@ -3230,12 +3774,29 @@ cs}\margm{Glspl-like cs}}, category={command} } +@index{comma, + name={\csfmt{,}}, + description={thin space}, + note={kernel command}, + category={command} +} + +@index{vec, + name={\csfmt{vec}}, + user1={\margm{character}}, + description={puts right arrow accent over \meta{character}}, + note={kernel command (maths mode)}, + category={command} +} + @index{zeroormore, - name={\code{*} (regular expression, zero or more)} + name={\code{*} (regular expression, zero or more)}, + text={\code{*}} } @index{matchanydot, - name={\code{.}\ (regular expression, match any)} + name={\code{.}\ (regular expression, match any)}, + text={\code{.}} } @index{periodchar, @@ -3249,14 +3810,65 @@ cs}\margm{Glspl-like cs}}, } @index{cs.space, - name={\csfmt{\textvisiblespace}} + name={\csfmt{\textvisiblespace}}, + description={produces an inter-word space}, + note={kernel command}, + category={command} +} + +@index{space, + name={\csfmt{space}}, + description={produces a space}, + note={kernel command}, + category={command} +} + +@index{aposchar, + name={\code{'} (apostrophe)}, + text={\code{'}}, + alias={apostrophe} +} + +@index{def, + name={\csfmt{def}}, + user1={\margm{cs}\meta{syntax}\margm{definition}}, + description={defines the control sequence \meta{cs}, without checking if the command + already exists}, + note={\TeX\ primitive}, + category={command} +} + +@index{edef, + name={\csfmt{edef}}, + user1={\margm{cs}\meta{syntax}\margm{definition}}, + description={defines the control sequence \meta{cs} to the full +expansion of \meta{definition}, without checking if the command + already exists}, + note={\TeX\ primitive}, + category={command} +} + +@index{ifstrempty, + name={\csfmt{if\-str\-empty}}, + user1={\margm{string}\margm{true}\margm{false}}, + description={tests if \meta{string} is empty}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{ifstrequal, + name={\csfmt{if\-str\-equal}}, + user1={\margm{string1}\margm{string2}\margm{true}\margm{false}}, + description={tests if \meta{string1} equals \meta{string2}}, + note={\styfmt{etoolbox}}, + category={command} } @index{undef, name={\csfmt{undef}}, user1={\meta{cs}}, description={undefines the control sequence \meta{cs}}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3266,7 +3878,26 @@ cs}\margm{Glspl-like cs}}, description={defines the control sequence whose name is given by \meta{cs-name}, without checking if the command already exists}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{csuse, + name={\csfmt{csuse}}, + user1={\margm{cs-name}}, + description={uses the control sequence whose name + is given by \meta{cs-name} or does nothing if the command + isn't defined}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{newrobustcmd, + name={\csfmt{new\-robust\-cmd}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={behaves like \cs{newcommand} but the newly defined +command will be robust}, + note={\styfmt{etoolbox}}, category={command} } @@ -3274,7 +3905,7 @@ cs}\margm{Glspl-like cs}}, name={\csfmt{if\-def\-empty}}, user1={\margm{cs}\margm{true}\margm{false}}, description={tests if the control sequence \meta{cs} is empty}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3283,7 +3914,7 @@ cs}\margm{Glspl-like cs}}, user1={\margm{cs-name}\margm{true}\margm{false}}, description={tests if the control sequence given by \meta{cs-name} is undefined}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3292,7 +3923,15 @@ is undefined}, user1={\margm{cs-name}\margm{true}\margm{false}}, description={tests if the control sequence given by \meta{cs-name} is defined}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{ifdef, + name={\csfmt{if\-def}}, + user1={\margm{cs}\margm{true}\margm{false}}, + description={tests if the control sequence \meta{cs} is defined}, + note={\styfmt{etoolbox}}, category={command} } @@ -3301,7 +3940,7 @@ is defined}, user1={\margm{element}\margm{list cs}\margm{true}\margm{false}}, description={tests if the expansion of \meta{element} is in the list stored in the control sequence \meta{list cs}}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3310,7 +3949,7 @@ is defined}, user1={\margm{element}\margm{list cs}\margm{true}\margm{false}}, description={tests if \meta{element} is in the list stored in the control sequence \meta{list cs}}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3319,7 +3958,7 @@ is defined}, user1={\margm{list cs}\margm{element}}, description={globally adds (expanded) \meta{element} to the list stored in the control sequence \meta{list cs}}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, category={command} } @@ -3328,7 +3967,26 @@ is defined}, user1={\margm{list cs}\margm{element}}, description={globally adds \meta{element} to the list stored in the control sequence \meta{list cs}}, - note={provided by \styfmt{etoolbox}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{appto, + name={\csfmt{appto}}, + user1={\margm{cs}\margm{code}}, + description={appends \meta{code} to the definition of + the control sequence \meta{cs}}, + note={\styfmt{etoolbox}}, + category={command} +} + +@index{forlistloop, + name={\csfmt{for\-list\-loop}}, + user1={\margm{handler cs}\margm{list cs}}, + description={iterates over the internal list given by the command + \meta{list cs} and performs \meta{handler cs}\margm{element} for + each element}, + note={\styfmt{etoolbox}}, category={command} } @@ -3337,7 +3995,39 @@ is defined}, user1={\margm{language name}\margm{text}}, description={typesets \meta{text} according to the rules of the given language}, - note={provided by \styfmt{babel}}, + note={\styfmt{babel}}, + category={command} +} + +@index{selectlanguage, + name={\csfmt{select\-language}}, + user1={\margm{language name}}, + description={switch to the rules of the given language}, + note={\styfmt{babel} and \styfmt{polyglossia}}, + category={command} +} + +@index{setmainlanguage, + name={\csfmt{set\-main\-language}}, + user1={\oargm{options}\margm{language name}}, + description={load the main document language}, + note={\styfmt{polyglossia}}, + category={command} +} + +@index{setotherlanguage, + name={\csfmt{set\-other\-language}}, + user1={\oargm{options}\margm{language name}}, + description={load a secondary document language}, + note={\styfmt{polyglossia}}, + category={command} +} + +@index{textlanguage, + name={\csfmt{text\-\meta{language}}}, + user1={\oargm{options}\margm{text}}, + description={typeset \meta{text} according to \meta{language}}, + note={\styfmt{polyglossia}}, category={command} } @@ -3454,6 +4144,12 @@ given language}, parent={abbreviationstyles} } +@index{long-em-short-em, + name={\abbrstylefmt{long\dhyphen em\dhyphen short\dhyphen em}}, + category={abbreviationstyle}, + parent={abbreviationstyles} +} + @index{long-short-desc, name={\abbrstylefmt{long\dhyphen short\dhyphen desc}}, category={abbreviationstyle}, @@ -3798,6 +4494,11 @@ hyphen}}, category={counter} } +@index{ctr.chapter, + name={\counterfmt{chapter}}, + category={counter} +} + @index{ctr.wrglossary, name={\counterfmt{wrglossary}}, category={counter} @@ -3847,10 +4548,12 @@ hyphen}}, user1={\meta{value}}, description={unless the value is \styoptfmt{off}, this option sets up \styfmt{glossaries-extra} for use with \bibgls: \styoptfmt{only} - (assumed if no \meta{value} supplied, indexing performed by - \bibgls) and \styoptfmt{alsoindex} (\bibgls\ is used to provide + (assumed if no \meta{value} supplied) indexing is performed by + \bibgls; \styoptfmt{nameref} (\sty{glossaries-extra} v1.37+) + like \styoptfmt{only} but includes extra information in the records; + \styoptfmt{alsoindex} (hybrid method) \bibgls\ is used to provide the entry definitions but \idx{makeindex} or \idx{xindy} is used - for the indexing)}, + for the indexing}, package={glossaries-extra}, category={packageoption}, parent={packageoptions} @@ -3878,7 +4581,7 @@ hyphen}}, package={glossaries,glossaries-extra}, description={defines the \code{symbols} glossary; with \styfmt{glossaries-extra} additionally defines - \gls{glsxtrnewsymbol}}, + \csref{glsxtrnewsymbol}}, category={packageoption}, parent={packageoptions} } @@ -3888,7 +4591,7 @@ hyphen}}, package={glossaries,glossaries-extra}, description={defines the \code{numbers} glossary; with \styfmt{glossaries-extra} additionally defines - \gls{glsxtrnewnumber}}, + \csref{glsxtrnewnumber}}, category={packageoption}, parent={packageoptions} } @@ -3965,7 +4668,7 @@ hyphen}}, @dualindexentry{styopt.indexcounter, name={\styoptfmt{index\-counter}}, - description={creates the \gls{ctr.wrglossary} counter, which is + description={creates the \counter{wrglossary} counter, which is incremented every time an entry is indexed with that counter, and sets that as the default location counter}, package={glossaries-extra}, @@ -4005,7 +4708,7 @@ hyphen}}, @dualindexentry{styopt.stylemods, name={\styoptfmt{stylemods}}, user1={\meta{value}}, - description={load the \gls{glossaries-extra-stylemods} package with the + description={load the \sty{glossaries-extra-stylemods} package with the supplied options (which should be a list of suffix parts identifying glossary style packages \styfmt{glossary-}\meta{suffix}); there are two keyword values: \styoptfmt{default} @@ -4201,8 +4904,8 @@ hyphen}}, If no value is supplied then \styopt[section]{section} is assumed. If this option is omitted, then the default is either \styopt[chapter]{section} or \styopt[section]{section}, depending - on whether or not \gls{chapter} has been defined. The starred or - unstarred version is determined by \gls{styopt.numberedsection}} + on whether or not \cs{chapter} has been defined. The starred or + unstarred version is determined by \styopt{numberedsection}} } @dualindexentry{styopt.ucmark, @@ -4320,7 +5023,7 @@ hyphen}}, description={prevents all the default styles from being loaded. If this option is used a style must be defined in the document or a package providing a style needs to be loaded (either - through \gls{styopt.stylemods} or with \gls{usepackage})}, + through \styopt{stylemods} or with \ics{usepackage})}, category={packageoption}, parent={packageoptions} } @@ -4343,8 +5046,8 @@ hyphen}}, description={suppresses the location lists from being displayed in the glossary lists (the package option isn't boolean, but the option of the same name for - \gls{printglossary}, \gls{printunsrtglossary} and - \gls{printnoidxglossary} is boolean); with \bibgls\ you can use + \cs{printglossary}, \cs{printunsrtglossary} and + \cs{printnoidxglossary} is boolean); with \bibgls\ you can use \csopt[false]{save-locations} instead}, category={packageoption}, parent={packageoptions} @@ -4377,7 +5080,7 @@ hyphen}}, name={\styoptfmt{nogroupskip}}, user1={\meta{boolean}}, description={if true, suppresses the visual separation between - letter groups}, + letter groups in glossary styles that support this option}, package={glossaries}, category={packageoption}, parent={packageoptions} @@ -4501,9 +5204,9 @@ hyphen}}, \styopt[ac]{shortcuts}, \styopt[abbreviations]{shortcuts} and \styopt[other]{shortcuts}), \styoptfmt{acronyms}\extstyopt\ (equivalent to base \styopt[true]{shortcuts}, synonym - \styoptfmt{acro}), \styoptfmt{ac}\extstyopt\ (provides \gls{ac} + \styoptfmt{acro}), \styoptfmt{ac}\extstyopt\ (provides \cs{ac} shortcuts that use \styfmt{glossaries-extra}'s new abbreviation - commands), \styoptfmt{abbreviations}\extstyopt\ (provides \gls{ab} + commands), \styoptfmt{abbreviations}\extstyopt\ (provides \cs{ab} shortcuts), \styoptfmt{other}\extstyopt\ (provides other shortcut commands), \styoptfmt{all}\extstyopt\ (synonym for \styopt[true]{shortcuts}) and \styoptfmt{none}\extstyopt\ (synonym @@ -4515,7 +5218,7 @@ hyphen}}, @dualindexentry{styopt.index, name={\styoptfmt{index}}, package={glossaries}, - description={defines the \code{index} glossary and \gls{newterm}}, + description={defines the \code{index} glossary and \csref{newterm}}, category={packageoption}, parent={packageoptions} } @@ -4529,7 +5232,7 @@ hyphen}}, name={\fieldfmt{alias}}, description={The entry with this field set is a synonym of the entry whose label is given by this field.}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={extrafield}, parent={fields} } @@ -4537,7 +5240,7 @@ hyphen}}, @dualindexentry{field.category, name={\fieldfmt{category}}, description={The entry's category label.}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={extrafield}, parent={fields} } @@ -4545,7 +5248,7 @@ hyphen}}, @dualindexentry{field.description, name={\fieldfmt{description}}, description={The description displayed in the glossary.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4553,23 +5256,23 @@ hyphen}}, @dualindexentry{field.descriptionplural, name={\fieldfmt{descriptionplural}}, description={The plural form of the description.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @dualindexentry{field.first, name={\fieldfmt{first}}, - description={The text to display on first use of \gls{gls}\margm{label}.}, - note={provided by \styfmt{glossaries}}, + description={The text to display on first use with \cs{gls}\margm{label}.}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @dualindexentry{field.firstplural, name={\fieldfmt{firstplural}}, - description={The text to display on first use of \gls{glspl}\margm{label}.}, - note={provided by \styfmt{glossaries}}, + description={The text to display on first use with \cs{glspl}\margm{label}.}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4577,8 +5280,8 @@ hyphen}}, @dualindexentry{field.long, name={\fieldfmt{long}}, description={The long form of an abbreviation. (Set internally - by commands like \gls{newabbreviation}.)}, - note={provided by \styfmt{glossaries}}, + by commands like \csref{newabbreviation}.)}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4586,7 +5289,7 @@ hyphen}}, @dualindexentry{field.longplural, name={\fieldfmt{longplural}}, description={The plural long form of an abbreviation.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4594,7 +5297,7 @@ hyphen}}, @dualindexentry{field.name, name={\fieldfmt{name}}, description={The name displayed in the glossary.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4602,7 +5305,7 @@ hyphen}}, @dualindexentry{field.parent, name={\fieldfmt{parent}}, description={The parent entry's label.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4610,8 +5313,8 @@ hyphen}}, @dualindexentry{field.plural, name={\fieldfmt{plural}}, description={The text to display on subsequent use of - \gls{glspl}\margm{label}.}, - note={provided by \styfmt{glossaries}}, + \cs{glspl}\margm{label}.}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4620,7 +5323,7 @@ hyphen}}, name={\fieldfmt{see}}, description={General purpose cross-reference (syntax: \code{see=\marg{\oargm{tag}\meta{xr-list}}}).}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4629,7 +5332,7 @@ hyphen}}, name={\fieldfmt{seealso}}, description={Cross-reference related entries (syntax: \code{seealso=\margm{xr-list}}).}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={extrafield}, parent={fields} } @@ -4637,8 +5340,8 @@ hyphen}}, @dualindexentry{field.short, name={\fieldfmt{short}}, description={The short form of an abbreviation. (Set internally - by commands like \gls{newabbreviation}.)}, - note={provided by \styfmt{glossaries}}, + by commands like \csref{newabbreviation}.)}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4646,7 +5349,7 @@ hyphen}}, @dualindexentry{field.shortplural, name={\fieldfmt{shortplural}}, description={The plural short form of an abbreviation.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4654,7 +5357,7 @@ hyphen}}, @dualindexentry{field.symbol, name={\fieldfmt{symbol}}, description={The associated symbol.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4662,7 +5365,7 @@ hyphen}}, @dualindexentry{field.symbolplural, name={\fieldfmt{symbolplural}}, description={The plural form of the associated symbol.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4670,8 +5373,8 @@ hyphen}}, @dualindexentry{field.text, name={\fieldfmt{text}}, description={The text to display on subsequent use of - \gls{gls}\margm{label}.}, - note={provided by \styfmt{glossaries}}, + \cs{gls}\margm{label}.}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4679,7 +5382,7 @@ hyphen}}, @dualindexentry{field.user1, name={\fieldfmt{user1}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4687,7 +5390,7 @@ hyphen}}, @dualindexentry{field.user2, name={\fieldfmt{user2}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4695,7 +5398,7 @@ hyphen}}, @dualindexentry{field.user3, name={\fieldfmt{user3}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4703,7 +5406,7 @@ hyphen}}, @dualindexentry{field.user4, name={\fieldfmt{user4}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4711,7 +5414,7 @@ hyphen}}, @dualindexentry{field.user5, name={\fieldfmt{user5}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4719,7 +5422,7 @@ hyphen}}, @dualindexentry{field.user6, name={\fieldfmt{user6}}, description={A general purpose user field.}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={basefield}, parent={fields} } @@ -4728,7 +5431,7 @@ hyphen}}, name={\fieldfmt{duallong}}, description={The long form of a dual abbreviation mapped by \atentry{dualabbreviation}.}, - note={provided by \appfmt{bib2gls}}, + note={\appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} } @@ -4737,7 +5440,7 @@ hyphen}}, name={\fieldfmt{duallongplural}}, description={The plural long form of a dual abbreviation mapped by \atentry{dualabbreviation}.}, - note={provided by \appfmt{bib2gls}}, + note={\appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} } @@ -4746,7 +5449,7 @@ hyphen}}, name={\fieldfmt{dualshort}}, description={The short form of a dual abbreviation mapped by \atentry{dualabbreviation}.}, - note={provided by \appfmt{bib2gls}}, + note={\appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} } @@ -4755,7 +5458,7 @@ hyphen}}, name={\fieldfmt{dualshortplural}}, description={The plural short form of a dual abbreviation mapped by \atentry{dualabbreviation}.}, - note={provided by \appfmt{bib2gls}}, + note={\appfmt{bib2gls}}, category={bib2glsfield}, parent={fields} } @@ -4764,7 +5467,7 @@ hyphen}}, name={\fieldfmt{prefix}}, description={The prefix associated with the \field{text} field.}, - note={provided by \styfmt{glossaries-prefix}}, + note={\styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} } @@ -4773,7 +5476,7 @@ hyphen}}, name={\fieldfmt{prefixfirst}}, description={The prefix associated with the \field{first} field.}, - note={provided by \styfmt{glossaries-prefix}}, + note={\styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} } @@ -4782,7 +5485,7 @@ field.}, name={\fieldfmt{prefixfirstplural}}, description={The prefix associated with the \field{firstplural} field.}, - note={provided by \styfmt{glossaries-prefix}}, + note={\styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} } @@ -4791,7 +5494,7 @@ field.}, name={\fieldfmt{prefixplural}}, description={The prefix associated with the \field{plural} field.}, - note={provided by \styfmt{glossaries-prefix}}, + note={\styfmt{glossaries-prefix}}, category={prefixfield}, parent={fields} } @@ -4799,7 +5502,7 @@ field.}, @dualindexentry{field.access, name={\fieldfmt{access}}, description={The replacement text for the \field{name} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4808,7 +5511,7 @@ field.}, name={\fieldfmt{descriptionaccess}}, description={The replacement text for the \field{description} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4817,7 +5520,7 @@ field.}, name={\fieldfmt{descriptionpluralaccess}}, description={The replacement text for the \field{descriptionplural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4825,7 +5528,7 @@ field.}, @dualindexentry{field.firstaccess, name={\fieldfmt{firstaccess}}, description={The replacement text for the \field{first} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4834,7 +5537,7 @@ field.}, name={\fieldfmt{firstpluralaccess}}, description={The replacement text for the \field{firstplural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4842,7 +5545,7 @@ field.}, @dualindexentry{field.longaccess, name={\fieldfmt{longaccess}}, description={The replacement text for the \field{long} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4851,7 +5554,7 @@ field.}, name={\fieldfmt{longpluralaccess}}, description={The replacement text for the \field{longplural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4859,7 +5562,7 @@ field.}, @dualindexentry{field.pluralaccess, name={\fieldfmt{pluralaccess}}, description={The replacement text for the \field{plural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4867,7 +5570,7 @@ field.}, @dualindexentry{field.shortaccess, name={\fieldfmt{shortaccess}}, description={The replacement text for the \field{short} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4876,7 +5579,7 @@ field.}, name={\fieldfmt{shortpluralaccess}}, description={The replacement text for the \field{shortplural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4884,7 +5587,7 @@ field.}, @dualindexentry{field.symbolaccess, name={\fieldfmt{symbolaccess}}, description={The replacement text for the \field{symbol} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4893,7 +5596,7 @@ field.}, name={\fieldfmt{symbolpluralaccess}}, description={The replacement text for the \field{symbolplural} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4902,7 +5605,7 @@ field.}, name={\fieldfmt{textaccess}}, description={The replacement text for the \field{text} field.}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={accessfield}, parent={fields} } @@ -4930,6 +5633,15 @@ field.}, parent={internalfields} } +@dualindexentry{field.primarylocations, + name={\fieldfmt{primarylocations}}, + description={Stores the locations that use one of the designated +primary formats, if enabled.}, + note={internal field set by \appfmt{bib2gls}}, + category={internalfield}, + parent={internalfields} +} + @dualindexentry{field.indexcounter, name={\fieldfmt{index\-counter}}, description={Stores the location corresponding to the matching @@ -4942,7 +5654,7 @@ field.}, @dualindexentry{field.counter, name={\fieldfmt{counter}}, description={The default counter used for indexing (assigned by - the \gls{dual.opt.counter} option).}, + the \csopt{counter} option).}, note={internal field set by \appfmt{bib2gls}}, category={internalfield}, parent={internalfields} @@ -4951,7 +5663,7 @@ field.}, @dualindexentry{field.group, name={\fieldfmt{group}}, description={The letter group determined by the comparator - (or assigned by the \gls{dual.opt.group} option).}, + (or assigned by the \csopt{group} option).}, note={internal field set by \appfmt{bib2gls}}, category={internalfield}, parent={internalfields} @@ -5003,7 +5715,7 @@ field.}, @dualindexentry{field.secondarygroup, name={\fieldfmt{secondarygroup}}, description={The letter group determined by the - comparator used with the \gls{dual.opt.secondary} sort.}, + comparator used with the \csopt{secondary} sort.}, note={internal field set by \appfmt{bib2gls}}, category={internalfield}, parent={internalfields} @@ -5012,7 +5724,7 @@ field.}, @dualindexentry{field.secondarysort, name={\fieldfmt{secondarysort}}, description={The sort value determined by the - comparator used with the \gls{dual.opt.secondary} sort.}, + comparator used with the \csopt{secondary} sort.}, note={internal field set by \appfmt{bib2gls}}, category={internalfield}, parent={internalfields} @@ -5038,7 +5750,7 @@ field.}, @dualindexentry{field.type, name={\fieldfmt{type}}, description={The glossary this entry belongs to (assigned by - the \gls{dual.opt.type} option).}, + the \csopt{type} option).}, note={internal field set by \appfmt{bib2gls}}, category={internalfield}, parent={internalfields} @@ -5046,7 +5758,7 @@ field.}, @dualindexentry{field.fieldendpunc, name={\meta{field}\fieldfmt{endpunc}}, - description={Used with the \gls{dual.opt.check-end-punctuation} + description={Used with the \csopt{check-end-punctuation} option.}, note={internal field set by \appfmt{bibgls}}, category={internalfield}, @@ -5584,6 +6296,13 @@ field.}, parent={commandlineoptions} } +@dualindexentry{switch.merge-nameref-on, + name={\longargfmt{merge\dhyphen nameref\dhyphen on}}, + user1={\meta{rule}}, + category={switch}, + parent={commandlineoptions} +} + @dualindexentry{switch.force-cross-resource-refs, name={\longargfmt{force\dhyphen cross\dhyphen resource\dhyphen refs}}, symbol={\shortargfmt{x}}, @@ -5851,6 +6570,40 @@ field.}, name={post-description hook} } +@index{languagexml, + name={language resource file (\extfmt{xml})} +} + +@index{tag.page, + name={\xmltagfmt{tag.page}}, + parent={languagexml} +} + +@index{tag.pages, + name={\xmltagfmt{tag.pages}}, + parent={languagexml} +} + +@index{tag.passim, + name={\xmltagfmt{tag.passim}}, + parent={languagexml} +} + +@index{sentence.terminators, + name={\xmltagfmt{sentence.terminators}}, + parent={languagexml} +} + +@index{grouptitle.case.lc, + name={\xmltagfmt{grouptitle.case.}\meta{lc}}, + parent={languagexml} +} + +@index{xmlsee, + name={XML resource file}, + see={languagexml} +} + @index{encoding} @index{digraph} @@ -5877,6 +6630,11 @@ field.}, alias={full-stop} } +@index{apostrophe, + name={apostrophe (\code{'})}, + text={apostrophe} +} + @index{resourceset, name={resource set} } @@ -5936,9 +6694,17 @@ field.}, name={lower case} } +@index{titlecase, + name={title case} +} + +@index{sentencecase, + name={sentence case} +} + @index{case-change, - name = {case change}, - seealso = {uppercase,lowercase} + name = {case-change}, + seealso = {uppercase,lowercase,titlecase,sentencecase} } @index{unicodecategories, @@ -5997,6 +6763,11 @@ field.}, parent={unicodecategories} } +@index{punctuationdash, + name={\unicodecategoryfmt{Punctuation, Dash}}, + parent={unicodecategories} +} + @index{texmfcnf.openinany, name={\texmfcnffmt{openin\_any}} } @@ -6173,8 +6944,8 @@ field.}, name={\filefmt{markuplanguages.bib}} } -@dualindexentry{file.sample-languages.tex, - name={\filefmt{sample\dhyphen languages.tex}} +@dualindexentry{file.sample-markuplanguages.tex, + name={\filefmt{sample\dhyphen markuplanguages.tex}} } @dualindexentry{file.usergroups.bib, @@ -6214,7 +6985,7 @@ field.}, user1={\oargm{link text}\margm{label}}, description={creates a hyperlink to the entry information in the glossary}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6223,7 +6994,7 @@ field.}, user1={\margm{label}\margm{field}}, description={iterates over the items the given field, which contains an \styfmt{etoolbox} internal list}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, seealso={glsxtrfieldforlistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, category={command} } @@ -6233,8 +7004,7 @@ field.}, user1={\margm{label}\margm{field}\margm{handler}}, description={iterates over the items the given field, which contains an \styfmt{etoolbox} internal list, using the given handler}, - note={provided by \styfmt{glossaries-extra}, use at least v1.29 to -avoid a bug}, + note={\styfmt{glossaries-extra} v1.29+}, seealso={glsxtrfielddolistloop,glsxtrfieldifinlist,glsxtrfieldlistadd}, category={command} } @@ -6244,7 +7014,7 @@ avoid a bug}, user1={\margm{label}\margm{field}\margm{cs}}, description={fetches the value of the given field for the given label and stores it in the command \meta{cs}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6253,7 +7023,7 @@ avoid a bug}, user1={\margm{cs}\margm{label}}, description={assigns the sort value for \cs{index} when using auto-indexing}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @@ -6262,7 +7032,7 @@ avoid a bug}, user1={\margm{label}}, description={used for the actual value in \cs{index} when using auto-indexing}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @@ -6270,8 +7040,56 @@ avoid a bug}, 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}, - note={provided by \styfmt{glossaries}}, + 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}}, + note={\styfmt{glossaries}}, + seealso={glsseeitem,glsseeitemformat,glsseesep,glsseelastsep}, + category={command} +} + +@index{glsseeitem, + name={\csfmt{gls\-see\-item}}, + user1={\margm{label}}, + description={formats an element of the cross-reference list. + The default behaviour is to create a hyperlink (if enabled) to the + referenced entry with the link text given by + \code{\cs{glsseeitemformat}\margm{label}}}, + note={\styfmt{glossaries}}, + seealso={glsseeformat,glsseeitemformat}, + category={command} +} + +@index{glsseeitemformat, + name={\csfmt{gls\-see\-item\-format}}, + user1={\margm{label}}, + description={formats an element of the cross-reference list. + With the base \styfmt{glossaries} package this just does + \code{\cs{glsentrytext}\margm{label}}. With + \styfmt{glossaries-extra} this uses either \cs{glsentryshort} + or \cs{glsentryname} depending on whether or not the + \field{short} field has been set}, + note={\styfmt{glossaries} v3.0+}, + seealso={glsseeformat,glsseeitem}, + category={command} +} + +@index{glsseesep, + name={\csfmt{gls\-see\-sep}}, + description={the separator used between all but the last + entries of a cross-reference list}, + note={\styfmt{glossaries}}, + seealso={glsseeformat,glsseelastsep}, + category={command} +} + +@index{glsseelastsep, + name={\csfmt{gls\-see\-last\-sep}}, + description={the separator used between the penultimate and + ultimate entries of a cross-reference list}, + note={\styfmt{glossaries}}, + seealso={glsseeformat,glsseesep}, category={command} } @@ -6280,7 +7098,77 @@ avoid a bug}, user1={\margm{tag}\margm{labels}}, description={formats the entries identified in the comma separated list of labels as a set of cross-references}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsxtrhiername, + name={\csfmt{gls\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep}}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiernamesep}, + category={command} +} + +@index{glsxtrhiernamesep, + name={\csfmt{gls\-xtr\-hier\-name\-sep}}, + description={Separator between hierarchical levels displayed with + \cs{glsxtrhiername} (and case-changing variants). This defaults + to \qt{\glsxtrhiernamesep} with the \styfmt{glossaries-extra} + package, but the \bibgls\ interpreter has a different definition + to assist sorting}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiername}, + category={command} +} + +@index{Glsxtrhiername, + name={\csfmt{Gls\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where the top-most name has the + first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@index{GlsXtrhiername, + name={\csfmt{Gls\-Xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where each name has the + first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@index{GLSxtrhiername, + name={\csfmt{GLS\-xtr\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where the top-most name is converted to \idx{uppercase}}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, + category={command} +} + +@index{GLSXTRhiername, + name={\csfmt{GLS\-XTR\-hier\-name}}, + user1={\margm{label}}, + description={Displays the hierarchical name for the entry + identified by \meta{label} with each level separated by + \cs{glsxtrhiernamesep} where each name is converted + to \idx{uppercase}}, + note={\styfmt{glossaries-extra} v1.37+}, + seealso={glsxtrhiername,glsxtrhiernamesep}, category={command} } @@ -6289,7 +7177,7 @@ avoid a bug}, user1={\margm{label}}, description={additional category-independent code for the post-name hook}, - note={provided by \styfmt{glossaries-extra} version 1.25+}, + note={\styfmt{glossaries-extra} v1.25+}, category={command} } @@ -6298,7 +7186,16 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{text} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrytext, + name={\csfmt{Gls\-entry\-text}}, + user1={\margm{label}}, + description={displays the value of the \field{text} field with + the first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries}}, category={command} } @@ -6307,7 +7204,55 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{plural} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryplural, + name={\csfmt{Gls\-entry\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{plural} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentryfirst, + name={\csfmt{gls\-entry\-first}}, + user1={\margm{label}}, + description={expands to the value of the + \field{first} field}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryfirst, + name={\csfmt{Gls\-entry\-first}}, + user1={\margm{label}}, + description={displays the value of the + \field{first} field with the first letter converted to + \idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentryfirstplural, + name={\csfmt{gls\-entry\-first\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{firstplural} field}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryfirstplural, + name={\csfmt{Gls\-entry\-first\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{firstplural} field with the first letter converted to + \idx{uppercase}}, + note={\styfmt{glossaries}}, category={command} } @@ -6316,7 +7261,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{name} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6326,7 +7271,7 @@ post-name hook}, description={displays the value of the \field{name} field with the first character converted to upper case}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6335,7 +7280,17 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{description} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrydesc, + name={\csfmt{Gls\-entry\-desc}}, + user1={\margm{label}}, + description={displays the value of the + \field{description} field with the first letter converted to + upper case}, + note={\styfmt{glossaries}}, category={command} } @@ -6344,7 +7299,112 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{symbol} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrysymbol, + name={\csfmt{Gls\-entry\-symbol}}, + user1={\margm{label}}, + description={displays the value of the + \field{symbol} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentrysymbolplural, + name={\csfmt{gls\-entry\-symbol\-plural}}, + user1={\margm{label}}, + description={expands to the value of the + \field{symbolplural} field}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrysymbolplural, + name={\csfmt{Gls\-entry\-symbol\-plural}}, + user1={\margm{label}}, + description={displays the value of the + \field{symbolplural} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentrylong, + name={\csfmt{gls\-entry\-long}}, + user1={\margm{label}}, + description={expands to the value of the \field{long} field + without any formatting or indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentrylongpl, + name={\csfmt{gls\-entry\-long\-pl}}, + user1={\margm{label}}, + description={expands to the value of the \field{longplural} field + without any formatting or indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrylong, + name={\csfmt{Gls\-entry\-long}}, + user1={\margm{label}}, + description={displays the value of the + \field{long} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentrylongpl, + name={\csfmt{Gls\-entry\-long\-pl}}, + user1={\margm{label}}, + description={displays the value of the + \field{longplural} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentryshort, + name={\csfmt{gls\-entry\-short}}, + user1={\margm{label}}, + description={expands to the value of the + \field{short} field without any formatting or indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentryshortpl, + name={\csfmt{gls\-entry\-short\-pl}}, + user1={\margm{label}}, + description={expands to the value of the + \field{shortplural} field without any formatting or indexing}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryshort, + name={\csfmt{Gls\-entry\-short}}, + user1={\margm{label}}, + description={displays the value of the + \field{short} field without any formatting or indexing but + with the first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryshortpl, + name={\csfmt{Gls\-entry\-short\-pl}}, + user1={\margm{label}}, + description={displays the value of the + \field{shortplural} field without any formatting or indexing + but with the first letter converted to \idx{uppercase}}, + note={\styfmt{glossaries}}, category={command} } @@ -6353,7 +7413,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user1} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6362,7 +7422,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user2} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6371,7 +7431,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user3} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6380,7 +7440,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user4} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6389,7 +7449,7 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user5} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6398,7 +7458,67 @@ post-name hook}, user1={\margm{label}}, description={expands to the value of the \field{user6} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuseri, + name={\csfmt{Gls\-entry\-useri}}, + user1={\margm{label}}, + description={displays the value of the + \field{user1} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuserii, + name={\csfmt{Gls\-entry\-userii}}, + user1={\margm{label}}, + description={displays the value of the + \field{user2} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuseriii, + name={\csfmt{Gls\-entry\-useriii}}, + user1={\margm{label}}, + description={displays the value of the + \field{user3} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuseriv, + name={\csfmt{Gls\-entry\-useriv}}, + user1={\margm{label}}, + description={displays the value of the + \field{user4} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuserv, + name={\csfmt{Gls\-entry\-userv}}, + user1={\margm{label}}, + description={displays the value of the + \field{user5} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glsentryuservi, + name={\csfmt{Gls\-entry\-uservi}}, + user1={\margm{label}}, + description={displays the value of the + \field{user6} field with the first letter converted to +\idx{uppercase}}, + note={\styfmt{glossaries}}, category={command} } @@ -6407,7 +7527,7 @@ post-name hook}, user1={\margm{category}\margm{attribute}\margm{value}}, description={sets the value of the attribute for the given category}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6418,7 +7538,7 @@ category}, \field{description} field in parentheses if the entry that was just referenced was used for the first time}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6429,7 +7549,7 @@ category}, \field{symbol} field in parentheses if the entry that was just referenced was used for the first time and has the \field{symbol} field set}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6440,7 +7560,7 @@ category}, this appends a space and, in parentheses, the value of the \field{symbol} field (if set) followed by the value of the \field{description} field}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -6448,7 +7568,7 @@ category}, name={\csfmt{gls\-plural\-suffix}}, user1={}, description={the suffix used to construct the default plural}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6457,7 +7577,7 @@ category}, user1={}, description={the suffix used to construct the default plural for the short form of acronyms}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6466,7 +7586,7 @@ category}, user1={}, description={the style sensitive suffix used to construct the default plural for the short form of abbreviations}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, seealso={glsxtrabbrvpluralsuffix}, category={command} } @@ -6476,31 +7596,44 @@ category}, user1={}, description={the default suffix used to construct the plural for the short form of abbreviations}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@index{glsxtrscsuffix, + name={\csfmt{gls\-xtr\-sc\-suffix}}, + user1={}, + description={the suffix used to construct the plural for + the short form of abbreviations with one of the small-cap + (\code{sc}) styles}, + note={\styfmt{glossaries-extra}}, category={command} } @index{glsdefpostlink, name={\csfmt{gls\-def\-post\-link}}, user1={\margm{category}\margm{definition}}, - description={define the post-link hook for the given category}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + description={define the post-link hook + \cs{glsxtrpostlinkcategory} for the given category}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @index{glsdefpostname, name={\csfmt{gls\-def\-post\-name}}, user1={\margm{category}\margm{definition}}, - description={define the post-name hook for the given category}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + description={define the post-name hook + \cs{glsxtrpostnamecategory} for the given category}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @index{glsdefpostdesc, name={\csfmt{gls\-def\-post\-desc}}, user1={\margm{category}\margm{definition}}, - description={define the post-description hook for the given category}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + description={define the post-description hook + \csfmt{glsxtrpostdesc}\meta{category} for the given category}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -6509,7 +7642,7 @@ category}, user1={\margm{true}\margm{false}}, description={only for use in the post-link hooks this tests if the entry just referenced was used for the first time}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6521,7 +7654,7 @@ category}, if the entry doesn't exist (an error or warning message will occur and ?? will appear in the document). This command is not for use in the post-link hooks}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={GlsXtrIfUnusedOrUndefined,glsxtrifwasfirstuse}, category={command} } @@ -6533,17 +7666,26 @@ category}, hasn't been used or is undefined, otherwise it does \meta{false}. This command is not for use in the post-link hooks}, - note={provided by \styfmt{glossaries-extra} v1.34+}, + note={\styfmt{glossaries-extra} v1.34+}, seealso={ifglsused,glsxtrifwasfirstuse}, category={command} } +@index{GlsXtrLocationField, + name={\csfmt{GlsXtrLocationField}}, + user1={}, + description={expands to the internal name of the field storing the +location list, defaulting to \field{location}}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + @index{glslabel, name={\csfmt{glslabel}}, user1={}, description={only for use in the post-link hooks, this expands to the label of the entry that was last referenced}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6553,7 +7695,7 @@ hasn't been description={only for use in the glossary, such as in the style or in the post-name or post-description hooks, this expands to the label of the current entry}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6563,7 +7705,35 @@ label of the current entry}, description={only for use in the \meta{true} part of \cs{ifglshasfield} or \cs{glsxtrifhasfield}, this expands to the field value}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentrytitlecase, + name={\csfmt{gls\-entry\-title\-case}}, + user1={\margm{entry label}\margm{field label}}, + description={fetches the given field and applies + \ics{capitalisewords} to it}, + note={\styfmt{glossaries} v4.22+}, + category={command} +} + +@index{capitalisewords, + name={\csfmt{capitalise\-words}}, + user1={\margm{text}}, + description={converts the first letter of each word to + \idx{uppercase} using \ics{makefirstuc}}, + note={\styfmt{mfirstuc} v1.06+}, + category={command} +} + +@index{MFUnocap, + name={\csfmt{MFU\-no\-cap}}, + user1={\margm{word}}, + description={identifies \meta{word} as one that + should not have its case-changed by \ics{capitalisewords} + unless it occurs at the start}, + note={\styfmt{mfirstuc} v1.09+}, category={command} } @@ -6572,7 +7742,25 @@ field value}, user1={\margm{entry label}\margm{field label}}, description={expands to the value of the given field for the given entry}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@index{Glsxtrusefield, + name={\csfmt{Gls\-xtr\-use\-field}}, + user1={\margm{entry label}\margm{field label}}, + description={like \cs{glsxtrusefield} but converts the first + letter to \idx!{uppercase}}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@index{GLSxtrusefield, + name={\csfmt{GLS\-xtr\-use\-field}}, + user1={\margm{entry label}\margm{field label}}, + description={as \cs{glsxtrusefield} but converts the value to + \idx{uppercase}}, + note={\styfmt{glossaries-extra} v1.37+}, category={command} } @@ -6582,7 +7770,17 @@ field value}, description={assigns the given \meta{value} to the field identified by \meta{field label} for the entry identified by \meta{entry label}}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, + category={command} +} + +@index{xGlsXtrSetField, + name={\csfmt{xGls\-Xtr\-Set\-Field}}, + user1={\margm{entry label}\margm{field label}\margm{value}}, + description={globally assigns the (protected) full expansion of the given \meta{value} to the field + identified by \meta{field label} for the + entry identified by \meta{entry label}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -6593,7 +7791,7 @@ field value}, (defined and not empty) without testing if the entry exists and adds implicit scoping to \meta{true} and \meta{false}}, - note={provided by \styfmt{glossaries-extra} v1.19+}, + note={\styfmt{glossaries-extra} v1.19+}, seealso={GlsXtrIfFieldUndef}, category={command} } @@ -6605,7 +7803,7 @@ field value}, (defined and not empty) without testing if the entry exists and without introducing an implicit scope}, - note={provided by \styfmt{glossaries-extra} v1.19+}, + note={\styfmt{glossaries-extra} v1.19+}, seealso={GlsXtrIfFieldUndef}, category={command} } @@ -6615,7 +7813,7 @@ field value}, user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, description={tests if the given field isn't defined for the given entry, which may also not exist}, - note={provided by \styfmt{glossaries-extra} v1.23+}, + note={\styfmt{glossaries-extra} v1.23+}, category={command} } @@ -6624,7 +7822,7 @@ field value}, user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, description={tests if the given field value is the same as \meta{text} for the given entry, which may not exist}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -6633,7 +7831,7 @@ field value}, user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, description={like \cs{GlsXtrIfFieldEqStr} but first (protected) fully expands \meta{text} (but not the field value)}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -6642,7 +7840,7 @@ fully expands \meta{text} (but not the field value)}, user1={\margm{field label}\margm{entry label}\margm{text}\margm{true}\margm{false}}, description={like \cs{GlsXtrIfFieldEqStr} but first (protected) fully expands both the field value and \meta{text}}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -6651,7 +7849,7 @@ fully expands both the field value and \meta{text}}, 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={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={glsxtrifhasfield,GlsXtrIfFieldUndef}, category={command} } @@ -6662,7 +7860,7 @@ fully expands both the field value and \meta{text}}, description={tests if the given entry, which must be defined, has the \field{symbol} field set to value that's not empty and not \csfmt{relax}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef}, category={command} } @@ -6672,7 +7870,7 @@ fully expands both the field value and \meta{text}}, user1={\margm{entry label}\margm{true}\margm{false}}, description={tests if the given entry, which must be defined, has the \field{description} field set}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={ifglshassymbol,ifglshasdescsuppressed}, category={command} } @@ -6682,7 +7880,7 @@ fully expands both the field value and \meta{text}}, user1={\margm{entry label}\margm{true}\margm{false}}, description={tests if the given entry, which must be defined, has the \field{description} field set to \cs{nopostdesc}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={ifglshasdesc}, category={command} } @@ -6692,7 +7890,7 @@ fully expands both the field value and \meta{text}}, user1={\margm{entry label}\margm{true}\margm{false}}, description={tests if the given entry, which must be defined, has the \field{parent} field set}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6706,7 +7904,25 @@ fully expands both the field value and \meta{text}}, field. With \bibgls, a more efficient approach is to use \csopt{save-child-count} and test the value of the \field{childcount} field}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{ifglshasshort, + name={\csfmt{if\-gls\-has\-short}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{short} field set}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{ifglshaslong, + name={\csfmt{if\-gls\-has\-long}}, + user1={\margm{entry label}\margm{true}\margm{false}}, + description={tests if the given entry, which must be defined, has the + \field{long} field set}, + note={\styfmt{glossaries}}, category={command} } @@ -6718,7 +7934,7 @@ integer. If the field is undefined or empty, the value is assumed to be 0. If the field is set, it must expand to an integer value. The value can be referenced in \meta{true} or \meta{false} with \cs{glscurrentfieldvalue}}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, seealso={GlsXtrIfFieldEqNum}, category={command} } @@ -6731,7 +7947,7 @@ integer \meta{number}. If the field is undefined or empty, the value is assumed be 0. If the field is set, it must expand to an integer value. The value can be referenced in \meta{true} or \meta{false} with \cs{glscurrentfieldvalue}}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, seealso={GlsXtrIfFieldNonZero}, category={command} } @@ -6744,7 +7960,7 @@ 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}}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.31+}, + note={\styfmt{glossaries-extra-bib2gls} v1.31+}, seealso={GlsXtrIfFieldNonZero}, category={command} } @@ -6755,7 +7971,7 @@ can be referenced in \meta{true} or \meta{false} with description={should expand to \meta{true} if the post-link hook should check for a following full stop (in addition to attribute checks) otherwise should expand to \meta{false}}, - note={provided by \styfmt{glossaries-extra} v1.23+}, + note={\styfmt{glossaries-extra} v1.23+}, category={command} } @@ -6764,7 +7980,7 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={governs the way the \field{name} field is set by the \abbrstyle{long-short-desc} abbreviation styles}, - note={provided by \styfmt{glossaries-extra} v1.17+}, + note={\styfmt{glossaries-extra} v1.17+}, category={command} } @@ -6773,7 +7989,7 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={governs the way the \field{name} field is set by the \abbrstyle{long-short} abbreviation styles}, - note={provided by \styfmt{glossaries-extra} v1.25+}, + note={\styfmt{glossaries-extra} v1.25+}, category={command} } @@ -6782,7 +7998,7 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={governs the way the \field{name} field is set by the \abbrstyle{long-only-short-only} abbreviation styles}, - note={provided by \styfmt{glossaries-extra} v1.25+}, + note={\styfmt{glossaries-extra} v1.25+}, category={command} } @@ -6791,27 +8007,28 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={governs the way the \field{name} field is set by the \abbrstyle{long-only-short-only} abbreviation styles}, - note={provided by \styfmt{glossaries-extra} v1.17+}, + note={\styfmt{glossaries-extra} v1.17+}, category={command} } @index{glsaddkey, name={\csfmt{gls\-add\-key}}, user1={\margm{key}\margm{default value}\margm{no link cs}\margm{no link ucfirst cs}\margm{link cs}\margm{link ucfirst cs}\margm{link allcaps cs}}, - description={adds a new key for use in \cs{newglossaryentry} + description={adds a new key for use in \csref{newglossaryentry} and associated commands to access it}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @index{glsxtrprovidestoragekey, name={\csfmt{gls\-xtr\-provide\-storage\-key}}, user1={\margm{key}\margm{default value}\margm{no link cs}}, - description={adds a new key, if not already defined, for use in \cs{newglossaryentry} + description={adds a new key, if not already defined, for use in +\csref{newglossaryentry} and an associated command to access it where (unlike \cs{glsaddstoragekey}) the \meta{no link cs} part may be empty if unrequired}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -6819,8 +8036,8 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{gls\-add\-storage\-key}}, user1={\margm{key}\margm{default value}\margm{no link cs}}, description={adds a new key for internal use that can be set in - \cs{newglossaryentry}}, - note={provided by \styfmt{glossaries}}, + \csref{newglossaryentry}}, + note={\styfmt{glossaries}}, category={command} } @@ -6830,7 +8047,7 @@ can be referenced in \meta{true} or \meta{false} with description={defines the control sequence \meta{cs} to be used with abbreviation tagging with the given categories}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6839,7 +8056,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\margm{text}}, description={font used by tagging command defined by \cs{GlsXtrEnableInitialTagging}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command}, seealso={GlsXtrEnableInitialTagging} } @@ -6849,33 +8066,31 @@ can be referenced in \meta{true} or \meta{false} with user1={\oargm{type}\margm{label}\margm{text}}, description={creates a hyper target for the group given by \meta{label} for the given glossary type and displays the text}, - note={provided by \styfmt{glossary-hypernav}}, + note={\styfmt{glossary-hypernav}}, category={command} } @index{newentry, name={\csfmt{newentry}}, user1={\margm{label}\margm{\keyvallist}}, - description={equivalent to \csref[noindex]{newglossaryentry}}, - note={provided by \styfmt{glossaries-extra}'s shortcuts}, + description={equivalent to \csref{newglossaryentry}}, + note={\styfmt{glossaries-extra}'s shortcuts}, category={command} } @index{newsym, name={\csfmt{newsym}}, user1={\margm{label}\margm{\keyvallist}\margm{symbol}}, - description={equivalent to \gls{glsxtrnewsymbol}}, - note={provided by \styfmt{glossaries-extra}'s - \styopt{shortcuts} package option}, + description={equivalent to \csref{glsxtrnewsymbol}}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, category={command} } @index{newnum, name={\csfmt{newnum}}, user1={\margm{label}\margm{\keyvallist}}, - description={equivalent to \gls{glsxtrnewnumber}}, - note={provided by \styfmt{glossaries-extra}'s - \styopt{shortcuts} package option}, + description={equivalent to \csref{glsxtrnewnumber}}, + note={\styfmt{glossaries-extra} \styopt{shortcuts}}, category={command} } @@ -6883,8 +8098,8 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{acronym\-type}}, user1={}, description={expands to the default acronym glossary type when using - \cs{newacronym}}, - note={provided by \styfmt{glossaries}}, + \csref{newacronym}}, + note={\styfmt{glossaries}}, category={command} } @@ -6892,8 +8107,8 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{gls\-xtr\-abbrv\-type}}, user1={}, description={expands to the default glossary type when using - \cs{newabbreviation}}, - note={provided by \styfmt{glossaries-extra}}, + \csref{newabbreviation}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -6901,7 +8116,7 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{no\-post\-desc}}, user1={}, description={suppresses the post-description hook}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6910,7 +8125,7 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={suppresses the post-description punctuation without suppressing the post-description hook}, - note={provided by \styfmt{glossaries-extra} v1.22+}, + note={\styfmt{glossaries-extra} v1.22+}, category={command} } @@ -6920,7 +8135,7 @@ can be referenced in \meta{true} or \meta{false} with description={used within post-description category hooks, this restores the post-description punctuation if it's been suppressed with \cs{glsxtrnopostpunc}}, - note={provided by \styfmt{glossaries-extra} v1.23+}, + note={\styfmt{glossaries-extra} v1.23+}, category={command} } @@ -6929,7 +8144,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\oargm{type}\margm{file}}, description={locally redefines \cs{glsdefaulttype} to \meta{type} and inputs \meta{file}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6939,7 +8154,7 @@ can be referenced in \meta{true} or \meta{false} with description={defines a new glossary identified by \meta{type} with the given title and associated file extensions used by \appfmt{makeindex} or \appfmt{xindy}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6948,7 +8163,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\margm{type}\margm{title}}, description={defines a new glossary identified by \meta{type} with the given title}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -6959,7 +8174,7 @@ can be referenced in \meta{true} or \meta{false} with suppressed) identified by \meta{type} that's not included in the list used by commands, such as \cs{printunsrtglossaries}, that iterate over defined glossaries}, - note={provided by \styfmt{glossaries} v4.08+}, + note={\styfmt{glossaries} v4.08+}, category={command} } @@ -6970,7 +8185,7 @@ can be referenced in \meta{true} or \meta{false} with suppressing hyperlinks) identified by \meta{type} that's not included in the list used by commands, such as \cs{printunsrtglossaries}, that iterate over defined glossaries}, - note={provided by \styfmt{glossaries-extra} v1.11+}, + note={\styfmt{glossaries-extra} v1.11+}, category={command} } @@ -6979,7 +8194,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\margm{type}}, description={as \cs{newignoredglossary} but does nothing if a glossary identified by \meta{type} already exists}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -6988,7 +8203,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\margm{type}}, description={as \ics{provideignoredglossary} but doesn't suppress hyperlinks}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -6996,7 +8211,7 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{delimN}}, user1={}, description={used to delimited individual locations}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7005,7 +8220,7 @@ can be referenced in \meta{true} or \meta{false} with user1={}, description={used as a separator between the start and end locations of a range}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7014,7 +8229,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\margm{location list cs}}, description={iterates over the given internal location list using the \cs{glsnoidxloclisthandler} handler}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7023,7 +8238,7 @@ can be referenced in \meta{true} or \meta{false} with description={the handler used by the internal list loop function used in \cs{glsnoidxloclist}}, user1={\margm{location}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7031,7 +8246,7 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{glossentry}}, user1={\margm{label}\margm{location list}}, description={used in the glossary to display a top-level entry}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries} v3.08a+}, category={command} } @@ -7039,7 +8254,122 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{subglossentry}}, user1={\margm{level}\margm{label}\margm{location list}}, description={used in the glossary to display a sub-entry}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries} v3.08a+}, + category={command} +} + +@index{newglossarystyle, + name={\csfmt{new\-glossary\-style}}, + user1={\margm{name}\margm{definition}}, + description={defines a new glossary style called \meta{name}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{setglossarystyle, + name={\csfmt{set\-glossary\-style}}, + user1={\margm{name}}, + description={sets the glossary style identified by \meta{name}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glossaryheader, + name={\csfmt{glossary\-header}}, + description={implemented at the start of a glossary (modified by +glossary styles)}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsentryitem, + name={\csfmt{gls\-entry\-item}}, + user1={\margm{label}}, + description={increments and displays the \counter{glossaryentry} +counter, if appropriate}, + note={\styfmt{glossaries} v3.0+}, + category={command} +} + +@index{glssubentryitem, + name={\csfmt{gls\-sub\-entry\-item}}, + user1={\margm{label}}, + description={increments and displays the \counter{glossarysubentry} +counter, if appropriate}, + note={\styfmt{glossaries} v3.0+}, + category={command} +} + +@index{glstarget, + name={\csfmt{gls\-target}}, + user1={\margm{label}\margm{text}}, + description={creates a hypertarget for the entry given by +\meta{label} (the target for commands like \cs{gls}) and displays \meta{text}}, + note={\styfmt{glossaries} v1.18+}, + category={command} +} + +@index{glsnamefont, + name={\csfmt{gls\-name\-font}}, + user1={\margm{text}}, + description={used by \cs{glossentryname} to format the name}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glossentryname, + name={\csfmt{gloss\-entry\-name}}, + user1={\margm{label}}, + description={used by glossary styles to display the name}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glossentrysymbol, + name={\csfmt{gloss\-entry\-symbol}}, + user1={\margm{label}}, + description={used by glossary styles to display the symbol}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glspostdescription, + name={\csfmt{glspostdescription}}, + description={a hook added after the description in some glossary +styles (all if the \sty{glossaries-extra-stylemods} package is +loaded to patch them). This hook is used to reflect the +\styopt{nopostdot} package option for \sty{glossaries} +and the \styopt{postpunc} option for \sty{glossaries-extra}}, + note={\styfmt{glossaries} and modified by +\styfmt{glossaries-extra}}, + category={command} +} + +@index{glossentrynameother, + name={\csfmt{gloss\-entry\-name\-other}}, + user1={\margm{label}\margm{field}}, + description={acts like \ics{glossentryname} (obeys + \catattr{glossname} and \catattr{glossnamefont} + or \cs{glsnamefont} and the post-name hook) but uses + the given \meta{field} instead of the \field{name} field}, + note={\styfmt{glossaries-extra} v1.22+}, + category={command} +} + +@index{glossentrydesc, + name={\csfmt{gloss\-entry\-desc}}, + user1={\margm{label}}, + description={used by glossary styles to display the description}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glossentrydesc, + name={\csfmt{Gloss\-entry\-desc}}, + user1={\margm{label}}, + description={like \cs{glossentrydesc} but converts the first +letter to uppercase}, + note={\styfmt{glossaries}}, category={command} } @@ -7049,7 +8379,7 @@ can be referenced in \meta{true} or \meta{false} with description={iterates over all entries defined for all glossaries (or for the sub-list provided in the options) and performs \cs{glsadd} for each entry}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7059,8 +8389,8 @@ can be referenced in \meta{true} or \meta{false} with description={iterates over all entries defined for all glossaries (or for the sub-list provided in the options) and performs \cs{glsadd} for each entry that hasn't been used with - the \gls[noindex]{glsadd.format} set to \code{glsignore}}, - note={provided by \styfmt{glossaries}}, + the \glsaddopt{format} set to \code{glsignore}}, + note={\styfmt{glossaries}}, category={command} } @@ -7068,7 +8398,7 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{glsadd}}, user1={\oargm{options}\margm{label}}, description={indexes the entry without displaying any text}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7077,7 +8407,7 @@ can be referenced in \meta{true} or \meta{false} with user1={\oargm{options}\margm{label list}}, description={indexes each entry identified in the comma-separated list of labels without displaying any text}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -7109,7 +8439,7 @@ can be referenced in \meta{true} or \meta{false} with name={\csfmt{theglossaryentry}}, description={textual representation of the \counter{glossaryentry} counter, which is defined with the \styopt{entrycounter} option}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7117,7 +8447,7 @@ counter, which is defined with the \styopt{entrycounter} option}, name={\csfmt{theHglossaryentry}}, description={hypertarget associated with the \counter{glossaryentry} counter, which is defined with the \styopt{entrycounter} option}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7127,7 +8457,7 @@ counter, which is defined with the \styopt{entrycounter} option}, description={increments the \counter{glossaryentry} counter, which is defined with the \styopt{entrycounter} option, and automatically labels it with \cs{label}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7135,7 +8465,7 @@ labels it with \cs{label}}, name={\csfmt{currentglossary}}, description={defined within the glossary to the current glossary type, this has no meaning outside of the glossary list}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7143,7 +8473,7 @@ type, this has no meaning outside of the glossary list}, name={\csfmt{front\-matter}}, user1={}, description={switches to front matter}, - note={provided by book-like classes}, + note={book-like classes}, category={command} } @@ -7151,7 +8481,7 @@ type, this has no meaning outside of the glossary list}, name={\csfmt{main\-matter}}, user1={}, description={switches to main matter}, - note={provided by book-like classes}, + note={book-like classes}, category={command} } @@ -7159,7 +8489,7 @@ type, this has no meaning outside of the glossary list}, name={\csfmt{back\-matter}}, user1={}, description={switches to back matter}, - note={provided by book-like classes}, + note={book-like classes}, category={command} } @@ -7167,8 +8497,8 @@ type, this has no meaning outside of the glossary list}, name={\csfmt{Gls\-Xtr\-Set\-Default\-Number\-Format}}, user1={\margm{format}}, description={set the default format to use if the - \gls[noindex]{glsadd.format} key isn't set}, - note={provided by \styfmt{glossaries-extra} v1.19+}, + \glsaddopt{format} key isn't set}, + note={\styfmt{glossaries-extra} v1.19+}, category={command} } @@ -7176,7 +8506,7 @@ type, this has no meaning outside of the glossary list}, name={\csfmt{Gls\-Xtr\-Set\-Default\-Gls\-Opts}}, user1={\margm{options}}, description={set the default options for commands like \cs{gls}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -7185,7 +8515,7 @@ type, this has no meaning outside of the glossary list}, user1={\margm{text}}, description={default location format, uses \cs{glshypernumber} if hyperlinks enabled otherwise just does \meta{text}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7193,7 +8523,7 @@ hyperlinks enabled otherwise just does \meta{text}}, name={\csfmt{gls\-hyper\-number}}, user1={\margm{text}}, description={a location format that has a hyperlink (if enabled)}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7202,7 +8532,7 @@ hyperlinks enabled otherwise just does \meta{text}}, user1={\margm{text}}, description={a location format that uses the sans-serif font that also has a hyperlink (if enabled)}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7211,7 +8541,7 @@ hyperlinks enabled otherwise just does \meta{text}}, user1={\margm{text}}, description={a location format that uses the italic font that also has a hyperlink (if enabled)}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7220,7 +8550,25 @@ hyperlinks enabled otherwise just does \meta{text}}, user1={\margm{text}}, description={a location format that uses the bold font that also has a hyperlink (if enabled)}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{hyperemph, + name={\csfmt{hyperemph}}, + user1={\margm{text}}, + description={a location format that uses \ics{emph} to set the + font and also has a hyperlink (if enabled)}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{hyperrm, + name={\csfmt{hyperrm}}, + user1={\margm{text}}, + description={a location format that uses the serif (Roman) + font that also has a hyperlink (if enabled)}, + note={\styfmt{glossaries}}, category={command} } @@ -7234,6 +8582,21 @@ hyperlinks enabled otherwise just does \meta{text}}, category={command} } +@index{em, + name={\csfmt{em}}, + description={switch to emphasized font (until end of current scope)}, + note={kernel command}, + category={command} +} + +@index{textsf, + name={\csfmt{textsf}}, + user1={\margm{text}}, + description={displays the given text in sans-serif}, + note={kernel command}, + category={command} +} + @index{textbf, name={\csfmt{textbf}}, user1={\margm{text}}, @@ -7242,6 +8605,13 @@ hyperlinks enabled otherwise just does \meta{text}}, category={command} } +@index{bfseries, + name={\csfmt{bfseries}}, + description={switch to bold (until end of current scope)}, + note={kernel command}, + category={command} +} + @index{textit, name={\csfmt{textit}}, user1={\margm{text}}, @@ -7251,6 +8621,49 @@ hyperlinks enabled otherwise just does \meta{text}}, category={command} } +@index{texttt, + name={\csfmt{texttt}}, + user1={\margm{text}}, + description={displays the given text in monospaced font}, + note={kernel command}, + category={command} +} + +@index{@firstofone, + name={\csfmt{@first\-of\-one}}, + user1={\margm{code}}, + description={does \meta{code}}, + note={kernel command}, + category={command} +} + +@index{@gobble, + name={\csfmt{@gobble}}, + user1={\margm{code}}, + description={does nothing (the argument is discarded)}, + note={kernel command}, + category={command} +} + +@index{@for, + name={\csfmt{@for}}, + user1={\meta{cs}:=\meta{list}\csfmt{do}\margm{code}}, + description={iterates over each item in the comma-separated +\meta{list}, and on each iteration sets \meta{cs} to the current +element and performs \meta{code}}, + note={kernel command}, + category={command} +} + +@index{alph, + name={\csfmt{alph}}, + user1={\margm{counter}}, + description={displays the given counter as an alphabetic character +from \qt{a} to \qt{z}}, + note={kernel command}, + category={command} +} + @index{footnote, name={\csfmt{footnote}}, user1={\oargm{number}\margm{text}}, @@ -7264,7 +8677,7 @@ hyperlinks enabled otherwise just does \meta{text}}, user1={\margm{text}}, description={indexes the given term by writing the relevant information to an associated file that can then be processed -by \gls{makeindex} or \gls{xindy}}, +by \idx{makeindex} or \idx{xindy}}, note={kernel command}, category={command} } @@ -7274,7 +8687,7 @@ by \gls{makeindex} or \gls{xindy}}, user1={\margm{text}}, description={does nothing but when used as a location format \bibgls\ recognises it as an \idx{ignoredrecord}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7284,7 +8697,7 @@ by \gls{makeindex} or \gls{xindy}}, description={identifies the style file in the \ext{aux} file for the benefit of external tools like \idx{makeglossaries} and \idx{makeglossaries-lite}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7293,8 +8706,8 @@ by \gls{makeindex} or \gls{xindy}}, user1={\margm{text}}, description={does nothing but when used as a location format \bibgls\ recognises it as an \idx{ignoredrecord} indexed by - commands like \cs{rgls}}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + commands like \csref{rgls}}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -7395,6 +8808,14 @@ usual delay}, category={command} } +@index{detokenize, + name={\csfmt{detokenize}}, + user1={\margm{general text}}, + description={expands the argument to a list of character tokens}, + note={{}\eTeX\ primitive}, + category={command} +} + @index{input, name={\csfmt{input}}, user1={\margm{file}}, @@ -7403,6 +8824,15 @@ usual delay}, category={command} } +@index{IfFileExists, + name={\csfmt{IfFileExists}}, + user1={\margm{file}\margm{true}\margm{false}}, + description={if the given \meta{file} exists does \meta{true} + otherwise does \meta{false}}, + note={kernel command}, + category={command} +} + @index{jobname, name={\csfmt{jobname}}, user1={}, @@ -7428,8 +8858,16 @@ usual delay}, category={command} } +@index{ifnum, + name={\csfmt{ifnum}}, + user1={\meta{number1}\meta{comparison}\meta{number2}}, + description={integer conditional}, + note={\TeX\ primitive}, + category={command} +} + @index{renewcommand, - name={\csfmt{renewcommand}}, + name={\csfmt{re\-new\-com\-mand}}, user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, description={redefines an existing command}, note={kernel command}, @@ -7437,7 +8875,7 @@ usual delay}, } @index{newcommand, - name={\csfmt{newcommand}}, + name={\csfmt{new\-com\-mand}}, user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, description={defines a new command}, note={kernel command}, @@ -7445,7 +8883,7 @@ usual delay}, } @index{providecommand, - name={\csfmt{providecommand}}, + name={\csfmt{pro\-vide\-com\-mand}}, user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, description={defines a command if it's not already defined}, note={kernel command}, @@ -7497,7 +8935,15 @@ usual delay}, user1={\margm{symbol}}, description={renders given maths symbol in bold if supported by the current font}, - note={provided by \styfmt{amsmath}}, + note={\styfmt{amsmath}}, + category={command} +} + +@index{mathcal, + name={\csfmt{mathcal}}, + user1={\margm{character}}, + description={renders the given (\idx!{uppercase}) maths character in a calligraphic font}, + note={kernel command (maths mode)}, category={command} } @@ -7505,7 +8951,7 @@ usual delay}, name={\csfmt{ifglsentryexists}}, user1={\margm{label}\margm{true}\margm{false}}, description={tests if the entry given by \meta{label} exists}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7513,7 +8959,7 @@ usual delay}, name={\csfmt{gls\-default\-type}}, user1={}, description={the default glossary type}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7521,7 +8967,7 @@ usual delay}, name={\csfmt{gls\-symbols\-group\-name}}, user1={}, description={the name used for the symbols group}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7529,7 +8975,7 @@ usual delay}, name={\csfmt{gls\-numbers\-group\-name}}, user1={}, description={the name used for the numbers group}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7539,7 +8985,7 @@ usual delay}, description={display the glossary by iterating over all entries associated with that glossary in the order in which they were defined}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.08+}, category={command} } @@ -7549,7 +8995,7 @@ usual delay}, description={as \cs{printunsrtglossary} but performs \meta{code} first (scoped to localise any assignments within \meta{code})}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -7558,7 +9004,7 @@ usual delay}, user1={}, description={iterates over all non-ignored defined glossaries and performs \cs{printunsrtglossary} for each one}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.08+}, category={command} } @@ -7566,24 +9012,24 @@ usual delay}, name={\csfmt{print\-unsrt\-glos\-sary\-entry\-process\-hook}}, user1={\margm{label}}, description={performed at each iteration of the internal loop used -by \gls{printunsrtglossary}}, - note={provided by \styfmt{glossaries-extra} v1.21+}, +by \cs{printunsrtglossary}}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @index{printunsrtglossaryskipentry, name={\csfmt{print\-unsrt\-glos\-sary\-skip\-entry}}, description={only allowed within - \gls{printunsrtglossaryentryprocesshook} this command + \cs{printunsrtglossaryentryprocesshook} this command indicates that the current entry should be skipped}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @index{printunsrtglossarypredoglossary, name={\csfmt{print\-unsrt\-glos\-sary\-pre\-do\-glos\-sary}}, - description={hook performed by \gls{printunsrtglossary}}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + description={hook performed by \cs{printunsrtglossary}}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -7593,7 +9039,7 @@ by \gls{printunsrtglossary}}, description={expands to the value of the \field{category} field for the entry identified by \meta{label} or nothing if the entry hasn't been defined}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -7602,7 +9048,7 @@ hasn't been defined}, user1={\margm{label}\margm{category}\margm{true}\margm{false}}, description={does \meta{true} if the \field{category} field for the entry given by \meta{label} is \meta{category}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -7613,7 +9059,7 @@ hasn't been defined}, in the comma-separated \meta{list}, where both \meta{label} and \meta{list} are fully expanded before testing. This test is designed for \emph{labels} which should be fully expandable}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -7665,20 +9111,37 @@ hasn't been defined}, category={commandoption}, } +@index{printgloss.nogroupskip, + parent = {printunsrtglossary}, + name = {\csoptfmt{no\-group\-skip}}, + category={commandoption}, +} + @index{cs.makeglossaries, name={\csfmt{make\-glos\-saries}}, user1={}, description={opens associated glossary files to be processed - by \gls{makeindex} or \gls{xindy}}, - note={provided by \styfmt{glossaries}}, + by \idx{makeindex} or \idx{xindy}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{makenoidxglossaries, + name={\csfmt{make\-noidx\-glos\-saries}}, + user1={}, + description={indicates that \TeX\ should be used to sort and + collate the glossary information instead of using an + external application; this command should not be used + with \bibgls}, + note={\styfmt{glossaries} v4.04+}, category={command} } @index{printglossary, name={\csfmt{print\-glos\-sary}}, user1={\oargm{options}}, - description={inputs file created by \gls{makeindex} or \gls{xindy}}, - note={provided by \styfmt{glossaries}}, + description={inputs file created by \idx{makeindex} or \idx{xindy}}, + note={\styfmt{glossaries}}, category={command} } @@ -7687,7 +9150,7 @@ hasn't been defined}, user1={}, description={iterates over all non-ignored defined glossaries and performs \cs{printglossary} for each one}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7695,7 +9158,7 @@ hasn't been defined}, name={\csfmt{print\-noidx\-glos\-sary}}, user1={\oargm{options}}, description={uses \TeX\ to sort, collate and list the glossary}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries} v4.04+}, category={command} } @@ -7704,7 +9167,7 @@ hasn't been defined}, user1={}, description={iterates over all non-ignored defined glossaries and performs \cs{printnoidxglossary} for each one}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries} v4.04+}, category={command} } @@ -7712,7 +9175,16 @@ hasn't been defined}, name={\csfmt{make\-first\-uc}}, user1={\margm{text}}, description={converts the first letter of \meta{text} to upper case}, - note={provided by \styfmt{mfirstuc}}, + note={\styfmt{mfirstuc}}, + category={command} +} + +@index{xmakefirstuc, + name={\csfmt{xmake\-first\-uc}}, + user1={\margm{text}}, + description={applies \cs{makefirstuc} with one level expansion + of the first token of \meta{text}}, + note={\styfmt{mfirstuc} v1.01+}, category={command} } @@ -7720,7 +9192,7 @@ hasn't been defined}, name={\csfmt{ac}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={equivalent to \cs{gls}}, - note={provided by \styfmt{glossaries-extra} \styopt{shortcuts} package + note={\styfmt{glossaries-extra} \styopt{shortcuts} package option}, category={command} } @@ -7729,8 +9201,8 @@ option}, name={\csfmt{ab}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={equivalent to \cs{gls}}, - note={provided by \styfmt{glossaries-extra} - \styopt[abbreviations]{shortcuts} package option}, + note={\styfmt{glossaries-extra} + \styopt[abbreviations]{shortcuts}}, category={command} } @@ -7738,7 +9210,23 @@ option}, name={\csfmt{glsxtrp}}, user1={\margm{field}\margm{label}}, description={displays the given field for the entry given by label}, - note={provided by \styfmt{glossaries-extra} v1.07+}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@index{glsps, + name={\csfmt{glsps}}, + user1={\margm{label}}, + description={shortcut for \code{\cs{glsxtrp}\marg{short}\margm{label}}}, + note={\styfmt{glossaries-extra} v1.07+}, + category={command} +} + +@index{glspt, + name={\csfmt{glspt}}, + user1={\margm{label}}, + description={shortcut for \code{\cs{glsxtrp}\marg{text}\margm{label}}}, + note={\styfmt{glossaries-extra} v1.07+}, category={command} } @@ -7746,8 +9234,8 @@ option}, name={\csfmt{Gls\-Xtr\-Fmt\-Field}}, user1={}, description={expands to the internal label of the field used - to store the control sequence name for use with \cs{glsxtrfmt}}, - note={provided by \styfmt{glossaries-extra} v1.12}, + to store the control sequence name for use with \csref{glsxtrfmt}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -7756,7 +9244,7 @@ option}, user1={\margm{label}}, description={applies \cs{glsseeformat} to the entry's \field{see} field if not empty}, - note={provided by \styfmt{glossaries-extra} v1.06+}, + note={\styfmt{glossaries-extra} v1.06+}, category={command} } @@ -7765,15 +9253,15 @@ option}, user1={\margm{label}}, description={applies \cs{glsseeformat} to the entry's \field{seealso} field if not empty}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @index{glsxtrsetaliasnoindex, name={\csfmt{gls\-xtr\-set\-alias\-noindex}}, user1={}, - description={hooks into the alias \gls{gls.noindex} setting}, - note={provided by \styfmt{glossaries-extra} v1.12+}, + description={hooks into the alias \glsopt{noindex} setting}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @@ -7783,7 +9271,7 @@ option}, description={used to format the entries whose labels are given in \meta{xr list} as a list of \qt{see also} cross-references}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @@ -7791,7 +9279,7 @@ cross-references}, name={\csfmt{gls\-xtr\-index\-seealso}}, user1={\margm{label}\margm{xr list}}, description={indexes a \qt{see also} cross-reference}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @@ -7799,7 +9287,7 @@ cross-references}, name={\csfmt{glssee}}, user1={\oargm{tag}\margm{label}\margm{xr label list}}, description={indexes a \qt{see} cross-reference}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7808,7 +9296,7 @@ cross-references}, user1={\margm{xr label list}}, description={formats the list of cross-reference labels, without the initial \qt{see} tag}, - note={provided by \styfmt{glossaries-extra} v1.16+}, + note={\styfmt{glossaries-extra} v1.16+}, category={command} } @@ -7818,7 +9306,7 @@ the initial \qt{see} tag}, description={sets the abbreviation style to \meta{style-name} for the given \meta{category}, must be used before the abbreviation is defined}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -7826,7 +9314,7 @@ defined}, name={\csfmt{glshex}}, user1={}, description={expands to \cs{cs.string}\cs{u}}, - note={provided by \styfmt{glossaries-extra} v1.21+ (moved to + note={\styfmt{glossaries-extra} v1.21+ (moved to \styfmt{glossaries-extra-bib2gls} in v1.27)}, category={command} } @@ -7834,8 +9322,8 @@ defined}, @index{glscapturedgroup, name={\csfmt{glscapturedgroup}}, user1={}, - description={expands to \cs{cs.string}\gls{dollarchar}}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.31+}, + description={expands to \cs{cs.string}\idx{dollarchar}}, + note={\styfmt{glossaries-extra-bib2gls} v1.31+}, category={command} } @@ -7844,7 +9332,7 @@ defined}, user1={}, description={expands to the set of common entry aliases for \atentry{bibtexentry}}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.29+}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, category={command} } @@ -7853,16 +9341,25 @@ defined}, user1={}, description={defines the standard \BibTeX\ fields using \cs{glsaddstoragekey}}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.29+}, + note={\styfmt{glossaries-extra-bib2gls} v1.29+}, category={command} } @index{glsxtrprovidecommand, - name={\csfmt{glsxtrprovidecommand}}, + name={\csfmt{gls\-xtr\-provide\-command}}, user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, description={behaves like \cs{providecommand} in the document but like \cs{renewcommand} in \bibgls}, - note={provided by \styfmt{glossaries-extra-bib2gls} v1.27+}, + note={\styfmt{glossaries-extra-bib2gls} v1.27+}, + category={command} +} + +@index{glsrenewcommand, + name={\csfmt{gls\-re\-new\-command}}, + user1={\margm{cs}\oargm{n}\oargm{def}\margm{code}}, + description={behaves like \cs{renewcommand} but only generates a +warning rather than an error if the command isn't already defined}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, category={command} } @@ -7871,8 +9368,8 @@ defined}, user1={}, description={provides code that locally redefines commands during the protected write operation performed by - \cs{glsxtrresourcefile}}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + \csref{glsxtrresourcefile}}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -7881,7 +9378,7 @@ defined}, user1={}, description={expands to the field label used to store the entry group labels}, - note={provided by \styfmt{glossaries-extra} v1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -7889,7 +9386,7 @@ defined}, name={\csfmt{glo\-link\-prefix}}, user1={}, description={target name prefix used in entry hyperlinks}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7898,16 +9395,26 @@ defined}, user1={\oargm{type}\margm{code}}, description={appends \meta{code} to the preamble for the given glossary}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@index{glossarypreamble, + name={\csfmt{glossary\-preamble}}, + description={the preamble for all glossaries except + those that have the preamble explicitly set with + \cs{apptoglossarypreamble}}, + note={\styfmt{glossaries-extra}}, + seealso={apptoglossarypreamble}, category={command} } @index{glsbackslash, name={\csfmt{glsbackslash}}, user1={}, - description={expands to a literal backslash \texttt{\glsbackslash} + description={expands to a literal backslash \idx{backslashchar} character}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7916,7 +9423,7 @@ glossary}, user1={\margm{text}}, description={encapsulates \meta{text} with literal straight double-quotes \texttt{\glsquote{\meta{text}}}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7924,7 +9431,7 @@ glossary}, name={\csfmt{glstildechar}}, user1={}, description={expands to a literal tilde \texttt{\glstildechar} character}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7933,7 +9440,7 @@ glossary}, user1={}, description={language-sensitive name used for the location list header for some glossary styles}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -7941,7 +9448,7 @@ glossary}, name={\csfmt{seealsoname}}, user1={}, description={language sensitive \qt{see also} text}, - note={provided by \styfmt{glossaries-extra} or language + note={\styfmt{glossaries-extra} or language packages}, category={command} } @@ -7952,7 +9459,7 @@ packages}, description={used by the parenthetical abbreviation styles, this expands to the label of the field used to store the parenthetical material}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra} v1.04+}, category={command} } @@ -7964,9 +9471,9 @@ packages}, to format the parenthetical material where \meta{text} is the default parenthetical text and \meta{label} is the entry's label. This checks the field given - by \gls{glsxtruserfield} and, if set, the \meta{text} is + by \cs{glsxtruserfield} and, if set, the \meta{text} is followed by a comma and the user value}, - note={provided by \styfmt{glossaries-extra} v1.04+}, + note={\styfmt{glossaries-extra} v1.04+}, category={command} } @@ -7974,7 +9481,7 @@ packages}, name={\csfmt{gls\-xtr\-full\-sep}}, user1={\margm{label}}, description={the separator used in the full format for the parenthetical styles}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -7983,16 +9490,16 @@ packages}, user1={\margm{label}\margm{text}}, description={encapsulates \meta{text} in \csfmt{foreignlanguage} where the language label is obtained from the locale tag - given in the field identified by \gls{GlsXtrForeignTextField}}, - note={provided by \styfmt{glossaries-extra} v1.32+}, + given in the field identified by \cs{GlsXtrForeignTextField}}, + note={\styfmt{glossaries-extra} v1.32+}, category={command} } @index{GlsXtrForeignTextField, name={\csfmt{Gls\-Xtr\-Foreign\-Text\-Field}}, - description={used by \gls{GlsXtrForeignText} to identify + description={used by \cs{GlsXtrForeignText} to identify the field containing the locale tag}, - note={provided by \styfmt{glossaries-extra} v1.32+}, + note={\styfmt{glossaries-extra} v1.32+}, category={command} } @@ -8000,7 +9507,7 @@ packages}, name={\csfmt{gls\-xtr\-paren}}, user1={\margm{text}}, description={used to markup parenthetical material}, - note={provided by \styfmt{glossaries-extra} v1.17+}, + note={\styfmt{glossaries-extra} v1.17+}, category={command} } @@ -8010,7 +9517,7 @@ packages}, description={hook used after the description is displayed in the glossary for entries that have the \field{category} set to \code{abbreviation}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8020,7 +9527,7 @@ packages}, description={hook used after the description is displayed in the glossary for entries that have the \field{category} set to \code{symbol}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8030,7 +9537,7 @@ packages}, description={hook used after the description is displayed in the glossary for entries that have the \field{category} set to \code{general}}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8039,21 +9546,18 @@ packages}, user1={}, description={hook used after the description is displayed in the glossary for entries that have the - \field{category} set to \meta{category}}, - note={common category hooks such as - \cs{glsxtrpostdescgeneral} are provided by -\styfmt{glossaries-extra}, custom categories need the hook defined}, + \field{category} set to \meta{category}. Common category hooks + such as \cs{glsxtrpostdescgeneral} are provided by + \styfmt{glossaries-extra}, custom categories need the hook defined}, category={command} } @index{glsxtrpostnamecategory, name={\csfmt{gls\-xtr\-post\-name\-\meta{category}}}, user1={}, - description={hook used after the name is displayed in the - glossary for entries that have the - \field{category} set to \meta{category}}, - note={user needs to define hook for use with - \styfmt{glossaries-extra}}, + description={hook used by \cs{glossentryname} for entries + that have the \field{category} set to \meta{category}. + If required, this hook can be defined with \cs{glsdefpostname}}, category={command} } @@ -8062,40 +9566,59 @@ packages}, user1={}, description={hook used after commands like \cs{gls} for entries that have the - \field{category} set to \meta{category}}, - note={user needs to define hook for use with - \styfmt{glossaries-extra}}, + \field{category} set to \meta{category}. If required, + this hook can be defined with \cs{glsdefpostlink}}, category={command} } @index{GlsXtrFmtDefaultOptions, name={\csfmt{Gls\-Xtr\-Fmt\-Default\-Options}}, user1={}, - description={the default options used by \cs{glsxtrfmt}}, - note={provided by \styfmt{glossaries-extra}}, + description={the default options used by \csref{glsxtrfmt}}, + note={\styfmt{glossaries-extra} v1.12+}, category={command} } @index{glslink, name={\csfmt{glslink}}, - user1={\oargm{options}\margm{label}\oargm{text}}, + user1={\oargm{options}\margm{label}\margm{text}}, description={links to the entry's location in the glossary with the given link text without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={glsdisp}, category={command} } @index{glsdisp, name={\csfmt{glsdisp}}, - user1={\oargm{options}\margm{label}\oargm{text}}, + user1={\oargm{options}\margm{label}\margm{text}}, description={links to the entry's location in the glossary with the given link text and marks the entry as having been used}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, seealso={glslink}, category={command} } +@index{dglslink, + name={\csfmt{dgls\-link}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={like \cs{glslink} but tries the prefixes + identified with commands like \cs{glsxtraddlabelprefix}}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dglsdisp}, + category={command} +} + +@index{dglsdisp, + name={\csfmt{dgls\-disp}}, + user1={\oargm{options}\margm{label}\margm{text}}, + description={like \cs{glsdisp} but tries the prefixes + identified with commands like \cs{glsxtraddlabelprefix}}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dglsdisp}, + category={command} +} + @index{glsxtrshort, name={\csfmt{glsxtrshort}}, user1={\oargm{options}\margm{label}}, @@ -8103,7 +9626,7 @@ packages}, the link text obtained from the \field{short} field (using the appropriate abbreviation style) without altering the first use flag}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8114,7 +9637,7 @@ packages}, the link text obtained from the \field{long} field (using the appropriate abbreviation style) without altering the first use flag}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8126,7 +9649,7 @@ packages}, fields (using the appropriate abbreviation style) without altering the first use flag}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -8135,7 +9658,7 @@ fields (using the user1={\margm{text}}, description={used to encapsulate each word in the long form of an abbreviation by the \catattr{markwords} attribute}, - note={provided by \styfmt{glossaries-extra} v1.17+}, + note={\styfmt{glossaries-extra} v1.17+}, category={command} } @@ -8143,7 +9666,7 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{glsxtrwordsep}}, description={used to mark spaces between each word in the long form of an abbreviation by the \catattr{markwords} attribute}, - note={provided by \styfmt{glossaries-extra} v1.17+}, + note={\styfmt{glossaries-extra} v1.17+}, category={command} } @@ -8153,7 +9676,16 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{text} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{Glstext, + name={\csfmt{Glstext}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={as \cs{glstext} but converts the first letter to + \idx{uppercase}}, + note={\styfmt{glossaries}}, category={command} } @@ -8163,7 +9695,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{name} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8173,7 +9705,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{first} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8183,7 +9715,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{symbol} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8193,7 +9725,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{description} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8203,7 +9735,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user1} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8213,7 +9745,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user2} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8223,7 +9755,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user3} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8233,7 +9765,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user4} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8243,7 +9775,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user5} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8253,7 +9785,7 @@ abbreviation by the \catattr{markwords} attribute}, description={links to the entry's location in the glossary with the link text obtained from the \field{user6} field without altering the first use flag}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8262,16 +9794,16 @@ abbreviation by the \catattr{markwords} attribute}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={like \cs{gls} but checks for the record count trigger setting}, - note={provided by \styfmt{glossaries-extra} version 1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @dualindexentry{rglsformat, name={\csfmt{rglsformat}}, user1={\margm{label}\oargm{insert}}, - description={used by \cs{rgls} if the record count + description={used by \csref{rgls} if the record count switch is triggered}, - note={provided by \styfmt{glossaries-extra} version 1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -8279,8 +9811,8 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{glsxtr\-enable\-record\-count}}, user1={}, description={redefines \cs{gls} etc to their - \cs{rgls} counterpart}, - note={provided by \styfmt{glossaries-extra} version 1.21+}, + \csref{rgls} counterpart}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -8289,7 +9821,7 @@ abbreviation by the \catattr{markwords} attribute}, user1={\margm{category list}\margm{value}}, description={sets the \catattr{recordcount} attribute to \meta{value} for the given categories}, - note={provided by \styfmt{glossaries-extra} version 1.21+}, + note={\styfmt{glossaries-extra} v1.21+}, category={command} } @@ -8303,7 +9835,7 @@ abbreviation by the \catattr{markwords} attribute}, \field{text} field for general entries) where the text is optionally hyperlinked to the relevant place in the glossary}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8325,6 +9857,12 @@ abbreviation by the \catattr{markwords} attribute}, parent={gls} } +@index{gls.hyper, + name={\csoptfmt{hyper}}, + category={commandoption}, + parent={gls} +} + @index{gls.textformat, name={\csoptfmt{text\-format}}, category={commandoption}, @@ -8347,7 +9885,7 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{glspl}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={as \cs{gls} but shows the plural form}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8356,7 +9894,7 @@ abbreviation by the \catattr{markwords} attribute}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={as \cs{gls} but converts the first letter of the link text to upper case}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8364,7 +9902,7 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{Glspl}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={as \cs{Gls} but shows the plural form}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8372,7 +9910,7 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{GLS}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={as \cs{gls} but converts the link text to upper case}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8380,17 +9918,88 @@ abbreviation by the \catattr{markwords} attribute}, name={\csfmt{GLSpl}}, user1={\oargm{options}\margm{label}\oargm{insert}}, description={as \cs{GLS} but shows the plural form}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @index{pgls, name={\csfmt{pgls}}, user1={\oargm{options}\margm{label}\oargm{insert}}, - description={does \meta{prefix}\gls{gls}\oargm{options}\margm{label}\oargm{insert}, + description={does \meta{prefix}\cs{gls}\oargm{options}\margm{label}\oargm{insert}, where the \meta{prefix} is obtained from the appropriate prefix field}, - note={provided by \styfmt{glossaries-prefix}}, + note={\styfmt{glossaries-prefix}}, + category={command} +} + +@index{dgls, + name={\csfmt{dgls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{gls} but tries to + determine the label prefix from the label prefix list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@index{dglspl, + name={\csfmt{dglspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{glspl} but tries to + determine the label prefix from the label prefix list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@index{dGls, + name={\csfmt{dGls}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{Gls} but tries to + determine the label prefix from the label prefix list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@index{dGlspl, + name={\csfmt{dGlspl}}, + user1={\oargm{options}\margm{label}\oargm{insert}}, + description={intended for documents with a mixture of + single and dual entries, this is like \cs{Glspl} but tries to + determine the label prefix from the label prefix list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, + category={command} +} + +@index{glsxtraddlabelprefix, + name={\csfmt{gls\-xtr\-add\-label\-prefix}}, + user1={\margm{prefix}}, + description={appends \meta{prefix} to the prefix label list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dgls,glsxtrprependlabelprefix,glsxtrclearlabelprefixes}, + category={command} +} + +@index{glsxtrprependlabelprefix, + name={\csfmt{gls\-xtr\-prepend\-label\-prefix}}, + user1={\margm{prefix}}, + description={prepends \meta{prefix} to the prefix label list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={dgls,glsxtraddlabelprefix,glsxtrclearlabelprefixes}, + category={command} +} + +@index{glsxtrclearlabelprefixes, + name={\csfmt{gls\-xtr\-clear\-label\-prefixes}}, + user1={\margm{prefix}}, + description={clears the prefix label list}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsxtraddlabelprefix,glsxtrprependlabelprefix}, category={command} } @@ -8399,7 +10008,51 @@ abbreviation by the \catattr{markwords} attribute}, user1={\oargm{level}\margm{text}}, description={used with the \glostyle{alttree} style to set the widest entry name for the given level}, - note={provided by \styfmt{glossary-tree}}, + note={\styfmt{glossary-tree}}, + category={command} +} + +@index{glsxtrSetWidest, + name={\csfmt{gls\-xtr\-Set\-Widest}}, + user1={\margm{type}\margm{level}\margm{text}}, + description={used by \csref{bibglssetwidest} to set the + widest entry name for the given level for the \glostyle{alttree} + style and the styles provided by \sty{glossary-longextra}}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glssetwidest,glslongextraSetWidest}, + category={command} +} + +@index{glsxtrSetWidestFallback, + name={\csfmt{gls\-xtr\-Set\-Widest\-Fallback}}, + user1={\margm{max depth}\margm{list}}, + description={used by \csref{bibglssetwidesttoplevelfallback} and + \csref{bibglssetwidestfallback} to set the + widest entry name for the \glostyle{alttree} + style and the styles provided by \sty{glossary-longextra} + using the commands provided by \sty{glossaries-extra-stylemods}}, + note={\styfmt{glossaries-extra-bib2gls} v1.37+}, + seealso={glsFindWidestTopLevelName,glsFindWidestLevelTwo}, + category={command} +} + +@index{glslongextraSetWidest, + name={\csfmt{gls\-long\-extra\-Set\-Widest}}, + user1={\margm{text}}, + description={used with the styles provided by the + \sty{glossary-longextra} package to set the + widest entry name}, + note={\styfmt{glossary-longextra} v1.37+}, + seealso={glslongextraUpdateWidest}, + category={command} +} + +@index{glslongextraUpdateWidest, + name={\csfmt{gls\-long\-extra\-Update\-Widest}}, + user1={\margm{text}}, + description={as \cs{glslongextraSetWidest} but only sets if \meta{text} is + wider than the current value}, + note={\styfmt{glossary-longextra} v1.37+}, category={command} } @@ -8408,8 +10061,7 @@ abbreviation by the \catattr{markwords} attribute}, user1={\oargm{level}\margm{text}}, description={as \cs{glssetwidest} but only sets if \meta{text} is wider than the current value}, - note={provided by \styfmt{glossaries-extra-stylemods} version -1.23+}, + note={\styfmt{glossaries-extra-stylemods} v1.23+}, seealso={glssetwidest,eglsupdatewidest}, category={command} } @@ -8418,8 +10070,7 @@ wider than the current value}, name={\csfmt{egls\-update\-widest}}, user1={\oargm{level}\margm{text}}, description={as \cs{glsupdatewidest} but expands \meta{text}}, - note={provided by \styfmt{glossaries-extra-stylemods} version -1.23+}, + note={\styfmt{glossaries-extra-stylemods} v1.23+}, seealso={glssetwidest,glsupdatewidest}, category={command} } @@ -8428,7 +10079,7 @@ wider than the current value}, name={\csfmt{gls\-Find\-Widest\-Top\-Level\-Name}}, user1={\oargm{glossary list}}, description={CamelCase synonym for \cs{glsfindwidesttoplevelname}}, - note={provided by \styfmt{glossaries-extra-stylemods}}, + note={\styfmt{glossaries-extra-stylemods}}, seealso={glsfindwidesttoplevelname}, category={command} } @@ -8438,7 +10089,7 @@ wider than the current value}, user1={\oargm{glossary list}}, description={finds the widest top-level name in the given glossaries}, - note={provided by \styfmt{glossary-tree}}, + note={\styfmt{glossary-tree}}, category={command} } @@ -8447,7 +10098,7 @@ glossaries}, user1={\oargm{glossary list}}, description={finds the widest name in the given glossaries for the top level and first two sub-levels}, - note={provided by \styfmt{glossaries-extra-stylemods}}, + note={\styfmt{glossaries-extra-stylemods}}, seealso={glsfindwidesttoplevelname}, category={command} } @@ -8457,7 +10108,27 @@ glossaries}, user1={\margm{label}}, description={used with the \glostyle{bookindex} style to format the entry's name}, - note={provided by \styfmt{glossary-bookindex}}, + note={\styfmt{glossary-bookindex}}, + category={command} +} + +@index{glsxtrbookindexprelocation, + name={\csfmt{glsxtr\-book\-index\-pre\-location}}, + user1={\margm{label}}, + description={used with the \glostyle{bookindex} style before the +location list}, + note={\styfmt{glossary-bookindex}}, + category={command} +} + +@index{glsxtrprelocation, + name={\csfmt{glsxtr\-pre\-location}}, + user1={}, + description={used before the location list in the + \glostyle{bookindex} style and the styles patched by + \styfmt{glossaries-extra-stylemods}}, + note={\styfmt{glossary-bookindex} v1.21+ and + \styfmt{glossaries-extra-stylemods} v1.21+}, category={command} } @@ -8465,27 +10136,123 @@ glossaries}, name={\csfmt{gls\-abbrv\-sc\-font}}, user1={\margm{text}}, description={used with \qt{sc} abbreviation styles to format the -short form using \gls{textsc}}, - note={provided by \styfmt{glossaries-extra} v1.17+}, +short form using \cs{textsc}}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@index{glsabbrvonlyfont, + name={\csfmt{gls\-abbrv\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +short form}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@index{glslongonlyfont, + name={\csfmt{gls\-long\-only\-font}}, + user1={\margm{text}}, + description={used with \qt{only} abbreviation styles to format the +long form}, + note={\styfmt{glossaries-extra} v1.17+}, + category={command} +} + +@index{glsabbrvfont, + name={\csfmt{gls\-abbrv\-font}}, + user1={\margm{text}}, + description={generic abbreviation font command for the short form}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@index{glslongfont, + name={\csfmt{gls\-long\-font}}, + user1={\margm{text}}, + description={generic abbreviation font command for the long form}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@index{glsshorttok, + name={\csfmt{gls\-short\-tok}}, + description={token register used in the construction of + acronyms or abbreviations to allow the style hooks to access the short form}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glslongtok, + name={\csfmt{gls\-long\-tok}}, + description={token register used in the construction of + acronyms or abbreviations to allow the style hooks to access the long form}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{glsuserdescription, + name={\csfmt{gls\-user\-description}}, + user1={\margm{description}\margm{label}}, + description={used with \qt{user} abbreviation styles to + encapsulate the description. Just does + \code{\cs{glslonguserfont}\margm{description}} by default}, + note={\styfmt{glossaries-extra} v1.30+}, + category={command} +} + +@index{glslonguserfont, + name={\csfmt{gls\-long\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the long form}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@index{glsfirstlonguserfont, + name={\csfmt{gls\-first\-long\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the long form on first use}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@index{glsabbrvuserfont, + name={\csfmt{gls\-abbrv\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the short form}, + note={\styfmt{glossaries-extra} v1.04+}, + category={command} +} + +@index{glsfirstabbrvuserfont, + name={\csfmt{gls\-first\-abbrv\-user\-font}}, + user1={\margm{text}}, + description={used with \qt{user} abbreviation styles to + format the short form on first use}, + note={\styfmt{glossaries-extra} v1.04+}, category={command} } @index{glsxtrifinmark, name={\csfmt{gls\-xtr\-if\-in\-mark}}, user1={\margm{true}\margm{true}}, - description={used by commands like \gls{glsfmtshort}, this expands + description={used by commands like \cs{glsfmtshort}, this expands to \meta{true} in page headings and the table of contents, otherwise it expands to \meta{false}}, - note={provided by \styfmt{glossaries-extra} v1.07+}, + note={\styfmt{glossaries-extra} v1.07+}, category={command} } @index{glsxtrRevertTocMarks, name={\csfmt{gls\-xtr\-Revert\-Toc\-Marks}}, - description={restores original behaviour of \gls{tableofcontents} - so that \gls{glsxtrifinmark} expands to \meta{false} in the table + description={restores original behaviour of \cs{tableofcontents} + so that \cs{glsxtrifinmark} expands to \meta{false} in the table of contents}, - note={provided by \styfmt{glossaries-extra} v1.07+}, + note={\styfmt{glossaries-extra} v1.07+}, category={command} } @@ -8493,7 +10260,7 @@ of contents}, name={\csfmt{gls\-tree\-name\-fmt}}, user1={\margm{text}}, description={used with the tree styles to format the entry's name}, - note={provided by \styfmt{glossary-tree} v4.08+ and redefined by + note={\styfmt{glossary-tree} v4.08+ and \styfmt{glossaries-extra-stylemods} v1.31+}, seealso={glstreegroupheaderfmt,glstreenavigationfmt,glstreedefaultnamefmt}, category={command} @@ -8504,8 +10271,8 @@ of contents}, user1={\margm{text}}, description={used with the tree styles to format the group headings}, - note={provided by \styfmt{glossary-tree} v4.22+ and redefined - by \styfmt{glossaries-extra-stylemods} v1.31+}, + note={\styfmt{glossary-tree} v4.22+ and + \styfmt{glossaries-extra-stylemods} v1.31+}, category={command} } @@ -8514,8 +10281,8 @@ headings}, user1={\margm{text}}, description={used with the tree styles to format the navigation elements}, - note={provided by \styfmt{glossary-tree} v4.22+ and redefined - by \styfmt{glossaries-extra-stylemods} v1.31+}, + note={\styfmt{glossary-tree} v4.22+ and + \styfmt{glossaries-extra-stylemods} v1.31+}, category={command} } @@ -8524,7 +10291,15 @@ elements}, user1={\margm{text}}, description={used as the default format for \cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and \cs{glstreenavigationfmt}}, - note={provided by \styfmt{glossaries-extra-stylemods} v1.31+}, + note={\styfmt{glossaries-extra-stylemods} v1.31+}, + category={command} +} + +@index{glstreeprelocation, + name={\csfmt{gls\-tree\-pre\-location}}, + description={inserted before the location list for top-level +entries in the \glostyle{tree}-like styles}, + note={\styfmt{glossaries-extra-stylemods} v1.21+}, category={command} } @@ -8533,7 +10308,7 @@ elements}, user1={}, description={length register used by the tabular styles to specify the width of the description column}, - note={provided by \styfmt{glossary-long} and + note={\styfmt{glossary-long} and \styfmt{glossary-super}}, category={command} } @@ -8543,80 +10318,15 @@ the width of the description column}, user1={\margm{label}\margm{location list}}, description={used by the \glostyle{alttree} styles to format the symbol, description and location}, - note={provided by \styfmt{glossaries-extra-stylemods}}, - category={command} -} - -@index{glsentrylong, - name={\csfmt{gls\-entry\-long}}, - user1={\margm{label}}, - description={displays the long form without any formatting or -indexing}, - note={provided by \styfmt{glossaries}}, - category={command} -} - -@index{glossentryname, - name={\csfmt{gloss\-entry\-name}}, - user1={\margm{label}}, - description={used by glossary styles to display the name}, - note={provided by \styfmt{glossaries}}, - category={command} -} - -@index{glsnamefont, - name={\csfmt{gls\-name\-font}}, - user1={\margm{text}}, - description={used by \cs{glossentryname} to format the name}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries-extra-stylemods} v1.05+}, category={command} } -@index{glossentrynameother, - name={\csfmt{gloss\-entry\-name\-other}}, - user1={\margm{label}\margm{field}}, - description={acts like \ics{glossentryname} (obeys - \catattr{glossname} and \catattr{glossnamefont} - or \cs{glsnamefont} and the post-name hook) but uses - the given \meta{field} instead of the \field{name} field}, - note={provided by \styfmt{glossaries-extra} v1.22+}, - category={command} -} - -@index{glossentrydesc, - name={\csfmt{gloss\-entry\-desc}}, - user1={\margm{label}}, - description={used by glossary styles to display the description}, - note={provided by \styfmt{glossaries}}, - category={command} -} - -@index{Glossentrydesc, - name={\csfmt{Gloss\-entry\-desc}}, - user1={\margm{label}}, - description={like \cs{glossentrydesc} but converts the first -letter to uppercase}, - note={provided by \styfmt{glossaries}}, - category={command} -} - -@index{glossentrysymbol, - name={\csfmt{gloss\-entry\-symbol}}, - user1={\margm{label}}, - description={used by glossary styles to display the symbol}, - note={provided by \styfmt{glossaries}}, - category={command} -} - -@index{glspostdescription, - name={\csfmt{glspostdescription}}, - description={a hook added after the description in some glossary -styles (all if the \sty{glossaries-extra-stylemods} package is -loaded to patch them). This hook is used to reflect the -\gls{styopt.nopostdot} package option for \sty{glossaries} -and the \styopt{postpunc} option for \sty{glossaries-extra}}, - note={provided by \styfmt{glossaries} and modified by -\styfmt{glossaries-extra}}, +@index{glsxtrAltTreePar, + name={\csfmt{gls\-xtr\-Alt\-Tree\-Par}}, + description={used by the \glostyle{alttree} styles to indicate a +paragraph break that retains the hanging indent}, + note={\styfmt{glossaries-extra-stylemods} v1.05+}, category={command} } @@ -8625,7 +10335,7 @@ and the \styopt{postpunc} option for \sty{glossaries-extra}}, user1={\margm{accessible text}\margm{text}}, description={used by the accessibility support to interface with the \sty{accsupp} package}, - note={provided by \styfmt{glossaries-accsupp}}, + note={\styfmt{glossaries-accsupp}}, category={command} } @@ -8635,7 +10345,7 @@ the \sty{accsupp} package}, description={iterates over all entries defined in the listed glossaries and perform \meta{body} where you can use the control sequence \meta{cs} to reference the current label}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8647,7 +10357,7 @@ the \sty{accsupp} package}, by \meta{label} and performs \meta{handler}\margm{element} on each element of the list, where \meta{handler} is a control sequence which takes a single argument}, - note={provided by \styfmt{glossaries-extra} version 1.24+}, + note={\styfmt{glossaries-extra} v1.24+}, seealso={glsxtrendfor}, category={command} } @@ -8657,7 +10367,7 @@ the \sty{accsupp} package}, user1={}, description={may be used within the handler macro of \cs{glsxtrforcsvfield} to prematurely break the loop}, - note={provided by \styfmt{glossaries-extra} version 1.24+}, + note={\styfmt{glossaries-extra} v1.24+}, seealso={glsxtrforcsvfield}, category={command} } @@ -8666,7 +10376,7 @@ the \sty{accsupp} package}, name={\csfmt{Track\-Locale}}, user1={\margm{language tag}}, description={tracks the given language tag}, - note={provided by \styfmt{tracklang} version 1.3+}, + note={\styfmt{tracklang} v1.3+}, category={command} } @@ -8677,16 +10387,16 @@ the \sty{accsupp} package}, given language tag and stores it in the command \meta{cs}. The result will be empty if there's no tracked dialect associated with the given language tag}, - note={provided by \styfmt{tracklang} version 1.3+}, + note={\styfmt{tracklang} v1.3+}, category={command} } @index{TrackedDialectClosestSubMatch, name={\csfmt{Tracked\-Dialect\-Closest\-Sub\-Match}}, - description={set by \gls{GetTrackedDialectFromLanguageTag} + description={set by \cs{GetTrackedDialectFromLanguageTag} if an exact match isn't found but a partial match on the root language is found}, - note={provided by \styfmt{tracklang} version 1.3.6+}, + note={\styfmt{tracklang} v1.3.6+}, category={command} } @@ -8695,7 +10405,7 @@ the given language tag}, user1={\margm{tracklang label}\margm{true}\margm{false}}, description={tests if the \styfmt{tracklang} dialect label has been assigned a mapping to a language hook label}, - note={provided by \styfmt{tracklang} version 1.3+}, + note={\styfmt{tracklang} v1.3+}, category={command} } @@ -8704,7 +10414,7 @@ been assigned a mapping to a language hook label}, user1={\margm{tracklang label}}, description={the language hook label corresponding to the given \sty{tracklang} label}, - note={provided by \styfmt{tracklang} version 1.3+}, + note={\styfmt{tracklang} v1.3+}, category={command} } @@ -8713,7 +10423,7 @@ been assigned a mapping to a language hook label}, user1={\margm{text}}, description={used by commands like \cs{gls} to format the \idx{link-text}}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8722,7 +10432,7 @@ been assigned a mapping to a language hook label}, user1={\margm{text}}, description={used by commands like \cs{gls} to format the \idx{link-text} for regular terms}, - note={provided by \styfmt{glossaries-extra} v1.04+}, + note={\styfmt{glossaries-extra} v1.04+}, category={command} } @@ -8731,7 +10441,7 @@ been assigned a mapping to a language hook label}, user1={\margm{text}}, description={used by commands like \cs{gls} to format the \idx{link-text} for (non-regular) abbreviations}, - note={provided by \styfmt{glossaries-extra} v1.30+}, + note={\styfmt{glossaries-extra} v1.30+}, category={command} } @@ -8740,7 +10450,7 @@ been assigned a mapping to a language hook label}, user1={\margm{cs}\margm{text}}, description={fully expands \meta{text} and then does \meta{cs}\margm{expanded text}}, - note={provided by \styfmt{glossaries-extra} v1.30+}, + note={\styfmt{glossaries-extra} v1.30+}, category={command} } @@ -8749,10 +10459,10 @@ been assigned a mapping to a language hook label}, description={starts buffering calls to \cs{glsunset} for use in code where the boolean switch causes a problem. The buffer can later be processed and cleared with - \gls{GlsXtrStopUnsetBuffering}. The starred form + \cs{GlsXtrStopUnsetBuffering}. The starred form (added to v1.31) avoids duplicate labels in the buffer's internal list}, - note={provided by \styfmt{glossaries-extra} v1.30+}, + note={\styfmt{glossaries-extra} v1.30+}, category={command} } @@ -8761,8 +10471,8 @@ been assigned a mapping to a language hook label}, description={unsets (locally with the starred form) all the entry whose labels are stored in the buffer that was started with - \gls{GlsXtrStartUnsetBuffering} and clears the buffer}, - note={provided by \styfmt{glossaries-extra} v1.30+}, + \cs{GlsXtrStartUnsetBuffering} and clears the buffer}, + note={\styfmt{glossaries-extra} v1.30+}, category={command} } @@ -8772,9 +10482,9 @@ been assigned a mapping to a language hook label}, description={iterates over all the entry whose labels are stored in the buffer that was started with - \gls{GlsXtrStartUnsetBuffering} and implements + \cs{GlsXtrStartUnsetBuffering} and implements \meta{cs}\margm{label} at each iteration}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -8783,7 +10493,7 @@ been assigned a mapping to a language hook label}, user1 = {\margm{label}}, description={unsets the \idx{firstuseflag} so that the entry is marked as having been used}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8792,7 +10502,7 @@ marked as having been used}, user1 = {\margm{label}}, description={resets the \idx{firstuseflag} so that the entry is marked as not used}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -8800,7 +10510,7 @@ marked as not used}, name={\csfmt{Track\-Lang\-Last\-Tracked\-Dialect}}, user1={}, description={set by commands like \cs{TrackLocale}}, - note={provided by \styfmt{tracklang}}, + note={\styfmt{tracklang}}, category={command} } @@ -8809,7 +10519,7 @@ marked as not used}, user1={\margm{dialect}}, description={expands to the root language associated with the given (\styfmt{tracklang}) dialect label}, - note={provided by \styfmt{tracklang}}, + note={\styfmt{tracklang}}, category={command} } @@ -8818,7 +10528,7 @@ given (\styfmt{tracklang}) dialect label}, user1={\margm{year}\margm{month}\margm{day}\margm{dow}}, description={formats the given date where all arguments are numeric}, - note={provided by \styfmt{datetime2}}, + note={\styfmt{datetime2}}, category={command} } @@ -8826,7 +10536,7 @@ given (\styfmt{tracklang}) dialect label}, name={\csfmt{DTL\-format\-list}}, user1={\margm{list}}, description={formats a comma-separated list}, - note={provided by \styfmt{datatool-base}}, + note={\styfmt{datatool-base}}, category={command} } @@ -8835,7 +10545,7 @@ given (\styfmt{tracklang}) dialect label}, user1={}, description={used by \ics{DTLformatlist} to separate items in the list, except for the last pair}, - note={provided by \styfmt{datatool-base}}, + note={\styfmt{datatool-base}}, seealso={DTLformatlist}, category={command} } @@ -8845,7 +10555,7 @@ list, except for the last pair}, user1={}, description={used by \ics{DTLformatlist} to separate the last two items in the list}, - note={provided by \styfmt{datatool-base}}, + note={\styfmt{datatool-base}}, seealso={DTLformatlist}, category={command} } @@ -8855,7 +10565,7 @@ list}, user1={}, description={insert before \ics{DTLlistformatlastsep} if the list has three or more items}, - note={provided by \styfmt{datatool-base}}, + note={\styfmt{datatool-base}}, seealso={DTLformatlist}, category={command} } @@ -8864,7 +10574,7 @@ has three or more items}, name={\csfmt{DTL\-and\-name}}, user1={}, description={used in the definition of \ics{DTLlistformatlastsep}}, - note={provided by \styfmt{datatool-base}}, + note={\styfmt{datatool-base}}, seealso={DTLformatlist}, category={command} } @@ -8873,7 +10583,7 @@ has three or more items}, name={\csfmt{si}}, user1={\margm{unit}}, description={displays the unit with intelligent formatting}, - note={provided by \styfmt{siunitx}}, + note={\styfmt{siunitx}}, category={command} } @@ -8881,7 +10591,52 @@ has three or more items}, name={\csfmt{ce}}, user1={\margm{formula}}, description={displays the chemical formula}, - note={provided by \styfmt{mhchem}}, + note={\styfmt{mhchem}}, + category={command} +} + +@index{textweathersymbol, + name={\csfmt{text\-weather\-symbol}}, + user1={\margm{number}}, + description={displays weather symbol identified by \meta{number}}, + note={\styfmt{ifsym}}, + category={command} +} + +@index{toprule, + name={\csfmt{top\-rule}}, + description={horizontal rule for the top of a \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@index{midrule, + name={\csfmt{mid\-rule}}, + description={horizontal rule for divider between header and main + content of a \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@index{bottomrule, + name={\csfmt{bottom\-rule}}, + description={horizontal rule for the bottom of a + \envfmt{tabular}-like environment}, + note={\styfmt{booktabs}}, + category={command} +} + +@index{endhead, + name={\csfmt{end\-head}}, + description={ends the header section}, + note={\styfmt{longtable}}, + category={command} +} + +@index{endfoot, + name={\csfmt{end\-foot}}, + description={ends the footer section}, + note={\styfmt{longtable}}, category={command} } @@ -8889,7 +10644,7 @@ has three or more items}, name={\csfmt{MakeTextLowercase}}, user1={\margm{text}}, description={converts \meta{text} to lower case}, - note={provided by \styfmt{textcase}}, + note={\styfmt{textcase}}, category={command} } @@ -8897,7 +10652,7 @@ has three or more items}, name={\csfmt{MakeTextUppercase}}, user1={\margm{text}}, description={converts \meta{text} to upper case}, - note={provided by \styfmt{textcase}}, + note={\styfmt{textcase}}, category={command} } @@ -8906,7 +10661,7 @@ has three or more items}, user1={\margm{text}}, description={prevents \cs{MakeTextUppercase} and \cs{MakeTextLowercase} from converting \meta{text}}, - note={provided by \styfmt{textcase}}, + note={\styfmt{textcase}}, category={command} } @@ -8921,7 +10676,29 @@ has three or more items}, @index{char, name={\csfmt{char}}, user1={\meta{number}}, - description={accesses the character identified by \meta{number}}, + description={accesses the character identified by \meta{number} +(use \code{\csfmt{char}\idx{doublequotecharhex}\meta{hex}} if the +number is hexadecimal)}, + note={{}\TeX\ primitive}, + category={command} +} + +@index{number, + name={\csfmt{number}}, + user1={\meta{value}}, + description={expands the given numerical \meta{value} to + a base~10 integer number stripping any leading + zeros (use \code{\csfmt{char}\idx{doublequotecharhex}\meta{hex}} + if the value is hexadecimal)}, + note={{}\TeX\ primitive}, + category={command} +} + +@index{the, + name={\csfmt{the}}, + user1={\meta{register}}, + description={expands \meta{register} to the current value of the + register}, note={{}\TeX\ primitive}, category={command} } @@ -8975,6 +10752,146 @@ has three or more items}, category={command} } +@index{AA, + name={\csfmt{AA}}, + description={produces the \idx!{uppercase} A-ring character \AA}, + note={kernel command}, + category={command} +} + +@index{aa, + name={\csfmt{aa}}, + description={produces the \idx!{lowercase} a-ring character \aa}, + note={kernel command}, + category={command} +} + +@index{O, + name={\csfmt{O}}, + description={produces the \idx!{uppercase} O-slash character \O}, + note={kernel command}, + category={command} +} + +@index{o, + name={\csfmt{o}}, + description={produces the \idx!{lowercase} o-slash character \o}, + note={kernel command}, + category={command} +} + +@index{L, + name={\csfmt{L}}, + description={produces the \idx!{uppercase} L-slash character \L}, + note={kernel command}, + category={command} +} + +@index{l, + name={\csfmt{l}}, + description={produces the \idx!{lowercase} l-slash character \l}, + note={kernel command}, + category={command} +} + +@index{ae, + name={\csfmt{ae}}, + description={produces the \idx!{lowercase} \ae-ligature}, + note={kernel command}, + category={command} +} + +@index{AE, + name={\csfmt{AE}}, + description={produces the \idx!{uppercase} \AE-ligature}, + note={kernel command}, + category={command} +} + +@index{oe, + name={\csfmt{oe}}, + description={produces the \idx!{lowercase} \oe-ligature}, + note={kernel command}, + category={command} +} + +@index{OE, + name={\csfmt{OE}}, + description={produces the \idx!{uppercase} \OE-ligature}, + note={kernel command}, + category={command} +} + +@index{th, + name={\csfmt{th}}, + description={produces the \idx!{lowercase} thorn \th}, + note={kernel command}, + category={command} +} + +@index{TH, + name={\csfmt{TH}}, + description={produces the \idx!{uppercase} thorn \TH}, + note={kernel command}, + category={command} +} + +@index{ss, + name={\csfmt{ss}}, + description={produces the \idx!{lowercase} eszett \ss}, + note={kernel command}, + category={command} +} + +@index{SS, + name={\csfmt{SS}}, + description={produces the \idx!{uppercase} eszett \SS}, + note={kernel command}, + category={command} +} + +@index{ng, + name={\csfmt{ng}}, + description={produces the \idx!{lowercase} eng \ng}, + note={kernel command}, + category={command} +} + +@index{NG, + name={\csfmt{NG}}, + description={produces the \idx!{uppercase} eng \NG}, + note={kernel command}, + category={command} +} + +@index{dh, + name={\csfmt{dh}}, + description={produces the \idx!{lowercase} eth \dh}, + note={kernel command}, + category={command} +} + +@index{DH, + name={\csfmt{DH}}, + description={produces the \idx!{uppercase} eth \DH}, + note={kernel command}, + category={command} +} + +@index{dj, + name={\csfmt{dj}}, + description={produces the \idx!{lowercase} d-stroke \dj}, + note={kernel command}, + category={command} +} + +@index{DJ, + name={\csfmt{DJ}}, + description={produces the \idx!{uppercase} d-stroke \DJ}, + note={kernel command}, + category={command} +} + @index{textsuperscript, name={\csfmt{textsuperscript}}, user1={\margm{text}}, @@ -9064,12 +10981,26 @@ by \meta{name}}, category={command} } +@index{cs.color, + name={\csfmt{color}}, + user1={\oargm{model}\margm{spec}}, + description={switches the current font colour}, + note={\styfmt{color}}, + category={command} +} + +@index{textcolor, + name={\csfmt{textcolor}}, + user1={\oargm{model}\margm{spec}\margm{text}}, + description={typesets \meta{text} in the given colour}, + note={\styfmt{color}}, + category={command} +} + @index{cjkname, name={\csfmt{cjkname}}, user1={\margm{CJK characters}}, - description={displays \meta{CJK characters} in the appropriate - encoding}, - note={provided by \styfmt{CJKutf8}}, + description={example command}, category={command} } @@ -9077,7 +11008,7 @@ by \meta{name}}, name={\csfmt{citation}}, user1={\margm{label}}, description={written to the \ext{aux} file on each occurrence of - \gls[noindex]{cite}}, + \cs{cite}}, note={kernel command}, category={command} } @@ -9136,6 +11067,16 @@ occurred}, category={command} } +@index{autoref, + name={\csfmt{autoref}}, + user1={\margm{id}}, + description={cross-reference with textual tag inferred from the +associated counter}, + seealso={label}, + note={\sty{hyperref}}, + category={command} +} + @index{par, name={\csfmt{par}}, description={paragraph break}, @@ -9148,7 +11089,7 @@ occurred}, user1={\margm{target name}\margm{text}}, description={create a hyperlink to \meta{target name} with the given \meta{text}}, - note={provided by \styfmt{hyperref}}, + note={\styfmt{hyperref}}, category={command} } @@ -9157,10 +11098,58 @@ occurred}, user1={\margm{target name}\margm{text}}, description={create a hypertarget with the given \meta{target name} and the displayed \meta{text}}, - note={provided by \styfmt{hyperref}}, + note={\styfmt{hyperref}}, category={command} } +@index{cs.hyperref, + name={\csfmt{hyperref}}, + note={\styfmt{hyperref}}, + category={command} +} + +@index{cs.hyperref.ext, + parent={cs.hyperref}, + name={\csfmt{hyperref}}, + user1={\margm{URL}\margm{category}\margm{name}\margm{text}}, + description={create a hyperlink to an external location with + the anchor formed from \code{\meta{category}.\meta{name}} + and the displayed \meta{text}}, + category={command} +} + +@index{cs.hyperref.int, + parent={cs.hyperref}, + name={\csfmt{hyperref}}, + user1={\oargm{label}\margm{text}}, + description={create an internal hyperlink with + the displayed \meta{text} to the same place + that \code{\cs{ref}\margm{label}} would be linked. + Note that the \meta{label} argument isn't optional. The + square bracket notation disambiguates from the + syntax for the external form of \cs{cs.hyperref.ext}}, + category={command} +} + +@index{@currentlabelname, + name={\csfmt{@current\-label\-name}}, + user1={}, + description={used to store the current title information for the next instance + of \cs{label}}, + note={\styfmt{hyperref}}, + category={command} +} + +@index{@currentHref, + name={\csfmt{@current\-H\-ref}}, + user1={}, + description={used to store the current anchor for the next instance + of \cs{label}}, + note={\styfmt{hyperref}}, + category={command} +} + + @index{glsrefentry, name={\csfmt{gls\-ref\-entry}}, user1={\margm{label}}, @@ -9168,7 +11157,7 @@ name} and the displayed \meta{text}}, \styopt{subentrycounter} may be used to cross-reference the entry's number in the glossary list with \cs{ref}}, seealso={ref}, - note={provided by \styfmt{glossaries} v3.0+}, + note={\styfmt{glossaries} v3.0+}, category={command} } @@ -9179,7 +11168,7 @@ name} and the displayed \meta{text}}, \styopt{subentrycounter} may be used to cross-reference the entry's number in the glossary list with \cs{pageref}}, seealso={pageref}, - note={provided by \styfmt{glossaries-extra} v1.11}, + note={\styfmt{glossaries-extra} v1.11}, category={command} } @@ -9188,8 +11177,8 @@ name} and the displayed \meta{text}}, user1={\margm{label}}, description={displays the given entry name including a hypertarget (if \sty{hyperref} has been loaded) as the destination for commands like -\gls{gls}}, - note={provided by \styfmt{glossaries-extra} v1.21}, +\cs{gls}}, + note={\styfmt{glossaries-extra} v1.21}, category={command} } @@ -9200,7 +11189,7 @@ name} and the displayed \meta{text}}, in the supplied internal \meta{field} where \meta{header} is the code to use in the header (leave empty for default)}, - note={provided by \styfmt{glossaries-extra} v1.22+}, + note={\styfmt{glossaries-extra} v1.22+}, category={command} } @@ -9209,16 +11198,16 @@ to use in the header (leave empty for default)}, user1={\margm{label}}, description={used to show the target name when the \styopt[showtargets]{debug} option is on}, - note={provided by \styfmt{glossaries} v4.32+}, + note={\styfmt{glossaries} v4.32+}, category={command} } @index{GlsEntryCounterLabelPrefix, name={\csfmt{Gls\-Entry\-Counter\-Label\-Prefix}}, - description={used as a prefix in the \gls{label} command + description={used as a prefix in the \cs{label} command automatically implemented by the \styopt{entrycounter} and \styopt{subentrycounter} options}, - note={provided by \styfmt{glossaries} v4.38+}, + note={\styfmt{glossaries} v4.38+}, category={command} } @@ -9226,7 +11215,7 @@ to use in the header (leave empty for default)}, name={\csfmt{Gls\-Xtr\-Stand\-alone\-Glossary\-Type}}, description={expands to the label for \gls{currentglossary} within \gls{glsxtrglossentry} and \gls{glsxtrglossentryother}}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, category={command} } @@ -9235,7 +11224,25 @@ to use in the header (leave empty for default)}, user1 = {\margm{label}}, description={used within \gls{glsxtrglossentry} and \gls{glsxtrglossentryother} to display sub-item labels}, - note={provided by \styfmt{glossaries-extra} v1.31+}, + note={\styfmt{glossaries-extra} v1.31+}, + category={command} +} + +@index{GlsXtrStandaloneEntryName, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Entry\-Name}}, + user1 = {\margm{label}}, + description={used within \gls{glsxtrglossentry} to + display the name (with a hypertarget, if supported)}, + note={\styfmt{glossaries-extra} v1.37+}, + category={command} +} + +@index{GlsXtrStandaloneEntryOther, + name={\csfmt{Gls\-Xtr\-Stand\-alone\-Entry\-Other}}, + user1 = {\margm{label}\margm{field}}, + description={used within \gls{glsxtrglossentryother} to + display the given field value (with a hypertarget, if supported)}, + note={\styfmt{glossaries-extra} v1.37+}, category={command} } @@ -9243,7 +11250,16 @@ to use in the header (leave empty for default)}, name={\csfmt{gls\-reset\-entry\-counter}}, description={resets the \counter{glossaryentry} counter if the \styopt{entrycounter} setting is on}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, + category={command} +} + +@index{setentrycounter, + name={\csfmt{set\-entry\-counter}}, + user1={\oargm{prefix}\margm{counter}}, + description={sets up the entry's associated counter and prefix + required by \cs{glshypernumber}}, + note={\styfmt{glossaries}}, category={command} } @@ -9252,7 +11268,7 @@ to use in the header (leave empty for default)}, user1 = {\margm{\keyvallist}}, description={applies the base \styfmt{glossaries} options that are allowed to be changed after the package has loaded}, - note={provided by \styfmt{glossaries}}, + note={\styfmt{glossaries}}, category={command} } @@ -9261,7 +11277,7 @@ to use in the header (leave empty for default)}, user1 = {\margm{\keyvallist}}, description={applies the extension \styfmt{glossaries-extra} options that are allowed to be changed after the package has loaded}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9270,7 +11286,7 @@ to use in the header (leave empty for default)}, user1={\margm{label}}, description={separator used before the description for the \glostyle{tree} styles}, - note={provided by \styfmt{glossary-tree} v4.26+}, + note={\styfmt{glossary-tree} v4.26+}, category={command} } @@ -9280,7 +11296,7 @@ to use in the header (leave empty for default)}, description={displays the pre-description separator, the description and the post-description hook for the \glostyle{treenoname} styles}, - note={provided by \styfmt{glossaries-extra-stylemods} v1.31+}, + note={\styfmt{glossaries-extra-stylemods} v1.31+}, category={command} } @@ -9289,7 +11305,7 @@ to use in the header (leave empty for default)}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the short form of the given abbreviation}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9298,7 +11314,7 @@ displays the short form of the given abbreviation}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the long form of the given abbreviation}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9307,7 +11323,7 @@ displays the long form of the given abbreviation}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the full form of the given abbreviation}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9316,7 +11332,7 @@ displays the full form of the given abbreviation}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the given entry's name}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9325,7 +11341,7 @@ displays the given entry's name}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the given entry's \field{first} field}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, category={command} } @@ -9334,7 +11350,18 @@ displays the given entry's \field{first} field}, user1={\margm{label}}, description={provided for use in section or caption titles, this displays the given entry's \field{text} field}, - note={provided by \styfmt{glossaries-extra}}, + note={\styfmt{glossaries-extra}}, + category={command} +} + +@index{theHentrycounter, + name={\csfmt{the\-H\-entry\-counter}}, + user1={}, + description={when indexing, this is set to the + \csfmt{theH}\meta{counter} command corresponding to the + current indexing counter (or, if undefined, + \csfmt{the}\meta{counter})}, + note={\styfmt{glossaries}}, category={command} } @@ -9359,7 +11386,7 @@ sectioning commands to write to it}, name={\csfmt{ul}}, user1={\margm{text}}, description={underlines the given text}, - note={provided by \styfmt{soul}}, + note={\styfmt{soul}}, category={command} } @@ -9367,7 +11394,7 @@ sectioning commands to write to it}, name={\csfmt{ding}}, user1={\margm{number}}, description={displays the symbol associated with the given number}, - note={provided by \styfmt{pifont}}, + note={\styfmt{pifont}}, category={command} } diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod index b45b4ca5e91..b1d0342978b 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.pod @@ -101,6 +101,12 @@ Merge an entry's B<wrglossary> records for the same page locations. Don't merge an entry's B<wrglossary> records. +=item B<--merge-nameref-on> I<rule> + +Rule for merging locations created with the record=nameref package option +(requires glossaries-extra.sty version 1.37+). The I<rule> may be +one of: B<hcounter>, B<href>, B<title> or B<location>. + =item B<--force-cross-resource-refs> or B<-x> Force cross-resource referencing mode on. diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index 39be41ea2ff..fcb6fd34bae 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -1,11 +1,10 @@ -% arara: xelatex +% arara: lualatex +% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry") % arara: bibtex -% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") -% arara: xelatex if missing("toc") -% arara: xelatex if changed("glstex") +% arara: lualatex if changed("glstex") || missing("toc") % arara: bib2gls: {group: on} -% arara: xelatex -% arara: xelatex if found ("log", "Rerun") +% arara: lualatex +% arara: lualatex if found ("log", "Rerun") \documentclass[titlepage=false,index=totoc,bibliography=totoc, fontsize=12pt,captions=tableheading]{scrreprt} @@ -16,11 +15,17 @@ \usepackage[no-math]{fontspec} \setmainfont{Linux Libertine O} +\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase] +\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}} + \newfontface\greekmono{FreeMono}[Scale=MatchLowercase] -\newfontface\devangari{FreeSerif} -\newcommand{\devone}{{\devangari\char"0967}} -\newcommand{\devtwo}{{\devangari\char"0968}} -\newcommand{\devsix}{{\devangari\char"096C}} +\newfontface\freeserif{FreeSerif} +\newcommand{\devone}{{\freeserif\char"0967}} +\newcommand{\devtwo}{{\freeserif\char"0968}} +\newcommand{\devsix}{{\freeserif\char"096C}} +\newcommand{\insularG}{{\freeserif\char"A77D}} +\newcommand{\insularg}{{\freeserif\char"1D79}} +\newcommand{\longs}{\char"017F} \usepackage[x11names]{xcolor} \usepackage{alltt} @@ -47,6 +52,9 @@ ] {glossaries-extra} +\lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small}, + commentstyle={\color{gray}}} + \renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}} \glsxtrprovidestoragekey{note}{}{} @@ -89,9 +97,11 @@ \newcommand{\glsxtrpostnameenvironment}{\space environment} \newcommand{\glsxtrpostnamecounter}{\space counter} +\newcommand*{\csfmtfont}[1]{\texttt{#1}} + \newcommand*{\csfmt}[1]{% \texorpdfstring - {\texttt{\char`\\ #1}}% + {\csfmtfont{\char`\\ #1}}% {\string\\#1}% } @@ -110,9 +120,13 @@ dual-type={main}, combine-dual-locations={primary}, selection={recorded and deps and see}, - strip-missing-parents + strip-missing-parents, + save-child-count ] +\glsxtraddlabelprefix{} +\glsxtraddlabelprefix{idx.} + \DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} \IfFileExists{../java/Bib2Gls.java} @@ -132,6 +146,7 @@ \newcommand{\frontmatter}{% \clearpage\pagenumbering{roman}% + \pagestyle{headings}% \mainmatterfalse } \newcommand{\mainmatter}{% @@ -140,8 +155,6 @@ \mainmattertrue } -\pagestyle{headings} - \newcommand{\bibgls}{\appfmt{bib2gls}} \newcommand*{\BibTeX}{\hologo{BibTeX}} @@ -160,6 +173,13 @@ \newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}} +\newcommand{\qtdelim}[1]{\idx{doublequotechardelim}#1\idx{doublequotechardelim}} + +\newcommand{\ifnumhex}[1]{\cs{ifnum}\idx{doublequotecharhex}#1} + +\newcommand{\charhex}[1]{\cs{char}\idx{doublequotecharhex}#1} +\newcommand{\icharhex}[1]{\ics{char}\idx[format=glsnumberformat,noindex=false]{doublequotecharhex}#1} + \newcommand{\era}[1]{\texorpdfstring{\textsc{\MakeLowercase{#1}}}{#1}} \newcommand{\dequals}{% @@ -212,16 +232,24 @@ {\string\\jobname-#1.glstex}% } +\definecolor{field}{named}{DarkSlateGray4} +\definecolor{cs}{named}{DarkSeaGreen4} +\definecolor{styopt}{named}{DarkOrchid4} +\definecolor{entry}{named}{SteelBlue4} +\definecolor{comment}{named}{gray} +\definecolor{attribute}{named}{Purple4} +\definecolor{style}{named}{Blue4} + \newcommand{\extstyopt}{\textsuperscript{\textdagger}} \newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} \newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} \newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} \newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} -\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{DarkSeaGreen4}{\optfmt{#1}}}{#1}} -\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{DarkOrchid4}{\optfmt{#1}}}{#1}} -\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{DarkSlateGray4}#1}}{#1}} -\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{SteelBlue4}#1}}{#1}} +\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}} +\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}} +\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}} +\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}} \newcommand*{\atentryfmt}[1]{\entryfmt{@#1}} \newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} \newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} @@ -229,6 +257,7 @@ \newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} \newcommand*{\idprefixfmt}[1]{% \texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}} +\newcommand*{\xmltagfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} \newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}} @@ -260,16 +289,16 @@ \newcommand*{\extfmt}[1]{\filefmt{.#1}}% -\glsxtrnewgls[format=glsignore]{idx.}{\ext} +\glsxtrnewgls[format=glsignore]{idx.ext.}{\ext} \newcommand*{\iext}[1]{% - \glsxtrtitleorpdforheading{\idx{#1}}{.#1}{\extfmt{#1}}% + \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}% } \glsxtrnewgls[format=glsignore]{idx.}{\sty} \newcommand*{\isty}[1]{% - \texorpdfstring{\idx{#1}}{#1}% + \texorpdfstring{\idx[noindex=false]{#1}}{#1}% } \newcommand*{\env}[1]{% @@ -286,6 +315,10 @@ \texorpdfstring{\idx{glostyle.#1}}{#1}% } +\newcommand*{\iglostyle}[1]{% + \texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}% +} + \newcommand*{\catattr}[1]{% \texorpdfstring{\idx{#1}}{#1}% } @@ -309,6 +342,16 @@ {#2\ifblank{#1}{}{=#1}}% } +\newcommand*{\istyopt}[2][]{% + \texorpdfstring% + {% + \gls[noindex=false]{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}% + }% + {#2\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}} + \newcommand*{\keyvallist}{% \texorpdfstring {key\dequals value list}% @@ -331,6 +374,7 @@ \newcommand{\nosecformatdef}[1]{% \begin{definition} + \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% \glsadd{#1}\glsxtrglossentry{#1}% \glsentryuseri{#1}% \end{definition}\ignorespaces @@ -338,11 +382,20 @@ \newcommand{\nosecdef}[1]{% \begin{flushleft}\ttfamily + \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}% \glsadd{#1}\glsxtrglossentry{#1}% \glsentryuseri{#1}% \end{flushleft}\ignorespaces } +\newcommand{\inlinedef}[1]{% + \code + {% + \glsadd{#1}\glsxtrglossentry{#1}% + \glsentryuseri{#1}% + }% +} + \newcommand*{\csref}{\gls} \newcommand*{\cs}[1]{% @@ -350,12 +403,36 @@ {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\glsentryname{idx.#1}}}% } +\glsxtridentifyglslike{idx.}{\cs} + \newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}} +\newcommand*{\csdisp}[2]{% + \texorpdfstring + {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\csfmt{#2}}}% + {\string\\#2}% +} + +\newcommand*{\icsdisp}[3][]{% + \glsadd[#1]{idx.#2}\glsdohyperlink{\glolinkprefix cs.idx.#2}{\csfmt{#3}}% +} + +\newcommand*{\encapdisp}[2]{% + \texorpdfstring + {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\code{#2}}}% + {#2}% +} + +\glsxtridentifyglslike{idx.}{\ics} + \newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}} -\newcommand*{\postdeschook}[2][]{% - \glslink[#1]{idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#2}}} +\newcommand*{\postdeschook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#1}}} +\newcommand*{\postnamehook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostnamecategory}{\csfmt{glsxtrpostname#1}}} +\newcommand*{\postlinkhook}[1]{% + \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#1}}} \newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}% {% @@ -390,6 +467,8 @@ \newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}% \newcommand*{\glsopt}[2][]{\gencsopt{#1}{idx.gls}{#2}}% \newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{idx.glsadd}{#2}}% +\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{idx.printgloss}{#2}}% +\newcommand*{\iprintglossopt}[2][]{\glsadd{idx.printgloss.#2}\gencsopt{#1}{idx.printgloss}{#2}}% \newcommand*{\gencsopt}[3]{% \texorpdfstring% @@ -417,6 +496,8 @@ \glsxtrglossentry{field.#1}{}% } +\newcommand*{\fieldref}[1]{\gls[format=glsignore]{field.#1}} + \newglossarystyle{fieldstyle}{% \renewenvironment{theglossary}% {% @@ -480,24 +561,55 @@ \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}% }% \renewcommand*{\glossentry}[2]{% - \item + \glstreeitem \glstarget{cs.##1}{\strut}% \glsxtrifhasfield{dualid}{##1}% {% \glshyperlink{\glscurrentfieldvalue}% \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{note}{##1}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% \nopagebreak\par\hspace{10pt}% \Glossentrydesc{\glscurrentfieldvalue}% + \ifglshasdesc{\glscurrentfieldvalue}{\@. }{}% }% {% - \glstarget{cs.##1}{\strut}\gls[hyper=false]{##1}% + \gls[hyper=false]{##1}% \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{note}{##1}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% \nopagebreak\par\hspace{10pt}% \Glossentrydesc{##1}% + \ifglshasdesc{##1}{\@. }{}% + }% + \GlsXtrIfHasNonZeroChildCount{##1}% + {This command has \glscurrentfieldvalue\ forms:}{}% + \par\medskip + }% + \renewcommand*{\subglossentry}[3]{% + \glstreesubitem \glstarget{cs.##2}{\strut}% + \glsxtrifhasfield{dualid}{##2}% + {% + \glshyperlink{\glscurrentfieldvalue}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{note}{##2}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% + \nopagebreak\par\hspace{20pt}% + \Glossentrydesc{\glscurrentfieldvalue}% + \ifglshasdesc{\glscurrentfieldvalue}{.}{}% + }% + {% + \gls[hyper=false]{##2}% + \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}% + \glsxtrifhasfield{note}{##2}% + {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}% + {}% + \nopagebreak\par\hspace{20pt}% + \Glossentrydesc{##2}% + \ifglshasdesc{##2}{.}{}% }% - \glsxtrifhasfield{note}{##1}% - {\space(\glscurrentfieldvalue)}% - {}% - .% \par\medskip }% } @@ -516,7 +628,8 @@ ]% {% \let\printunsrtglossaryentryprocesshook\commandsummaryhook - \glsxtrlocalsetgrouptitle{glssymbols}{@}% + \let\csref\cs + \glsxtrlocalsetgrouptitle{glssymbols}{}% }% } @@ -597,6 +710,8 @@ \newcommand*{\atentrypageref}[1]{% \atentry{#1} (page~\glsxtrpageref{entry.#1})}% +\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}} + \newcommand{\argsection}[2][\section]{% \def\switcharg{}% \def\switchalt{}% @@ -647,7 +762,7 @@ {\string-\string-#1}% } -\newcommand*{\unicodecategoryfmt}[1]{\textsf{#1}} +\newcommand*{\unicodecategoryfmt}[1]{\qt{\textsf{#1}}} \definecolor{defbackground}{rgb}{1,1,0.75} \newsavebox\defsbox @@ -671,6 +786,9 @@ \ignorespacesafterend } +\newcommand{\introguide}{\href{bib2gls-begin.pdf}{\qt{\styfmt{glossaries-extra} +and \bibgls: An Introductory Guide} (\filefmt{bib2gls-begin.pdf})}} + \setcounter{tocdepth}{4} \newcommand*{\sectionref}[1]{\cref{#1}} @@ -710,6 +828,35 @@ \tabcontents } +\makeatletter +\newcommand*{\tablelistcs}[2]{% + \tmpctr=0\relax + \def\tabcontents{}% + \loop + \advance\tmpctr by 1\relax + \appto\tabcontents{l}% + \ifnum\tmpctr<#1 + \repeat +% + \edef\tabcontents{\noexpand\begin{tabular}{@{}\tabcontents @{}}}% + \def\thislist{#2}% + \dtlsortlist{\thislist}{\dtlicompare}% + \tmpctr=1\relax + \@for\thislabel:=\thislist\do{% + \eappto\tabcontents{\noexpand\ics{\thislabel}}% + \ifnum\tmpctr<#1\relax + \appto\tabcontents{&}% + \advance\tmpctr by 1\relax + \else + \appto\tabcontents{\\}% + \tmpctr=1\relax + \fi + }% + \appto\tabcontents{\end{tabular}}% + \tabcontents +} +\makeatother + % This is a bit fiddly. Need to represent \vec{v} in typewriter % font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't % work) @@ -732,8 +879,32 @@ files} \renewcommand{\fps@figure}{htbp} \newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}} + +\newcommand{\setupcodeenvfmts}{% + \def\cmd{\char`\\}% + \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}% + \renewcommand*{\styfmt}[1]{##1}% + \renewcommand*{\counterfmt}[1]{##1}% + \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}% + \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}% + \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}% +} + \newenvironment{codeenv} - {\begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces} + {% + \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}% + \setupcodeenvfmts + \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces + \parindent\z@\parfillskip\@flushglue\parskip\z@skip + } + {\end{flushleft}\ignorespacesafterend} + +\newenvironment{codeenv*} + {% + \setupcodeenvfmts + \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces + \parindent\z@\parfillskip\@flushglue\parskip\z@skip + } {\end{flushleft}\ignorespacesafterend} \begingroup @@ -753,16 +924,18 @@ files} \makeatother +\renewcommand{\titlepagestyle}{empty} + \begin{document} \maketitle \pagenumbering{alph} -\thispagestyle{empty} +\pagestyle{empty} \begin{abstract} The \bibgls\ command line application can be used to extract glossary information stored in a \ext{bib} file and convert it into glossary entry definitions that can be read using -\styfmt{glossaries-extra}'s \ics{GlsXtrLoadResources} command. When used +\styfmt{glossaries-extra}'s \gls{GlsXtrLoadResources} command. When used in combination with the \styoptfmt{record} package option, \bibgls\ can select only those entries that have been used in the document, as well as any dependent entries, which reduces the \TeX\ resources @@ -795,7 +968,7 @@ then you can use the supplementary tool \idx{convertgls2bib} to convert the entries to the \ext{bib} format required by \bibgls. See \sectionref{sec:gls2bib} for further details. -The supplementary file \filefmt{bib2gls-begin.pdf} is an +The supplementary file \introguide\ is an introductory guide to the \sty{glossaries-extra} package, which you may prefer to start with if you are unfamiliar with the \sty{glossaries} and \sty{glossaries-extra} packages. @@ -838,7 +1011,7 @@ the \ext{log} file for warnings. You can't use \ics{glsaddall} with \bibgls\ as that command works by iterating over all defined entries and calling -\ics{glsadd}\margm{label}. On the first \LaTeX\ run there are no +\code{\ics{glsadd}\margm{label}}. On the first \LaTeX\ run there are no 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 @@ -871,44 +1044,44 @@ enabled.) \section{Example Use} The glossary entries are stored in a \ext{bib} file. For example, the file \filefmt{entries.bib} might contain: -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal} -} - -@abbreviation{html, - short="html", - long={hypertext markup language} -} - -@symbol{v, - name={$\vec{v}$}, - text={\vec{v}}, - description={a vector} -} - -@index{goose,plural="geese"} -\end{verbatim} +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=\marg{hypertext markup language} +} +\strut +\atentry{symbol}\marg{v, + \field{name}=\marg{\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}}, + \field{text}=\marg{\cs{vec}\marg{v}}, + \field{description}=\marg{a vector} +} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} Here's an example document that uses this data: -\begin{verbatim} -\documentclass{article} - -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - sort={en-GB}% sort according to 'en-GB' locale -] - -\begin{document} -\Gls{bird} and \gls{goose}. -Symbol: $\gls{v}$. -Abbreviation: \gls{html}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cs{usepackage}\oarg{\styoptref{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort}\comment{sort according to 'en-GB' locale} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. +Symbol: \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar}. +Abbreviation: \cs{gls}\marg{html}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} If this document is called \filefmt{myDoc.tex}, the build process is: \begin{verbatim} @@ -918,51 +1091,58 @@ pdflatex myDoc \end{verbatim} (This manual assumes \appfmt{pdflatex} for simplicity. Replace with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as -appropriate.) +appropriate.) If you want \idxpl{lettergroup} (either headed, with +styles like \glostyle{indexgroup}, or just a blank line separator +with \styopt[false]{nogroupskip}) then you need to use the +\longarg{group} switch: +\begin{verbatim} +pdflatex myDoc +bib2gls --group myDoc +pdflatex myDoc +\end{verbatim} You can have multiple instances of \gls{GlsXtrLoadResources}. For example: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,index,abbreviations,symbols]{glossaries-extra} - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - sort={en-GB},% sort according to 'en-GB' locale - match={entrytype={entry}},% only select @entry - type={main}% put these entries in the 'main' glossary -] - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - sort={en-GB},% sort according to 'en-GB' locale - match={entrytype={abbreviation}},% only select @abbreviation - type={abbreviations}% put these entries in the 'abbreviations' glossary -] - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - sort={letter-case},% case-sensitive letter sort - match={entrytype={symbol}},% only select @symbol - type={symbols}% put these entries in the 'symbols' glossary -] - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - sort={en-GB},% sort according to 'en-GB' locale - match={entrytype={index}},% only select @index - type={index}% put these entries in the 'index' glossary -] - -\begin{document} -\Gls{bird} and \gls{goose}. -Symbol: $\gls{v}$. -Abbreviation: \gls{html}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{\styopt{record},\styopt{index},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{entry}]{match},\comment{only select \atentry{entry}} + \csopt[main]{type}\comment{put these entries in the 'main' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{abbreviation}]{match},\comment{only select \atentry{abbreviation}} + \csopt[abbreviations]{type}\comment{put these in the 'abbreviations' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[letter-case]{sort},\comment{case-sensitive letter sort} + \csopt[entrytype=\marg{symbol}]{match},\comment{only select \atentry{symbol}} + \csopt[symbols]{type}\comment{put these entries in the 'symbols' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale} + \csopt[entrytype=\marg{index}]{match},\comment{only select \atentry{index}} + \csopt[index]{type}\comment{put these entries in the 'index' glossary} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}. +Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gls}\marg{html}. +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +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 @@ -976,7 +1156,18 @@ those entries that are required in the document are defined, so \ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used. (The \qtt{unsrt} part of the command name indicates that all defined entries should be listed in the order of definition from -\styfmt{glossaries-extra}'s point of view.) +\styfmt{glossaries-extra}'s point of view, see the supplementary +document \introguide\ for further details.) + +If you don't provide a value with the \styopt{record} option, then +\styopt[only]{record} is assumed. This saves the same indexing +information that's used with the \ics{cs.makeglossaries} and +\ics{makenoidxglossaries} methods (described in the main +\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. +See \longarg{merge-nameref-on} for further details. If you additionally want to use an indexing application, such as \idx{xindy}, you need the package option @@ -991,16 +1182,22 @@ makeglossaries myDoc pdflatex myDoc \end{verbatim} (The entries aren't defined until the second \LaTeX\ run, so the -indexing files required by \idx!{makeindex} or \idx!{xindy} can't be -created until then.) There are more examples provided in -\sectionref{sec:examples}. +indexing files required by \idx!{xindy} or \idx!{makeindex} can't be +created until then.) In this case, \bibgls\ is simply being used to +fetch the entry definitions from one or more \ext{bib} files, with +the sorting and collating performed by the other indexing +application (so the resource option list would need +\csopt[none]{sort} and \csopt[false]{save-locations}). In general, +it's best to avoid this hybrid method unless you have a particular +set of \idx{xindy} rules that can't be replicated with \bibgls. \section{Defining a New Glossary} \label{sec:newglossary} 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 define an \idx{ignoredglossary}? +\ics{newignoredglossary*}. Why the starred forms and why define an +\idx{ignoredglossary}? The base \styfmt{glossaries} package was originally designed to work with \idx!{makeindex}. Support for \idx!{xindy} was later added, but @@ -1050,9 +1247,9 @@ So \cs{newignoredglossary} is useful with \bibgls\ if you're happy to use \cs{printunsrtglossary} as it reduces the overall number of internal control sequences. Since there is now the possibility of targets (created within \cs{printunsrtglossary}), it's useful to -have an \idx{ignoredglossary} that doesn't suppress the hyperlinks. -The \styfmt{glossaries-extra} package provides a starred form -\ics{newignoredglossary*} that doesn't suppress the hyperlinks. +have an \idx{ignoredglossary} that doesn't suppress the hyperlinks, +which can be obtained with the starred form \ics{newignoredglossary*} +provided by \styfmt{glossaries-extra}. Some resource options, such as \csopt{master}, \csopt{secondary} and \csopt{trigger-type}, need to ensure that a @@ -1080,7 +1277,7 @@ in stages: \begin{description} \item[Stage 1 (Initialisation)] Occurs after the \ext{aux} file has -been parsed, this stage parses the resource option list and ensures +been read, this stage parses the resource option list and ensures options are valid and don't cause a conflict. The transcript will show the message \begin{alltt} @@ -1117,7 +1314,9 @@ the corresponding set of \ext{bib} files: performed, except for the \field{name} field; \item suffixes are appended if required (for example, with \csopt{short-plural-suffix}); - \item field replications are made (\csopt{replicate-fields}); + \item field replications are made (\csopt{replicate-fields}), + and any of the above case-change or suffixes required + on the replicated fields are performed; \item the \field{group} field is assigned if \csopt{group} is set; \item any variables (identified by \atentry{string}) are expanded (if not already done in any of the previous steps); @@ -1125,6 +1324,8 @@ the corresponding set of \ext{bib} files: \csopt{bibtex-contributor-fields} are converted; \item any fields that must be converted into a label form (\csopt{labelify} or \csopt{labelify-list}) are processed; + \item any fields identified by \csopt{dependency-fields} are parsed for + dependent entries; \item any fields whose value must be a label are interpreted if \csopt{interpret-label-fields} is set; \item the \field{parent} field is adjusted according to the label prefix @@ -1187,8 +1388,8 @@ different \idx{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 -\field{alias}) in recorded entries that reference unrecorded -entries. +\field{alias} or fields identified with \csopt{dependency-fields}) +in recorded entries that reference unrecorded entries. The \qt{cross-referenced by} dependencies enabled with \csopt[recorded and deps and see]{selection} (where an unrecorded @@ -1246,7 +1447,7 @@ processed in the same loop. The dual index entries such as \atentry{dualindexentry} (described in \sectionref{sec:dualentry}) are designed to provide a way of -including an entry in both a glossary (with a description) and also +including an entry in a glossary (with a description) and also include the term (without the description) in an index. Additional terms that should only appear in the index can be defined with \atentry{index}. (See, for example, the \exfile{sample-multi1.tex} @@ -1255,31 +1456,31 @@ and \exfile{sample-multi2.tex} sample files.) Although \bibgls\ is designed to create indexes as well as glossary lists using the same interface (\cs{gls} etc), it is possible to have a mixture of \bibgls\ and \ics{index}. For example: -\begin{verbatim} -\documentclass{report} - -\usepackage{makeidx} -\usepackage[record]{glossaries-extra} - -\makeindex -\GlsXtrLoadResources[src={entries}] - -\glssetcategoryattribute{general}{dualindex}{true} -\glssetcategoryattribute{symbol}{dualindex}{true} -\glssetcategoryattribute{abbreviation}{dualindex}{true} - -\glssetcategoryattribute{general}{indexname}{hyperbf} -\glssetcategoryattribute{symbol}{indexname}{hyperbf} -\glssetcategoryattribute{abbreviation}{indexname}{hyperbf} - -\begin{document} -\chapter{Example} -\gls{bird}, \gls{html}, $\gls{v}$ and \glspl{goose}. - -\printunsrtglossaries -\printindex -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\marg{makeidx} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\cmd{makeindex} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\ics{glssetcategoryattribute}\marg{general}\marg{dualindex}\marg{true} +\cs{glssetcategoryattribute}\marg{symbol}\marg{dualindex}\marg{true} +\cs{glssetcategoryattribute}\marg{abbreviation}\marg{dualindex}\marg{true} +\strut +\cs{glssetcategoryattribute}\marg{general}\marg{indexname}\marg{hyperbf} +\cs{glssetcategoryattribute}\marg{symbol}\marg{indexname}\marg{hyperbf} +\cs{glssetcategoryattribute}\marg{abbreviation}\marg{indexname}\marg{hyperbf} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Example} +\cs{gls}\marg{bird}, \cs{gls}\marg{html}, \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar} and \cs{glspl}\marg{goose}. +\strut +\cs{printunsrtglossaries} +\cmd{printindex} +\cmd{end}\marg{document} +\end{codeenv} If the document is called \filefmt{myDoc.tex} then the document build is: \begin{verbatim} @@ -1318,6 +1519,26 @@ settings, so if these values are unset, \bibgls\ will default to \code{a} (any) for \texmfcnf{openinany} and \code{p} (paranoid) for \texmfcnf{openoutany}. +The only external processes that are run by \bibgls\ are calls to +\idx{kpsewhich} to check the security settings and locate files on +\TeX's path. These are started with Java's \code{ProcessBuilder} +class so there should be no issues with spaces or shell special characters +in the argument. The \longarg{debug} switch will write the process +call in the transcript file and will delimit the argument in the log +with single quote characters for convenience, but the process isn't +actually called in that way. + +\bibgls\ creates files with the extension \ext{glstex}, which are +input by \gls{glsxtrresourcefile} (and therefore by the shortcut +\gls{GlsXtrLoadResources}). This extension is fixed and is imposed +by both \bibgls\ and \gls{glsxtrresourcefile}. \bibgls\ also creates +a transcript file with the default extension \ext{glg}. This may be +overridden by the \longarg{log-file} switch, but \bibgls\ always +forbids write access to any file with the following extensions: +\extfmt{tex}, \extfmt{ltx}, \extfmt{sty}, \extfmt{cls}, +\extfmt{bib}, \extfmt{dtx}, \extfmt{ins}, \extfmt{def} and +\extfmt{ldf}. + \section{Localisation} \label{sec:lang.xml} @@ -1358,7 +1579,7 @@ from the resource file. In the event that the loaded resource file doesn't match the document language, you will have to manually set the correct translation (in English, this would be \csopt[Page\dcomma Pages]{loc-prefix}). The default definition of -\csref{bibglspassim} is also obtained from the resource file. +\gls!{bibglspassim} is also obtained from the resource file. \section{Conditional Document Build} @@ -1369,8 +1590,8 @@ by searching the \iext{aux} file for instances of Each instance corresponds to an instance of \gls{glsxtrresourcefile} where \meta{filename} is the base name of the \iext{glstex} file that \bibgls\ needs to create for this resource set. If the -\meta{options} part is missing the \csopt{src} option, this also indicates -the base name for the \iext{bib} file. +\meta{options} part is missing the \csopt{src} option, then +\meta{filename} also indicates the base name for the \iext{bib} file. So the simplest check to determine if \bibgls\ needs to be run is to test if the \iext{aux} file contains \gls{glsxtr@resource}. For @@ -1396,6 +1617,8 @@ complicated.) In general, the basic algorithm is: \begin{enumerate} +\item Run \LaTeX\ (or PDF\LaTeX\ etc). + \item If \gls{glsxtr@resource} is found in the \ext{aux} file then: \begin{enumerate} @@ -1403,7 +1626,7 @@ In general, the basic algorithm is: \item run \LaTeX\ (or PDF\LaTeX\ etc). \end{enumerate} -\item If \idx{@istfilename} is found in the \ext{aux} file then: +\item If \ics{@istfilename} is found in the \ext{aux} file then: \begin{enumerate} \item run \idx{makeglossaries} (or \idx{makeglossaries-lite}); @@ -1411,14 +1634,19 @@ In general, the basic algorithm is: \end{enumerate} \end{enumerate} -This allows for the \styopt[alsoindex]{record} package option. +This allows for the \styopt[alsoindex]{record} package option. See +also +\href{https://www.dickimaw-books.com/latex/buildglossaries}{\qt{Incorporating +\idx[hyper=false,noindex]{makeglossaries} or +\idx[hyper=false,noindex]{makeglossaries-lite} or \bibgls\ into +the document build}}~\cite{buildglossaries}. \section{Manual Installation} If you are unable to install \bibgls\ through your \TeX\ package manager, you can install manually using the instructions below. Replace \meta{TEXMF} with the path to your local or home TEXMF tree -(for example, \filefmt{~/texmf}). +(for example, \filefmt{\glstildechar/texmf}). Copy the files provided to the following locations: \begin{itemize} @@ -1432,7 +1660,12 @@ Copy the files provided to the following locations: (English resource file.) \item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf} (This document.) +\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf} +(Introductory guide.) \end{itemize} +If you use the Unix \appfmt{man} command, copy the +\filefmt{bib2gls.1} and \filefmt{convertgls2bib.1} files to the +appropriate location. If you are using a Unix-like system, there are also bash scripts provided called \file{bib2gls.sh} and \file{convertgls2bib.sh}. @@ -1478,7 +1711,6 @@ executables. You may need to refresh \TeX's database to ensure that \idx{kpsewhich} can find the \iext{jar} files. - To test that the application has been successfully installed, open a command prompt or terminal and run the following command: \begin{verbatim} @@ -1525,6 +1757,14 @@ since these fields must be just a label characters allowed in a label). \end{itemize} +Information in the \ext{aux} file is parsed for specific commands +but the arguments of those commands are not interpreted so, for +example, UTF-8 characters that occur in any resource options will +need to be detokenized when using \sty{inputenc} to prevent +expansion when they are written to the \ext{aux} file. (In some +options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex} +syntax to specify a UTF-8 character.) + The \longarg{no-interpret} switch will turn off the interpreter, but the library will still be used to parse the \ext{aux} and \ext{bib} files. Note that the \field{see} field doesn't use the interpreter @@ -1548,7 +1788,7 @@ environments provided within the document. number of packages that the parser recognises. Note that in some cases there's only very limited support. For example, \isty{siunitx}'s \ics{si} command is recognised but other -commands aren't from that package aren't. See +commands from that package aren't. See \longargpageref{list-known-packages} for further details. Since the parser doesn't have a full set of commands available @@ -1558,6 +1798,39 @@ defined, it will simply behave like \cs{newcommand}. Whereas with \ics{providecommand} the parser will only define the command if it's unrecognised. +The interpreter has its own internal implementation of the +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 +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.) + +\begin{table}[htbp] +\caption{Glossary-Related Commands Implemented by the \bibgls\ Interpreter} +\label{tab:bibglsdefs} +\setlength{\tabcolsep}{4pt}% +\centering +\tablelistcs{3}{glsxtrprovidecommand,bibglsuppercase,bibglslowercase,bibglsfirstuc,% +bibglstitlecase,GlsXtrEnableInitialTagging,bibglscontributorlist,% +bibglshyperlink,glshyperlink,bibglscontributor,bibglsdatetime,% +bibglsdate,bibglstime,glsentryname,glsentrytext,glsentryshort,% +glsentrylong,glsentryfirst,glsentrysymbol,glsentryuseri,% +glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv,% +glsentryuservi,glsentryplural,glsentryfirstplural,glsentryshortpl,% +glsentrylongpl,glsentrysymbolplural,Glsentryname,Glsentrytext,% +Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,% +Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,% +Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,% +Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,% +bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,% +glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,% +glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,% +GLSxtrhiername,GLSXTRhiername} +\end{table} + If a command isn't recognised, you can provide it in the \atentry{preamble} and use \ics{char} to map a symbol to the most appropriate Unicode character. For example, suppose your document @@ -1566,14 +1839,14 @@ loads a package that provides symbols for use on maps, such as can provide versions of these commands just for \bibgls's use:\footnote{These commands won't work with PDF\LaTeX, as the \cs{char} values are too large, but they're fine for \bibgls.} -\begin{verbatim} -@preamble{"\providecommand{\Harbour}{\char"2693} -\providecommand{\Battlefield}{\char"2694} -\providecommand{\Stadium}{\char"26BD}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} +\cs{providecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{providecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} +\end{codeenv} Since these use \cs{providecommand}, they won't overwrite the document's version (provided these commands have been defined before -\cs{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\ +\gls!{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\ to not write the \atentry{preamble} contents to the resource file using \csopt[false]{write-preamble}. Now you can either sort these symbols by @@ -1586,51 +1859,51 @@ rule that recognises these Unicode characters (for example, complicated for simple regular expressions. The \TeX\ parser library performs better than a simple pattern match, and that's the purpose of \file{texparserlib.jar} and why it's used by \bibgls\ (and by -\idx{convertgls2bib}). When -the \longarg{debug} mode is on, any warnings or errors triggered by -the \longarg{interpret} mode will be written to the transcript -prefixed with \code{texparserlib:} (the results of the conversions -will be included in the transcript as informational messages -prefixed with \code{texparserlib:} even with \longarg{no-debug}). +\idx{convertgls2bib}). When the \longarg{debug} mode is on, any +warnings or errors triggered by the interpreter will be written to +the transcript prefixed with \code{texparserlib:} (the results of +the conversions will be included in the transcript as informational +messages prefixed with \code{texparserlib:} even with +\longarg{no-debug}). For example, suppose the \ext{bib} file includes: -\begin{verbatim} -@preamble{ -"\providecommand{\mtx}[1]{\boldsymbol{#1}} -\providecommand{\set}[1]{\mathcal{#1}} -\providecommand{\card}[1]{|\set{#1}|} -\providecommand{\imaginary}{i}"} - -@entry{M, - name={{}$\mtx{M}$}, - text={\mtx{M}}, - description={a matrix} -} - -@entry{v, - name={{}$\vec{v}$}, - text={\vec{v}}, - description={a vector} -} - -@entry{S, - name={{}$\set{S}$}, - text={\set{S}}, - description={a set} -} - -@entry{card, - name={{}$\card{S}$}, - text={\card{S}}, - description={the cardinality of the set $\set{S}$} -} - -@entry{i, - name={{}$\imaginary$}, - text={\imaginary}, - description={square root of minus one ($\sqrt{-1}$)} +\begin{codeenv} +\atentry{preamble}\marg{ +\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\ics{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\cs{providecommand}\marg{\cmd{imaginary}}\marg{i}}} +\strut +\atentry{entry}\marg{M, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{mtx}\marg{M}}, + \field{description}=\marg{a matrix} +} +\strut +\atentry{entry}\marg{v, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}}, + \field{text}=\marg{\cs{vec}\marg{v}}, + \field{description}=\marg{a vector} +} +\strut +\atentry{entry}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{description}=\marg{a set} +} +\strut +\atentry{entry}\marg{card, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{description}=\marg{the cardinality of the set \idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}} +} +\strut +\atentry{entry}\marg{i, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{imaginary}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{imaginary}}, + \field{description}=\marg{square root of minus one (\idx{mshiftchar}\cmd{sqrt}\marg{-1}\idx{mshiftchar})} } -\end{verbatim} +\end{codeenv} (The empty group at the start of the \field{name} fields protects against the possibility that the \catattr{glossname} category attribute might be set to \optfmt{firstuc}, which @@ -1665,12 +1938,12 @@ rather than the string \qtt{\&x\meta{hex};}. The interpreter is first passed the code provided with \atentry{preamble}: -\begin{verbatim} -\providecommand{\mtx}[1]{\boldsymbol{#1}} -\providecommand{\set}[1]{\mathcal{#1}} -\providecommand{\card}[1]{|\set{#1}|} -\providecommand{\imaginary}{i} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\cs{providecommand}\marg{\cmd{imaginary}}\marg{i} +\end{codeenv} (unless \csopt[false]{interpret-preamble}). This means that the provided commands are now recognised by the interpreter when it has to parse the fields later. @@ -1681,8 +1954,7 @@ code that's passed to the interpreter is: {}$\mtx{M}$ \end{verbatim} The transcript (\iext{glg}) file will show the results of the -conversion:\footnote{The \longarg{debug} mode will show additional -information.} +conversion: \begin{verbatim} texparserlib: {}$\mtx{M}$ -> M \end{verbatim} @@ -1697,7 +1969,7 @@ For the \code{v} entry, the code is: \end{verbatim} The transcript shows: \begin{alltt} -texparserlib: \marg{}\$\csfmt{vec}\marg{v}\$ -> \usebox\varrow +texparserlib: \marg{}\$\ics{vec}\marg{v}\$ -> \usebox\varrow \end{alltt} So the \field{sort} value for this entry is set to \qtt{\usebox\varrow}, which consists of two Unicode characters \hex{76} @@ -1745,6 +2017,9 @@ The transcript shows: texparserlib: {}$\imaginary$ -> i \end{verbatim} So the \field{sort} value for this entry is set to \qtt{i}. +If \csopt[false]{interpret-preamble} had been used, \csfmt{imaginary} +wouldn't be recognised and would be discarded, leaving an empty sort +value. This means that in the case of the default \csopt[sort]{sort-field} with \csopt[letter-case]{sort}, these entries will be defined in @@ -1823,13 +2098,14 @@ the letter groups.\footnote{For more information on collation keys see the class in Java's API~\cite{collationkey}.} Suppose I add a new symbol to my \ext{bib} file: -\begin{verbatim} -@symbol{angstrom, - name={\AA}, - description={\AA ngstr\"om} +\begin{codeenv} +\atentry{symbol}\marg{angstrom, + \field{name}=\marg{\ics{AA}}, + \field{description}=\marg{\cs{AA} ngstr\ics{umlaut}om} } -\end{verbatim} -and I also use this entry in the document. Then with +\end{codeenv} +and I also use this entry in the document.\footnote{A better method +is to use \sty{siunitx} instead.} Then with \csopt[en]{sort}, the order is: \code{card} ($\card{S}$), \code{angstrom} (\AA), \code{i} ($\imaginary$), \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), and \code{v} ($\vec{v}$). @@ -1841,7 +2117,7 @@ However, if I change the locale to \csopt[sv]{sort}, the \longarg{group} switch shows that it's been placed in the \qt{\AA} letter group. -If you are using Java~8, you can set the +\label{locale.provider}If you are using Java~8, you can set the \code{java.locale.providers} property~\cite{javacldr} to use the \idx{CLDR} \idx{localeprovider}, which has more extensive support for locales than the native \idx{JRE}. For example: @@ -1849,8 +2125,7 @@ support for locales than the native \idx{JRE}. For example: java.locale.providers=CLDR,JRE \end{verbatim} This isn't available for Java~7, and should be enabled by default -for the proposed Java~9. Alternatively, you can provide your own -rule using \csopt[custom]{sort} and \csopt{sort-rule}. The property +for the proposed Java~9. The property can either be set in a script that runs \bibgls, for example, \begin{verbatim} java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" @@ -1858,14 +2133,15 @@ java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@" (where \verb|$jarpath| is the path to the \file{bib2gls.jar} file and \verb|"$@"| is the argument list) or you can set the property as the default for all Java applications by adding -the definition to the \code{\_JAVA\_OPTIONS} environment variable. +the definition to the \code{JAVA\_TOOL\_OPTIONS} environment +variable~\cite{javaoptions}. For example, in a bash shell: \begin{verbatim} -export _JAVA_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI' +export JAVA_TOOL_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI' \end{verbatim} or in Windows: \begin{verbatim} -set _JAVA_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI +set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI \end{verbatim} \chapter{Command Line Options} @@ -1879,7 +2155,6 @@ bib2gls \oargm{options} \meta{filename} \end{alltt} where \meta{filename} is the name of the \ext{aux} file. (The extension may be omitted.) Only one \meta{filename} is permitted. - Available options are listed below. \argsection{help} @@ -1939,7 +2214,7 @@ Sets the name of the transcript file. By default, the name is the same as the \iext{aux} file but with a \iext{glg} extension. Note that if you use \bibgls\ in combination with \idx{xindy} or \idx{makeindex}, you will need to change the transcript file name to -prevent interference. +prevent conflict. \argsection{dir} @@ -1955,9 +2230,9 @@ then you need to take care how you invoke \bibgls. Suppose I have a file called \filefmt{test-entries.bib} that contains my entry definitions and a document called \filefmt{mydoc.tex} that selects the \ext{bib} file using: -\begin{verbatim} -\GlsXtrLoadResources[src={test-entries}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[test-entries]{src}} +\end{codeenv} (\filefmt{test-entries.bib} is in the same directory as \filefmt{mydoc.tex}). If I compile this document using @@ -1967,9 +2242,9 @@ pdflatex -output-directory tmp mydoc then the auxiliary file \filefmt{mydoc.aux} will be written to the \filefmt{tmp} sub-directory. The resource information is listed in the \ext{aux} file as -\begin{verbatim} -\glsxtr@resource{src={test-entries}}{mydoc} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@resource}\marg{\csopt[test-entries]{src}}\marg{mydoc} +\end{codeenv} If I run \bibgls\ from the \filefmt{tmp} directory, then it won't be able to find the \filefmt{test-entries.bib} file (since it's in the parent directory). @@ -1980,7 +2255,7 @@ using bib2gls tmp/mydoc \end{verbatim} then the \ext{aux} file is found and the transcript file is -\filefmt{tmp/mydoc.glg} (since the default is the same as the +\filefmt{tmp/mydoc.glg} (since the default path name is the same as the \ext{aux} file but with the extension changed to \iext{glg}) but the output file \filefmt{mydoc.glstex} will be written to the current directory. @@ -2002,12 +2277,7 @@ for more details. \argsection{no-interpret} Switch off the interpreter mode. See \sectionref{sec:texparserlib} -for more details about the interpreter. If the interpreter is off, -the transcript (\iext{log}) file won't be parsed, so if you need -\bibgls\ to know that you are using \sty{fontspec} but you don't -want the interpreter on then you must use -\longarg{packages}\code{ fontspec} to indicate that UTF-8 is -natively supported. +for more details about the interpreter. \argsection{no-break-space} @@ -2021,14 +2291,13 @@ space. \argsection{cite-as-record} -Treat instances of \ics{citation}\margm{label} found in the +Treat instances of \code{\ics{citation}\margm{label}} found in the \ext{aux} file as though it was actually an \idx{ignoredrecord}: \begin{codeenv} -\gls{glsxtr@record}\margm{label}\marg{}\marg{page}\marg{glsignore}\marg{} +\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{} \end{codeenv} Note that \code{\cs{citation}\marg{*}} will always be skipped. Use \csopt[all]{selection} to select all entries. - This switch is most useful in conjunction with \atentrypageref{bibtexentry}. @@ -2050,6 +2319,70 @@ Don't merge an entry's \counter{wrglossary} records. This means that you may end up with duplicate page numbers in the entry's location list, but they will link to different parts of the page. +\argsection{merge-nameref-on} + +The \styopt[nameref]{record} package option (introduced to +\sty{glossaries-extra} version 1.37) provides extra information +in the record when indexing, obtained from \ics{@currentlabelname}, +\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as: +\begin{codeenv} +\format{glsxtr@record} +\end{codeenv} +the record is written as: +\nosecdef{glsxtr@record@nameref} +If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href} +will always be empty. The most reliable target is given by +\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the +associated counter name and \meta{hcounter} is +obtained from \cs{theHentrycounter}, which is set to the hyper +target command \csfmt{theH}\meta{counter} during indexing. Since +this information can't be included in the location when indexing +with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries} +package tries to obtain a prefix from which the target name can be +formed. This doesn't work if \csfmt{theH}\meta{counter} can't be +formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in +broken links. Since \bibgls\ doesn't have the same restrictions, the +actual target can be included in the record. You can then customize +the document to choose whether to use \meta{href} (to link to the +nearest anchor) or \meta{hcounter} to link to the place where the +indexing counter was incremented. + +The \code{nameref} record will be written to the \idx{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. + +With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be +\code{Doc-Start} at the start of the document and is updated +globally on every instance of \ics{refstepcounter}. The +\meta{title} is updated locally by certain commands, such as +\ics{section} or \ics{caption}. This means that the \meta{href} +may not always correspond to the \meta{title}, so using +the \styopt[nameref]{record} package option can have unpredictable +results if the \meta{title} is used as link text with \meta{href} as +the target. + +For compactness, \bibgls\ tries to merge duplicate or near +duplicate records. There are four possible rules that it will +use for \code{nameref} records, identified by \meta{rule} in the +\longarg{merge-nameref-on} switch: +\begin{itemize} +\item \optfmt{location}: merge records that match on the +\meta{prefix}, \meta{counter} and \meta{location} parts (as regular +records); +\item \optfmt{title}: merge records that match on the \meta{counter} +and \meta{title} parts; +\item \optfmt{href}: merge records that match on the \meta{counter} +and \meta{href} parts; +\item \optfmt{hcounter}: merge records that match on the \meta{counter} +and \meta{hcounter} parts. +\end{itemize} +The default \meta{rule} is \optfmt{hcounter}. Note that for all +rules the \meta{counter} must match. See the \qt{Nameref Record} +section of the \sty{glossaries-extra} user manual for further +details. + \argsection{force-cross-resource-refs} Force \idx{crossresourceref} mode on (see @@ -2063,12 +2396,12 @@ The mode will be enabled if applicable (see \argsection{support-unicode-script} -Text superscript (\cs{textsuperscript}) and subscript -(\cs{textsubscript}) will use Unicode super/subscript characters +Text superscript (\ics{textsuperscript}) and subscript +(\ics{textsubscript}) will use Unicode super/subscript characters if available (default). For example, -\begin{verbatim} -\textsuperscript{(2)} -\end{verbatim} +\begin{codeenv} +\cs{textsuperscript}\marg{(2)} +\end{codeenv} will be converted to \code{\textsuperscript{(2)}}, which consists of: \hex{207D} (superscript left parenthesis) \hex{00B2} (superscript two) \hex{207E} (superscript right @@ -2076,9 +2409,9 @@ parenthesis). If the entire contents of the argument can't be represented by Unicode characters, the interpreter uses \verb|<sup>| and \verb|<sub>| markup, which is then stripped by \bibgls. For example, -\begin{verbatim} -\textsuperscript{(2,3)} -\end{verbatim} +\begin{codeenv} +\cs{textsuperscript}\marg{(2,3)} +\end{codeenv} will be converted to \begin{verbatim} <sup>(2,3)</sup> @@ -2100,9 +2433,9 @@ Text superscript (\cs{textsuperscript}) and subscript Note that if other commands are provided that expand to Unicode superscript or subscript characters, then they won't be affected by this setting. For example, if \csfmt{superiortwo} is defined as -\begin{verbatim} -\providecommand{\superiortwo}{\char"B2} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}} +\end{codeenv} then it will be interpreted as \hex{00B2} (superscript two) even if this setting is on. @@ -2133,16 +2466,19 @@ characters are allowed in labels (for \csopt{labelify} and Packages that fall into the second category are: \isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited), \isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics}, -\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils}, \isty{probsoln}, \isty{shortvrb}, +\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils}, +\isty{mfirstuc-english}, \isty{probsoln}, \isty{shortvrb}, and \isty{xspace}. These are less likely to be needed within fields and so aren't checked for by default. If they are needed then you can instruct \bibgls\ to support them with \longarg{packages}. -(If you're wondering about the selection, the \file{texparserlib.jar} -library was originally written for another application that required -support for some of them.) - +Note that \sty{mfirstuc} is always automatically loaded, but +\sty{mfirstuc-english} is not implemented unless explicitly +requested with \code{\longarg{packages} mfirstuc-english}. +If you're wondering about the selection, the \file{texparserlib.jar} +library was originally written for another application that required +support for some of them. \argsection{packages} @@ -2196,24 +2532,26 @@ the command can't be replaced) is to insert an empty group in front of it. For example, the following definition -\begin{verbatim} -\newabbreviation{shtml}{shtml}{\glsps{ssi} enabled \glsps{short}{html}} -\end{verbatim} -will cause a problem for \verb|\Gls{shtml}| on first use. - -The above example, would be written in a \ext{bib} file as: -\begin{verbatim} -@abbreviation{shtml, - short={shtml}, - long={\glsps{ssi} enabled \glsps{html}} +\begin{codeenv} +\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}} +\end{codeenv} +will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use. +The above example would be written in a \ext{bib} file as: +\begin{codeenv} +\atentry{abbreviation}\marg{shtml, + \field{short}=\marg{shtml}, + \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}} } -\end{verbatim} - -The argument should either be a comma-separated list of fields or -the keyword \code{all} (which indicates all fields). -\bibgls\ will automatically insert an empty group at the -start of the listed fields that start with a problematic command, -and a warning will be written to the transcript. Unknown fields are +\end{codeenv} +The default \sty{mfirstuc} protection will automatically insert an empty +group before \code{\cs{glsps}\marg{ssi}} when writing the definition +in the \ext{glstex} file. + +The argument for this switch should either be a comma-separated list +of fields or the keyword \code{all} (which indicates all fields). +\bibgls\ will automatically insert an empty group at the start of +the listed fields that start with a problematic command, and a +warning will be written to the transcript. Unknown fields are skipped even if they're included in the list. An empty argument is equivalent to \longarg{no-mfirstuc-protection}. The default value is \code{all}. @@ -2227,10 +2565,11 @@ above. This works in the same way as \longarg{mfirstuc-protection} but guards against fields starting with inline maths -(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the \field{name} field -starts with \verb|$x$| and the glossary style automatically tries to -convert the first letter of the name to \idx{uppercase}, then this will -cause a problem. +(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the +\field{name} field starts with +\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style +automatically tries to convert the first letter of the name to +\idx{uppercase}, then this will cause a problem. With \longarg{mfirstuc-math-protection} set, \bibgls\ will automatically insert an empty group at the start of the field and @@ -2300,11 +2639,11 @@ range takes precedence. The mapping tests are applied as the records are read. For example, suppose the records are listed in the \ext{aux} file as: -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{emph}{3} -\glsxtr@record{gls.sample}{}{page}{hypersf}{3} -\glsxtr@record{gls.sample}{}{page}{hyperbf}{3} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{emph}}\marg{3} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hypersf}}\marg{3} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{3} +\end{codeenv} and \bibgls\ is invoked with \begin{verbatim} bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc @@ -2392,7 +2731,7 @@ alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or with the letter sort methods listed in \tableref{tab:sortoptionsletter} or with the letter-number sort methods listed in \tableref{tab:sortoptionsletternumber}. The group -label is obtained from \csref{bibglslettergroup}. +label is obtained from \gls!{bibglslettergroup}. \item[\idx{nonlettergroup} (or \idx{symbolgroup})] The first non-ignored character of all the sort values within this group @@ -2405,33 +2744,33 @@ The alphabetic sort methods ignore many punctuation characters, so an entry that has a non-alphabetic initial character in the sort value may actually be placed in a \idx{lettergroup}. -The group label is obtained from \csref{bibglsothergroup}. +The group label is obtained from \gls!{bibglsothergroup}. \item[\idx{emptygroup}] The sort value is empty when sorting with an alphabetical, letter or letter-number method, typically a result of the original value consisting solely of commands that \bibgls\ -can't interpret. The group label is obtained from \csref{bibglsemptygroup}. +can't interpret. The group label is obtained from \gls!{bibglsemptygroup}. \item[\idx{numbergroup}] The entries were sorted by one of the numeric comparisons listed in \tableref{tab:sortoptionsnumerical}. -The group label is obtained from \csref{bibglsnumbergroup}. +The group label is obtained from \gls!{bibglsnumbergroup}. \item[\idx{datetimegroup}] The entries were sorted by one of the date-time comparisons listed in \tableref{tab:sortoptionsdatetime} (where both date and time are present). -The group label is obtained from \csref{bibglsdatetimegroup}. +The group label is obtained from \gls!{bibglsdatetimegroup}. \item[\idx{dategroup}] The entries were sorted by one of the date comparisons (where the time is omitted). -The group label is obtained from \csref{bibglsdategroup}. +The group label is obtained from \gls!{bibglsdategroup}. \item[\idx{timegroup}] The entries were sorted by one of the time comparisons (where the date is omitted). -The group label is obtained from \csref{bibglstimegroup}. +The group label is obtained from \gls!{bibglstimegroup}. \item[\idx{customgroup}] The group label is explicitly set either in the \ext{bib} file or using the \csopt[\meta{label}]{group} resource -option. You will need to use \ics{glsxtrsetgrouptitle} to provide an +option. You will need to use \gls{glsxtrsetgrouptitle} to provide an associated title if the \meta{label} isn't the same as the title. Remember that the label can't contain any active characters, so you can't use non-ASCII characters in \meta{label} with \sty{inputenc} @@ -2454,7 +2793,7 @@ by the following line in the \langxml: \begin{verbatim} <entry key="grouptitle.case.ij">IJ</entry> \end{verbatim} -If there isn't a \code{grouptitle.case.\meta{lc}} key (where +If there isn't a \idx{grouptitle.case.lc} key (where \meta{lc} is the \idx!{lowercase} version), then only the first character will be converted to \idx{uppercase} otherwise the value supplied by the resource file is used. This resource key is only checked for @@ -2476,7 +2815,7 @@ letter group character to \idx{uppercase}. The case-sensitive ordering Glossary styles with navigational links to groups (such as \glostyle{indexhypergroup}) require an extra run for the ordinary -\csfmt{makeglossaries} and \csfmt{makenoidxglossaries} methods. For +\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For example, for the document \filefmt{myDoc.tex}: \begin{verbatim} pdflatex myDoc @@ -2496,26 +2835,28 @@ With \bibgls, if the \optfmt{type} is provided (through the \field{type} field or via options such as \csopt{type} and \csopt{dual-type}) then this information can be determined when \bibgls\ is ready to write the \iext{glstex} file, which means that -the extra \LaTeX\ run isn't necessary. +the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know +the glossary type then it will fallback on the original method +which requires an extra \LaTeX\ run. For example: -\begin{verbatim} -\documentclass{article} -\usepackage[colorlinks]{hyperref} -\usepackage[record,abbreviations,style=indexhypergroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries},% data in entries.bib - type={main}% put these entries in the 'main' glossary -] - -\GlsXtrLoadResources[src={abbrvs},% data in abbrvs.bib - type={abbreviations}% put these entries in the 'abbreviations' glossary -] -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib} + \csopt[main]{type}\comment{put these entries in the 'main' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib} + \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary} +} +\end{codeenv} Here the \csopt{type} is set and \bibgls\ can detect that \isty{hyperref} has been loaded, so if the \longargfmt{group} switch is used, then the group hyperlinks can be set (using -\csref{bibglshypergroup}). This means that the build process is +\gls!{bibglshypergroup}). This means that the build process is just: \begin{verbatim} pdflatex myDoc @@ -2529,18 +2870,18 @@ the default behaviour of \isty{glossary-hypernav}'s If \isty{hyperref} isn't loaded or the \longargfmt{group} switch isn't used or the \field{type} isn't set or your version of -\sty{glossaries} is too old, then the information isn't saved. +\sty{glossaries} is too old, then the information can't be saved in +the \ext{glstex} file. For example: -\begin{verbatim} -\documentclass{article} -\usepackage[colorlinks]{hyperref} -\usepackage[record,abbreviations,style=indexhypergroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries}]% data in entries.bib - -\GlsXtrLoadResources[src={abbrvs}]% data in abbrvs.bib -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib} +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib} +\end{codeenv} This requires the build process: \begin{verbatim} pdflatex myDoc @@ -2570,11 +2911,11 @@ recognised by Java. For example, \code{utf8} will be mapped to \styfmt{glossaries-extra} will assume the encoding is \code{utf8} and write that value to the \ext{aux} file. -If neither package has been loaded, \bibgls\ will assume the -operating system's default encoding. 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}). +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 +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}). If you have a problem with non-ASCII characters not displaying correctly in your document: @@ -2626,14 +2967,14 @@ before the entries are defined (that is, before using Trim leading and trailing spaces from field values. For example, if the \ext{bib} file contains: -\begin{verbatim} -@entry{sample, - name = { sample }, - description = { +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name} = \marg{ sample }, + \field{description} = \marg{ an example } } -\end{verbatim} +\end{codeenv} This will cause spurious spaces. Using \longarg{trim-fields} will automatically trim the values before writing the \iext{glstex} file. @@ -2653,7 +2994,7 @@ number of records found for the entry; \item \field{recordcount.counter}: set to the total number of records found for the entry for the given counter. \end{itemize} -These fields can then be used with the \ics{rgls}-like commands. +These fields can then be used with the \gls{rgls}-like commands. The default behaviour of \nosecdef{rgls} is to check the \field{recordcount} field against the \catattr{recordcount} @@ -2662,12 +3003,12 @@ attribute value. This attribute can be set with where \meta{category list} is a comma-separated list of category labels and \meta{value} is a positive integer. If the value of the \field{recordcount} field is greater than -\meta{value} then \ics{rgls} behaves like \ics{gls}, otherwise +\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise it does \nosecdef{rglsformat} instead. -If the use of \ics{rglsformat} is triggered in this way, -then \ics{rgls} writes a record to the \iext{aux} file +If the use of \gls{rglsformat} is triggered in this way, +then \gls{rgls} writes a record to the \iext{aux} file with the \glsopt{format} set to \encap{glstriggerrecordformat}. This ensures that the record count is correct on the next run, but the record isn't added to the location list as @@ -2676,22 +3017,22 @@ Note that the entry will still appear in the usual glossary unless you assign it to a different one with \csopt{trigger-type}. If the \catattr{recordcount} attribute hasn't been set -\ics{rgls} behaves like \ics{gls}. (That is, \ics{rgls} +\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls} uses the same internal command used by \ics{gls}.) You can use \ics{glsxtrenablerecordcount} to redefine \ics{gls} -to \ics{rgls}, so that you can continue to use \ics{gls} +to \gls{rgls}, so that you can continue to use \ics{gls} without having to switch command name. For example: -\begin{verbatim} -\GlsXtrLoadResources[ - src=abbrevs,% entries defined in abbrevs.bib - trigger-type=ignored, - category=abbreviation -] -\glsxtrenablerecordcount -\GlsXtrSetRecordCountAttribute{abbreviation}{1} -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib} + \csopt[ignored]{trigger-type}, + \csopt[abbreviation]{category} +} +\cs{glsxtrenablerecordcount} +\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1} +\end{codeenv} See the \sty{glossaries-extra} user manual~\cite{glossaries-extra} for further details. @@ -2703,7 +3044,7 @@ Switch off record counting. (Default.) Automatically implements \longarg{record-count} and additionally sets the \field{recordcount.counter.location} fields. -These fields can then be used with the \ics{rgls}-like +These fields can then be used with the \gls{rgls}-like commands. \argsection{no-record-count-unit} @@ -2719,19 +3060,21 @@ switch off record counting. \bibgls\ recognises certain entry types. Any unrecognised types will be ignored and a warning will be written to the transcript file. Entries are defined in the usual \ext{bib} format: -\begin{alltt} -@\meta{entry-type}\marg{\meta{id}, +\begin{codeenv*} +\idx{atchar}\meta{entry-type}\marg{\meta{id}, \meta{field-name-1} = \margm{text}, - ... + \ldots \meta{field-name-n} = \margm{text} } -\end{alltt} +\end{codeenv*} where \meta{entry-type} is the entry type (listed below), \meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and \meta{id} is a unique label. The label can't contain any spaces or -commas. In general it's best to stick with alpha-numeric labels. -The field values may be delimited by braces \margm{text} or -double-quotes \code{"\meta{text}"}. +commas, and most special characters are forbidden. The hyphen character and +some other punctuation characters are allowed by \bibgls, but you need to make +sure that your document hasn't made them active. In general it's best to +stick with alpha-numeric labels. The field values may be delimited by braces +\margm{text} or double-quotes \code{\qtdelim{\meta{text}}}. The \csopt{label-prefix} option can be used to instruct \bibgls\ to insert prefixes to the labels (\meta{id}) when the data is read. @@ -2863,8 +3206,8 @@ entry has the \field{see} field already set, any instance of The \field{seealso} key was only added to \sty{glossaries-extra} v1.16, but this field may be used with \bibgls\ even if you only have version 1.14 or 1.15. If the key isn't available, -\code{seealso=\margm{xr-list}} will be treated as -\code{see=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource +\code{\field{seealso}=\margm{xr-list}} will be treated as +\code{\field{see}=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource option \csopt{seealso} won't have an effect). You can't use both \field{see} and \field{seealso} for the same entry with \bibgls. Note that the \field{seealso} field doesn't allow for the optional @@ -2876,6 +3219,13 @@ or change the definition of \ics{seealsoname} or rather than \field{seealso} by \bibgls. Again, it's better to just use the \field{seealso} field directly. +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 +\field{seealso} fields. + \begin{table}[hbtp] \caption{Fields Provided by \styfmt{glossaries-extra}}\label{tab:fields} \centering @@ -2903,12 +3253,12 @@ Provided by \isty{glossaries-accsupp}} \printfields{accessfield}% \par} \medskip -Don't load \isty{glossaries-accsupp} directly (with \csfmt{usepackage}) when using +Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage}) when using \styfmt{glossaries-extra}. Load using the \styopt{accsupp} package option instead. -\begin{verbatim} -\usepackage[record,accsupp]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra} +\end{codeenv} \end{table} \begin{table}[hbtp] @@ -2919,7 +3269,7 @@ You may define and assign \field{bibtextype} (although it's more likely to be aliased). Don't define any of others, and don't use any of them in the \ext{bib} file, except for \field{group}, \field{sort} or \field{type} although those three are best -assigned in the resource command or by \bibgls.\par +set in the resource command or by \bibgls.\par \bigskip \centering \printfields{internalfield}% @@ -2950,27 +3300,27 @@ variables that may be used in field values. Don't include braces or double-quote delimiters when referencing a variable. You can use \idx{stringconcat} to concatenate strings. For example: -\begin{verbatim} -@string{ssi={server-side includes}} -@string{html={hypertext markup language}} - -@abbreviation{shtml, - short="shtml", - long=ssi # " enabled " # html, - see={ssi,html} -} - -@abbreviation{html, - short="html", - long=html -} - -@abbreviation{ssi, - short="ssi", - long=ssi +\begin{codeenv} +\atentry{string}\marg{ssi=\marg{server-side includes}} +\atentry{string}\marg{html=\marg{hypertext markup language}} +\strut +\atentry{abbreviation}\marg{shtml, + \field{short}=\qtdelim{shtml}, + \field{long}=ssi \idx{stringconcat} \qtdelim{ enabled } \idx{stringconcat} html, + \field{see}=\marg{ssi,html} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=html +} +\strut +\atentry{abbreviation}\marg{ssi, + \field{short}=\qtdelim{ssi}, + \field{long}=ssi } -\end{verbatim} -Note the difference between \code{="ssi"} (a field value delimited by +\end{codeenv} +Note the difference between \code{=\qtdelim{ssi}} (a field value delimited by double-quotes), the undelimited \code{=ssi} (a reference to the variable), the grouped \code{=\marg{ssi,html}} (a field value delimited by braces) and \code{ssi} the entry label. @@ -2980,15 +3330,15 @@ delimited by braces) and \code{ssi} the entry label. The standard \atentry{preamble} is available and can be used to provide command definitions used within field values. For example: -\begin{verbatim} -@preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} - -@entry{matrix, - name={matrix}, - plural={matrices}, - description={rectangular array of values, denoted $\mtx{M}$} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} +\strut +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values, denoted \idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}} } -\end{verbatim} +\end{codeenv} Alternatively you can use \ics{glsxtrprovidecommand} which behaves the same as \ics{providecommand} within the document but behaves like \ics{renewcommand} within \bibgls, which allows you to change @@ -3002,21 +3352,21 @@ The \TeX\ parser library used by \bibgls\ will parse the contents of as a fallback when \field{sort} is omitted (unless \csopt[false]{interpret-preamble} is set in the resource options). For example: -\begin{verbatim} -@preamble{"\providecommand{\set}[1]{\mathcal{#1}} -\providecommand{\card}[1]{|\set{#1}|}"} - -@entry{S, - name={{}$\set{S}$}, - text={\set{S}}, - description={a set} -} -@entry{card, - name={{}$\card{S}$}, - text={\card{S}}, - description={the cardinality of \gls{S}} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} +\strut +\atentry{entry}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{description}=\marg{a set} +} +\atentry{entry}\marg{card, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{description}=\marg{the cardinality of \cs{gls}\marg{S}} } -\end{verbatim} +\end{codeenv} Neither entry has the \field{sort} field, so \bibgls\ has to fall back on the \field{name} field and, since this contains the special characters \idx{escchar} (backslash), \idx{mshiftchar} (maths @@ -3040,17 +3390,17 @@ interpret the \field{name} fields. \item Define the commands in both the document and in \atentry{preamble}. For example: -\begin{verbatim} -\newcommand{\set}[1]{\mathcal{#1}} -\newcommand{\card}[1]{|\set{#1}|} -\GlsXtrLoadResources[src={my-data}] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\end{codeenv} Alternatively: -\begin{verbatim} -\GlsXtrLoadResources[src={my-data}] -\providecommand{\set}[1]{\mathcal{#1}} -\providecommand{\card}[1]{|\set{#1}|} -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|} +\end{codeenv} If the provided definitions match those given in the \ext{bib} file, there's no difference. If they don't match then in the first example the document definitions will take precedence (but the interpreter @@ -3063,23 +3413,23 @@ The default is the \field{user1} field, but this can be changed to another field by redefining \ics{GlsXtrFmtField}. The \ext{bib} file can now look like this: -\begin{verbatim} -@preamble{"\providecommand{\set}[1]{\mathcal{#1}} -\providecommand{\card}[1]{|\set{#1}|}"} - -@symbol{S, - name={{}$\set{S}$}, - text={\set{S}}, - user1={set}, - description={a set} -} -@symbol{cardS, - name={{}$\card{S}$}, - text={\card{S}}, - user1={card}, - description={the cardinality of \gls{S}} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}} +\strut +\atentry{symbol}\marg{S, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{set}\marg{S}}, + \field{user1}=\marg{set}, + \field{description}=\marg{a set} +} +\atentry{symbol}\marg{cardS, + \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}}, + \field{text}=\marg{\cmd{card}\marg{S}}, + \field{user1}=\marg{card}, + \field{description}=\marg{the cardinality of \cs{gls}\marg{S}} } -\end{verbatim} +\end{codeenv} Within the document, you can format \meta{text} using the formatting command provided in the \field{user1} field with: \nosecformatdef{glsxtrfmt} @@ -3093,14 +3443,14 @@ which inserts additional material inside the link text but outside the formatting command. If the entry given by \meta{label} hasn't been defined, -then \csref{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for +then \gls!{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for the starred version) and a warning is issued. (There's no warning if the entry is defined but the field hasn't been set.) The \meta{options} are as for \ics{glslink} but \ics{glslink} will -actually be using -\begin{alltt} -\ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\csfmt{}\meta{csname}\margm{text}\meta{insert}} -\end{alltt} +actually be using: +\begin{codeenv} +\ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\cmd{}\meta{csname}\margm{text}\meta{insert}} +\end{codeenv} where the default options \meta{def-options} are given by \ics{GlsXtrFmtDefaultOptions}. The default definition of this is just \code{noindex} which suppresses the automatic indexing or @@ -3110,11 +3460,11 @@ manual~\cite{glossaries-extra} for further details.) The This means that the document doesn't need to actually provide \verb|\set| or \verb|\card| but can instead use, for example, -\begin{alltt} +\begin{codeenv} \gls{glsxtrfmt}\marg{S}\marg{A} \gls{glsxtrentryfmt}\marg{cardS}\marg{B} -\end{alltt} -instead of +\end{codeenv} +instead of: \begin{verbatim} \set{A} \card{B} @@ -3124,11 +3474,11 @@ a warning. Since this is a bit cumbersome to write, you can provide shortcut commands. For example: -\begin{verbatim} -\GlsXtrLoadResources[src={my-data}] -\newcommand{\gset}[2][]{\glsxtrfmt[#1]{S}{#2}} -\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardS}{#2}} -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}} +\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{S}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardS}\marg{\idx{param}2}} +\end{codeenv} Whilst this doesn't seem a great deal different from simply providing the definitions of \csfmt{set} and \csfmt{card} in the document, this means you don't have to worry about remembering @@ -3140,58 +3490,58 @@ automatically produce a hyperlink to the glossary entry if the Here's an alternative \ext{bib} that defines entries with a term, a description and a symbol: -\begin{verbatim} -@preamble{"\providecommand{\setfmt}[1]{\mathcal{#1}} -\providecommand{\cardfmt}[1]{|\setfmt{#1}|}"} - -@entry{set, - name={set}, - symbol={\setfmt{S}}, - user1={setfmt}, - description={collection of values} -} -@entry{cardinality, - name={cardinality}, - symbol={\cardfmt{S}}, - user1={cardfmt}, - description={the number of elements in the \gls{set} $\glssymbol{set}$} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\cmd{setfmt}\marg{\idx{param}1}|}}} +\strut +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{symbol}=\marg{\cmd{setfmt}\marg{S}}, + \field{user1}=\marg{setfmt}, + \field{description}=\marg{collection of values} +} +\atentry{entry}\marg{cardinality, + \field{name}=\marg{cardinality}, + \field{symbol}=\marg{\cmd{cardfmt}\marg{S}}, + \field{user1}=\marg{cardfmt}, + \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} } -\end{verbatim} +\end{codeenv} I've changed the entry labels and the names of the formatting commands. The definitions in the document need to reflect the change in label but not the change in the formatting commands: -\begin{verbatim} -\newcommand{\gset}[2][]{\glsxtrfmt[#1]{set}{#2}} -\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardinality}{#2}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} +\end{codeenv} Here's another approach that allows for a more complicated argument for the cardinality. (For example, if the argument is an expression involving set unions or intersections.) The \ext{bib} file is now: -\begin{verbatim} -@preamble{"\providecommand{\setfmt}[1]{\mathcal{#1}} -\providecommand{\cardfmt}[1]{|#1|}"} - -@entry{set, - name={set}, - symbol={\setfmt{S}}, - user1={setfmt}, - description={collection of values} -} -@entry{cardinality, - name={cardinality}, - symbol={\cardfmt{\setfmt{S}}}, - user1={cardfmt}, - description={the number of elements in the \gls{set} $\glssymbol{set}$} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\idx{param}1|}}} +\strut +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{symbol}=\marg{\cmd{setfmt}\marg{S}}, + \field{user1}=\marg{setfmt}, + \field{description}=\marg{collection of values} +} +\atentry{entry}\marg{cardinality, + \field{name}=\marg{cardinality}, + \field{symbol}=\marg{\cmd{cardfmt}\marg{\cmd{setfmt}\marg{S}}}, + \field{user1}=\marg{cardfmt}, + \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}} } -\end{verbatim} +\end{codeenv} This has removed the \csfmt{setfmt} command from the definition of \csfmt{cardfmt}. Now the definitions in the document are: -\begin{verbatim} -\newcommand{\gset}[1]{\glsxtrentryfmt{set}{#1}} -\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardinality}{#2}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}} +\end{codeenv} This allows for code such as: \begin{verbatim} \[ \gcard{\gset{A} \cap \gset{B}} \] @@ -3199,10 +3549,10 @@ This allows for code such as: which will link back to the \code{cardinality} entry in the glossary and avoids any hyperlinking with \csfmt{gset}. Alternatively to avoid links with \csfmt{gcard} as well: -\begin{verbatim} -\newcommand{\gset}[1]{\glsxtrentryfmt{set}{#1}} -\newcommand{\gcard}[1]{\glsxtrentryfmt{cardinality}{#1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\cs{newcommand}\marg{\cmd{gcard}}[1]\marg{\gls{glsxtrentryfmt}\marg{cardinality}\marg{\idx{param}1}} +\end{codeenv} Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands, but their actual definitions are determined in the \ext{bib} file. @@ -3211,23 +3561,23 @@ but their actual definitions are determined in the \ext{bib} file. The entry types described in this section create a single glossary definition per entry (from \styfmt{glossaries-extra}'s point of view). -For example -\begin{verbatim} -@entry{matrix, - name={matrix}, - plural={matrices}, - description={rectangular array of values} +For example: +\begin{codeenv} +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} } -\end{verbatim} -is analogous to -\begin{verbatim} -\newglossaryentry{matrix}% label -{% fields - name={matrix}, - plural={matrices}, - description={rectangular array of values} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{matrix}\comment{label} +\marg{\comment{fields} + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} } -\end{verbatim} +\end{codeenv} The \csopt{secondary} option allows the creation of a fake glossary with the entry labels in its internal list in a different order. This means that the same data can be displayed in two separate lists @@ -3241,41 +3591,41 @@ definitions per \ext{bib} entry. Regular terms are defined by the \atentry{entry} field. This requires the \field{description} field and either \field{name} or \field{parent}. - For example: -\begin{verbatim} -@preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} - -@entry{matrix, - name={matrix}, - plural={matrices}, - description={rectangular array of values, denoted \gls{M}}, - seealso={vector} -} - -@entry{M, - name={\ensuremath{M}}, - description={a \gls{matrix}} -} - -@entry{vector, - name = "vector", - description = {column or row of values, denoted \gls{v}}, - seealso={matrix} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}} +\strut +\atentry{entry}\marg{matrix, + \field{name}=\marg{matrix}, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values, denoted \cs{gls}\marg{M}}, + \field{seealso}=\marg{vector} +} +\strut +\atentry{entry}\marg{M, + \field{name}=\marg{\cs{ensuremath}\marg{M}}, + \field{description}=\marg{a \cs{gls}\marg{matrix}} +} +\strut +\atentry{entry}\marg{vector, + \field{name} = \qtdelim{vector}, + \field{description} = \marg{column or row of values, denoted \cs{gls}\marg{v}}, + \field{seealso}=\marg{matrix} +} +\strut +\atentry{entry}\marg{v, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{vec}\marg{v}}}, + \field{description}=\marg{a \cs{gls}\marg{vector}} } +\end{codeenv} -@entry{v, - name={\ensuremath{\vec{v}}}, - description={a \gls{vector}} -} -\end{verbatim} -If the \field{name} field is omitted it will be set from the -parent's \field{name}. If the \field{sort} field is missing the -default is obtained from the \field{name} field. -(This can be overridden with \csopt{sort-field}.) +If the \field{sort} field is missing the default is obtained from the +\field{name} field. (A different field can be selected for the sort value with +\csopt{sort-field}.) For hierarchical entries, if the \field{name} field is +omitted it will be obtained from the parent's \field{name}. Terms defined using \atentry{entry} will be written to the output -(\ext{glstex}) file using the command \csref{bibglsnewentry}. +(\ext{glstex}) file using the command \gls!{bibglsnewentry}. \entrysection{symbol} @@ -3283,12 +3633,12 @@ The \atentry{symbol} entry type is much like \atentry{entry}, but it's designed specifically for symbols, so in the previous example, the \code{M} and \code{v} terms would be better defined using the \atentry{symbol} entry type instead. For example: -\begin{verbatim} -@symbol{M, - name={\ensuremath{M}}, - description={a \gls{matrix}} +\begin{codeenv} +\atentry{symbol}\marg{M, + \field{name}=\marg{\cs{ensuremath}\marg{M}}, + \field{description}=\marg{a \cs{gls}\marg{matrix}} } -\end{verbatim} +\end{codeenv} The required fields are \field{name} or \field{parent}. The \field{description} field is required if the \field{name} field is @@ -3298,7 +3648,7 @@ given by the entry label (unless overridden by \atentry{entry} where the sort defaults to \field{name} if omitted. Terms that are defined using \atentry{symbol} will be written to -the output file using the command \csref{bibglsnewsymbol}. +the output file using the command \gls!{bibglsnewsymbol}. \entrysection{number} @@ -3307,44 +3657,44 @@ numbers. The numbers don't have to be explicit digits and may have a symbolic representation. There's no real difference between the behaviour of \atentry{number} and \atentry{symbol} except that terms defined using \atentry{number} will be written to the output file -using the command \csref{bibglsnewnumber}. +using the command \gls!{bibglsnewnumber}. For example, the file \filefmt{constants.bib} might define mathematical constants like this: -\begin{verbatim} -@number{pi, - name={\ensuremath{\pi}}, - description={the ratio of the length of the circumference +\begin{codeenv} +\atentry{number}\marg{pi, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference of a circle to its diameter}, - user1={3.14159} + \field{user1}=\marg{3.14159} } - -@number{e, - name={\ensuremath{e}}, - description={base of natural logarithms}, - user1={2.71828} +\strut +\atentry{number}\marg{e, + \field{name}=\marg{\cs{ensuremath}\marg{e}}, + \field{description}=\marg{base of natural logarithms}, + \field{user1}=\marg{2.71828} } -\end{verbatim} +\end{codeenv} This stores the approximate value in the \field{user1} field. This can be used to sort the entries in numerical order according to the values rather than the symbols: -\begin{verbatim} -\GlsXtrLoadResources[ - src={constants},% constants.bib - category={number},% set the category for all selected entries - sort={double},% numerical double-precision sort - sort-field={user1}% sort according to 'user1' field -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[constants]{src},\comment{constants.bib} + \csopt[number]{category},\comment{set the category for all selected entries} + \csopt[double]{sort},\comment{numerical double-precision sort} + \csopt[user1]{sort-field}\comment{sort according to 'user1' field} +} +\end{codeenv} The \csopt[number]{category} option makes it easy to adjust the glossary format to include the \field{user1} field: -\begin{verbatim} -\renewcommand{\glsxtrpostdescnumber}{% - \ifglshasfield{useri}{\glscurrententrylabel} - { (approximate value: \glscurrentfieldvalue)}% - {}% +\begin{codeenv} +\ics{glsdefpostdesc}\marg{number}\marg{\comment{} + \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} \entrysection{index} @@ -3353,70 +3703,66 @@ 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.) However, this means that if the name contains any characters -that can't be used in the label, you will need the \field{name} -field. If the \field{sort} field is missing the -default is obtained from the \field{name} field. +entry.) 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}. Example: -\begin{verbatim} -@index{duck} - -@index{goose,plural={geese}} - -@index{sealion,name={sea lion}} - -@index{facade,name={fa\c{c}ade}} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{goose,\field{plural}=\marg{geese}} +\atentry{index}\marg{sealion,\field{name}=\marg{sea lion}} +\atentry{index}\marg{facade,\field{name}=\marg{fa\ics{c}\marg{c}ade}} +\end{codeenv} Terms that are defined using \atentry{index} will be written to the output -file using the command \csref{bibglsnewindex}. +file using the command \gls!{bibglsnewindex}. \entrysection{indexplural} The \atentry{indexplural} entry type is similar to the -\atentry{index} entry type except that the \field{name} field if -missing is obtained from the \field{plural} field. If the +\atentry{index} entry type except that the \field{name} field, if +missing, is obtained from the \field{plural} field. If the \field{plural} field is missing it's obtained from the \field{text} field with the plural suffix appended. If the \field{text} field is missing, it's obtained from the original entry label. If the \field{sort} field is missing the default is obtained from the \field{name} field. All fields are optional. For example: -\begin{verbatim} -@indexplural{goose, - plural = {geese} +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{plural} = \marg{geese} } - -@indexplural{duck} - -@indexplural{chateau, - text = {ch\^ateau}, - plural = {ch\^ateaux} +\strut +\atentry{indexplural}\marg{duck} +\strut +\atentry{indexplural}\marg{chateau, + \field{text} = \marg{ch\ics{cs.circum}ateau}, + \field{plural} = \marg{ch\cs{cs.circum}ateaux} } -\end{verbatim} +\end{codeenv} This is equivalent to: -\begin{verbatim} -@indexplural{goose, - name = {geese}, - text = {goose}, - plural = {geese} -} - -@indexplural{duck, - name = {ducks}, - text = {duck}, - plural = {ducks} -} - -@indexplural{chateau, - name = {ch\^ateaux}, - text = {ch\^ateau}, - plural = {ch\^ateaux} +\begin{codeenv} +\atentry{indexplural}\marg{goose, + \field{name} = \marg{geese}, + \field{text} = \marg{goose}, + \field{plural} = \marg{geese} +} +\strut +\atentry{indexplural}\marg{duck, + \field{name} = \marg{ducks}, + \field{text} = \marg{duck}, + \field{plural} = \marg{ducks} +} +\strut +\atentry{indexplural}\marg{chateau, + \field{name} = \marg{ch\cs{cs.circum}ateaux}, + \field{text} = {ch\cs{cs.circum}ateau}, + \field{plural} = {ch\cs{cs.circum}ateaux} } -\end{verbatim} +\end{codeenv} Terms that are defined using \atentry{indexplural} will be written to the output -file using the command \csref{bibglsnewindexplural}. +file using the command \gls!{bibglsnewindexplural}. \entrysection{abbreviation} @@ -3424,12 +3770,15 @@ The \atentry{abbreviation} entry type is designed for abbreviations. The required fields are \field{short} and \field{long}. If the \field{sort} key is missing, \bibgls\ will use the field given by \csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field. -You can also use \csopt{short-case-change} to convert the case of -the \field{short} field. +(If you want an equivalent of \gls!{newdualentry}, use +\atentry{dualabbreviationentry} instead.) -If you use \csopt[name]{sort-field}, then the fallback for the +If you use \csopt[name]{sort-field} (rather than the default +\csopt[sort]{sort-field}), then the fallback for the \field{name} field is always the \field{short} field, regardless of -the \csopt{abbreviation-sort-fallback} setting. +the \csopt{abbreviation-sort-fallback} setting, unless you use +\csopt{abbreviation-name-fallback} to change the fallback for the +\field{name} field. Note that you must set the abbreviation style before loading the resource file to ensure that the abbreviations are defined @@ -3446,46 +3795,83 @@ you sometimes need it, and then instruct \bibgls\ to ignore it when you don't want it. For example: -\begin{verbatim} -@abbreviation{html, - short ="html", - long = {hypertext markup language}, - description={a markup language for creating web pages} +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} } -\end{verbatim} +\end{codeenv} If you want the \abbrstyle{long-noshort-desc} style, then you can put the following in your document (where the \ext{bib} file is called \filefmt{entries-abbrv.bib}): -\begin{verbatim} -\setabbreviationstyle{long-noshort-desc} -\GlsXtrLoadResources[src={entries-abbrv.bib}, - abbreviation-sort-fallback={long}] -\end{verbatim} +\begin{codeenv} +\ics{setabbreviationstyle}\marg{long-noshort-desc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[long]{abbreviation-sort-fallback}} +\end{codeenv} Whereas, if you want the \abbrstyle{long-short-sc} style, then you can instead do: -\begin{verbatim} -\setabbreviationstyle{long-short-sc} -\GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}] -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},\csopt[description]{ignore-fields}} +\end{codeenv} or to convert the short value to \idx{uppercase} and use the \abbrstyle{long-short-sm} style instead: -\begin{verbatim} -\setabbreviationstyle{long-short-sm} -\GlsXtrLoadResources[src={entries-abbrv.bib}, - short-case-change={uc},% convert short value to upper case - ignore-fields={description}] -\end{verbatim} -(If you want an equivalent of \csfmt{newdualentry}, use -\atentry{dualabbreviationentry} instead.) +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sm} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[uc]{short-case-change},\comment{convert short value to upper case} + \csopt[description]{ignore-fields}} +\end{codeenv} + +Case-changing can be applied with \csopt{short-case-change} to +convert the case of the \field{short} field, as illustrated above. +If you use a style that obtains the \field{description} from the +\field{long} form, but you want to apply a case-change to the +\field{description} field with \csopt{description-case-change}, then +you can copy the \field{long} field to the \field{description} with +\csopt[\field{long}=\field{description}]{replicate-fields}. + +For example, if \filefmt{entries-abbrv.bib} contains: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +then the document may include: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[firstuc]{description-case-change}, + \csopt[\field{long}=\field{description}]{replicate-fields}} +\end{codeenv} +Note that this can cause a problem for styles that set the +\field{description} field to the \field{long} form encapsulated by a +style command (such as with the \abbrstyle{long-em-short-em} style) +as this will override the style setting. + +Similarly, if you want to change the case of the \field{name} field: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src}, + \csopt[firstuc]{description-case-change}, + \csopt[uc]{name-case-change}, + \csopt[\field{long}=\field{description},\field{short}=\field{name}]{replicate-fields}} +\end{codeenv} +Again, this will lose any custom formatting command that would +usually be applied by the abbreviation style to the \field{name} +field (and \field{description}, if applicable). Terms defined using \atentry{abbreviation} will be written to the output -file using the command \csref{bibglsnewabbreviation}. +file using the command \gls!{bibglsnewabbreviation}. \entrysection{acronym} The \atentry{acronym} entry type is like \atentry{abbreviation} except that the term is written to the output file using the command -\csref{bibglsnewacronym}. +\gls!{bibglsnewacronym}. \entrysection{contributor} @@ -3493,13 +3879,13 @@ The \atentry{contributor} entry type is primarily provided for use by the \atentry{bibtexentry} type. You may use it explicitly if you want, but you need to take care that it doesn't clash with \atentry{bibtexentry}. It behaves much like \atentry{index} except that the -term is written to the output file using the command -\csref{bibglsnewcontributor}. There are no required fields. As with +term is written to the \ext{glstex} file using the command +\gls!{bibglsnewcontributor}. There are no required fields. As with \atentry{index}, if the \field{name} field is missing, the fallback value is the entry's label. When this entry type is automatically created by \atentry{bibtexentry}, the \field{name} is set to \begin{codeenv} -\ics{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix} +\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix} \end{codeenv} If you do explicitly use \atentry{contributor} you need to make sure it's @@ -3511,25 +3897,23 @@ updated, and the \field{bibtexentry} and \field{bibtexentry@entrytype} internal fields can be set for the \atentry{contributor} entry. For example: -\begin{verbatim} -@contributor{KnuthDonaldE, - name={\bibglscontributor{Donald E.}{}{Knuth}{}}, - description={Famous mathematician and computer scientist who - created \TeX} -} - -@book{texbook, - title = {The {\TeX book}}, - author = {Donald E. Knuth}, - publisher = {Addison-Wesley}, +\begin{codeenv} +\atentry{contributor}\marg{KnuthDonaldE, + \field{name}=\marg{\gls{bibglscontributor}\marg{Donald E.}\marg{}\marg{Knuth}\marg{}}, + \field{description}=\marg{Famous mathematician and computer scientist who + created \cmd{TeX}} +} +\strut +@book\marg{texbook, + title = \marg{The {\cmd{TeX} book}}, + author = \marg{Donald E. Knuth}, + publisher = \marg{Addison-Wesley}, year = 1986 } -\end{verbatim} +\end{codeenv} The resource options then need to include: \begin{codeenv} - \csopt[ - \ics{GlsXtrBibTeXEntryAliases} - ]{entry-type-aliases}, + \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}, \csopt[ \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} ]{labelify-replace} @@ -3555,32 +3939,32 @@ functionally like \atentry{symbol}) or is functionally like \code{@}\meta{primary} and the dual is functionally like \code{@}\meta{dual}. -For example -\begin{verbatim} -@dualabbreviationentry{svm, - short = {SVM}, - long = {support vector machine}, - description = {statistical pattern recognition technique} +For example: +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{short} = \marg{SVM}, + \field{long} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} } -\end{verbatim} -is like -\begin{verbatim} -@abbreviation{svm, - short = {SVM}, - long = {support vector machine}, +\end{codeenv} +is like: +\begin{codeenv} +\atentry{abbreviation}\marg{svm, + \field{short} = \marg{SVM}, + \field{long} = \marg{support vector machine}, } -@entry{dual.svm, - text = {SVM}, - name = {support vector machine}, - description = {statistical pattern recognition technique} +\atentry{entry}\marg{dual.svm, + \field{text} = \marg{SVM}, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} } -\end{verbatim} -and is analogous to -\begin{verbatim} -\newabbreviation{svm}{SVM}{support vector machine} -\newglossaryentry{dual.svm}{name={support vector machine},text={SVM}, - description={statistical pattern recognition technique}} -\end{verbatim} +\end{codeenv} +and is analogous to: +\begin{codeenv} +\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine} +\gls{newglossaryentry}\marg{dual.svm}\marg{\field{name}=\marg{support vector machine},\field{text}=\marg{SVM}, + \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} @@ -3629,48 +4013,48 @@ the \ext{glstex} file so that the internal list of labels is in the appropriate order. For example, suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@index{aardvark} -@index{mouse} -@index{zebra} -@dualindexabbreviation{xml, - short={XML}, - long={extensible markup language} -} -@dualabbreviationentry{ssi, - short={SSI}, - long={server-side includes}, - description={directives placed in \gls{html} pages +\begin{codeenv} +\atentry{index}\marg{aardvark} +\atentry{index}\marg{mouse} +\atentry{index}\marg{zebra} +\atentry{dualindexabbreviation}\marg{xml, + \field{short}=\marg{XML}, + \field{long}=\marg{extensible markup language} +} +\atentry{dualabbreviationentry}\marg{ssi, + \field{short}=\marg{SSI}, + \field{long}=\marg{server-side includes}, + \field{description}=\marg{directives placed in \cs{gls}\marg{html} pages evaluated by the server} } -@dualindexabbreviation{html, - short={HTML}, - long={hypertext markup language} +\atentry{dualindexabbreviation}\marg{html, + \field{short}=\marg{HTML}, + \field{long}=\marg{hypertext markup language} } -@dualabbreviationentry{css, - short={CSS}, - long={cascading stylesheets}, - description={a language that describes the style of an - \gls{html} document} +\atentry{dualabbreviationentry}\marg{css, + \field{short}=\marg{CSS}, + \field{long}=\marg{cascading stylesheets}, + \field{description}=\marg{a language that describes the style of an + \cs{gls}\marg{html} document} } -\end{verbatim} +\end{codeenv} This contains a mixture of entry types, including \atentry{dualindexabbreviation} (where the dual is the abbreviation) and \atentry{dualabbreviationentry} (where the primary is the abbreviation). Now consider the following document: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,abbreviations]{glossaries-extra} - -\GlsXtrLoadResources[selection=all,src=entries] - -\begin{document} -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt{abbreviations}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection},\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} This uses the default \csopt[combine]{sort}, so all the entries are sorted together, resulting in the order: \code{aardvark}, @@ -3687,44 +4071,44 @@ sorted together, resulting in the order: The \LaTeX\ code written to the \iext{glstex} file is essentially (but not exactly): -\begin{verbatim} -% from @index{aardvark}: -\newglossaryentry{aardvark}{name={aardvark},description={}} - -% dual of @dualabbreviationentry{css,...}: -\newglossaryentry{dual.css}{name={cascading stylesheets},text={CSS}, - description={a language that describes the style of an - \glsxtrshort{html} document}} - -% primary of @dualabbreviationentry{css,...}: -\newabbreviation{css}{CSS}{cascading stylesheets} - -% primary of @dualindexabbreviation{html,...}: -\newglossaryentry{html}{name={HTML},description={}} - -% dual of @dualindexabbreviation{html,...}: -\newabbreviation{dual.html}{HTML}{hypertext markup language} - -% from @index{mouse}: -\newglossaryentry{mouse}{name={mouse},description={}} - -% dual of @dualabbreviationentry{ssi,...}: -\newglossaryentry{dual.ssi}{name={server-side includes},text={SSI}, - description={directives placed in \glsxtrshort{html} pages +\begin{codeenv} +\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}:} +\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}:} +\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} +\strut +\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}:} +\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}:} +\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}} - -% primary of @dualabbreviationentry{ssi,...}: -\newabbreviation{ssi}{SSI}{server-side includes} - -% primary of @dualindexabbreviation{xml,...}: -\newglossaryentry{xml}{name={XML},description={}} - -% dual of @dualindexabbreviation{xml,...}: -\newabbreviation{dual.xml}{XML}{extensible markup language} - -% from @index{zebra}: -\newglossaryentry{zebra}{name={zebra},description={}} -\end{verbatim} +\strut +\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}:} +\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}} +\strut +\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}:} +\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}} +\end{codeenv} Since the document uses the \styopt{abbreviations} package option, \gls{newabbreviation} automatically assigns the abbreviation to the \code{abbreviations} glossary (created through that package @@ -3764,13 +4148,13 @@ 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 with: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries, - dual-sort={letter-nocase}, - selection=all -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[letter-nocase]{dual-sort}, + \csopt[all]{selection} +} +\end{codeenv} then \bibgls\ first orders the primaries: \begin{itemize} \item \code{aardvark} (name: aardvark), @@ -3783,28 +4167,28 @@ then \bibgls\ first orders the primaries: \end{itemize} and writes them to the \ext{glstex} file (functionally like): -\begin{verbatim} -% from @index{aardvark}: -\newglossaryentry{aardvark}{name={aardvark},description={}} - -% primary of @dualabbreviationentry{css,...}: -\newabbreviation{css}{CSS}{cascading stylesheets} - -% primary of @dualindexabbreviation{html,...}: -\newglossaryentry{html}{name={HTML},description={}} - -% from @index{mouse}: -\newglossaryentry{mouse}{name={mouse},description={}} - -% primary of @dualabbreviationentry{ssi,...}: -\newabbreviation{ssi}{SSI}{server-side includes} - -% primary of @dualindexabbreviation{xml,...}: -\newglossaryentry{xml}{name={XML},description={}} - -% from @index{zebra}: -\newglossaryentry{zebra}{name={zebra},description={}} -\end{verbatim} +\begin{codeenv} +\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}:} +\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets} +\strut +\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}:} +\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} +\strut +\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: \begin{itemize} \item \code{dual.css} (name: cascading stylesheets), @@ -3814,23 +4198,23 @@ Then \bibgls\ orders the duals: \end{itemize} and writes them to the \ext{glstex} file (functionally like): -\begin{verbatim} -% dual of @dualabbreviationentry{css,...}: -\newglossaryentry{dual.css}{name={cascading stylesheets},text={CSS}, - description={a language that describes the style of an - \glsxtrshort{html} document}} - -% dual of @dualindexabbreviation{html,...}: -\newabbreviation{dual.html}{HTML}{hypertext markup language} - -% dual of @dualabbreviationentry{ssi,...}: -\newglossaryentry{dual.ssi}{name={server-side includes},text={SSI}, - description={directives placed in \glsxtrshort{html} pages +\begin{codeenv} +\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}:} +\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} +\strut +\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}} - -% dual of @dualindexabbreviation{xml,...}: -\newabbreviation{dual.xml}{XML}{extensible markup language} -\end{verbatim} +\strut +\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) the entries are defined in the order: \begin{enumerate} @@ -3891,51 +4275,51 @@ The default mappings are: The required fields are as for \atentry{entry}. For example: -\begin{verbatim} -@dualentry{child, - name={child}, - plural={children}, - description={enfant} -} -\end{verbatim} -Is like -\begin{verbatim} -@entry{child, - name={child}, - plural={children}, - description={enfant} - descriptionplural={enfants} +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} } - -@entry{dual.child, - description={child}, - descriptionplural={children}, - name={enfant} - plural={enfants} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{entry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} + \field{descriptionplural}=\marg{enfants} +} +\strut +\atentry{entry}\marg{dual.child, + \field{description}=\marg{child}, + \field{descriptionplural}=\marg{children}, + \field{name}=\marg{enfant} + \field{plural}=\marg{enfants} } -\end{verbatim} +\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 -defined using \csref{bibglsnewdualentry}. The \field{category} +defined using \gls!{bibglsnewdualentry}. The \field{category} and \field{type} fields can be set for the dual entry using the \csopt{dual-category} and \csopt{dual-type} options. For example: -\begin{verbatim} -\newglossary*{english}{English} -\newglossary*{french}{French} - -\GlsXtrLoadResources[ - src = {entries-dual},% data in entries-dual.bib - type = {english},% put primary entries in glossary 'english' - dual-type = {french},% put dual entries in glossary 'french' - category = {dictionary},% set the primary category to 'dictionary' - dual-category = {dictionary},% set the dual category to 'dictionary' - sort = {en},% sort primary entries according to language 'en' - dual-sort = {fr}% sort dual entries according to language 'fr' -] -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{french}\marg{French} +\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'} +} +\end{codeenv} \entrysection{dualindexentry} @@ -3955,89 +4339,93 @@ be a subset of all indexed entries. If no \field{name} is given, the dual entry is assigned the (unprefixed) entry label. For example: -\begin{verbatim} -@dualindexentry{array, - description={ordered list of values} +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} } -\end{verbatim} -This is effectively like -\begin{verbatim} -@index{array} - -@entry{dual.array, - name={array}, - description={ordered list of values} +\end{codeenv} +This is effectively like: +\begin{codeenv} +\atentry{index}\marg{array} +\strut +\atentry{entry}\marg{dual.array, + \field{name}=\marg{array}, + \field{description}=\marg{ordered list of values} } -\end{verbatim} +\end{codeenv} The primary entries are defined using -\csref{bibglsnewdualindexentry}, +\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 -\csref{bibglsnewdualindexentrysecondary}. +\gls!{bibglsnewdualindexentrysecondary}. This is the most convenient way of having an entry that's also automatically indexed. For example, suppose the file \filefmt{terms.bib} contains: -\begin{verbatim} -@index{duck} -@index{zebra} -@index{aardvark} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{zebra} +\atentry{index}\marg{aardvark} +\end{codeenv} and suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@dualindexentry{array, - description={ordered list of values} +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} } - -@dualindexentry{vector, - name={vector}, - description={column or row of values} +\strut +\atentry{dualindexentry}\marg{vector, + \field{name}=\marg{vector}, + \field{description}=\marg{column or row of values} } - -@dualindexentry{set, - description={collection of values} +\strut +\atentry{dualindexentry}\marg{set, + \field{description}=\marg{collection of values} } - -@dualindexentry{matrix, - plural={matrices}, - description={rectangular array of values} +\strut +\atentry{dualindexentry}\marg{matrix, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} } -\end{verbatim} +\end{codeenv} These entries can be used in an example document that has an index and a glossary: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record,index,stylemods=mcols]{glossaries-extra} - -\GlsXtrLoadResources[ - src={terms,entries}, - type=index, - label-prefix={idx.}, - dual-prefix={gls.}, - combine-dual-locations={primary}, - dual-type=main -] - -\begin{document} -\gls{gls.array}, \gls{gls.vector}, \gls{gls.set}, \gls{gls.matrix}. - -\gls{idx.duck}, \gls{idx.aardvark}, \gls{idx.zebra}. - -\renewcommand{\glstreenamefmt}[1]{\textsc{#1}} -\printunsrtglossary[type=main,style=index,nogroupskip] - -\renewcommand{\glstreenamefmt}[1]{#1} -\renewcommand{\glstreegroupheaderfmt}[1]{\textbf{#1}} -\printunsrtglossary[type=index,style=mcolindexgroup] -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[terms,entries]{src}, + \csopt[index]{type}, + \csopt[idx.]{label-prefix}, + \csopt[gls.]{dual-prefix}, + \csopt[primary]{combine-dual-locations}, + \csopt[main]{dual-type} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cs{gls}\marg{idx.duck}, \cs{gls}\marg{idx.aardvark}, \cs{gls}\marg{idx.zebra}. +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\ics{textsc}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt[index]{style},\iprintglossopt{nogroupskip}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\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 index. +To avoid the inconvenience of remembering which prefix to use, you can +set up the prefixes with \ics{glsxtraddlabelprefix} and reference entries +with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc. + \entrysection{dualindexabbreviation} The \atentry{dualindexabbreviation} entry type is similar to @@ -4049,28 +4437,28 @@ field mapping is: However in this case the required fields are \field{short} and \field{long}. The \field{name} for the primary entry defaults to \field{short} if omitted. (This may be changed with the -\csopt{abbreviation-name-fallback} option) The fallback for the +\csopt{abbreviation-name-fallback} option.) The fallback for the \field{sort} field is given by \csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field. For example: -\begin{verbatim} -@dualindexabbreviation{html, - short={html}, - long = {hypertext markup language} +\begin{codeenv} +\atentry{dualindexabbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} } -\end{verbatim} -is like -\begin{verbatim} -@index{html} - -@abbreviation{dual.html, - short={html}, - long = {hypertext markup language} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{index}\marg{html,\field{name}=\marg{HTML}} +\strut +\atentry{abbreviation}\marg{dual.html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} } -\end{verbatim} +\end{codeenv} The primary term is defined using -\csref{bibglsnewdualindexabbreviation}, which encapsulates the +\gls!{bibglsnewdualindexabbreviation}, which encapsulates the \field{name} to match the font used by the dual abbreviation. The encapsulation command depends on the \csopt{abbreviation-name-fallback} value. If it's @@ -4081,7 +4469,7 @@ 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 -\csref{bibglsnewdualindexabbreviationsecondary}. +\gls!{bibglsnewdualindexabbreviationsecondary}. \entrysection{dualindexsymbol} @@ -4098,124 +4486,119 @@ The required field is: \field{symbol}. 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 -\csref{bibglsnewdualindexsymbol}, +\gls!{bibglsnewdualindexsymbol}, which by default sets the \field{category} to \optfmt{index}, and the dual entries are defined using -\csref{bibglsnewdualindexsymbolsecondary}, +\gls!{bibglsnewdualindexsymbolsecondary}, which by default sets the \field{category} to \optfmt{symbol}. For example: -\begin{verbatim} -@dualindexsymbol{pi, - symbol={\ensuremath{\pi}}, - description={ratio of a circle's circumference to its diameter} +\begin{codeenv} +\atentry{dualindexsymbol}\marg{pi, + \field{symbol}=\marg{\cs{ensuremath}\marg{\ics{pi}}}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} } -\end{verbatim} -is like -\begin{verbatim} -@index{pi,symbol={\ensuremath{\pi}}} - -@symbol{dual.pi, - name={\ensuremath{\pi}}, - symbol={pi}, - description={ratio of a circle's circumference to its diameter} +\end{codeenv} +is like: +\begin{codeenv} +\atentry{index}\marg{pi,\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}} +\strut +\atentry{symbol}\marg{dual.pi, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{symbol}=\marg{pi}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} } -\end{verbatim} +\end{codeenv} For example, suppose I have a file called \filefmt{symbols.bib} that contains: -\begin{verbatim} -@dualindexsymbol{pi, - symbol={\ensuremath{\pi}}, - description={ratio of a circle's circumference to its diameter} +\begin{codeenv} +\atentry{dualindexsymbol}\marg{pi, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{ratio of a circle's circumference to its diameter} } - -@dualindexsymbol{e, - name={Euler's number}, - symbol={\ensuremath{e}}, - description={base of the natural logarithm} +\strut +\atentry{dualindexsymbol}\marg{e, + \field{name}=\marg{Euler's number}, + \field{symbol}=\marg{\cs{ensuremath}\marg{e}}, + \field{description}=\marg{base of the natural logarithm} } -\end{verbatim} +\end{codeenv} Then the previous example document can be modified to have an index, a glossary and a list of symbols: -\begin{verbatim} -\documentclass{report} - -\usepackage[colorlinks]{hyperref} -\usepackage[record,symbols,index,stylemods=mcols]{glossaries-extra} - -\newcommand{\bibglsnewdualindexsymbolsecondary}[5]{% - \longnewglossaryentry*{#1}{name={#3},category=symbol,% - symbol={#4},#2,type={symbols}}{#5}% -} - -\newcommand{\indexprimary}[1]{\glsadd[format=hyperbf]{idx.#1}} - -\renewcommand{\glsxtrpostdescsymbol}{% - \indexprimary{\glscurrententrylabel}% -} - -\renewcommand{\glsxtrpostdescgeneral}{% - \indexprimary{\glscurrententrylabel}% -} - -\GlsXtrLoadResources[ - src={entries,terms,symbols}, - type=index, - set-widest, - label-prefix={idx.}, - dual-prefix={}, - combine-dual-locations={primary}, - dual-sort={letter-case}, - dual-type=main -] - -\glsxtrnewglslike[hyper=false]{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} - -\begin{document} -\gls{array}, \gls{vector}, \gls{set}, \glspl{matrix}. - -\idx{duck}, \idx{aardvark}, \idx{zebra}. - -\gls{e} and \gls{pi}. - -\newpage -\gls{array}, \idx{vector}, \idx{set}, \gls{matrix}. - -\newpage -\gls{array}, \gls{vector}, \gls{set}, \gls{matrix}. - - -\renewcommand{\glstreenamefmt}[1]{\textsc{#1}} -\printunsrtglossary[type=main,nogroupskip,style=alttree] - -\renewcommand{\glstreenamefmt}[1]{#1} -\printunsrtglossary[type=symbols,nogroupskip,style=index] - -\renewcommand{\glstreenamefmt}[1]{#1} -\renewcommand{\glstreegroupheaderfmt}[1]{\textbf{#1}} -\printunsrtglossary[type=index,style=mcolindexgroup] - -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{symbols},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra} +\strut +\cs{newcommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=symbol,\comment{} + \field{symbol}=\marg{\idx{param}4},\idx{param}2,\field{type}=\marg{symbols}}\marg{\idx{param}5}\comment{} +} +\strut +\cs{newcommand}\marg{\cmd{indexprimary}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{idx.\idx{param}1}} +\strut +\cs{glsdefpostdesc}\marg{symbol}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} +\cs{glsdefpostdesc}\marg{general}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries,terms,symbols]{src}, + \csopt[index]{type}, + \csopt{set-widest}, + \csopt[idx.]{label-prefix}, + \csopt[\empty]{dual-prefix}, + \csopt[primary]{combine-dual-locations}, + \csopt[letter-case]{dual-sort}, + \csopt[main]{dual-type} +} +\strut +\gls{glsxtrnewglslike}\oarg{\glsopt[false]{hyper}}\marg{idx.}\marg{\cmd{idx}}\marg{\cmd{idxpl}}\marg{\cmd{Idx}}\marg{\cmd{Idxpl}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{glspl}\marg{matrix}. +\cmd{idx}\marg{duck}, \cmd{idx}\marg{aardvark}, \cmd{idx}\marg{zebra}. +\cs{gls}\marg{e} and \cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{array}, \cmd{idx}\marg{vector}, \cmd{idx}\marg{set}, \cs{gls}\marg{matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{gls}\marg{matrix}. +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textsc}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt{nogroupskip},\printglossopt[\glostyle{alttree}]{style}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt{nogroupskip},\printglossopt[index]{style}} +\strut +\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{mcolindexgroup}]{style}} +\strut +\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} and \csfmt{Idxpl}). This means I don't need to worry about the -label prefix and it also switches off the hyperlinks. These custom -commands are defined using +label prefix and it also switches off the hyperlinks (with +\code{\glsopt[false]{hyper}}). These custom +commands are defined using: \nosecformatdef{glsxtrnewglslike} -which, in this case, essentially does -\begin{verbatim} -\newcommand{\idx}[2][]{\gls[hyper=false,#1]{idx.#2}} -\newcommand{\Idx}[2][]{\Gls[hyper=false,#1]{idx.#2}} -\newcommand{\idxpl}[2][]{\glspl[hyper=false,#1]{idx.#2}} -\newcommand{\Idxpl}[2][]{\Glspl[hyper=false,#1]{idx.#2}} -\end{verbatim} +which, in this case, essentially does: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{idx}}[2][]\marg{\cs{gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{Idx}}[2][]\marg{\cs{Gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{idxpl}}[2][]\marg{\cs{glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\cs{newcommand}\marg{\cmd{Idxpl}}[2][]\marg{\cs{Glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}} +\end{codeenv} but the new commands will also recognise the \ics{gls} modifiers, so \verb|\idx+| will behave like \verb|\gls+| which wouldn't be possible if \csfmt{idx} was defined using \ics{newcommand} in the -above manner. +above manner. There's a similar command: +\nosecformatdef{glsxtrnewgls} +if no case-changing versions are required. -I've also redefined \csref{bibglsnewdualindexsymbolsecondary} to put +I've also redefined \gls!{bibglsnewdualindexsymbolsecondary} to put the dual entries created with \atentry{dualindexsymbol} into the \code{symbols} glossary (which is created with the \styopt{symbols} package option), so it overrides the @@ -4239,14 +4622,21 @@ bib2gls -g myDoc pdflatex myDoc \end{verbatim} +As from \sty{glossaries-extra-bib2gls} version 1.37, an alternative +method is to identify possible label prefixes with +\ics{glsxtraddlabelprefix} or \ics{glsxtrprependlabelprefix} and use +\ics{dgls}, \ics{dglspl}, \ics{dGls} or \ics{dGlspl}. See the +\styfmt{glossaries-extra} user manual~\cite{glossaries-extra} for +further details. + \entrysection{dualindexnumber} The \atentry{dualindexnumber} entry type is almost identical to \atentry{dualindexsymbol}, but the primary entries are defined using -\csref{bibglsnewdualindexnumber}, +\gls!{bibglsnewdualindexnumber}, which by default sets the \field{category} to \optfmt{index}, and the dual entries are defined using -\csref{bibglsnewdualindexnumbersecondary}, +\gls!{bibglsnewdualindexnumbersecondary}, which by default sets the \field{category} to \optfmt{number}. \entrysection{dualabbreviationentry} @@ -4278,25 +4668,25 @@ The fallback for the \field{sort} is given by \field{short} field. For example: -\begin{verbatim} -@dualabbreviationentry{svm, - long = {support vector machine}, - short = {SVM}, - description = {statistical pattern recognition technique} +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{long} = \marg{support vector machine}, + \field{short} = \marg{SVM}, + \field{description} = \marg{statistical pattern recognition technique} } -\end{verbatim} -is rather like doing -\begin{verbatim} -@abbreviation{svm, - long = {support vector machine}, - short = {SVM} +\end{codeenv} +is rather like doing: +\begin{codeenv} +\atentry{abbreviation}\marg{svm, + \field{long} = \marg{support vector machine}, + \field{short} = \marg{SVM} } - -@entry{dual.svm, - name = {support vector machine}, - description = {statistical pattern recognition technique} +\strut +\atentry{entry}\marg{dual.svm, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{statistical pattern recognition technique} } -\end{verbatim} +\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. @@ -4310,17 +4700,17 @@ 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{alltt} -\csref{bibglsnewdualabbreviationentry} -\end{alltt} -(which uses \gls{newabbreviation}) for the primary entries and with -\begin{alltt} -\csref{bibglsnewdualabbreviationentrysecondary} -\end{alltt} +with: +\begin{codeenv} +\gls{bibglsnewdualabbreviationentry} +\end{codeenv} +(which uses \gls{newabbreviation}) for the primary entries 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, this will put the primary entry in the +package option is used, the primary entry 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. @@ -4342,58 +4732,58 @@ This is like \atentry{dualentry} but the default mappings are: \end{itemize} The \field{name} and \field{symbol} fields are required. For example: -\begin{verbatim} -@dualsymbol{pi, - name={pi}, - symbol={\ensuremath{\pi}}, - description={the ratio of the length of the circumference +\begin{codeenv} +\atentry{dualsymbol}\marg{pi, + \field{name}=\marg{pi}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference of a circle to its diameter} } -\end{verbatim} +\end{codeenv} -Entries are defined using \csref{bibglsnewdualsymbol}, which by +Entries are defined using \gls!{bibglsnewdualsymbol}, which by default sets the \field{category} to \optfmt{symbol}. \entrysection{dualnumber} This is almost identical to \atentry{dualsymbol} but entries are -defined using \csref{bibglsnewdualnumber}, which by default sets +defined using \gls!{bibglsnewdualnumber}, which by default sets the \field{category} to \optfmt{number}. The above example could be defined as a number since $\pi$ is a constant: -\begin{verbatim} -@dualnumber{pi, - name={pi}, - symbol={\ensuremath{\pi}}, - description={the ratio of the length of the circumference +\begin{codeenv} +\atentry{dualnumber}\marg{pi, + \field{name}=\marg{pi}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}, + \field{description}=\marg{the ratio of the length of the circumference of a circle to its diameter}, - user1={3.14159} + \field{user1}=\marg{3.14159} } -\end{verbatim} +\end{codeenv} This has stored the approximate value in the \field{user1} field. The post-description hook could then be adapted to show this. -\begin{verbatim} -\renewcommand{\glsxtrpostdescnumber}{% - \ifglshasfield{useri}{\glscurrententrylabel} - { (approximate value: \glscurrentfieldvalue)}% - {}% +\begin{codeenv} +\cs{glsdefpostdesc}\marg{number}\marg{\comment{} + \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}} + \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} This use of the \field{user1} field means that the dual entries could be sorted numerically according to the approximate value: -\begin{verbatim} -\usepackage[record,postdot,numbers,style=index]{glossaries-extra} - -\GlsXtrLoadResources[ - src={entries},% entries.bib - dual-type={numbers}, - dual-sort={double},% decimal sort - dual-sort-field={user1} -] -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{postdot},\styopt{numbers},\styopt[index]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[numbers]{dual-type}, + \csopt[double]{dual-sort},\comment{decimal sort} + \csopt[user1]{dual-sort-field} +} +\end{codeenv} \entrysection{dualabbreviation} @@ -4416,9 +4806,9 @@ This includes some new fields: \field{dualshort}, \field{dualshortplural}, \field{duallong} and \field{duallongplural}. If these aren't already defined, they will be provided in the \iext{glstex} file with -\begin{alltt} +\begin{codeenv} \ics{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{} -\end{alltt} +\end{codeenv} Note that this use with an empty third argument prevents the creation of a field access command (analogous to \ics{glsentrytext}). The value can be accessed with @@ -4432,89 +4822,88 @@ need to be sorted according to the \field{long} field instead, use \csopt[long]{abbreviation-sort-fallback}. Terms that are defined using \atentry{dualabbreviation} will be -written to the output file using \csref{bibglsnewdualabbreviation}. +written to the output file using \gls!{bibglsnewdualabbreviation}. If the \csopt{dual-abbrv-backlink} option is on, the default field used for the backlinks is the \field{dualshort} field, so you'll need to make sure you adapt the glossary style to show that field. The -simplest way to do this is through the category post description -hook. +simplest way to do this is through the category \idx{postdescriptionhook}. For example, if the entries all have the \field{category} set to \optfmt{abbreviation}, then this requires redefining -\ics{glsxtrpostdescabbreviation}. +\ics{glsxtrpostdescabbreviation} (either with \cs{renewcommand} +or via \cs{glsdefpostdesc}). Here's an example dual abbreviation for a document where English is the primary language and German is the secondary language: -\begin{alltt} -@dualabbreviation\marg{rna, - short=\marg{RNA}, - dualshort=\marg{RNS}, - long=\marg{ribonucleic acid}, - duallong=\marg{Ribonukleins\"aure} +\begin{codeenv} +\atentry{dualabbreviation}\marg{rna, + \field{short}=\marg{RNA}, + \field{dualshort}=\marg{RNS}, + \field{long}=\marg{ribonucleic acid}, + \field{duallong}=\marg{Ribonukleins\"aure} } -\end{alltt} +\end{codeenv} If the abbreviation is in the file called \filefmt{entries-dual-abbrv.bib}, then here's an example document: -\begin{verbatim} -\documentclass{article} - -\usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} - -\usepackage[ngerman,main=english]{babel} -\usepackage[colorlinks]{hyperref} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{english}{English} -\newglossary*{german}{German} - -\setabbreviationstyle{long-short} - -\renewcommand*{\glsxtrpostdescabbreviation}{% - \ifglshasfield{dualshort}{\glscurrententrylabel} - {% - \space(\glscurrentfieldvalue)% - }% - {}% -} - -\GlsXtrLoadResources[ - src={entries-dual-abbrv},% entries-dual-abbrv.bib - type=english,% put primary entries in glossary 'english' - dual-type=german,% put primary entries in glossary 'german' - label-prefix={en.},% primary label prefix - dual-prefix={de.},% dual label prefix - sort=en,% sort primary entries according to language 'en' - dual-sort=de-1996,% sort dual entries according to 'de-1996' - % (German new orthography) - dual-abbrv-backlink% add links in the glossary to the opposite - %entry -] - -\begin{document} - -English: \gls{en.rna}; \gls{en.rna}. - -German: \gls{de.rna}; \gls{de.rna}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\strut +\cmd{usepackage}[ngerman,main=english]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{german}\marg{German} +\strut +\cs{setabbreviationstyle}\marg{long-short} +\strut +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} +} +\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'} + \comment{(German new orthography)} + \csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry} +} +\strut +\cmd{begin}\marg{document} +\strut +English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} If the \csopt{label-prefix} is omitted, then only the dual entries will have a prefix: -\begin{verbatim} -English: \gls{rna}; \gls{rna}. - -German: \gls{de.rna}; \gls{de.rna}. -\end{verbatim} +\begin{codeenv} +English: \cs{gls}\marg{rna}; \cs{gls}\marg{rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\end{codeenv} Another variation is to use the \abbrstyle{long-short-user} abbreviation style and modify the associated \ics{glsxtruserfield} so that the \field{duallong} field is selected for the parenthetical material: -\begin{verbatim} -\renewcommand*{\glsxtruserfield}{duallong} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} This means that the first use of the primary entry is displayed as \begin{quote} ribonucleic acid (RNA, Ribonukleins\"aure) @@ -4526,121 +4915,119 @@ Ribonukleins\"aure (RNS, ribonucleic acid) Here's an example to be used with the \abbrstyle{long-short-desc} style: -\begin{alltt} -@dualabbreviation\marg{rna, - short=\marg{RNA}, - dualshort=\marg{RNS}, - long=\marg{ribonucleic acid}, - duallong=\marg{Ribonukleins\"aure} - description=\marg{a polymeric molecule}, - user1=\marg{Ein polymeres Molek\"ul} +\begin{codeenv} +\atentry{dualabbreviation}\marg{rna, + \field{short}=\marg{RNA}, + \field{dualshort}=\marg{RNS}, + \field{long}=\marg{ribonucleic acid}, + \field{duallong}=\marg{Ribonukleins\"aure} + \field{description}=\marg{a polymeric molecule}, + \field{user1}=\marg{Ein polymeres Molek\"ul} } -\end{alltt} +\end{codeenv} This stores the dual description in the \field{user1} field, so this needs a mapping. The new example document is much the same as the previous one, except that the \csopt{dual-abbrv-map} option is needed to include the mapping between the \field{description} and \field{user1} fields: -\begin{verbatim} -\documentclass{article} - -\usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} - -\usepackage[ngerman,main=english]{babel} -\usepackage[colorlinks]{hyperref} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{english}{English} -\newglossary*{german}{German} - -\setabbreviationstyle{long-short-desc} - -\renewcommand*{\glsxtrpostdescabbreviation}{% - \ifglshasfield{dualshort}{\glscurrententrylabel} - {% - \space(\glscurrentfieldvalue)% - }% - {}% -} - -\GlsXtrLoadResources[ - src={entries-dual-abbrv-desc},% entries-dual-abbrv-desc.bib - type=english,% put primary entries in glossary 'english' - dual-type=german,% put primary entries in glossary 'german' - label-prefix={en.},% primary label prefix - dual-prefix={de.},% dual label prefix - sort=en,% sort primary entries according to language 'en' - abbreviation-sort-fallback={long},% fallback on 'long' field - dual-sort=de-1996,% sort dual entries according to 'de-1996' - % (German new orthography) - dual-abbrv-backlink,% add links in the glossary to the opposite - % entry -% dual key mappings: - dual-abbrv-map={% - {short,shortplural,long,longplural,dualshort,dualshortplural, +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\strut +\cmd{usepackage}[ngerman,main=english]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{german}\marg{German} +\strut +\cs{setabbreviationstyle}\marg{long-short-desc} +\strut +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} +} +\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[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field} + \csopt[de-1996]{dual-sort},\comment{sort dual entries 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:} + \csopt[\comment{} + \marg{short,shortplural,long,longplural,dualshort,dualshortplural, duallong,duallongplural,description,user1}, - {dualshort,dualshortplural,duallong,duallongplural,short,shortplural, + \marg{dualshort,dualshortplural,duallong,duallongplural,short,shortplural, long,longplural,user1,description} - } -] - -\begin{document} - -English: \gls{en.rna}; \gls{en.rna}. - -German: \gls{de.rna}; \gls{de.rna}. - -\printunsrtglossaries -\end{document} -\end{verbatim} + ]{dual-abbrv-map} +} +\strut +\cmd{begin}\marg{document} +\strut +English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}. +\strut +German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} Note that since this document uses the \abbrstyle{long-short-desc} abbreviation style, the \csopt{abbreviation-sort-fallback} needs to be changed to \optfmt{long}. If I change the order of the mapping to: -\begin{verbatim} - dual-abbrv-map={% - {long,longplural,short,shortplural,dualshort,dualshortplural, +\begin{codeenv} + \csopt[\comment{} + \marg{long,longplural,short,shortplural,dualshort,dualshortplural, duallong,duallongplural,description,user1}, - {duallong,duallongplural,dualshort,dualshortplural,short,shortplural, + \marg{duallong,duallongplural,dualshort,dualshortplural,short,shortplural, long,longplural,user1,description} -\end{verbatim} + ]{dual-abbrv-map} +\end{codeenv} Then the back-link field will switch to \field{duallong}. The -post-description hook can be modified to allow for this: -\begin{verbatim} -\renewcommand*{\glsxtrpostdescabbreviation}{% - \ifglshasfield{duallong}{\glscurrententrylabel} - {% - \space(\glscurrentfieldvalue)% - }% - {}% +\idx{postdescriptionhook} can be modified to allow for this: +\begin{codeenv} +\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} + \cs{ifglshasfield}\marg{duallong}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cmd{space}(\cs{glscurrentfieldvalue})\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} An alternative is to use the \abbrstyle{long-short-user-desc} style -without the post-description hook: -\begin{verbatim} -\setabbreviationstyle{long-short-user-desc} - -\renewcommand*{\glsxtruserfield}{duallong} -\end{verbatim} +without the \idx!{postdescriptionhook}: +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-user-desc} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} However be careful with this approach as it can cause nested hyperlinks. In this case it's better to use the \abbrstyle{long-postshort-user-desc} style which defers the parenthetical material until after the link-text: -\begin{verbatim} -\setabbreviationstyle{long-postshort-user-desc} - -\renewcommand*{\glsxtruserfield}{duallong} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-postshort-user-desc} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong} +\end{codeenv} If the back-link field has been switched to \field{duallong} then -the post-description hook is no longer required. +the \idx!{postdescriptionhook} is no longer required. \entrysection{dualacronym} As \atentry{dualabbreviation} but defines the entries with -\csref{bibglsnewdualacronym}. +\gls!{bibglsnewdualacronym}. \section{Tertiary Entry Types} \label{sec:tertiaryentry} @@ -4672,46 +5059,46 @@ This entry type is very similar to 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: -\begin{verbatim} -@tertiaryindexabbreviationentry{html, - short={HTML}, - long = {hypertext markup language}, - description={a markup language for creating web pages} +\begin{codeenv} +\atentry{tertiaryindexabbreviationentry}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} } -\end{verbatim} -is analogous to -\begin{verbatim} -\newglossaryentry{html,name={HTML},description={}} - -\newabbreviation{dual.html}{HTML}{hypertext markup language} - -\newglossaryentry{tertiary.html, - name={hypertext markup language}, - description={a markup language for creating web pages} +\end{codeenv} +is analogous to: +\begin{codeenv} +\gls{newglossaryentry}\marg{html,\field{name}=\marg{HTML},\field{description}=\marg{}} +\strut +\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language} +\strut +\gls{newglossaryentry}\marg{tertiary.html, + \field{name}=\marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages} } -\end{verbatim} +\end{codeenv} The last two are actually defined using one command: -\begin{verbatim} -\bibglsnewtertiaryindexabbreviationentrysecondary - {dual.html}% secondary label - {tertiary.html}% tertiary label - {...}% secondary fields - {...}% tertiary fields - {HTML}% primary name - {HTML}% short - {hypertext markup language}% long - {a markup language for creating web pages}% description -\end{verbatim} -The \csref{bibglsnewtertiaryindexabbreviationentrysecondary} +\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{HTML}\comment{short} + \marg{hypertext markup language}\comment{long} + \marg{a markup language for creating web pages}\comment{description} +\end{codeenv} +The \gls!{bibglsnewtertiaryindexabbreviationentrysecondary} command is provided in the \iext{glstex} file as: -\begin{verbatim} -\providecommand{\bibglsnewtertiaryindexabbreviationentrysecondary}[8]{% - \newabbreviation[#3]{#1}{#6}{#7}% - \longnewglossaryentry*{#2}% - {name={\protect\bibglsuselongfont{#7}{\glscategory{#1}}},#4}% - {#8}% +\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{} + \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} + \marg{\field{name}=\marg{\cmd{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\ics{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} + \marg{\idx{param}8}\comment{} } -\end{verbatim} +\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 @@ -4756,7 +5143,7 @@ access any of the \BibTeX\ fields, you will need to alias or define them. For example: \begin{codeenv} \csopt[ - title=name + \fieldfmt{title}=\field{name} ]{field-aliases} \end{codeenv} Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's @@ -4765,7 +5152,7 @@ if will convert \fieldfmt{type} to \field{bibtextype}, so you must use \field{bibtextype} as the identifier when aliasing. Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which -uses \ics{glsaddstoragekey} to provided all the standard \BibTeX\ +uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\ fields. (Remember that new fields must be defined before the first \idx{resourceset}.) @@ -4785,10 +5172,10 @@ be selected if \csopt[recorded and deps and see]{selection}). You can instruct \bibgls\ to treat \ics{citation} as an \idx{ignoredrecord} using \longarg{cite-as-record}. -Each contributor is effectively defined as +Each contributor is effectively defined as: \begin{codeenv} \atentry{contributor}\marg{\meta{label}, - name=\marg{\ics{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}} + \field{name}=\marg{\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}} } \end{codeenv} The label is obtained by converting the \field{name} @@ -4805,20 +5192,20 @@ new \atentry{bibtexentry} added to its internal \field{bibtexentry} field. The main \atentry{bibtexentry} is defined using -\ics{bibglsnewbibtexentry} and is followed by +\gls{bibglsnewbibtexentry} and is followed by: \begin{codeenv} -\ics{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} +\gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id} \end{codeenv} where \meta{id} is the label identifying the main \atentry{bibtexentry} and \meta{contributor-id} is the -label identifier the contributor, for each contributor that has +label identifying the contributor, for each contributor that has been selected. -Each contributor is defined using \ics{bibglsnewcontributor}. The definition -is followed by +Each contributor is defined using \gls{bibglsnewcontributor}. The definition +is followed by: \begin{codeenv} -\ics{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id} -\ics{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id} +\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id} +\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id} \end{codeenv} for each selected \atentry{bibtexentry} associated with that contributor. The second line provides the internal list field @@ -4833,88 +5220,87 @@ For example: \begin{codeenv} \cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}} -\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\% - \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\% - \marg{\% +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} \cs{glsxtrfieldforlistloop} - \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\% - \marg{\csfmt{contributorhandler}}\% - }% - \marg{\csfmt{par} No titles.}\% + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\csfmt{par} No titles.}\comment{} } \end{codeenv} -(where the resource option \csopt[title=name]{field-aliases} +(where the resource option \csopt[\fieldfmt{title}=\field{name}]{field-aliases} has been used). - Here's an example that uses the test \file{xampl.bib} file that's provided with \TeX\ distributions: \begin{codeenv} -\csfmt{documentclass}\marg{article} - -\cs{usepackage}[record,nomain]\marg{glossaries-extra} - +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut \cs{newglossary*}\marg{contributors}\marg{Authors/Editors} \cs{newglossary*}\marg{titles}\marg{Titles} - -\cs{newcommand}\marg{\ics{bibglsnewbibtexentry}}[4]\marg{\% - \cs{longnewglossaryentry}*\marg{\#1}\marg{name={\#3},\#2,type=\marg{titles}}\marg{\#4}\% +\strut +\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}={\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} } - -\cs{GlsXtrLoadResources}[ +\strut +\gls{GlsXtrLoadResources}\oarg{ \csopt[xampl]{src}, \csopt[false]{write-preamble}, \csopt[ \ics{GlsXtrBibTeXEntryAliases} ]{entry-type-aliases}, \csopt[ - title=name + \fieldfmt{title}=\field{name} ]{field-aliases}, \csopt[ - note=name + \fieldfmt{note}=\field{name} ]{replicate-fields}, \csopt[ \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{} ]{labelify-replace}, \csopt[contributors]{type}, \csopt[same as original entry]{category}, - \csopt[category]{sort-field}, - \csopt[name]{sort-suffix} -] - -\ics{glsxtrsetgrouptitle}\marg{article}\marg{Articles} -\cs{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets} -\cs{glsxtrsetgrouptitle}\marg{book}\marg{Books} -\cs{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters} -\cs{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous} - -\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\#1} (\#1)} - -\cs{newcommand}\marg{\postdeschook{contributor}}{\% - \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\% - \marg{\% + \csopt[\field{category}]{sort-field}, + \csopt[\field{name}]{sort-suffix} +} +\strut +\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\gls{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets} +\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\gls{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters} +\gls{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous} +\strut +\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\idx{param}1} (\idx{param}1)} +\strut +\cs{newcommand}\marg{\postdeschook{contributor}}{\comment{} + \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} \ics{glsxtrfieldforlistloop} - \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\% - \marg{\csfmt{contributorhandler}}\% - }\% - \marg{\csfmt{par} No titles.}\% + \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\csfmt{par} No titles.}\comment{} } - +\strut \csfmt{begin}\marg{document} -Sample\idx!{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}. -Another sample\idx!{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}. - +Sample\idx{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}. +Another sample\idx{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}. +\strut \csfmt{bibliographystyle}\marg{plain} \ics{bibliography}\marg{xampl} - -\cs{printunsrtglossary}[type=contributors,style=altlist] -\cs{printunsrtglossary*}[type=titles,style=indexgroup] -\marg{\% - \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}{category}\% - \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\csfmt{emph}\marg{\#1}}\% - \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\csfmt{textbf}\marg{\#1}}\% -} - +\strut +\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] +\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] +\marg{\comment{} + \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{category}\comment{} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} +} +\strut \csfmt{end}\marg{document} \end{codeenv} If the file is called \filefmt{myDoc.tex} then the document build @@ -4932,16 +5318,19 @@ pdflatex myDoc Make sure that you use \isty{glossaries-extra} with the \styopt{record} package option. This ensures that \bibgls\ can pick -up the required information from the \iext{aux} file, and it also -loads the supplementary \ics{glossaries-extra-bib2gls} package -(from version 1.27 onwards). The option also -switches on the \styopt[none]{sort} package option (if you have a new +up the required information from the \iext{aux} file, and both +\styopt[only]{record} and \styopt[nameref]{record} additionally +load the supplementary \isty{glossaries-extra-bib2gls} package. +These two \styopt{record} option values also +switch on the \styopt[none]{sort} package option (if you have a new enough version of the base \isty{glossaries} package), which means 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 \styopt[alsoindex]{record}). +external files (unless you use the hybrid \styopt[alsoindex]{record}, +in which case you need to prevent \bibgls\ from sorting using the +\csopt[none]{sort} resource option). The \iext{glstex} resource files created by \bibgls\ are loaded in the document using @@ -4958,26 +5347,26 @@ resource file is called the \idx{resourceset} (see There's a shortcut command that uses \ics{jobname} in the \meta{filename}: \nosecformatdef{GlsXtrLoadResources} -The first instance of this command is equivalent to -\begin{alltt} +The first instance of this command is equivalent to: +\begin{codeenv} \gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}} -\end{alltt} -Any additional use of \gls{GlsXtrLoadResources} is equivalent to -\begin{alltt} +\end{codeenv} +Any additional use of \gls{GlsXtrLoadResources} is equivalent to: +\begin{codeenv} \gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}-\meta{n}} -\end{alltt} +\end{codeenv} where \meta{n} is number. For example: -\begin{verbatim} -\GlsXtrLoadResources[src=entries-en,sort={en}] -\GlsXtrLoadResources[src=entries-fr,sort={fr}] -\GlsXtrLoadResources[src=entries-de,sort={de-1996}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}} +\end{codeenv} This is equivalent to: -\begin{verbatim} -\glsxtrresourcefile[src=entries-en,sort={en}]{\jobname} -\glsxtrresourcefile[src=entries-fr,sort={fr}]{\jobname-1} -\glsxtrresourcefile[src=entries-de,sort={de-1996}]{\jobname-2} -\end{verbatim} +\begin{codeenv} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}}\marg{\cs{jobname}} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}}\marg{\cs{jobname}-1} +\gls{glsxtrresourcefile}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}}\marg{\cs{jobname}-2} +\end{codeenv} In general, it's simplest just to use \gls{GlsXtrLoadResources}. The optional argument \meta{options} is a comma-separated @@ -5000,43 +5389,43 @@ or you can load them separately with different settings applied. For example, if the files \filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} have the same settings: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} Alternatively, if they have different settings: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms},type=main] -\GlsXtrLoadResources[src={entries-symbols},sort=use,type=symbols] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},\csopt[main]{type}} +\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 of \gls{glsxtrresourcefile} but only one glossary type, the glossary will effectively contain blocks of sorted entries. For example, if \filefmt{file1.bib} contains: -\begin{verbatim} -@index{duck} -@index{zebra} -@index{aardvark} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{duck} +\atentry{index}\marg{zebra} +\atentry{index}\marg{aardvark} +\end{codeenv} and \filefmt{file2.bib} contains: -\begin{verbatim} -@index{caterpillar} -@index{bee} -@index{wombat} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{caterpillar} +\atentry{index}\marg{bee} +\atentry{index}\marg{wombat} +\end{codeenv} then -\begin{verbatim} -\GlsXtrLoadResources[src={file1,file2}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[file1,file2]{src}} +\end{codeenv} will result in the list: aardvark, bee, caterpillar, duck, wombat, zebra. These six entries are all defined when \csfmt{jobname}\filefmt{.glstex} is read. Whereas -\begin{verbatim} -\GlsXtrLoadResources[src={file1}] -\GlsXtrLoadResources[src={file2}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[file1]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[file2]{src}} +\end{codeenv} will result in the list: aardvark, duck, zebra, bee, caterpillar, wombat. The first three (aardvark, duck, zebra) are defined when \csfmt{jobname}\filefmt{.glstex} is read. The second three (bee, @@ -5047,70 +5436,67 @@ defined entries, this is the ordering used. Abbreviation styles must be set (using \ics{setabbreviationstyle}) before the resource command that selects the abbreviations from the appropriate \ext{bib} file, since the entries are defined (through -\gls{newabbreviation} or \cs{newacronym}) when +\gls{newabbreviation} or \gls{newacronym}) when \gls{glsxtrresourcefile} inputs the \ext{glstex} file. (Similarly for any associated abbreviation style commands that must be set before abbreviations are defined, such as \cs{glsxtrlongshortdescname}.) Note \bibgls\ allows \iext{bib} files that don't provide any entries. This can be used to provide commands in \atentry{preamble}. -For example, suppose I have \filefmt{defs.bib} that just contains -\begin{verbatim} -@preamble{"\providecommand{\strong}[1]{\textbf{\color{red}#1}} -\providecommand{\test}[2]{#2 (#1)}"} -\end{verbatim} +For example, suppose I have \filefmt{defs.bib} that just contains: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{strong}}[1]\marg{\cs{textbf}\marg{\ics{cs.color}\marg{red}\idx{param}1}} +\cs{providecommand}\marg{\cmd{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} +\end{codeenv} This provides two commands: \nosecdef{strong} (which sets the font weight and colour) and -\begin{alltt} -\csfmt{test}\margm{first}\margm{second} -\end{alltt} -(which just displays its second -argument followed by the first in parentheses). +\nosecdef{parenswap} +(which just displays its second argument followed by the first in parentheses). Suppose I also have \filefmt{entries.bib} that contains: -\begin{verbatim} -@index{example, - name={\strong{\test{stuff}{example}}} +\begin{codeenv} +\atentry{index}\marg{example, + \field{name}=\marg{\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}} } -@index{sample} -@index{test} -@index{foo} -@index{bar} -\end{verbatim} +\atentry{index}\marg{sample} +\atentry{index}\marg{test} +\atentry{index}\marg{foo} +\atentry{index}\marg{bar} +\end{codeenv} This contains an entry that requires the commands provided in \filefmt{defs.bib}, so to ensure those commands are defined, I can do: -\begin{verbatim} -\GlsXtrLoadResources[src={defs,entries}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src}} +\end{codeenv} Unfortunately this results in the sort value for \code{example} being set to \code{redexample (stuff)} because the interpreter has -detected the provided commands and expanded -\begin{verbatim} -\strong{\test{stuff}{example}} -\end{verbatim} -to -\begin{verbatim} -\textbf{\color{red}example (stuff)} -\end{verbatim} -It discards font changes, so \csfmt{textbf} is ignored, but it doesn't -recognise \csfmt{color} and so doesn't know that the first argument is +detected the provided commands and expanded: +\begin{codeenv} +\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} +\end{codeenv} +to: +\begin{codeenv} +\cs{textbf}\marg{\cs{cs.color}\marg{red}example (stuff)} +\end{codeenv} +It discards font changes, so \cs{textbf} is ignored, but it doesn't +recognise \cs{cs.color} and so doesn't know that the first argument is just the colour specifier and therefore doesn't discard it. This means that \qt{\textbf{\color{red}example (stuff)}} is placed between \qt{foo} and \qt{sample} instead of between \qt{bar} and \qt{foo}. I can prevent the interpreter from parsing \atentry{preamble}: -\begin{verbatim} -\GlsXtrLoadResources[src={defs,entries},interpret-preamble=false] -\end{verbatim} -Now when the sort value for \code{example} is obtained from -\begin{verbatim} -\strong{\test{stuff}{example}} -\end{verbatim} -no expansion occurs (since \csfmt{strong} and \csfmt{test} are -unrecognised) so the sort value ends up as +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} +Now when the sort value for \code{example} is obtained from: +\begin{codeenv} +\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}} +\end{codeenv} +no expansion occurs (since \gls{strong} and \gls{parenswap} are now +unrecognised) so the sort value ends up as: \code{stuffexample} which places \qt{\textbf{\color{red}example (stuff)}} between \qt{sample} and \qt{test}, which is again incorrect. @@ -5120,29 +5506,29 @@ commands into two \iext{bib} files: one that shouldn't be interpreted and one that should. For example, \filefmt{defs-nointerpret.bib}: -\begin{verbatim} -@preamble{"\providecommand{\strong}[1]{\textbf{\color{red}#1}}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{strong}}[1]\marg{\cs{textbf}\marg{\cs{cs.color}\marg{red}\idx{param}1}}}} +\end{codeenv} and \filefmt{defs-interpret.bib}: -\begin{verbatim} -@preamble{"\providecommand{\test}[2]{#2 (#1)}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}} +\end{codeenv} Now the first one can be loaded with \csopt[false]{interpret-preamble}: -\begin{verbatim} -\GlsXtrLoadResources[src={defs-nointerpret},interpret-preamble=false] -\end{verbatim} -This creates a \iext{glstex} file that provides \csfmt{strong} but +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-nointerpret]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} +This creates a \iext{glstex} file that provides \gls{strong} but doesn't define any entries. The other file \filefmt{defs-interpret.bib} can then be loaded with the default \csopt[true]{interpret-preamble}: -\begin{verbatim} -\GlsXtrLoadResources[src={defs-interpret,entries}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret,entries]{src}} +\end{codeenv} The provided commands are remembered by the interpreter, so you can also do: -\begin{verbatim} -\GlsXtrLoadResources[src={defs-interpret}] -\GlsXtrLoadResources[src={entries}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} 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 @@ -5172,16 +5558,16 @@ This is a boolean option that determines whether or not the interpreter should parse the contents of \atentry{preamble}. The default is \optfmt{true}. If \optfmt{false}, the preamble contents will still be written to the \iext{glstex} file, but any -commands provided in the preamble won't be recognised if the -interpreter is needed to determine an entry's sort value. +commands provided in the preamble won't be recognised by the +interpreter (see \sectionref{sec:texparserlib}). -Related options are \csopt{set-widest}, which uses the interpreter -to determine the widest name for the \glostyle{alttree} style, -\csopt{interpret-label-fields}, which governs whether or not fields -that must only contain a label should be interpreted, -\csopt{labelify}, which converts a field into a string suitable for -use as a label, and \csopt{labelify-list}, which converts a field -into a string suitable for use as a comma-separated list of labels. +Related options are: \csopt{set-widest} (which uses the interpreter to determine +the widest name for the \glostyle{alttree} style or the +\isty{glossary-longextra} styles), \csopt{interpret-label-fields} (which governs +whether or not fields that must only contain a label should be interpreted), +\csopt{labelify} (which converts a field into a string suitable for use as a +label), and \csopt{labelify-list} (which converts a field into a string suitable +for use as a comma-separated list of labels). \optsection{write-preamble} @@ -5200,29 +5586,43 @@ The \glostyle{alttree} glossary style needs to know the widest using \ics{glssetwidest} provided by the \styfmt{glossary-tree} package (or similar commands like \ics{glsupdatewidest} provided by \styfmt{glossaries-extra-stylemods}), but this requires knowing -which name is the widest. Alternative one of the iterative commands +which name is the widest. Alternatively, one of the iterative commands such as \ics{glsFindWidestTopLevelName} can be used, which slows the 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}. + +The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest}, +which sets the widest name for those styles that need it. As from version +1.8, \bibgls\ now checks for the existence of this command and will use it with +\csopt{set-widest} to allow for the new styles provided by the +\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 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 aren't provided in the \ext{bib} files preamble, \emph{this option may not -work}. For example, if one entry has the \field{name} defined as -\begin{verbatim} -name={some {\Huge huge} text} -\end{verbatim} -and another entry has the \field{name} defined as -\begin{verbatim} -name={some {\small small} text} -\end{verbatim} +work}. For example, if one entry has the \field{name} defined as: +\begin{codeenv} +\field{name}=\marg{some \marg{\cmd{Huge} huge} text} +\end{codeenv} +and another entry has the \field{name} defined as: +\begin{codeenv} +\field{name}=\marg{some \marg{\cmd{small} small} text} +\end{codeenv} then \bibgls\ will determine that the second name is the widest although the first will actually be wider when it's rendered in the document. -When using this option, the transcript file will include the message +When using this option, the transcript file will include the message: \begin{alltt} Calculated width of '\meta{text}': \meta{number} \end{alltt} @@ -5261,7 +5661,8 @@ selected. This will then be implemented as follows: This leaves \TeX\ to compute the width according to the document fonts. If \bibgls\ can't correctly determine the widest entry then you will need to use one of the commands provided by -\sty{glossary-tree} or \sty{glossaries-extra-stylemods} to set it. +\sty{glossary-tree}, \sty{glossary-longextra} or +\sty{glossaries-extra-stylemods} to set it. In general, if you have more than one glossary it's best to set the \field{type} using options like \csopt{type} and @@ -5270,86 +5671,86 @@ set the \field{type} using options like \csopt{type} and \optsection{entry-type-aliases} In the \ext{bib} file, the data is identified by -\code{@\meta{entry-type}}, such as \code{@abbreviation}. +\code{@\meta{entry-type}}, such as \atentry[noindex]{abbreviation}. It may be that you want to replace all instances of \code{@\meta{entry-type}} with a different type of entry. For example, suppose my \ext{bib} file contains abbreviations defined in the form: -\begin{verbatim} -@abbreviation{html, - short ={html}, - long = {hypertext markup language}, - description={a markup language for creating web pages} +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{a markup language for creating web pages} } -\end{verbatim} +\end{codeenv} but suppose in one of my documents I actually want all these -abbreviations defined with \atentry{dualabbreviationentry} -instead of \atentry{abbreviation}. Instead of editing +abbreviations defined with \atentry[noindex]{dualabbreviationentry} +instead of \atentry[noindex]{abbreviation}. Instead of editing the \ext{bib} file I can just supply a mapping: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - entry-type-aliases={abbreviation=dualabbreviationentry} -] -\end{verbatim} -This makes all instances of \code{@abbreviation} -behave as \code{@dualabbreviationentry}. You can have more than +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[abbreviation=dualabbreviationentry]{entry-type-aliases} +} +\end{codeenv} +This makes all instances of \atentry[noindex]{abbreviation} +behave as \atentry[noindex]{dualabbreviationentry}. You can have more than one mapping. For example: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - entry-type-aliases={ - % @abbreviation -> @dualabbreviationentry: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[ + \comment{\atentry{abbreviation} -> \atentry{dualabbreviationentry}:} abbreviation=dualabbreviationentry, - % @entry -> @index: + \comment{\atentry{entry} -> \atentry{index}:} entry=index - } -] -\end{verbatim} + ]{entry-type-aliases} +} +\end{codeenv} This option isn't cumulative. Multiple instances of \csopt{entry-type-aliases} override previous instances. If \meta{\keyvallist} is empty there will be no mappings. Here's another example entry in a \ext{bib} file: -\begin{verbatim} -@foo{html, - name={HTML}, - short={HTML}, - long={hypertext markup language}, - description={hypertext markup language} +\begin{codeenv} +@foo\marg{html, + \field{name} = \marg{HTML}, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description} = \marg{hypertext markup language} } -\end{verbatim} +\end{codeenv} Ordinarily this entry would be ignored since \code{@foo} isn't recognised, but it can be mapped like this: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - ignore-fields={short,long}, - entry-type-aliases={foo=entry} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[short,long]{ignore-fields}, + \csopt[foo=entry]{entry-type-aliases} +} +\end{codeenv} This treats the entry as though it had been defined as: -\begin{verbatim} -@entry{html, - name={HTML}, - description={hypertext markup language} +\begin{codeenv} +\atentry{entry}\marg{html, + \field{name} = \marg{HTML}, + \field{description} = \marg{hypertext markup language} } -\end{verbatim} -whereas -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - ignore-fields={name,description}, - entry-type-aliases={foo=abbreviation} -] -\end{verbatim} +\end{codeenv} +whereas: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name,description]{ignore-fields}, + \csopt[foo=abbreviation]{entry-type-aliases} +} +\end{codeenv} treats the entry as though it had been defined as: -\begin{verbatim} -@abbreviation{html, - short={HTML}, - long={hypertext markup language} +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language} } -\end{verbatim} +\end{codeenv} \optsection{action} @@ -5372,11 +5773,11 @@ definition will be ignored. (The warnings can be found in the \sty{glossaries-extra} not by \bibgls.) For example, if you try: -\begin{verbatim} -\newglossary*{copies}{Copies} -\GlsXtrLoadResources[src={entries}] -\GlsXtrLoadResources[sort=use,type=copies,src={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{copies}\marg{Copies} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\gls{GlsXtrLoadResources}\oarg{\csopt[use]{sort},\csopt[copies]{type},\csopt[entries]{src}} +\end{codeenv} you'll find that the \code{copies} glossary is empty and there will be warnings in the \ext{log} file when the second resource file is loaded. @@ -5424,28 +5825,29 @@ sorting.) The purpose of the copy action is simply to provide a duplicate list in a different order. Remember that if you are using \sty{hyperref}, you need to use -\code{target=false} in the optional argument of +\code{\printglossopt[false]{target}} in the optional argument of \ics{printunsrtglossary} for the glossary containing the copies to prevent duplicate hypertargets. Commands like \cs{gls} will link to the original entries. For example, in the preamble: -\begin{verbatim} -\newignoredglossary{copies} - -\GlsXtrLoadResources[src={entries}] - -\GlsXtrLoadResources[ - sort=use, - action={copy}, - type=copies, - src={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newignoredglossary}\marg{copies} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[use]{sort}, + \csopt[copy]{action}, + \csopt[copies]{type}, + \csopt[entries]{src} +} +\end{codeenv} and later in the document: -\begin{verbatim} -\printunsrtglossary[title={Glossary (Alphabetical)},style=indexgroup] -\printunsrtglossary[type=copies,title={Glossary (Order of Use)}, - style=index,nogroupskip, - target=false] -\end{verbatim} +\begin{codeenv} +\cs{printunsrtglossary}\oarg{\printglossopt[Glossary (Alphabetical)]{title},\printglossopt[\glostyle{indexgroup}]{style}} +\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Glossary (Order of Use)]{title}, + \printglossopt[index]{style},\printglossopt{nogroupskip},\comment{no grouping} + \printglossopt[false]{target}} +\end{codeenv} Note also the need to use \code{nogroupskip} and a non-group style for the duplicates since the \field{group} field will have been assigned in the first resource set if \bibgls\ was invoked with @@ -5460,17 +5862,17 @@ before you display the glossary. The simplest way to do this is with the starred form of \cs{printunsrtglossary}. For example, if \csopt[dupgroup]{copy-action-group-field} is added to the options for the second resource set: -\begin{alltt} -\ics{printunsrtglossary*}\oarg{type=copies,title={Duplicates},style=indexgroup} +\begin{codeenv} +\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[\glostyle{indexgroup}]{style}} \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} -\end{alltt} +\end{codeenv} This just does: -\begin{verbatim} -\begingroup - \renewcommand{\glsxtrgroupfield}{dupgroup}% - \printunsrtglossary[type=copies,title={Duplicates},style=indexgroup] -\endgroup -\end{verbatim} +\begin{codeenv} +\cmd{begingroup} + \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{} + \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[indexgroup]{style}} +\cmd{endgroup} +\end{codeenv} \section{Selection Options} @@ -5487,22 +5889,22 @@ them). The \ext{bib} extension may be omitted. Remember that if \meta{list} contains multiple files it must be grouped to protect the comma from the \meta{options} list. -For example -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}] -\end{verbatim} +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} indicates that \bibgls\ must read the files \filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} and create the file given by \ics{jobname}\iext{glstex} on the first instance or \ics{jobname}\code{-}\meta{n}\ext{glstex} on subsequent use. -With \csref{glsxtrresourcefile}\oargm{options}\margm{filename}, if +With \code{\gls!{glsxtrresourcefile}\oargm{options}\margm{filename}}, if the \csopt{src} option is omitted, the \ext{bib} file is assumed to be \meta{filename}\ext{bib}. For example: -\begin{verbatim} -\glsxtrresourcefile{entries-symbols} -\end{verbatim} +\begin{codeenv} +\gls{glsxtrresourcefile}\marg{entries-symbols} +\end{codeenv} indicates that \bibgls\ needs to read the file \filefmt{entries-symbols.bib}, which contains the entry data, and create the file \filefmt{entries-symbols.glstex}. If the \ext{bib} file is @@ -5510,14 +5912,38 @@ different or if you have multiple \ext{bib} files, you need to use the \csopt{src} option. \gls{GlsXtrLoadResources} uses \ics{jobname} as the argument of -\gls{glsxtrresourcefile} on the first instance, so -\begin{verbatim} -\GlsXtrLoadResources[] -\end{verbatim} -will assume \optfmt{src=\ics{jobname}}. Remember that subsequent uses +\gls{glsxtrresourcefile} on the first instance, so: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{} +\end{codeenv} +will assume \csopt[\ics{jobname}]{src}. Remember that subsequent uses of \gls{GlsXtrLoadResources} append a suffix, so in general it's best to always supply \csopt{src}. +If you have non-ASCII characters in the \ext{bib} filename but +aren't using \XeLaTeX\ or \LuaLaTeX, then you will need to use +\ics{detokenize} to prevent expansion when the information is +written to the \ext{aux} file. Similarly for any special characters +that need protecting (although it's better not to use special +characters in filenames). For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{T2A}\marg{fontenc} +\cmd{usepackage}\oarg{utf8}\marg{inputenc} +\cmd{usepackage}\oarg{russian}\marg{babel} +\cmd{usepackage}\oarg{record}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\cs{detokenize}\marg{\textcyrillicmono{кириллица}}]{src},\comment{data in \textcyrillicmono{кириллица.bib}} + \csopt[all]{selection} +} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} + \optsection{selection} By default all entries that have records in the \iext{aux} file will @@ -5527,11 +5953,11 @@ run, may need an additional build to ensure their location lists are updated. Remember that on the first \LaTeX\ run the \iext{glstex} files don't -exist. This means that the entries can't be defined. The +exist. This means that the entries aren't defined at that point. The \styopt{record} package option additionally switches on the \styopt[warn]{undefaction} option, which means that you'll only get warnings rather than errors when you reference entries in the -document. This means that you can't use \ics{glsaddall} with +document. You can't use \ics{glsaddall} with \bibgls\ because the glossary lists are empty on the first run, so there's nothing for \ics{glsaddall} to iterate over. Instead, if you want to add all defined entries, you need to @@ -5544,7 +5970,8 @@ their dependencies (default). add unrecorded entries whose \field{see} or \field{seealso} field refers to a recorded entry. \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, \field{parent} entries and those found referenced +\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}. @@ -5558,15 +5985,13 @@ supplied in the \csopt{src} option. The \meta{value} must be supplied. For example, suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@index{run} - -@index{sprint,see={run}} - -@index{dash,see={sprint}} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{run} +\atentry{index}\marg{sprint,\field{see}=\marg{run}} +\atentry{index}\marg{dash,\field{see}=\marg{sprint}} +\end{codeenv} If the document only references the \qt{run} entry (for example, -using \verb|\gls{run}|) then: +using \code{\cs{gls}\marg{run}}) then: \begin{itemize} \item If \csopt[recorded and deps]{selection}, only the \qt{run} entry is selected. The \qt{run} entry has a record, so it's @@ -5584,25 +6009,77 @@ selected. \end{itemize} 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. A better method would be: -\begin{verbatim} -@index{run} - -@index{sprint,see={run}} - -@index{dash,see={run}} -\end{verbatim} +is best avoided (especially for an index where there are no accompanying +descriptions and no \idx{locationlist} for the intermediate \qt{sprint}). +A better method would be: +\begin{codeenv} +\atentry{index}\marg{run} +\atentry{index}\marg{sprint,\field{see}=\marg{run}} +\atentry{index}\marg{dash,\field{see}=\marg{run}} +\end{codeenv} The \csopt[recorded and deps and see]{selection} in this case will select all three entries, and the document won't send the reader on a long-winded detour. +Now suppose that the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{run, + \field{name} = \marg{run}, + \field{description}=\marg{move fast using legs} +} +\strut +\atentry{entry}\marg{sprint, + \field{name} = \marg{sprint}, + \field{description}=\marg{run at full speed over short distance}, + \field{seealso}=\marg{run} +} +\strut +\atentry{entry}\marg{dash, + \field{name} = \marg{dash}, + \field{description}=\marg{run in a great hurry}, + \field{seealso}=\marg{sprint} +} +\end{codeenv} +and suppose the document only references \qt{dash} (for example, with +\code{\cs{gls}\marg{dash}}), then with the default \csopt[recorded and deps]{selection} +\qt{dash} will be selected because it has a record, and \qt{sprint} +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 +for the reader in their descriptions. + +A better method here would be for each entry to have a cross-reference +list that includes all related terms: +\begin{codeenv} +\atentry{entry}\marg{run, + \field{name} = \marg{run}, + \field{description}=\marg{move fast using legs}, + \field{seealso}=\marg{sprint,dash} +} +\strut +\atentry{entry}\marg{sprint, + \field{name} = \marg{sprint}, + \field{description}=\marg{run at full speed over short distance}, + \field{seealso}=\marg{run,dash} +} +\strut +\atentry{entry}\marg{dash, + \field{name} = \marg{dash}, + \field{description}=\marg{run in a great hurry}, + \field{seealso}=\marg{sprint,run} +} +\end{codeenv} +Now, whichever one is indexed in the document, the other two will automatically +be selected. + \optsection{match} It's possible to filter the selection by matching field values. If \meta{\keyvallist} is empty no filtering will be applied, otherwise \meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where \meta{key} is the name of a field or \optfmt{id} for the entry's -label or \optfmt{entrytype} for the entry type (as in +label or \optfmt{entrytype} for the \bibgls\ entry type (as in the part after \verb|@| identifying the entry not the \field{type} field identifying the glossary label). If you've used \csopt{entry-type-aliases}, this refers to the target entry type not @@ -5612,12 +6089,12 @@ The \meta{regex} part should be a regular expression conforming to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's Pattern class}~\cite{pattern}. The pattern is anchored -(\code{oo\idx{matchanydot}\idx{zeroormore}} matches +(\code{oo}\idx{matchanydot}\idx{zeroormore} matches \code{oops} but not \code{loops}) and \meta{regexp} can't be empty. Remember that \TeX\ will expand the option list as it writes the information to the \ext{aux} file so take care with special characters. For example, to match a literal -period use \cs{cs.string}\ics{cs.period} not \ics{cs.period} (backslash dot). +period use \cs{cs.string}\idx{cs.period} not \idx{cs.period} (backslash dot). If the field is missing its value it is assumed to be empty for the purposes of the pattern match even if it will be assigned a @@ -5626,7 +6103,7 @@ unrecognised by \bibgls\ any reference to it in \meta{\keyvallist} will be ignored. If a field is listed multiple times, the pattern for that -field is concatenated using +field is concatenated using: \begin{alltt} (?:\meta{pattern-1})|(?:\meta{pattern-2}) \end{alltt} @@ -5635,14 +6112,14 @@ and \meta{pattern-2} is the new pattern. This means it performs a logical OR\@. For the non-duplicate fields the logical operator is given by \csopt{match-op}. For example: -\begin{verbatim} -match-op={and}, -match={ - category=animals, - topic=biology, - category=vegetables -} -\end{verbatim} +\begin{codeenv} +\csopt[and]{match-op}, +\csopt[ + \field{category}=animals, + \fieldfmt{topic}=biology, + \field{category}=vegetables +]{match} +\end{codeenv} This will keep all the selected entries that satisfy: \begin{itemize} \item \field{category} matches \verb"(?:animals)|(?:vegetables)" @@ -5697,13 +6174,13 @@ For example, if I want to select all record entries and their dependencies, but I also want to make sure that any entries with the category set to \code{important} are always selected regardless of whether or not they have any records: -\begin{verbatim} -\GlsXtrLoadResource[ - src=entries,% data in entries.bib - match-action={add}, - match={category=important} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[add]{match-action}, + \csopt[\field{category}=important]{match} +} +\end{codeenv} \optsection{limit} @@ -5753,68 +6230,68 @@ this command will do \meta{false} as the \field{childcount} field won't be set. For example, suppose \filefmt{entries.bib} contains: -\begin{verbatim} -@index{birds} -@index{duck,parent={birds}} -@index{goose,plural={geese},parent={birds}} -@index{swan,parent={birds}} - -@index{minerals} -@index{quartz,parent={minerals}} -@index{corundum,parent={minerals}} -@index{amethyst,parent={minerals}} -@index{gypsum,parent={minerals}} -@index{gold,parent={minerals}} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{birds} +\atentry{index}\marg{duck,\field{parent}=\marg{birds}} +\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} +\atentry{index}\marg{swan,\field{parent}=\marg{birds}} +\strut +\atentry{index}\marg{minerals} +\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} +\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gold,\field{parent}=\marg{minerals}} +\end{codeenv} and the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries},save-child-count] - -\begin{document} -\gls{duck} and \gls{goose}. -\gls{quartz}, \gls{corundum}, \gls{amethyst}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{save-child-count}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{duck} and \cs{gls}\marg{goose}. +\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} Then the \ext{glstex} file will contain: -\begin{verbatim} -\GlsXtrSetField{birds}{childcount}{2} -\GlsXtrSetField{duck}{childcount}{0} -\glsxtrfieldlistadd{birds}{childlist}{duck} -\GlsXtrSetField{goose}{childcount}{0} -\glsxtrfieldlistadd{birds}{childlist}{goose} -\GlsXtrSetField{minerals}{childcount}{3} -\GlsXtrSetField{amethyst}{childcount}{0} -\glsxtrfieldlistadd{minerals}{childlist}{amethyst} -\GlsXtrSetField{corundum}{childcount}{0} -\glsxtrfieldlistadd{minerals}{childlist}{corundum} -\GlsXtrSetField{quartz}{childcount}{0} -\glsxtrfieldlistadd{minerals}{childlist}{quartz} -\end{verbatim} +\begin{codeenv} +\cs{GlsXtrSetField}\marg{birds}\marg{childcount}\marg{2} +\cs{GlsXtrSetField}\marg{duck}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{duck} +\cs{GlsXtrSetField}\marg{goose}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{goose} +\cs{GlsXtrSetField}\marg{minerals}\marg{childcount}\marg{3} +\cs{GlsXtrSetField}\marg{amethyst}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{amethyst} +\cs{GlsXtrSetField}\marg{corundum}\marg{childcount}\marg{0} +\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{corundum} +\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 +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 in parentheses: -\begin{verbatim} -\GlsXtrLoadResources[src={entries},category=general,save-child-count] - -\renewcommand{\glsxtrpostdescgeneral}{% - \glsxtrifhasfield{childcount}{\glscurrententrylabel} - { (child count: \glscurrentfieldvalue.)}% - {}% +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}} +\strut +\cs{glsdefpostdesc}\marg{general}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{childcount}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (child count: \cs{glscurrentfieldvalue}.)}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} \ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. -It's slightly more efficient that \ics{ifglshasfield} provided by +It's slightly more efficient than \ics{ifglshasfield} provided by the base \styfmt{glossaries} package, and it doesn't complain if the entry or field don't exist, but note that \ics{glsxtrifhasfield} implicitly scopes its content. Use the starred version to omit the @@ -5843,7 +6320,7 @@ This may take one of three values: \optfmt{false} (default), 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 checked. This option +that have a parent but have no siblings 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: \begin{itemize} @@ -5868,48 +6345,48 @@ or after sorting (\optfmt{postsort}). To disable this function use \csopt[false]{flatten-lonely}. For example, suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@index{birds} -@index{duck,parent={birds}} -@index{goose,plural={geese},parent={birds}} -@index{swan,parent={birds}} -@index{chicken,parent={birds}} - -@index{vegetable} -@index{cabbage,parent={vegetable}} - -@index{minerals} -@index{quartz,parent={minerals}} -@index{corundum,parent={minerals}} -@index{amethyst,parent={minerals}} -@index{gypsum,parent={minerals}} - -@index{aardvark} -@index{bard} -@index{buzz} - -@index{item} -@index{subitem,parent={item}} -@index{subsubitem,parent={subitem}} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{birds} +\atentry{index}\marg{duck,\field{parent}=\marg{birds}} +\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}} +\atentry{index}\marg{swan,\field{parent}=\marg{birds}} +\atentry{index}\marg{chicken,\field{parent}=\marg{birds}} +\strut +\atentry{index}\marg{vegetable} +\atentry{index}\marg{cabbage,\field{parent}=\marg{vegetable}} +\strut +\atentry{index}\marg{minerals} +\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}} +\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}} +\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}} +\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}} +\strut +\atentry{index}\marg{aardvark} +\atentry{index}\marg{bard} +\atentry{index}\marg{buzz} +\strut +\atentry{index}\marg{item} +\atentry{index}\marg{subitem,\field{parent}=\marg{item}} +\atentry{index}\marg{subsubitem,\field{parent}=\marg{subitem}} +\end{codeenv} and suppose the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources[src={entries.bib}] - -\begin{document} -\gls{duck}. -\gls{quartz}, \gls{corundum}, \gls{amethyst}. -\gls{aardvark}, \gls{bard}, \gls{buzz}. -\gls{vegetable}, \gls{cabbage}. -\gls{subsubitem}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{duck}. +\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}. +\cs{gls}\marg{aardvark}, \cs{gls}\marg{bard}, \cs{gls}\marg{buzz}. +\cs{gls}\marg{vegetable}, \cs{gls}\marg{cabbage}. +\cs{gls}\marg{subsubitem}. +\strut +\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. @@ -5956,9 +6433,9 @@ 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{verbatim} -\GlsXtrLoadResources[src={entries.bib},flatten-lonely=postsort] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}} +\end{codeenv} the hierarchy becomes: \begin{description}\setlength\itemsep{0pt}% \item[A] \null @@ -5983,26 +6460,26 @@ the hierarchy becomes: \end{description} \end{description} The \field{name} field of the \code{duck} entry has been -set to -\begin{verbatim} -name={\bibglsflattenedchildpostsort{birds}{duck}} -\end{verbatim} -the \field{text} field has been set to -\begin{verbatim} -text={duck} -\end{verbatim} +set to: +\begin{codeenv} +\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{birds}\marg{duck}} +\end{codeenv} +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}), 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 \csopt[only unrecorded parents]{flatten-lonely-rule} is in effect). -The default definition of \csref{bibglsflattenedchildpostsort} +The default definition of \gls!{bibglsflattenedchildpostsort} formats its arguments so that they are separated by a comma and space (\qt{birds, duck}). If the \field{text} field had been set in the original \atentry{index} definition of \text{duck}, it wouldn't have been altered. This adjustment ensures that in the -document \verb|\gls{duck}| still produces \qt{duck} rather than +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.) @@ -6013,29 +6490,29 @@ 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 -modified to -\begin{verbatim} -name={\bibglsflattenedchildpostsort{item}{subitem}} -\end{verbatim} +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 (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. \item The \code{subsubitem} entry is then adjusted moving from a sub-entry to a top-level entry. The \field{name} field was then -modified to -\begin{verbatim} -name= -{% - \bibglsflattenedchildpostsort - {% - % name from former parent - \bibglsflattenedchildpostsort{item}{subitem}% - }% - {subsubitem}% original name +modified to: +\begin{codeenv} +\field{name}= +\marg{\comment{} + \gls{bibglsflattenedchildpostsort} + \marg{\comment{} + \comment{name from former parent} + \gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}\comment{} + }\comment{} + \marg{subsubitem}\comment{original name} } -\end{verbatim} -The first argument of \csref{bibglsflattenedchildpostsort} is +\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 @@ -6053,11 +6530,12 @@ 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. If I change the rule: -\begin{verbatim} -\GlsXtrLoadResources[src={entries.bib}, - flatten-lonely-rule=discard unrecorded, - flatten-lonely=postsort] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[discard unrecorded]{flatten-lonely-rule}, + \csopt[postsort]{flatten-lonely} +} +\end{codeenv} then this will move the \code{cabbage} entry up a level but the original parent entry \code{vegetable} will remain: \begin{description}\setlength\itemsep{0pt}% @@ -6089,11 +6567,12 @@ remains in the B letter group before \qt{buzz}. With \csopt[presort]{flatten-lonely} the adjustments are made before the sorting is performed. For example, using: -\begin{verbatim} -\GlsXtrLoadResources[src={entries.bib}, - flatten-lonely-rule=discard unrecorded, - flatten-lonely=presort] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[discard unrecorded]{flatten-lonely-rule}, + \csopt[presort]{flatten-lonely} +} +\end{codeenv} the hierarchical order is now: \begin{description}\setlength\itemsep{0pt}% \item[A] \null @@ -6119,9 +6598,9 @@ the hierarchical order is now: \end{description} This method uses a different format for the modified \field{name} field. For example, the \code{duck} entry now has: -\begin{verbatim} -name={\bibglsflattenedchildpresort{duck}{birds}} -\end{verbatim} +\begin{codeenv} +\field{name}=\marg{\gls{bibglsflattenedchildpresort}\marg{duck}\marg{birds}} +\end{codeenv} The default definition of \gls{bibglsflattenedchildpresort} simply does the first argument and ignores the second. The sorting is then performed, but the interpreter recognises this command and can @@ -6131,15 +6610,15 @@ so \qt{duck} now ends up in the D letter group. If you provide a definition of \gls{bibglsflattenedchildpresort} in the \atentry{preamble}, it will be picked up by the interpreter. For example: -\begin{verbatim} -@preamble{"\providecommand{\bibglsflattenedchildpresort}[2]{#1 (#2)}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} +\end{codeenv} 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 location list and the rule isn't +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 after all relevant entries and their dependencies have been selected, so any cross-references within the parent entry (such as @@ -6149,11 +6628,11 @@ even if they wouldn't be selected if the parent entry 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 -\begin{alltt} -\csref{bibglsflattenedhomograph}\margm{name}\margm{parent label} -\end{alltt} -instead of the corresponding \csfmt{bibglsflattenedchild...sort}. +the child's name is set to: +\begin{codeenv*} +\format{bibglsflattenedhomograph} +\end{codeenv*} +instead of the corresponding \csfmt{bibglsflattenedchild\ldots sort}. This defaults to just \meta{name}. @@ -6164,21 +6643,21 @@ determine which sub-entries (that have no siblings) to adjust and which 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 location list will be altered. +that have a parent without a \idx{locationlist} will be altered. The parent entry 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 location list. +parent has a \idx{locationlist}. Only the parent entries that don't have a location list 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 location list. No entries will be discarded, so parent -entries that don't have a location list will still appear in 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 glossary. \end{description} -In the above, the location list includes records and +In the above, the \idx{locationlist} includes records and cross-references obtained from the \field{see} or \field{seealso} fields. See \csopt{flatten-lonely} for further details. @@ -6234,28 +6713,28 @@ the new parent entry can be assigned with \end{itemize} For example, consider the \exfile{books.bib} file which contains -entries like -\begin{verbatim} -@entry{ubik, - name={Ubik}, - description={novel by Philip K. Dick}, - identifier={book}, - author={\sortmediacreator{Philip K.}{Dick}}, - year={1969} +entries like: +\begin{codeenv} +\atentry{entry}\marg{ubik, + \field{name}=\marg{Ubik}, + \field{description}=\marg{novel by Philip K. Dick}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, + \fieldfmt{year}=\marg{1969} } -\end{verbatim} -then the field alias +\end{codeenv} +then the field alias: \begin{codeenv} -\csopt[author=parent]{field-aliases} +\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} +\end{codeenv} +will treat: +\begin{codeenv} + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, +\end{codeenv} +as though it had been defined as: +\begin{codeenv} + \field{parent}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}, \end{codeenv} -will treat -\begin{verbatim} - author={\sortmediacreator{Philip K.}{Dick}}, -\end{verbatim} -as though it had been defined as -\begin{verbatim} - parent={\sortmediacreator{Philip K.}{Dick}}, -\end{verbatim} This can be converted into a label with the options: \begin{codeenv} \csopt[parent]{labelify}, @@ -6264,9 +6743,9 @@ This can be converted into a label with the options: ]{labelify-replace} \end{codeenv} If the interpreter has been provided with the definition: -\begin{verbatim} -\providecommand*{\sortmediacreator}[2]{#2 #1} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}*\marg{\gls{sortmediacreator}}[2]\marg{\idx{param}2 \idx{param}1} +\end{codeenv} 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 @@ -6274,11 +6753,11 @@ can be used as the \field{name} if the parent needs to be created. Once all the entries have been processed, if \code{ubik} has been selected but no entry can be found with the label \code{DickPhilipK} then a new entry will be added as though it had been defined with: -\begin{verbatim} -@index{DickPhilipK, - name={\sortmediacreator{Philip K.}{Dick}} +\begin{codeenv} +\atentry{index}\marg{DickPhilipK, + \field{name}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}} } -\end{verbatim} +\end{codeenv} This is an alternative approach to the \exfile{sample-authors.tex} document from the \hyperref[sec:examples]{examples chapter}. @@ -6314,39 +6793,39 @@ glossary. This can be achieved with the \catattr{targeturl} and \catattr{targetname} category attributes. For example, without \bibgls\ the file \filefmt{mybook.tex} might look like: -\begin{verbatim} -\documentclass{book} -\usepackage[colorlinks]{hyperref} -\usepackage{glossaries-extra} - -\makeglossaries - -\newglossaryentry{sample}{name={sample},description={an example}} - -\begin{document} -\chapter{Example} -\gls{sample}. - -\printglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{book} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cs{cs.makeglossaries} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}\marg{document} +\cs{chapter}\marg{Example} +\cs{gls}\marg{sample}. +\strut +\cs{printglossaries} +\cmd{end}\marg{document} +\end{codeenv} The other document \filefmt{myarticle.tex} might look like: -\begin{verbatim} -\documentclass{article} -\usepackage[colorlinks]{hyperref} -\usepackage{glossaries-extra} - -\newignoredglossary*{external} -\glssetcategoryattribute{external}{targeturl}{mybook.pdf} -\glssetcategoryattribute{external}{targetname}{\glolinkprefix\glslabel} - -\newglossaryentry{sample}{type=external,category=external, - name={sample},description={an example}} - -\begin{document} -\gls{sample}. -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\marg{glossaries-extra} +\strut +\cs{newignoredglossary*}\marg{external} +\ics{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} +\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} +\strut +\gls{newglossaryentry}\marg{sample}\marg{\field{type}=external,\field{category}=external, + \field{name}=\marg{sample},\field{description}=\marg{an example}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{sample}. +\cmd{end}\marg{document} +\end{codeenv} In this case the \optfmt{main} glossary 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 @@ -6357,48 +6836,49 @@ references. (In which case, \csfmt{makeglossaries} and Note that both documents had to define the common terms. The above documents can be rewritten to work with \bibgls. First a \ext{bib} file needs to be created: -\begin{verbatim} -@entry{sample, - name={sample}, - description={an example} +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name}=\marg{sample}, + \field{description}=\marg{an example} } -\end{verbatim} +\end{codeenv} Assuming this file is called \filefmt{myentries.bib}, then \filefmt{mybook.tex} can be changed to: -\begin{verbatim} -\documentclass{book} -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[src={myentries}] - -\begin{document} -\chapter{Example} -\gls{sample}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{book} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{chapter}\marg{Example} +\cs{gls}\marg{sample}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} and \filefmt{myarticle.tex} can be changed to: -\begin{verbatim} -\documentclass{article} -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\newignoredglossary*{external} -\glssetcategoryattribute{external}{targeturl}{mybook.pdf} -\glssetcategoryattribute{external}{targetname}{\glolinkprefix\glslabel} - -\GlsXtrLoadResources[ - src={myentries}, - sort=none, - type=external, - category=external] - -\begin{document} -\gls{sample}. -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\cs{newignoredglossary*}\marg{external} +\cs{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf} +\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[myentries]{src}, + \csopt[none]{sort}, + \csopt[external]{type}, + \csopt[external]{category} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{sample}. +\cmd{end}\marg{document} +\end{codeenv} Most of the options related to sorting and the glossary format are unneeded here since the glossary isn't being displayed. This may be sufficient for your needs, but it may be that the book has changed @@ -6450,22 +6930,20 @@ 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 -\ics{provideignoredglossary*}\margm{type}. +\code{\ics{provideignoredglossary*}\margm{type}}. The above \filefmt{myarticle.tex} can be changed to: -\begin{verbatim} -\documentclass{article} -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[ - label-prefix={book.}, - master={mybook}] - -\begin{document} -\gls{book.sample}. -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[record]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{book.sample}. +\cmd{end}\marg{document} +\end{codeenv} There are some settings from the master document that you still need to repeat in the other document. These include @@ -6477,33 +6955,31 @@ For example, if the master document 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. -Suppose \filefmt{mybook.tex} loads the resources using -\begin{verbatim} -\GlsXtrLoadResources[src={myentries},label-prefix={term.}] -\end{verbatim} +Suppose \filefmt{mybook.tex} loads the resources using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src},\csopt[term.]{label-prefix}} +\end{codeenv} and \filefmt{myarticle.tex} loads the resources using: -\begin{verbatim} -\GlsXtrLoadResources[ - label-prefix={book.}, - master={mybook}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}} +\end{codeenv} Then the entries referenced in \filefmt{myarticle.tex} need to use the prefix \optfmt{book.term.}\ as in: -\begin{verbatim} -This is a \gls{book.term.sample} term. -\end{verbatim} +\begin{codeenv} +This is a \cs{gls}\marg{book.term.sample} term. +\end{codeenv} Remember that the category labels will need adjusting to reflect the change in category label in the dependent document. For example, if \filefmt{mybook.tex} included: -\begin{verbatim} -\setabbreviationstyle{long-short-sc} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\marg{long-short-sc} +\end{codeenv} then \filefmt{myarticle.tex} will need: -\begin{verbatim} -\setabbreviationstyle[master]{long-short-sc} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{master}\marg{long-short-sc} +\end{codeenv} (change \optfmt{master} to \meta{value} if you have used \csopt[\meta{value}]{category}). You can, of course, choose a different abbreviation style for the dependent document, @@ -6517,7 +6993,7 @@ then by default all the master document's you can use \optfmt{master-resources} to specify only those files that should be included. The value \meta{list} is a comma-separated list of names, where each name corresponds -to the final argument of \csref{glsxtrresourcefile}. +to the final argument of \gls!{glsxtrresourcefile}. Remember that \gls{GlsXtrLoadResources} is just a shortcut for \gls{glsxtrresourcefile} that bases the name on \ics{jobname}. (Note that, as with the argument of \gls{glsxtrresourcefile}, @@ -6529,12 +7005,12 @@ resource file and the files \suppresourcefmt{\meta{n}} For example, to just select the first and third of the supplementary resource files (omitting the primary \filefmt{mybook.glstex}): -\begin{verbatim} -\GlsXtrLoadResources[ - master={mybook}, - master-resources={mybook-1,mybook-3} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[mybook]{master}, + \csopt[mybook-1,mybook-3]{master-resources} +} +\end{codeenv} \section{Field and Label Options} \label{sec:fieldlabelopts} @@ -6556,7 +7032,7 @@ that may only contain labels should have their values interpreted \field{seealso} and \field{alias}). Although this option interprets commands within those fields, it doesn't strip any characters that can't be used within a label. The \field{see} field isn't included -as it may optionally start with \code{[\meta{tag}]} where \meta{tag} +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}. @@ -6614,23 +7090,23 @@ characters are removed. \end{enumerate} For example, suppose the \ext{bib} file contains: -\begin{verbatim} -@index{sample, - name={\AA ngstr\"om, \O stergaard, d'Arcy, and Fotheringay-Smythe} +\begin{codeenv} +\atentry{index}\marg{sample, + \field{name}=\marg{\ics{AA} ngstr\ics{umlaut}om, \ics{O} stergaard, d'Arcy, and Fotheringay-Smythe} } -\end{verbatim} -Then -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - labelify={name} -] -\end{verbatim} -will convert the \field{name} field into +\end{codeenv} +Then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{labelify} +} +\end{codeenv} +will convert the \field{name} field into: \begin{verbatim} Angstrom stergaard d'Arcy and Fotheringay-Smythe \end{verbatim} -if the document hasn't used \sty{fontspec} otherwise it will be +if the document hasn't used \sty{fontspec} otherwise it will be: \begin{verbatim} Ångström Østergaard d'Arcy and Fotheringay-Smythe \end{verbatim} @@ -6646,13 +7122,13 @@ the closest match. Alternatively, switch to using \XeLaTeX\ or You can use this option with \csopt{replicate-fields} if you need to retain the original: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - replicate-fields={name={user1}}, - labelify={user1} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\field{user1}]{labelify} +} +\end{codeenv} \optsection[\subsubsection]{labelify-list} @@ -6660,18 +7136,18 @@ This option is like \csopt{labelify} but it retains commas, as it's designed for fields that should be converted into a comma-separated list of labels. Any empty elements are removed. For example, with the \ext{bib} entry from above: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - replicate-fields={name={user1}}, - labelify-list={user1} -] -\end{verbatim} -will convert the \field{user1} field into +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} +will convert the \field{user1} field into: \begin{verbatim} Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe \end{verbatim} -or +or: \begin{verbatim} Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe \end{verbatim} @@ -6680,26 +7156,26 @@ depending on whether or not \sty{fontspec} was detected. \optsection[\subsubsection]{labelify-replace} This option takes a comma-separated list as a value with each -element in the list in the form \margm{regex}\margm{replacement} -where \margm{regex} is a regular expression (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's +element in the list in the form \code{\margm{regex}\margm{replacement}} +where \meta{regex} is a regular expression (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's Pattern class}~\cite{pattern}) and \meta{replacement} is the replacement text. Remember that the argument of -\cs{GlsXtrLoadResources} is expanded when written to the \ext{aux} +\gls{GlsXtrLoadResources} is expanded when written to the \ext{aux} file so take care to protect any special characters. For example, to -match a literal \idx{full-stop} use \cs{cs.string}\ics{cs.period} -rather than just \ics{cs.period} (backslash dot). +match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period} +rather than just \idx{cs.period} (backslash dot). In the \meta{replacement} part, you can use \ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence. For example: -\begin{verbatim} -\csopt[{([A-Z])\string\.}{\glscapturedgroup1}]{labelify-replace} -\end{verbatim} +\begin{codeenv} +\csopt[\marg{([A-Z])\ics{cs.string}\idx{cs.period}}\marg{\cs{glscapturedgroup}1}]{labelify-replace} +\end{codeenv} This removes any \idx{full-stop} that follows any of the characters A,\ldots,Z. Alternatively, you can just use \verb|\string\$| instead of \cs{glscapturedgroup}. If you want a literal dollar character, you need to use \cs{glshex}\code{24} (or -\verb|\string\u|). This isn't recommended for labels (since special +\verb|\string\u24|). This isn't recommended for labels (since special characters are automatically stripped), but \csopt{sort-replace} follows the same rules as \csopt{labelify-replace}, and it may be needed @@ -6709,19 +7185,19 @@ Both \csopt{labelify} and \csopt{labelify-list} use the \csopt{labelify-replace} setting to perform substitutions. For example, to replace the sub-string \qt{ and } (including spaces) with a comma: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - replicate-fields={name={user1}}, - labelify-replace={{ and }{,}}, - labelify-list={user1} -] -\end{verbatim} -The earlier example will now end up as +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[\marg{ and }\marg{,}]{labelify-replace}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} +The earlier example will now end up as: \begin{verbatim} Angstrom, stergaard, d'Arcy,Fotheringay-Smythe \end{verbatim} -or +or: \begin{verbatim} Ångström, Østergaard, d'Arcy,Fotheringay-Smythe \end{verbatim} @@ -6733,25 +7209,25 @@ converted to \verb|,,| and then the empty element is removed resulting in a single comma. You can have more than one replacement: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - replicate-fields={name={user1}}, - labelify-replace={ - { and }{,},% first substitution - {[ '\string\-]}{},% second substitution - {\string\u00D8}{O}% third substitution - }, - labelify-list={user1} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields}, + \csopt[ + \marg{ and }\marg{,},\comment{first substitution} + \marg{[ '\cs{cs.string}\cmd{-}]}\marg{},\comment{second substitution} + \marg{\ics{glshex}00D8}\marg{O}\comment{third substitution} + ]{labelify-replace}, + \csopt[\field{user1}]{labelify-list} +} +\end{codeenv} This additionally removes the space, apostrophe and hyphen characters (second substitution) and replaces \qt{\O} (\hex{00D8}) -with \qt{O} (third substitution) so the string now ends up as +with \qt{O} (third substitution) so the string now ends up as: \begin{verbatim} Angstrom,Ostergaard,dArcy,FotheringaySmythe \end{verbatim} -or +or: \begin{verbatim} Ångström,Ostergaard,dArcy,FotheringaySmythe \end{verbatim} @@ -6759,49 +7235,53 @@ depending on whether or not \sty{fontspec} was detected. \optsection[\subsubsection]{label-prefix} -The \csopt{label-prefix} option prepends \meta{tag} to each -entry's label. This \meta{tag} will also be inserted in front of any -cross-references, unless they start with \idprefix{dual} 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. - -For example, if the \ext{bib} file contains -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls {goose}} -} - -@entry{waterfowl, - name={waterfowl}, - description={Any \gls{bird} that lives in or about water}, - see={[see also]{duck,goose}} -} +The \csopt{label-prefix} option prepends \meta{tag} to each entry's label. This +\meta{tag} will also be inserted in front of any cross-references, unless they +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. -@index{duck} +As from version 1.8, the primary label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsprimaryprefixlabel} +\end{codeenv} -@index{goose,plural="geese"} -\end{verbatim} +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} +} +\strut +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{Any \cs{gls}\marg{bird} that lives in or about water}, + \field{see}=\marg{[see also]\marg{duck,goose}} +} +\strut +\atentry{index}\marg{duck} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} it's as though the entries had been defined as: -\begin{verbatim} -@entry{gls.bird, - name={bird}, - description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -} - -@entry{gls.waterfowl, - name={waterfowl}, - description={Any \gls{gls.bird} that lives in or about water}, - see={[see also]{gls.duck,gls.goose}} -} - -@index{gls.duck,name={duck}} - -@index{gls.goose,name={goose},plural="geese"} -\end{verbatim} +\begin{codeenv} +\atentry{entry}\marg{gls.bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or \cs{gls}\marg{gls.goose}} +} +\strut +\atentry{entry}\marg{gls.waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{Any \cs{gls}\marg{gls.bird} that lives in or about water}, + \field{see}=\marg{[see also]\marg{gls.duck,gls.goose}} +} +\strut +\atentry{index}\marg{gls.duck,\field{name}=\marg{duck}} +\strut +\atentry{index}\marg{gls.goose,\field{name}=\marg{goose},\field{plural}=\qtdelim{geese}} +\end{codeenv} Remember to use this prefix when you reference the terms in the document with commands like \ics{gls}. @@ -6830,7 +7310,7 @@ The actual suffix is formed from \meta{value}\meta{n} where \meta{n} is an integer that's incremented in the event of multiple duplicates. For example, \csopt[.copy]{duplicate-label-suffix} will change the label to \meta{id}\code{.copy1} for the first duplicate -of the entry whose label is \meta{id}, \meta{id}\code{.copy2} for +of the entry whose label is \meta{id}, and \meta{id}\code{.copy2} for the second duplicate, etc. \optsection[\subsubsection]{record-label-prefix} @@ -6838,26 +7318,26 @@ the second duplicate, etc. If set, this option will cause \bibgls\ to pretend that each record label starts with \meta{tag}, if it doesn't already. For example, suppose the records in the \ext{aux} file are: -\begin{verbatim} -\glsxtr@record{bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\end{codeenv} The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as though the records were given as: -\begin{verbatim} -\glsxtr@record{idx.bird}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.waterfowl}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.duck}{}{page}{glsnumberformat}{1} -\glsxtr@record{idx.goose}{}{page}{glsnumberformat}{1} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{idx.bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\end{codeenv} \optsection[\subsubsection]{cs-label-prefix} -If you have commands such as \ics{gls}\margm{label} or -\ics{glstext}\marg{label} in field +If you have commands such as \code{\ics{gls}\margm{label}} or +\code{\ics{glstext}\margm{label}} in field values (in situations where nested link text won't cause a problem) the \meta{label} will be converted as follows: \begin{itemize} @@ -6874,35 +7354,35 @@ prefixes then, if \csopt{cs-label-prefix} has been used the supplied value will be inserted otherwise the \csopt{label-prefix} setting will be inserted. \end{itemize} -For example, given -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{duck} or \gls{goose}} +For example, given: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}} } -\end{verbatim} +\end{codeenv} then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix} isn't included in the resource option list this will convert the \field{description} field to: -\begin{verbatim} -description = {feathered animal, such as a \gls{idx.duck} or -\gls{idx.goose}} -\end{verbatim} +\begin{codeenv} +\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{idx.duck} or +\cs{gls}\marg{idx.goose}} +\end{codeenv} However with \csopt[gls.]{cs-label-prefix} the \field{description} -field will be converted to -\begin{verbatim} -description = {feathered animal, such as a \gls{gls.duck} or -\gls{gls.goose}} -\end{verbatim} +field will be converted to: +\begin{codeenv} +\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or +\cs{gls}\marg{gls.goose}} +\end{codeenv} regardless of the \csopt{label-prefix} setting. Whereas if the -original entry definition is -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal, such as a \gls{dual.duck} or -\gls{dual.goose}} +original entry definition is: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{dual.duck} or +\cs{gls}\marg{dual.goose}} } -\end{verbatim} +\end{codeenv} then \idprefix{dual} will be replaced by the value of the \csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix} setting. @@ -6922,52 +7402,58 @@ an empty list, which will strip all \idprefix{extn} prefixes. Remember that \idx{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 +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsexternalprefixlabel} +\end{codeenv} + For example, suppose the file \filefmt{entries-terms.bib} contains: -\begin{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.set}} +\begin{codeenv} +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.set}} } -\end{verbatim} +\end{codeenv} and the file \filefmt{entries-symbols.bib} contains: -\begin{verbatim} -@symbol{set, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} +\begin{codeenv} +\atentry{symbol}\marg{set, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, + \field{description}=\marg{a \cs{gls}\marg{ext1.set}} } -\end{verbatim} +\end{codeenv} These files both contain an entry with the label \code{set} -but the \field{description} field includes \verb|\gls{ext1.set}| which is -referencing the entry from the other file. These +but the \field{description} field includes \code{\cs{gls}\marg{ext1.set}} +which is referencing the entry from the other file. These two files can be loaded without conflict using: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-terms}, - label-prefix={gls.}, - ext-prefixes={sym.} -] - -\GlsXtrLoadResources[src={entries-symbols}, - type=symbols, - label-prefix={sym.}, - ext-prefixes={gls.} -] -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src}, + \csopt[gls.]{label-prefix}, + \csopt[sym.]{ext-prefixes} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src}, + \csopt[symbols]{type}, + \csopt[sym.]{label-prefix}, + \csopt[gls.]{ext-prefixes} +} +\end{codeenv} Now the \code{set} entry from \filefmt{entries-terms.bib} will be defined with the label \code{gls.set} and the -description will be -\begin{verbatim} -collection of values, denoted \gls{sym.set} -\end{verbatim} +description will be: +\begin{codeenv} +collection of values, denoted \cs{gls}\marg{sym.set} +\end{codeenv} The \code{set} entry from \filefmt{entries-symbols.bib} will be defined with the label -\code{sym.set} and the description will be -\begin{verbatim} -a \gls{gls.set} -\end{verbatim} +\code{sym.set} and the description will be: +\begin{codeenv} +a \cs{gls}\marg{gls.set} +\end{codeenv} Note that in this case the \ext{bib} files have to be loaded as two separate resources. They can't be combined into a @@ -6977,31 +7463,31 @@ If you want to allow the flexibility to choose between loading them together or separately, you'll have to give them unique labels. For example, \filefmt{entries-terms.bib} could contain: -\begin{verbatim} -@entry{set, - name={set}, - description={collection of values, denoted \gls{ext1.S}} +\begin{codeenv} +\atentry{entry}\marg{set, + \field{name}=\marg{set}, + \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.S}} } -\end{verbatim} +\end{codeenv} and \filefmt{entries-symbols.bib} could contain: -\begin{verbatim} -@symbol{S, - name={\ensuremath{\mathcal{S}}}, - description={a \gls{ext1.set}} +\begin{codeenv} +\atentry{symbol}\marg{S, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}}, + \field{description}=\marg{a \cs{gls}\marg{ext1.set}} } -\end{verbatim} +\end{codeenv} Now they can be combined with: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}} +\end{codeenv} which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} prefix from the cross-references. Alternatively: -\begin{verbatim} -\GlsXtrLoadResources[src={entries-terms,entries-symbols}, - label-prefix={gls.}, - ext-prefixes={gls.} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}, + \csopt[gls.]{label-prefix}, + \csopt[gls.]{ext-prefixes} +} +\end{codeenv} which will insert the supplied \csopt{label-prefix} at the start of the labels in the entry definitions and will replace the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the @@ -7019,6 +7505,136 @@ If \meta{value} is a known field, it will be set after the field aliases, otherwise it will simply be added to the \ext{glstex} file using \ics{GlsXtrSetField} after the entry definition. +\optsection[\subsubsection]{dependency-fields} + +The \meta{list} should be a comma-separated list of fields that +have values in the form \code{\oargm{tag}\meta{id-list}} where +\meta{id-list} is a comma-separated list of entry labels. This +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 action is performed after \csopt{labelify-list}, if that's also +set. + +For example, suppose the file \filefmt{entries-en.bib} contains: +\begin{codeenv} +\atentry{index}\marg{cat, + \fieldfmt{translations-pt}=\marg{gato,gatinho}, + \field{seealso}=\marg{kitten} +} +\strut +\atentry{index}\marg{kitten, + \fieldfmt{translations-pt}=\marg{gato,gatinho} +} +\strut +\atentry{index}\marg{staple} +\atentry{index}\marg{rivet} +\atentry{index}\marg{mat} +\atentry{index}\marg{carpet} +\atentry{index}\marg{rug} +\atentry{index}\marg{tapestry} +\atentry{index}\marg{doormat} +\atentry{index}\marg{matting} +\atentry{index}\marg{coconut-matting, + \field{name}=\marg{coconut matting} +} +\atentry{index}\marg{track} +\atentry{index}\marg{furrow} +\end{codeenv} +and suppose the file \filefmt{entries-pt.bib} contains: +\begin{codeenv} +\atentry{index}\marg{gato, + \field{prefix}=\marg{o}, + \fieldfmt{translations-en}=\marg{cat,staple,rivet}, + \field{seealso}=\marg{gatinho} +} +\strut +\atentry{index}\marg{gatinho, + \fieldfmt{translations-en}=\marg{kitten} +} +\strut +\atentry{index}\marg{tapete, + \fieldfmt{translations-en}=\marg{carpet,rug,mat,tapestry} +} +\strut +\atentry{index}\marg{esteira, + \field{prefix}=\marg{a}, + \fieldfmt{translations-en}=\marg{mat,track,matting,furrow} +} +\strut +\atentry{index}\marg{capacho, + \field{prefix}=\marg{o}, + \fieldfmt{translations-en}=\marg{doormat,matting,mat,coconut-matting} +} +\end{codeenv} +The aim here is to have a document containing an +English-to-Portuguese and a Portuguese-to-English dictionary. The +custom \fieldfmt{translations-pt} and \fieldfmt{translations-pt} +fields contain comma-separated lists of possible translations. In +this case I don't want to use the \field{see} field (and, in fact, +can't for the entries that have the \field{seealso} field set), but +I can identify the values of those fields as dependent entries to +ensure that they are selected even if they're not referenced in the +document. + +For convenience I've aliased the custom fields to \field{user1}: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\cmd{usepackage}[british,brazilian]\marg{babel} +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nomain}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[\glostyle{bookindex}]{style} +}\marg{glossaries-extra} +\cmd{usepackage}\marg{\isty{glossaries-prefix}} +\strut +\cs{newglossary*}\marg{en}\marg{English Terms} +\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[en]{type}, + \csopt[entries-en]{src}, + \csopt[en-GB]{sort}, + \csopt[en]{category}, + \csopt[\fieldfmt{translations-pt}=\field{user1}]{field-aliases}, + \csopt[\field{user1}]{dependency-fields}, + \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[pt]{type}, + \csopt[entries-pt]{src}, + \csopt[pt-BR]{sort}, + \csopt[pt]{category}, + \csopt[\fieldfmt{translations-en}=\field{user1}]{field-aliases}, + \csopt[\field{user1}]{dependency-fields}, + \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} +} +\strut +\cs{apptoglossarypreamble}\oarg{en}\marg{\cs{selectlanguage}\marg{british}} +\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} +\strut +\cmd{begin}\marg{document} +\cs{selectlanguage}\marg{british} +The \cs{gls}\marg{cat} sat on the \cs{gls}\marg{mat}. +\strut +\cs{selectlanguage}\marg{brazilian} +O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}. +\strut +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{prefix}}\marg{\idx{param}1}\marg{\ics{xmakefirstuc}\cs{glscurrentfieldvalue}\cs{cs.space}}\marg{}\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\idx{param}1} + \marg{; translations: \cs{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} +} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} + \subsection{Assignments} \label{sec:fieldassignments} @@ -7034,14 +7650,14 @@ with \gls{glsxtrsetgrouptitle} if the title is different from the label. The default behaviour is \csopt[auto]{group}. For example: -\begin{verbatim} -\GlsXtrLoadResources[sort=integer,group={Constants}, - src={entries-constants}% data in entries-constants.bib -] -\GlsXtrLoadResources[sort=letter-case,group={Variables}, - src={entries-variables}% data in entries-variables.bib -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[integer]{sort},\csopt[Constants]{group}, + \csopt[entries-constants]{src}\comment{data in entries-constants.bib} +} +\gls{GlsXtrLoadResources}\oarg{\csopt[letter-case]{sort},\csopt[Variables]{group}, + \csopt[entries-variables]{src}\comment{data in entries-variables.bib} +} +\end{codeenv} In this case, if the \field{type} field hasn't been set in the \ext{bib} files, these entries will be added to the same glossary, but will be grouped according to each instance of \gls{GlsXtrLoadResources}, @@ -7085,54 +7701,52 @@ entry]{category} refers to the \emph{target} entry type whereas cases, the value is converted to \idx!{lowercase} to ensure consistency. For example, if the \ext{bib} file contains: -\begin{verbatim} -@entry{bird, - name={bird}, - description = {feathered animal} -} - -@index{duck} - -@index{goose,plural="geese"} - -@dualentry{dog, - name={dog}, - description={chien} +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description} = \marg{feathered animal} +} +\strut +\atentry{index}\marg{duck} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\strut +\atentry{dualentry}\marg{dog, + \field{name}=\marg{dog}, + \field{description}=\marg{chien} } -\end{verbatim} -then if the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={same as entry},src={entries}] -\end{verbatim} -this will set the \field{category} of the \code{bird} term to -\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and -\code{goose} terms to \optfmt{index} (since they were defined -with \atentry{index}), and the \field{category} of the \code{dog} -term to \optfmt{dualentry} (since it was -defined with \atentry{dualentry}). Note that the dual entry -\code{dual.dog} doesn't have the category set, since that's +\end{codeenv} +then if the document contains: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[same as entry]{category},\csopt[entries]{src}} +\end{codeenv} +this will set the \field{category} of the \code{bird} term to \optfmt{entry} +(since it was defined with \atentry{entry}), the \field{category} of the +\code{duck} and \code{goose} terms to \optfmt{index} (since they were defined +with \atentry{index}), and the \field{category} of the \code{dog} term to +\optfmt{dualentry} (since it was defined with \atentry{dualentry}). Note that +the dual entry \code{dual.dog} doesn't have the category set, since that's governed by \csopt{dual-category} instead. -If, instead, the document contains -\begin{verbatim} -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} +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} doesn't have the \field{category} set. -Note that the categories may be overridden by the commands, -such as \csref{bibglsnewindex}, that are used to actually define the -entries. +Note that the categories may be overridden by the commands that are used to +actually define the entries (such as \gls!{bibglsnewindex}). -For example, if the document contains -\begin{verbatim} -\newcommand{\bibglsnewdualentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% +For example, if the document contains: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{category}=\marg{dual}}\marg{\idx{param}4}\comment{} } - -\GlsXtrLoadResources[category={animals},src={entries}] -\end{verbatim} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}} +\end{codeenv} then both the \code{dog} and \code{dual.dog} entries will have their \field{category} field set to \optfmt{dual} since the new definition of \gls{bibglsnewdualentry} has overridden @@ -7171,30 +7785,30 @@ Note that this setting only changes the \field{type} field for primary entries. Use \csopt{dual-type} for dual entries. For example: -\begin{verbatim} -\usepackage[record,symbols]{glossaries-extra} - -\GlsXtrLoadResources[src={entries-symbols},type=symbols] -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[symbols]{type}} +\end{codeenv} Make sure that the glossary type has already been defined (see \sectionref{sec:newglossary}). In the above, the \styopt{symbols} option defines the \code{symbols} glossary. If you want to use a custom glossary, you need to provide it. For example: -\begin{verbatim} -\usepackage[record,nomain]{glossaries-extra} - -\newglossary*{dictionary}{Dictionary} - -\GlsXtrLoadResources[src={entries-symbols},type=dictionary] -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{dictionary}\marg{Dictionary} +\strut +\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.) \optsection[\subsubsection]{trigger-type} -The record counting commands, such as \ics{rgls}, use the special +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 identified as having a record for selection purposes, which is @@ -7209,7 +7823,7 @@ The provided value \meta{type} must be a glossary label (not one of the keywords allowed by \csopt{type}). You can define the glossary before loading the resource, but it's not required as \bibgls\ will write -\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file +\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file (see \sectionref{sec:newglossary}). \optsection[\subsubsection]{abbreviation-name-fallback} @@ -7230,15 +7844,15 @@ The \csopt{ignore-fields} key indicates that you want \bibgls\ to skip the fields listed in the supplied comma-separated \meta{list} of field labels. Remember that unrecognised fields will always be skipped. -For example, suppose my \ext{bib} file contains -\begin{verbatim} -@abbreviation{html, - short ="html", - long = {hypertext markup language}, - description={a markup language for creating web pages}, - seealso={xml} +For example, suppose my \ext{bib} file contains: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} =\qtdelim{html}, + \field{long} = \marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages}, + \field{seealso}=\marg{xml} } -\end{verbatim} +\end{codeenv} but I want to use the \abbrstyle{short-long} style and I don't want the cross-referenced term, then I can use \csopt[seealso,description]{ignore-fields}. @@ -7269,34 +7883,34 @@ so if \meta{field1} is listed in \csopt{ignore-fields} it won't be ignored (unless \meta{field2} is in \csopt{ignore-fields}). For example, suppose \filefmt{people.bib} contains: -\begin{verbatim} -@entry{alexander, - name={Alexander III of Macedon}, - description={Ancient Greek king of Macedon}, - born={20 July 356 BC}, - died={10 June 323 BC}, - othername={Alexander the Great} +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon}, + \field{description}=\marg{Ancient Greek king of Macedon}, + \fieldfmt{born}=\marg{20 July 356 BC}, + \fieldfmt{died}=\marg{10 June 323 BC}, + \fieldfmt{othername}=\marg{Alexander the Great} } -\end{verbatim} +\end{codeenv} This contains three non-standard fields: \fieldfmt{born}, \fieldfmt{died} and \fieldfmt{othername}. I could define these fields using \ics{glsaddkey}, but another possibility is to map these onto the user keys \field{user1}, \field{user2} and \field{user3}, which saves the overhead of providing new keys: -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - field-aliases={born=user1,died=user2,othername=user3} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} +} +\end{codeenv} \optsection[\subsubsection]{replicate-fields} The value of one field can be copied to other fields using this option where each \meta{key}\dequals\meta{value} pair is in the form -\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots} +\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}} where all values are field names. This copies the contents of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\ (only if the target field isn't already set with @@ -7305,24 +7919,24 @@ performed after \csopt{ignore-fields} (see \sectionref{sec:resourcesets}). For example, suppose \filefmt{people.bib} contains: -\begin{verbatim} -@entry{alexander, - name={Alexander III of Macedon (Alexander the Great)}, - text={Alexander}, - description={Ancient Greek king of Macedon} +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, + \field{text}=\marg{Alexander}, + \field{description}=\marg{Ancient Greek king of Macedon} } -\end{verbatim} +\end{codeenv} Since the \field{first} field hasn't been supplied, it will default to the value of the \field{text} field, but perhaps for one of my documents I'd like the \field{first} field to be the same as the \field{name} field. Rather than editing the \ext{bib} file, I can just do: -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - replicate-fields={name=first} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} This copies the contents of the \field{name} field into the \field{first} field. If you have more than one field in the list take care to brace the lists to avoid confusion. @@ -7331,50 +7945,51 @@ of the \field{name} field to both \field{first} and \field{firstplural} and copy the value of the \field{text} field to the \field{plural} field, then this requires braces for the inner list: -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - replicate-fields={name={first,firstplural},text=plural} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\marg{\field{first},\field{firstplural}},\field{text}=\field{plural}]{replicate-fields} +} +\end{codeenv} If my \filefmt{people.bib} file instead contained: -\begin{verbatim} -@entry{alexander, - name={Alexander III of Macedon (Alexander the Great)}, - first={Alexander the Great}, - text={Alexander}, - description={Ancient Greek king of Macedon} +\begin{codeenv} +\atentry{entry}\marg{alexander, + \field{name}=\marg{Alexander III of Macedon (Alexander the Great)}, + \field{first}=\marg{Alexander the Great}, + \field{text}=\marg{Alexander}, + \field{description}=\marg{Ancient Greek king of Macedon} } -\end{verbatim} -then -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - replicate-fields={name=first} -] -\end{verbatim} +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} won't alter the \field{first} field since \csopt{replicate-fields} -never overrides values. However, since \csopt{replicate-fields} -is always performed after \csopt{ignore-fields} it's possible to -ignore the \field{first} field which means that the \field{name} -value can then be copied into it: -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - ignore-fields={first}, - replicate-fields={name=first} -] -\end{verbatim} +doesn't override existing values by default. You can use +\csopt{replicate-override} to change this. Alternatively, since +\csopt{replicate-fields} is always performed after \csopt{ignore-fields} +it's possible to ignore the \field{first} field which means that the +\field{name} value can then be copied into it: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{first}]{ignore-fields}, + \csopt[\field{name}=\field{first}]{replicate-fields} +} +\end{codeenv} Note that the ordering within the resource options doesn't make a difference. The same result occurs with: -\begin{verbatim} -\GlsXtrLoadResources[ - src=people,% data in people.bib - replicate-fields={name=first}, - ignore-fields={first} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[people]{src},\comment{data in people.bib} + \csopt[\field{name}=\field{first}]{replicate-fields}, + \csopt[\field{first}]{ignore-fields} +} +\end{codeenv} \optsection[\subsubsection]{replicate-override} @@ -7411,10 +8026,10 @@ For example, if \csopt[dupgroup]{copy-action-group-field}, \csopt[copy]{action} and \csopt[copies]{type} are set in the resource options and \code{copies} identifies a custom glossary: -\begin{alltt} -\ics{printunsrtglossary*}\oarg{type=copies,style=indexgroup} +\begin{codeenv} +\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[\glostyle{indexgroup}]{style}} \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}} -\end{alltt} +\end{codeenv} This option is ignored when used with \csopt[define]{action}. This option is not used by \csopt{secondary} which will @@ -7428,10 +8043,10 @@ 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 style. For example: -\begin{verbatim} -\printunsrtglossary[nogroupskip,style=index] -\printunsrtglossary[type=copies,style=indexgroup] -\end{verbatim} +\begin{codeenv} +\cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}} +\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[indexgroup]{style}} +\end{codeenv} \optsection[\subsubsection]{copy-alias-to-see} @@ -7489,36 +8104,34 @@ punctuation character. This option only applies to the \optsection[\subsubsection]{strip-trailing-nopost} -This option is always performed before \csopt{post-description-dot} -when adjusting the \field{description} field. The default -setting is \csopt[false]{strip-trailing-nopost}. If -\optfmt{true} any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} -found in the \field{description} field will be removed. -Note that the command (possibly followed by ignored space) must be -at the very end of the description for it to be removed. A -description should not contain both commands. This option -only applies to the \field{description} field. +This option is always performed before \csopt{post-description-dot}. +The default setting is \csopt[false]{strip-trailing-nopost}. If \optfmt{true} +any trailing ungrouped \ics{nopostdesc} or \ics{glsxtrnopostpunc} found in the +\field{description} field will be removed. Note that the command (possibly +followed by ignored space) must be at the very end of the description for it to +be removed. A description should not contain both commands. This option only +applies to the \field{description} field. For example, \cs{nopostdesc} will be stripped from: -\begin{verbatim} -description={sample\nopostdesc} -\end{verbatim} -since it's at the end. It will also be stripped from -\begin{verbatim} -description={sample\nopostdesc } -\end{verbatim} +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}} +\end{codeenv} +since it's at the end. It will also be stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc} } +\end{codeenv} since the trailing space is ignored as it follows a control -word. It won't be stripped from -\begin{verbatim} -description={sample\nopostdesc{} } -\end{verbatim} +word. It won't be stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}\marg{} } +\end{codeenv} because the final space is now significant, but even without the space it still won't be stripped as the field ends with an empty group not with \cs{nopostdesc}. Similarly it won't be -stripped from -\begin{verbatim} -description={sample\nopostdesc\relax} -\end{verbatim} +stripped from: +\begin{codeenv} +\field{description}=\marg{sample\cs{nopostdesc}\cmd{relax}} +\end{codeenv} because again it's not at the end. \optsection[\subsubsection]{check-end-punctuation} @@ -7531,7 +8144,7 @@ end of sentence punctuation. This is determined as follows, for each or \idx{punctuationfinalquote}, check the character that comes before it; \item if the character is of type \idx{punctuationother}, then check -if it's listed in the entry given by \code{sentence.terminators} +if it's listed in the entry given by \idx{sentence.terminators} in \bibgls's \langxml. \end{itemize} If a sentence terminator is found, an internal field is created @@ -7540,7 +8153,7 @@ character. Fields whose values must be labels (such as \field{parent}, \field{category} and \field{type}) aren't checked, even if they're included in \meta{list}. -The default \code{sentence.terminators} is defined in \file{bib2gls-en.xml} +The default \idx{sentence.terminators} is defined in \file{bib2gls-en.xml} as: \begin{verbatim} <entry key="sentence.terminators">.?!</entry> @@ -7549,33 +8162,33 @@ Any character that isn't of type \idx{punctuationother} won't match. For example, the sample \exfile{books.bib} file contains: -\begin{verbatim} -@entry{whydidnttheyaskevans, - name={Why Didn't They Ask Evans?}, - description={novel by Agatha Christie}, - identifier={book}, - author={\sortmediacreator{Agatha}{Christie}}, - year={1934} +\begin{codeenv} +\atentry{entry}\marg{whydidnttheyaskevans, + \field{name}=\marg{Why Didn't They Ask Evans?}, + \field{description}=\marg{novel by Agatha Christie}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Agatha}\marg{Christie}}, + \fieldfmt{year}=\marg{1934} } -\end{verbatim} +\end{codeenv} With \csopt[name]{check-end-punctuation}, this entry will be assigned an internal field called -\fielddisp{fieldendpunc}{namendpunc} set to \code{?}\ -as that's included in \code{sentence.terminators} and is found +\fielddisp{fieldendpunc}{nameendpunc} set to \code{?}\ +as that's included in \idx{sentence.terminators} and is found at the end of the \field{name} field: -\begin{verbatim} -\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?} -\end{verbatim} +\begin{codeenv} +\cs{GlsXtrSetField}\marg{whydidnttheyaskevans}\marg{nameendpunc}\marg{?} +\end{codeenv} (Note that \csopt[first,text]{check-end-punctuation} won't match as there's no \field{first} or \field{text} field supplied.) If you have a field that ends with an abbreviation followed by a \idx{full-stop}, this will be considered an end of sentence terminator, but the main purpose of this option is to provide a way to deal with -cases like -\begin{verbatim} -Agatha Christie wrote \gls{whydidnttheyaskevans}. -\end{verbatim} +cases like: +\begin{codeenv} +Agatha Christie wrote \cs{gls}\marg{whydidnttheyaskevans}. +\end{codeenv} where the end of sentence punctuation following \cs{gls} needs to be discarded. This is needed regardless of whether or not the link text ends with an abbreviation or is a complete sentence. @@ -7584,16 +8197,16 @@ It's then possible to hook into the \idx{postlinkhook} \qt{discard period} check. By default this just checks the category attributes that govern whether or not to discard a following period, but (with \styfmt{glossaries-extra} v1.23+) it's possible to provide -an additional check by redefining +an additional check by redefining: \nosecdef{glsxtrifcustomdiscardperiod} This should expand to \meta{true} if the check should be performed otherwise it should expand to \meta{false}. You can reference the label using \cs{glslabel}. For example: -\begin{verbatim} -\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% - \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% +\begin{codeenv} +\cs{renewcommand}*\marg{\gls{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{nameendpunc}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} } -\end{verbatim} +\end{codeenv} This uses \ics{GlsXtrIfFieldUndef} rather than \ics{glsxtrifhasfield*} since there's no need to access the field's value. (The unstarred form \ics{glsxtrifhasfield} can't be used @@ -7605,22 +8218,347 @@ the field is defined (so \ics{GlsXtrIfFieldUndef} does the \meta{false} argument) but it's considered unset (so commands like \ics{ifglshasfield} do the \meta{false} argument). +\optsection[\subsubsection]{sort-label-list} + +This option takes a list as the value with each element in the list +in the form: +\begin{codeenv} +\code{\meta{field-list}:\meta{sort}:\meta{csname}} +\end{codeenv} +or: +\begin{codeenv} +\code{\meta{field-list}:\meta{sort}} +\end{codeenv} +where: +\begin{itemize} +\item \meta{field-list} is a comma-separated list of valid fields; +\item \meta{sort} is a valid sort method as per the \csopt{sort} +option, but not including \optfmt{none} or \optfmt{unsrt}; +\item \meta{csname} is the name (without a leading backslash) of a +command that takes a label as its sole mandatory argument that's +recognised by \bibgls' interpreter (such as those listed in +\tableref{tab:bibglsdefs}). +\end{itemize} +The final \code{:\meta{csname}} part may be omitted if no command +need be applied. (That is, sort by label.) + +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.) + +If the \meta{field-list} has more than one element +take care to use braces \code{\marg{}} to avoid confusion for the +list-parser. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\marg{see,seealso}:en:glsentryname]{sort-label-list} +} +\end{codeenv} + +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}). + +After the main sorting of each set of selected entries is performed +(as per \csopt{sort} or \csopt{dual-sort}), if this +option is set, then for each +\code{\margm{field-list}:\meta{sort}:\meta{csname}} the following +steps are performed: +\begin{enumerate} +\item For each entry \meta{id}: + \begin{enumerate} + \item For each \meta{field} in \meta{field-list}, if the field is + set for entry \meta{id} then: + + \begin{enumerate} + \item The field value must be in the form + \code{\oargm{tag}\meta{label-list}} where + \code{\oargm{tag}} is optional and + \meta{label-list} is a comma-separated list of entry labels + \meta{label$_1$}, \ldots, \meta{label$_n$}; + \item A new list is constructed where the $i$th element is: + \code{\marg{\csfmt{}\meta{csname}\margm{label$_i$}}} + unless \meta{csname} hasn't been set, in which case the + $i$th element is just \margm{label$_i$} (the optional + \oargm{tag} part is omitted); + \item This new list is sorted according to the interpreter's + definition of the command given by \meta{csname} (if provided) + and the designated \meta{sort} method; + \item The field value is reconstructed with the labels in the + corresponding order (prefixed with \code{\oargm{tag}} if it was + present in the original). + \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. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{index}\marg{bird} +\strut +\atentry{index}\marg{waterfowl, \field{parent}=\marg{bird} } +\strut +\atentry{index}\marg{duck, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{swan,duckling,parrot,goose} +} +\strut +\atentry{index}\marg{swan, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{goose,duck} +} +\strut +\atentry{index}\marg{goose, + \field{parent}=\marg{waterfowl}, + \field{seealso}=\marg{duck} +} +\strut +\atentry{index}\marg{parrot, \field{parent}=\marg{bird} } +\strut +\atentry{index}\marg{duckling, + \field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} +} +\strut +\atentry{index}\marg{fluffy} +\strut +\atentry{index}\marg{tardigrade, \field{name}=\marg{water bear} } +\strut +\atentry{index}\marg{velociraptor} +\end{codeenv} +And suppose the document contains: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[en]{sort}, + \csopt[\marg{seealso,see}:en:glsentryname]{sort-label-list} +} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{parrot}, \cs{gls}\marg{tardigrade}, \cs{gls}\marg{swan}, \cs{gls}\marg{duck}, +\cs{gls}\marg{goose}, \cs{gls}\marg{fluffy} \cs{gls}\marg{duckling}, \cs{gls}\marg{velociraptor}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +Then this reorders the \field{see} and \field{seealso} fields according to +the referenced entry's name (obtained with \ics{glsentryname}). + +For example, the \field{see} field for the \code{duckling} entry was +originally: +\begin{codeenv} +\field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade} +\end{codeenv} +but in the \ext{glstex} file it's written as: +\begin{codeenv} +\field{see}=\marg{[related terms]duck,fluffy,velociraptor,tardigrade} +\end{codeenv} +The reason for \code{tardigrade} being placed after +\code{velociraptor} is because +\code{\ics{glsentryname}\marg{tardigrade}} is expanded to \qt{water +bear} (and \qt{W} comes after \qt{V}). If no encapsulating command +was specified: +\begin{codeenv} +\csopt[\marg{seealso,see}:en]{sort-label-list} +\end{codeenv} +then the list would have been sorted according to the labels +instead (and so \code{tardigrade} would come before +\code{velociraptor}). Note that the optional tag is kept at the start of the +list. + +The \field{seealso} fields have also been changed. For example, +the \code{duck} entry originally had: +\begin{codeenv} +\field{seealso}=\marg{swan,duckling,parrot,goose} +\end{codeenv} +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) +but the \field{seealso} field has \code{duckling} first. + +If you want to maintain the hierarchy you can use \ics{glsxtrhiername} instead +of \ics{glsentryname}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[en]{sort}, + \csopt[\marg{seealso,see}:en:glsxtrhiername]{sort-label-list} +} +\end{codeenv} +The separator between the levels is +given by \ics{glsxtrhiernamesep} which is defined by +\sty{glossaries-extra} to produce \qt{\glsxtrhiernamesep}. +The \bibgls\ interpreter's definition of this command is different +to assist sorting and simply expands to a \idx{full-stop} to prevent +it from being replaced by the default word break marker. + +In this case \code{\ics{glsxtrhiername}\marg{swan}} would be +displayed as \qt{bird\glsxtrhiernamesep waterfowl\glsxtrhiernamesep +swan} if used in the document, but the interpreter converts it to +\qt{bird.waterfowl.swan}, so with the default \csopt{break-at} +setting the actual sort value becomes \code{bird.waterfowl.swan|} +(instead of \code{bird|waterfowl|swan|} which would be the result if +the interpreter used the same definition as \sty{glossaries-extra}). + +Therefore the \field{seealso} field for the \code{duck} entry ends up as: +\begin{codeenv} +\field{seealso}=\marg{parrot,goose,swan,duckling} +\end{codeenv} +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 +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 +the reader, you can redefine \ics{glsseeitemformat} in the document +to use \ics{glsxtrhiername}: +\begin{codeenv} +\cmd{renewcommand}*\marg{\cs{glsseeitemformat}}[1]\marg{\cs{glsxtrhiername}\marg{\idx{param}1}} +\end{codeenv} +This means that the \code{duck} cross-reference now appears in the +document as: bird\glsxtrhiernamesep parrot, bird\glsxtrhiernamesep +waterfowl\glsxtrhiernamesep goose, bird\glsxtrhiernamesep waterfowl +\glsxtrhiernamesep swan \& duckling. + +This next example document has two languages, English and +Portuguese. The file \filefmt{entries-en.bib} contains the English +terms, such as: +\begin{codeenv} +\atentry{index}\marg{cat, \fieldfmt{translations}=\marg{gato,gatinho} } +\atentry{index}\marg{kitten, \fieldfmt{translations}=\marg{gatinho} } +\atentry{index}\marg{staple, \fieldfmt{translations}=\marg{grampo}} +\atentry{index}\marg{rivet, \fieldfmt{translations}=\marg{rebite}} +\end{codeenv} +The file \filefmt{entries-pt.bib} contains the Portuguese +terms, such as: +\begin{codeenv} +\atentry{index}\marg{gato, \fieldfmt{translations}=\marg{cat,staple,rivet} } +\atentry{index}\marg{gatinho, \fieldfmt{translations}=\marg{kitten} } +\end{codeenv} + +Both files have a custom field called \fieldfmt{translations} that +will need to be either defined or aliased. This field contains a +comma-separated list of labels for the corresponding entries in the +other language file that provide a possible translation. Where a +word has multiple possible translations, I'd like the list sorted +alphabetically. (In practice, it would make more sense to sort them +according to how likely the translation is, but this is for +illustrative purposes.) For convenience, the +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 +are cross-resource references, but since there are no instances of +\atentry{preamble} it should be possible to resolve the references. + +The document code is: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}[utf8]\marg{inputenc} +\cmd{usepackage}[british,brazilian]\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nomain}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[bookindex]{style} +}\marg{glossaries-extra} +\cmd{usepackage}\marg{glossaries-prefix} +\strut +\cs{newglossary*}\marg{en}\marg{English Terms} +\cs{newglossary*}\marg{pt}\marg{Portuguese Terms} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection}, + \csopt[en]{type}, + \csopt[entries-en]{src}, + \csopt[en-GB]{sort}, + \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, + \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list} +} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[all]{selection}, + \csopt[pt]{type}, + \csopt[entries-pt]{src}, + \csopt[pt-BR]{sort}, + \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases}, + \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list} +} +\strut +\cs{apptoglossarypreamble}\oarg{en}\marg{\ics{selectlanguage}\marg{british}} +\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}} +\strut +\cmd{begin}\marg{document} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{glsxtrifhasfield}\marg{useri}\marg{\idx{param}1}\marg{: \ics{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{} +} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +In verbose mode, the transcript file indicates that it's performing +the label list sorting. For example, when sorting according to +\csopt[user1:pt-BR:glsentryname]{sort-label-list}, the transcript +file contains: +\begin{verbatim} +Label list sort method 'pt-BR' on field: user1 +\end{verbatim} +The \code{cat} entry has a list of two elements in this field: +\code{gato,gatinho}. This is converted into a new list where the +first element is: +\begin{codeenv} +\marg{\cs{glsentryname}\marg{gato}} +\end{codeenv} +and the second element is: +\begin{codeenv} +\marg{\cs{glsentryname}\marg{gatinho}} +\end{codeenv} +Regardless of the level of verbosity, the transcript file will +contain the conversions obtained by the interpreter: +\begin{verbatim} +texparserlib: {\glsentryname{gato}} -> gato +texparserlib: {\glsentryname{gatinho}} -> gatinho +\end{verbatim} +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 +order isn't what you expect, check the transcript file for messages. + \optsection[\subsubsection]{bibtex-contributor-fields} This option indicates that the listed fields all use \BibTeX's name syntax (as used in \BibTeX's \code{author} and \code{editor} fields). The values of these fields will be converted into the form: -\begin{alltt} +\begin{codeenv} \gls{bibglscontributorlist}\margm{contributor list}\margm{n} -\end{alltt} +\end{codeenv} where \meta{n} is the number of names in the list and \meta{contributor-list} is a comma-separated list of names in the form: -\begin{alltt} +\begin{codeenv} \gls{bibglscontributor}\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix} -\end{alltt} +\end{codeenv} -The \gls{bibglscontributorlist} commands is initially defined in +The \gls{bibglscontributorlist} command is initially defined in \bibgls's interpreter to just do the first argument and ignore the second. This means that if you're sorting on this field, the \qt{and} part between the final names doesn't appear in the sort value. @@ -7631,17 +8569,17 @@ so this command will be defined if you have at least v2.28 of \sty{datatool-base}.) For example, if the \field{name} field is specified as: -\begin{verbatim} -name={John Smith and Jane Doe and Dickie von Duck} -\end{verbatim} +\begin{codeenv} +\field{name}=\marg{John Smith and Jane Doe and Dickie von Duck} +\end{codeenv} then \csopt[name]{bibtex-contributor-fields} will convert the -\field{name} field value to -\begin{verbatim} -\bibglscontributorlist{% - \bibglscontributor{John}{}{Smith}{},% - \bibglscontributor{Jane}{}{Doe}{},% - \bibglscontributor{Dickie}{von}{Duck}{}}{3} -\end{verbatim} +\field{name} field value to: +\begin{codeenv} +\gls{bibglscontributorlist}\marg{\comment{} + \gls{bibglscontributor}\marg{John}\marg{}\marg{Smith}\marg{},\comment{} + \gls{bibglscontributor}\marg{Jane}\marg{}\marg{Doe}\marg{},\comment{} + \gls{bibglscontributor}\marg{Dickie}\marg{von}\marg{Duck}\marg{}}\marg{3} +\end{codeenv} With \csopt[von]{contributor-order} the sort value obtained from this field will be: \begin{verbatim} @@ -7676,34 +8614,34 @@ the \ext{glstex} using \cs{providecommand}, which means that \LaTeX\ will only pick up the first definition. For example: -\begin{verbatim} -\newcommand*{\bibglscontributor}[4]{% - #1\ifstrempty{#2}{}{ #2} #3\ifstrempty{#4}{}{, #4}% +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglscontributor}}[4]\marg{\comment{} + \idx{param}1\ics{ifstrempty}\marg{\idx{param}2}\marg{}\marg{ \idx{param}2} \idx{param}3\cs{ifstrempty}\marg{\idx{param}4}\marg{}\marg{, \idx{param}4}\comment{} } - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - bibtex-contributor-fields={name} -] -\end{verbatim} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{bibtex-contributor-fields} +} +\end{codeenv} This will display the names in the glossary with the forenames first, but \bibgls\ will sort according to surname. An alternative approach, if you need an initial resource set such as with the \exfile{no-interpret-preamble.bib} file: -\begin{verbatim} -\GlsXtrLoadResources[ - src={no-interpret-preamble}, - interpret-preamble=false, - bibtex-contributor-fields={name}, - contributor-order={forenames} -] - -\GlsXtrLoadResources[ - src={entries},% data in entries.bib - bibtex-contributor-fields={name} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble}, + \csopt[name]{bibtex-contributor-fields}, + \csopt[forenames]{contributor-order} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[name]{bibtex-contributor-fields} +} +\end{codeenv} Note the need to use \csopt[name]{bibtex-contributor-fields} in the first resource set even though there are no entries in the \ext{bib} file. This is because the definition of @@ -7722,7 +8660,7 @@ parsed according to \csopt{date-time-field-format} and fields parsed according to \csopt{dual-date-time-field-format} and \csopt{dual-date-time-field-locale}. If the field value is missing or doesn't match the given pattern it remains unchanged, otherwise -it's converted into the form +it's converted into the form: \nosecdef{bibglsdatetime} where \meta{original} is the value of the field before conversion. If the interpreter is on, the value will be interpreted before @@ -7735,7 +8673,7 @@ being parsed if it contains \idx{escchar}, \idx{mshiftchar}, As \csopt{date-time-fields} but for fields that only contain date (not time) information. If parsed correctly, the field is converted -to +to: \nosecdef{bibglsdate} The fields are parsed according to \csopt{date-field-format} and @@ -7747,7 +8685,7 @@ The fields are parsed according to As \csopt{date-time-fields} but for fields that only contain time (not date) information. If parsed correctly, the field is converted -to +to: \nosecdef{bibglstime} The fields are parsed according to \csopt{time-field-format} and @@ -7806,189 +8744,531 @@ by \csopt{time-fields}. The \meta{value} is as for \subsection{Case-Changing} \label{sec:fieldcase} -\optsection[\subsubsection]{short-case-change} - -The value of the \field{short} field may be automatically converted -to \idxlink{uppercase}{upper} or \idx{lowercase}. This option may take one of the following -values: +The \sty{glossaries-extra} package comes with the category +attributes \catattr{glossdesc} and \catattr{glossname}, which may +take the values \optfmt{firstuc} or \optfmt{title}. These don't +change the actual \field{name} or \field{description} fields, but +instead \ics{glossentryname} and \ics{glossentrydesc} (which are +used by the default glossary styles) check for the corresponding +attribute and apply the appropriate \idx{case-change} to the field value. + +So \ics{glossentryname} will use \ics{Glsentryname} if the +\catattr{glossname} attribute for the given entry is set to \optfmt{firstuc} +and \ics{glossentrydesc} will use \ics{Glsentrydesc} if the +\catattr{glossdesc} attribute is set to \optfmt{firstuc}. +The \optfmt{title} setting will instead use \ics{capitalisewords} +applied to the field value. + +The resource options described in this section provide an +alternative to those attributes that actually modify the relevant +field (rather than just adjusting the style code used to display it). +There are two forms of modification: the field is adjusted so that +the original value is encapsulated by a command or \bibgls\ will +perform the actual \idx{case-change} according to its own algorithm. +The results can vary according to the field content. + +Only a subset of known fields have a resource option that can be +used to apply a \idx{case-change}. For example, \csopt{name-case-change} +can be used to change the case of the \field{name} field, but +there's no equivalent option for the \field{text} field. + +Each of the case-changing resource options may take one of the +following values: \begin{itemize} \item \optfmt{none}: don't apply any case-changing (default); -\item \optfmt{lc}: convert to \idx{lowercase} (ignoring -\idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} -and \ics{si}\margm{text}); -\item \optfmt{uc}: convert to \idx{uppercase} (ignoring -\idx{mshiftchar}\meta{maths}\idx{mshiftchar}, \ics{ensuremath}\margm{maths} -and \ics{si}\margm{text}); -\item \optfmt{lc-cs}: convert to \idx{lowercase} using -\ics{MakeTextLowercase}; -\item \optfmt{uc-cs}: convert to \idx{uppercase} using -\ics{MakeTextUppercase}; -\item \optfmt{firstuc-cs}: convert to first letter \idx{uppercase} using -\ics{makefirstuc}; -\item \optfmt{firstuc}: convert the first alphabetical letter (or -group) to \idx{uppercase}. This uses the following rules: + +\item \optfmt{lc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglslowercase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{lowercase}; + +\item \optfmt{uc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglsuppercase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{uppercase}; + +\item \optfmt{firstuc-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglsfirstuc}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to first-letter \idx{uppercase}; + +\item \optfmt{title-cs}: make \bibgls\ behave as though the field +assignment: +\begin{codeenv} +\meta{field} = \margm{text} +\end{codeenv} +had actually been specified as: +\begin{codeenv*} +\meta{field} = \marg{\gls{bibglstitlecase}\margm{text}} +\end{codeenv*} +which uses \TeX\ to convert the field to \idx{titlecase}; + +\item \optfmt{lc}: convert to \idx{lowercase} by making the +appropriate modifications to tokens in the field value that have +a known \idx{lowercase} alternative (see below); + +\item \optfmt{uc}: convert to \idx{uppercase} by making the +appropriate modifications to tokens in the field value that have +a known \idx{uppercase} alternative (see below); + +\item \optfmt{firstuc}: convert to first letter \idx{uppercase} +by making the appropriate modification, if it has +a known \idx{uppercase} alternative (see below); + +\item \optfmt{title}: convert to \idx{titlecase} by making the +appropriate modifications to the first letter of each identified +word in the field value that has a known \idx{uppercase} +alternative (see below). + +A word-boundary is identified according to the +\csopt{word-boundaries} setting. Words to be excluded from the +case-changing (unless they occur at the start) can be identified +with \ics{MFUnocap} in the \atentry{preamble} or you can use +\code{\longarg{packages} mfirstuc-english} for the exclusion list +provided by the \isty{mfirstuc-english} package. Alternatively, you +can use \longarg{custom-packages} to load a simple package that +contains the required \cs{MFUnocap} commands (in a similar style to +\sty{mfirstuc-english}). + +The \bibgls\ word-boundary implementation is slightly different with +this setting than with the \cs{capitalisewords} command (implemented +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. + +\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. + +The \optfmt{\meta{option}-cs} settings defer the actual case-changing +to \TeX, which means that the case-changing has to be applied every +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 +the following rules: \begin{enumerate} -\item if \idx{mshiftchar}\meta{maths}\idx{mshiftchar} then stop (no case change); -\item if \ics{NoCaseChange}\margm{text} or -\ics{ensuremath}\margm{maths} or \ics{si}\margm{text} or \ics{protect} then skip; -\item if \csfmt{}\meta{csname}\margm{text} then apply the case change to -\meta{text} and stop; -\item if \csfmt{}\meta{csname} isn't followed by a group (and it's -not \ics{protect}), then stop (no case change applied); -\item if \margm{text} (a group) then convert the entire contents of -\meta{text} to \idx{uppercase} and stop; -\item if \meta{character} is an alphabetic character then change it -to its title case and stop; -\item otherwise skip and move on to the next token. + +\item If the token is a normal Unicode alphabetic character, it will +be replaced with the corresponding upper or lower case character, as +appropriate. +For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is +used as the replacement, for \optfmt{uc} the \idx{uppercase} character is +used as the replacement, and for \optfmt{lc} the \idx{lowercase} character +is used as the replacement. Many characters have the same upper and +title case alternative (for example, \qt{a} will be converted to \qt{A} +for the \optfmt{title}, \optfmt{firstuc} and \optfmt{uc} settings), but +some characters have different title and upper versions (for example, +the digraph \qt{\char"01F3} has the title version \qt{\char"01F2} +and \idx{uppercase} version \qt{\char"01F1}). + +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. + +\item If the token is a normal Unicode character that isn't alphabetical, +then this token will be skipped for all options. + +\item If \code{\idx{mshiftchar}\meta{maths}\idx{mshiftchar}} is +encountered, it will be skipped. If the option is \optfmt{firstuc} +then all remaining tokens are skipped, so no \idx{case-change} will be +performed. + +\item\label{case-change-group} If a group \code{\margm{content}} is +found, then the \idx{case-change} is applied to the entire \meta{content} +(which may be empty). This corresponds to the way \ics{makefirstuc} +and \ics{capitalisewords} work if a~word starts with a group. Note +that with \optfmt{firstuc} and \optfmt{title} the group content will +be converted according to \optfmt{uc}, so the normal \idx{uppercase} +character is used rather than the title case character (if they are +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. + +\item If a control sequence \csfmt{}\meta{csname} is found, then: + + \begin{enumerate} + \item If the control sequence is \cs{protect}, this token is skipped + for all options. + + \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}, + \ics{dh}, \ics{DH}, \ics{dj} or \ics{DJ}, then + it's replaced with its \idx{case-change} counterpart (if not already the + correct case). + + 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. + + \item If the control sequence is \ics{NoCaseChange}, then the + control sequence and its argument is ignored. With \optfmt{firstuc} + and \optfmt{title}, if \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}). 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. + + 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 + \optfmt{title} then the subsequent tokens + are skipped until a word-boundary is found (so no \idx{case-change} is + performed for this word). + + \item If the control sequence is \ics{glsentrytitlecase} then: + \begin{description} + \item[\optfmt{lc}] the control sequence is converted to + \ics{glsxtrusefield}; + \item[\optfmt{uc}] the control sequence is converted to + \ics{GLSxtrusefield}; + \item[\optfmt{firstuc}] the control sequence is converted to + \ics{Glsxtrusefield} and the remaining tokens are skipped; + \item[\optfmt{title}] the control sequence is left unchanged + and subsequent tokens are skipped until a word-boundary is found. + \end{description} + The field and entry label arguments are skipped. + + \item If the control sequence is \ics{glshyperlink} then the + \idx{case-change} is applied to its optional argument. (If there was no + optional argument in the original field value, one will be inserted.) + The label argument is skipped. + + 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. + + \item If the control sequence is \ics{glsdisp}, \ics{glslink}, + \ics{dglsdisp} or \ics{dglslink} then the \idx{case-change} will be + applied to the appropriate argument. The optional argument (if + present) and the label are skipped. + + 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. + + \item If the control sequence has a known case variant, it will be + substituted. For example, \ics{gls} will be changed to \ics{Gls} + or \ics{GLS}. In some cases there isn't an appropriate variant. + For example, \ics{glsentrytext} has a first-letter upper case + version \ics{Glsentrytext}, but not an all-caps version. + + 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. + + \item If the control sequence is followed by a group, then the + appropriate \idx{case-change} is applied to the group contents. + Unlike step~\ref{case-change-group}, the \idx{case-change} isn't + applied to the entire group content with \optfmt{firstuc} and + \optfmt{title}. (Again, this follows the way that + \ics{makefirstuc} and \ics{capitalisewords} work.) + + If there are subsequent groups, they won't be considered arguments, + but will be treated as groups, as per step~\ref{case-change-group}. + (This will only affect the \optfmt{title} setting as they will be + skipped by the \optfmt{firstuc} setting.) For complex cases, + consider using a semantic command that hides non-textual context + such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}. + + \item Otherwise the control sequence is skipped. + \end{enumerate} + +\item Anything else is skipped. + \end{enumerate} -\end{itemize} -For example, if the \ext{bib} file contains -\begin{verbatim} -@abbreviation{html, - short = "html", - long = "hypertext markup language" +For example, if an entry is defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{HTML}, + \field{long} = \marg{hypertext markup language}, + \field{description}=\marg{a markup language for creating web pages} } -\end{verbatim} -then \csopt[uc]{short-case-change} would convert the value of the -\field{short} field into -\begin{verbatim} -HTML -\end{verbatim} -whereas \csopt[uc-cs]{short-case-change} would convert it to -\begin{verbatim} -\MakeTextUppercase{html} -\end{verbatim} -In the case of \csopt[uc]{short-case-change} and \csopt[lc]{short-case-change} -only tokens that are recognised as characters will be converted. -For example, suppose I have a slightly more eccentric definition: -\begin{verbatim} -@abbreviation{html, - short = "ht\emph{ml}", - long = "hypertext markup language" +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[lc]{short-case-change}, + \csopt[title]{long-case-change}, + \csopt[firstuc]{description-case-change} } -\end{verbatim} +\end{codeenv} +will make the entry behave as if it had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{Hypertext Markup Language}, + \field{description}=\marg{A markup language for creating web pages} +} +\end{codeenv} +whereas: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[lc-cs]{short-case-change}, + \csopt[title-cs]{long-case-change}, + \csopt[firstuc-cs]{description-case-change} +} +\end{codeenv} +will make the entry behave as if it had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{\gls{bibglslowercase}\marg{HTML}}, + \field{long} = \marg{\gls{bibglstitlecase}\marg{hypertext markup language}}, + \field{description}=\marg{\gls{bibglsfirstuc}\marg{a markup language for creating web pages}} +} +\end{codeenv} +If the given field is missing, no change is made, except under +certain circumstances (see the relevant resource option for details). +For example, if an abbreviation is simply defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language} +} +\end{codeenv} +then: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[uc]{name-case-change}, + \csopt[title]{description-case-change} +} +\end{codeenv} +won't have an effect. Although the default \abbrstyle{long-short} abbreviation +style sets the \field{name} and \field{description} fields, \bibgls\ doesn't +have access to this information. + +Remember that you can create missing fields by copying the value +from another field. So if the resource options are changed to: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[uc]{name-case-change}, + \csopt[title]{description-case-change}, + \csopt[\field{short}=\field{name},\field{long}=\field{description}]{replicate-fields} +} +\end{codeenv} +then \bibgls\ will act as though the entry had been defined as: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \marg{html}, + \field{long} = \marg{hypertext markup language}, + \field{name} = \marg{HTML}, + \field{description} = \marg{Hypertext Markup Language} +} +\end{codeenv} +If the \abbrstyle{long-short-sc} abbreviation style is set (before +\gls{GlsXtrLoadResources}) then this will override the default style +for the \field{name} and \field{description}, so +\code{\cs{gls}\marg{html}} will display the short form using +\code{\ics{textsc}\marg{html}} but the \field{name} in the glossary +will be displayed using just \code{HTML}. + +Note that with \atentry{index} the \field{name} and \field{text} +fields will automatically be created if they are missing and +\csopt{name-case-change} is used. For example, if an entry is +defined as: +\begin{codeenv} +\atentry{index}\marg{duck} +\end{codeenv} +then \csopt[firstuc]{name-case-change} will make this entry behave +as though it was defined as: +\begin{codeenv} +\atentry{index}\marg{duck, + \field{name} = \marg{Duck}, + \field{text} = \marg{duck} +} +\end{codeenv} + +Suppose I have a slightly eccentric abbreviation definition: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{ht\cs{emph}\marg{ml}}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} then \csopt[uc]{short-case-change} would convert the value of the \field{short} field into: -\begin{verbatim} -HT\emph{ML} -\end{verbatim} -Note that \csfmt{emph} isn't modified as it's recognised as a command. -There's no attempt at interpreting the contents at this point (but -the value may later be interpreted during sorting). +\begin{codeenv} +HT\cs{emph}{ML} +\end{codeenv} +Note that \csfmt{emph} isn't modified as it's recognised as a +command. There's a difference between a group that follows a control +sequence and one that doesn't. For example: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{\marg{ht}ml}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} +In this case \csopt[firstuc]{short-case-change} will convert the +\field{short} field value to: +\begin{codeenv} +\marg{HT}ml +\end{codeenv} +(The entire contents of the group \code{\marg{ht}} has been +converted.) Whereas with: +\begin{codeenv} +\atentry{abbreviation}\marg{html, + \field{short} = \qtdelim{\cs{emph}\marg{ht}ml}, + \field{long} = \qtdelim{hypertext markup language} +} +\end{codeenv} +then \csopt[firstuc]{short-case-change} will convert the +\field{short} field value to: +\begin{codeenv} +\cs{emph}\marg{Ht}ml +\end{codeenv} +(Only the first letter of the argument \code{\marg{ht}} has been +converted.) -For example, suppose an abbreviation is defined using: -\begin{verbatim} -short = "z\ae\oe", -\end{verbatim} -then with \csopt[uc]{short-case-change}, this would be converted to -\begin{verbatim} -Z\ae\oe -\end{verbatim} -since the interpreter isn't being used at this stage. If the -interpreter is later used during sorting, the sort value will be set to -\code{Z\ae\oe}. +There's no attempt at interpreting the field contents at this point (but +the value may later be interpreted during sorting). +For example, suppose a \field{name} field is defined using: +\begin{codeenv} +\field{name} = \qtdelim{z\ics{ae}\ics{oe}}, +\end{codeenv} +then with \csopt[uc]{name-case-change}, the value would be converted to +\begin{codeenv} +Z\ics{AE}\ics{OE} +\end{codeenv} +because \cs{ae} and \cs{oe} have known \idx{uppercase} versions. -However, with \csopt[uc-cs]{short-case-change}, the \field{short} -value would be converted to -\begin{verbatim} -\MakeTextUppercase{z\ae\oe} -\end{verbatim} +With \csopt[uc-cs]{name-case-change}, the \field{name} +value would be converted to: +\begin{codeenv} +\gls{bibglsuppercase}\marg{z\cs{ae}\cs{oe}} +\end{codeenv} If the interpreter is used during sorting, the sort value will be set to -\code{Z\AE\OE}. +\code{Z\AE\OE} because the interpreter recognises all three commands. -You can use \ics{NoCaseChange}\margm{text} to prevent the given \meta{text} -from having the case changed. For example, if the \field{short} -field is defined as -\begin{verbatim} -short = {a\NoCaseChange{bc}d} -\end{verbatim} -then with \csopt[uc]{short-case-change}, this would be converted to -\begin{verbatim} -A\NoCaseChange{bc}D -\end{verbatim} -(This command is provided by \isty{textcase}, which is automatically -loaded by \styfmt{glossaries}.) +You can use \code{\ics{NoCaseChange}\margm{text}} to prevent the given +\meta{text} from having the case changed. For example, if the \field{short} +field is defined as: +\begin{codeenv} +\field{short} = \marg{a\cs{NoCaseChange}\marg{bc}d} +\end{codeenv} +then with \csopt[uc]{short-case-change}, this would be converted to +\begin{codeenv} +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 +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} +\end{codeenv} +then the result is: +\begin{codeenv} +\cs{NoCaseChange}\marg{h}Tml +\end{codeenv} +whereas with: +\begin{codeenv} +\field{short}=\marg{\marg{}html} +\end{codeenv} +then the result is just \code{\marg{}html} (since the case change is +applied to the empty group, which has no effect). If you have a command that takes a label or identifier as an argument then it's best to hide the label in a custom command. For example, if the \field{short} field in the \ext{bib} definition is defined as: -\begin{verbatim} - short = "ht\textcolor{red}{ml}", -\end{verbatim} +\begin{codeenv} + \field{short} = \qtdelim{ht\ics{textcolor}\marg{red}\marg{ml}}, +\end{codeenv} then with \csopt[uc]{short-case-change} this would end up as: -\begin{verbatim} -HT\textcolor{RED}{ML} -\end{verbatim} +\begin{codeenv} +HT\cs{textcolor}\marg{RED}\marg{ML} +\end{codeenv} which is incorrect. Instead, provide a command that hides the label (such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}). -The first letter upper casing \csopt[firstuc]{short-case-change} -is slightly more complicated. The simplest case is where -the field only contains alphabetical characters. For example, -suppose the \field{short} field is defined as: -\begin{verbatim} -short={html} -\end{verbatim} -then with \csopt[firstuc]{short-case-change} this would end up as -\code{Html} whereas -\begin{verbatim} -short={{ht}ml} -\end{verbatim} -would end up as \code{HTml} since it detects the grouping. -(You'll need to do this for the Dutch digraph \qt{ij}.) -Note that \ics{NoCaseChange} is skipped, and the case change is -applied to the material following its argument. For example, -suppose the \field{short} field is defined as: -\begin{verbatim} -short={\NoCaseChange{h}tml} -\end{verbatim} -then the result is -\begin{verbatim} -\NoCaseChange{h}Tml -\end{verbatim} -whereas with -\begin{verbatim} -short={{}html} -\end{verbatim} -then the result is just \code{html}. If a command is followed by -a group then the case change is applied to the group (unless the -command is \ics{NoCaseChange}, \ics{ensuremath} or \ics{si}). For -example, -suppose the \field{short} field is defined as: -\begin{verbatim} -short={\emph{ht}ml} -\end{verbatim} -then the result is -\begin{verbatim} -\emph{Ht}ml -\end{verbatim} -If a command isn't followed by a group (and it's not \ics{protect}) -then no change occurs. For example, -suppose the \field{short} field is defined as: -\begin{verbatim} -short={\ae html} -\end{verbatim} -then the result is -\begin{verbatim} -\ae html -\end{verbatim} -whereas with -\begin{verbatim} -short={\protect html} -\end{verbatim} -the result is -\begin{verbatim} -\protect Html -\end{verbatim} +\optsection[\subsubsection]{word-boundaries} + +Governs how the \optfmt{title} \idx{case-change} option +determines word boundaries. The \meta{list} must contain one or +more of the following keywords: +\begin{description} +\item[\optfmt{white space}] any white space Unicode character +that is not a non-breakable space indicates a word-boundary; +\item[\optfmt{cs space}] the control sequences +\ics{space} or \ics{cs.space} indicate a word-boundary; +\item[\optfmt{dash}] a Unicode character that belongs to the +\idx{punctuationdash} block indicates a word-boundary; +\item[\optfmt{nbsp}] the \idx{nbspchar} active character or the Unicode +non-breakable characters \hex{00A0}, \hex{2007} and \hex{202F} +indicate a word-boundary. +\end{description} +Any keyword that is not listed indicates that particular setting is off. This +option is not cumulative. Any subsequent use of +\csopt{word-boundaries} within the same set of resource options will +override previous settings. + +The default setting is \csopt[white space,cs +space]{word-boundaries}, which excludes non-breakable +spaces and dashes. + +\optsection[\subsubsection]{short-case-change} + +Applies a case-change to the \field{short} field (if present). +This option may take one of the values described above. See \csopt{dual-short-case-change} to adjust the \field{dualshort} field. +\optsection[\subsubsection]{long-case-change} + +Applies a case-change to the \field{long} field (if present). +This option may take one of the values described above. + +See \csopt{dual-long-case-change} to adjust the \field{duallong} +field. + \optsection[\subsubsection]{name-case-change} -As \csopt{short-case-change} but is applied to the \field{name} -field. If the \field{text} field hasn't been set, the \field{name} +Applies a case-change to the \field{name} field. +This option may take one of the values described above. + +If the \field{text} field hasn't been set, the \field{name} value is first copied to the \field{text} field. If the \field{name} field hasn't been set (for example, with the \atentry{index} entry type), it's copied from the fallback value (which @@ -7998,8 +9278,9 @@ the \field{name} field is missing no action is performed. \optsection[\subsubsection]{description-case-change} -As \csopt{short-case-change} but is applied to the -\field{description} field. +Applies a case-change to the \field{description} field (if present). +This option may take one of the values described above. + \section{Plurals} \label{sec:plurals} @@ -8063,17 +9344,17 @@ by category attributes}. This suffix command is set by the abbreviation styles. This means that every time an abbreviation style is implemented, \ics{abbrvpluralsuffix} is redefined. Most styles simply define this command as: -\begin{verbatim} -\renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{glsxtrabbrvpluralsuffix}} +\end{codeenv} where \ics{glsxtrabbrvpluralsuffix} expands to \ics{glspluralsuffix}. The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different definition: -\begin{verbatim} -\renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{protect}\ics{glsxtrscsuffix}} +\end{codeenv} This allows the suffix to be reverted back to the upright font, -counter-acting the affect of the small-caps font. +counteracting the affect of the small-caps font. This means that if you want to change or strip the suffix used for the plural short form, it's usually not sufficient to redefine @@ -8084,10 +9365,10 @@ use the category attributes. There are two attributes that affect the short plural suffix formation. The first is \catattr{aposplural} which uses the suffix -\begin{verbatim} -'\abbrvpluralsuffix -\end{verbatim} -That is, an apostrophe followed by \ics{abbrvpluralsuffix} is +\begin{codeenv*} +\idx{aposchar}\cs{abbrvpluralsuffix} +\end{codeenv*} +That is, an \idx{apostrophe} followed by \ics{abbrvpluralsuffix} is appended. The second attribute is \catattr{noshortplural} which suppresses the suffix and simply sets \field{shortplural} to the same as \field{short}. @@ -8098,32 +9379,43 @@ have a suffix and some where the plural shouldn't have a suffix then there are two approaches. The first approach is to use the category attributes. For example: -\begin{verbatim} -\glssetcategoryattribute{french}{noshortplural} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{french}\marg{\catattr{noshortplural}} +\end{codeenv} Now just make sure all the French abbreviations are have their \field{category} field set to \optfmt{french}: -\begin{verbatim} -\GlsXtrLoadResources[src={fr-abbrvs},category={french}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[french]{category}} +\end{codeenv} -The other approach is to use the options listed below. +The other approach is to use the options listed below for the given +\idx{resourceset}. For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}} +\end{codeenv} \optsection{short-plural-suffix} -Sets the plural suffix for the default \field{shortplural} to \meta{value}. If -this option is omitted or if -\csopt[use-default]{short-plural-suffix}, then \bibgls\ will leave +Sets the plural suffix for the default \field{shortplural} to +\meta{value}. The \meta{value} may be one of: +\begin{itemize} +\item \meta{suffix}: add the +\field{shortplural} field, if missing, with the given \meta{suffix}. +\item \meta{empty}: add the +\field{shortplural} field, if missing, with no suffix. +\item \optfmt{use-default}: leave it to \styfmt{glossaries-extra} to determine the appropriate default. -If the \meta{value} is omitted or empty, the suffix is set to empty. +\end{itemize} +The default setting is \csopt[use-default]{short-plural-suffix}. +If the \code{=\meta{value}} part is omitted, then +\csopt[\empty]{short-plural-suffix} is assumed. \optsection{dual-short-plural-suffix} Sets the plural suffix for the default \field{dualshortplural} field to -\meta{value}. If this option is omitted or if -\csopt[use-default]{dual-short-plural-suffix}, then \bibgls\ will leave it to -\styfmt{glossaries-extra} to determine the appropriate default. -If the \meta{value} is omitted or empty, the suffix is set to empty. +\meta{value}. As with \csopt{short-plural-suffix}, the default +setting is \csopt[use-default]{dual-short-plural-suffix}. If the +\meta{value} is omitted or empty, the suffix is set to empty. \section{Location List Options} \label{sec:locationopts} @@ -8132,60 +9424,99 @@ The \styopt{record} package option automatically adds two new keys: \field{loclist} and \field{location}. These two fields are set by \bibgls\ from the information supplied in the \iext{aux} file (unless the option \csopt[false]{save-locations} is used). The -\field{loclist} field has the syntax of an \isty{etoolbox} internal list +\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}). -Each item in the list is provided in the form -\begin{alltt} +\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: +\begin{codeenv} \ics{glsseeformat}\oargm{tag}\margm{label list}\marg{} -\end{alltt} +\end{codeenv} for the cross-reference supplied by the \field{see} field, -\begin{alltt} -\ics{glsxtruseseealsoformat}\margm{label list} -\end{alltt} +\begin{codeenv} +\ics{glsxtruseseealsoformat}\margm{xr list} +\end{codeenv} for the cross-reference supplied by the \field{seealso} field, -and \nosecdef{glsnoidxdisplayloc} -for the locations. You can iterate through the \field{loclist} value +for standard the internal locations, +\begin{codeenv} +\format{glsxtrdisplaysupploc} +\end{codeenv} +for 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 +\longarg{merge-nameref-on} for more information about \code{nameref} +records.) + +You can iterate through the \field{loclist} value using one of \sty{etoolbox}'s internal list loops (either by first fetching the list using \ics{glsfieldfetch} or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop} shortcuts). The \meta{format} is that supplied by the \glsopt{format} key -when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or encap in -\idx!{makeindex} parlance). If omitted, the default +when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or +\idx{encap} in \idx!{makeindex} parlance). If omitted, the default \glsopt[glsnumberformat]{format} is assumed (unless this default value is changed with \ics{GlsXtrSetDefaultNumberFormat}. - -Ranges can be explicitly formed using the parenthetical encap -syntax \glsopt[(]{format} and -\glsopt[)]{format} or \glsopt[(\meta{csname}]{format} and -\glsopt[)\meta{csname}]{format} (where \meta{csname} is the name of +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 +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 no longer have a hyperlink if you've used \sty{hyperref}. +If you want to retain the hyperlink you need the 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} +user manual for a list of all the \csfmt{hyper}\meta{xx} commands. + +Ranges can be explicitly formed using the parenthetical +syntax \glsopt[\idx{openrange}]{format} and +\glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and +\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of 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 \csref{bibglsrange}. (This command is not used with -ranges that are formed by collating consecutive locations.) +encapsulated by \gls!{bibglsrange}. (This command is not used with +ranges that are formed by collating consecutive locations.) The +initial marker is stripped from the \meta{format} argument of the +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 \verb|\gls{sample}| is used on page~1, -\verb|\gls[format=(]{sample}| is used on page~2, -\verb|\gls{sample}| is used on page~3, and -\verb|\gls[format=)]{sample}| is used on page~4, then the location +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 \verb|\gls[format=textbf]{sample}| then it would cause a -warning and be moved before the start of the range so that the -location list would then be 1, \textbf{3}, 2--4. +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. An \idx{ignoredrecord} identifies a term that needs to be treated as though it has a record for selection purposes, but the record should not be included in the location list. -The special format \glsaddopt[glsignore]{format} is provided +The special format \glsaddopt[\encap{glsignore}]{format} is provided by the \styfmt{glossaries} package for cases where the location should be ignored. (The command \ics{glsignore} simply ignores its argument.) This works reasonably well if an entry only has the one @@ -8205,34 +9536,34 @@ Those that don't have records won't have a location list.) For example, suppose you only want main matter locations 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: -\begin{alltt} +\begin{codeenv} \ics{backmatter} -\ics{GlsXtrSetDefaultNumberFormat}\marg{glsignore} -\end{alltt} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} If you also want to drop front matter locations as well: -\begin{alltt} +\begin{codeenv} \ics{frontmatter} -\cs{GlsXtrSetDefaultNumberFormat}\marg{glsignore} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \ldots \ics{mainmatter} -\cs{GlsXtrSetDefaultNumberFormat}\marg{glsnumberformat} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsnumberformat}} \ldots \cs{backmatter} -\cs{GlsXtrSetDefaultNumberFormat}\marg{glsignore} -\end{alltt} +\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} +\end{codeenv} Note that explicit range formations aren't discarded, so if -\encap{glsignore} is used in a range, such as -\begin{verbatim} -\glsadd[format=(glsignore]{sample} -... -\glsadd[format=)glsignore]{sample} -\end{verbatim} +\encap{glsignore} is used in a range, such as: +\begin{codeenv} +\ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample} +\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 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 \ics{rgls}, use the special +The 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. @@ -8253,36 +9584,38 @@ and instead parse the \field{loclist} field and re-order the locations or process them in some other way. Remember that you can also use \ics{glsnoidxloclist} provided by \styfmt{glossaries}. For example: -\begin{verbatim} -\glsfieldfetch{gls.sample}{loclist}{\loclist}% fetch location list -\glsnoidxloclist{\loclist}% iterate over locations -\end{verbatim} +\begin{codeenv} +\cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list} +\cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations} +\end{codeenv} This uses \ics{glsnoidxloclisthandler} as the list's handler macro, which simply displays each 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 location is listed in the \iext{aux} file in the form: +Each regular 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} is indexed twice on page 1: -\begin{verbatim} -\glsxtr@record{cat}{}{page}{glsnumberformat}{1} -\glsxtr@record{cat}{}{page}{glsnumberformat}{1} -\end{verbatim} +\begin{codeenv} +\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. Partial duplicates, where all arguments match except for \meta{format}, may be discarded depending on the value of \meta{format}. For example, if page~1 of the document -uses \verb|\gls{cat}| and \verb|\gls[format=hyperbf]{cat}| +uses \code{\cs{gls}\marg{cat}} and +\code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{cat}} then the \ext{aux} file will contain: -\begin{verbatim} -\glsxtr@record{cat}{}{page}{glsnumberformat}{1} -\glsxtr@record{cat}{}{page}{hyperbf}{1} -\end{verbatim} +\begin{codeenv} +\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\ makes the following tests: \begin{itemize} @@ -8327,7 +9660,7 @@ want the location lists (for example, you are using the custom location rule), then there's no need for \bibgls\ to process the locations. 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 +you're not additionally using \idx!{makeindex} or \idx!{xindy}, then the locations won't be available even if you don't have the \styopt{nonumberlist} option set. @@ -8337,13 +9670,301 @@ If you want the \field{location} field but don't need \field{loclist}, you can use \csopt[false]{save-loclist}. This can help to save resources and build time. +\optsection{save-primary-locations} + +It's sometimes useful to identify primary locations 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 +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. + +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 +\field{primarylocations} field but don't remove from the usual +\idx{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 +\field{primarylocations} field retain their given format); +\item \optfmt{start}: save primary locations in the +\field{primarylocations} field and also move to the start of the +usual \idx{locationlist}; +\item \optfmt{remove}: save primary locations in the +\field{primarylocations} field and remove from the usual +\idx{locationlist}. +\end{itemize} + +The primary locations 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 +\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 +style. + +For example, the \glostyle{bookindex} style inserts +\ics{glsxtrbookindexprelocation} before the location, so you could +redefine this: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{primarylocations}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \ics{glsxtrprelocation} + \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{location}\marg{\idx{param}1}\marg{;}\marg{}\comment{} + }\comment{} + \marg{}\comment{} + \cs{glsxtrprelocation} +} +\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 +unless they've been omitted.) + +You can switch from using the \field{location} field to the +\field{primarylocations} field by locally changing +\ics{GlsXtrLocationField}: +\begin{codeenv} +\cs{printunsrtglossary*}\marg{\comment{} + \cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{} +} +\end{codeenv} +Remember that the handler used by \cs{printunsrtglossary} will +fallback on the \field{loclist} field if the field identified +by \cs{GlsXtrLocationField} is missing or empty. You may want to +consider using \csopt[false]{save-loclist} to prevent this. + +\optsection{primary-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} +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 +associated entry's \field{primarylocations} field. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{codeenv} +\atentry{entry}\marg{bird, + \field{name}=\marg{bird}, + \field{description}=\marg{feathered animal} +} +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{any bird that lives in or about water} +} +\atentry{entry}\marg{zebra, + \field{name}=\marg{zebra}, + \field{description}=\marg{striped African horse} +} +\atentry{entry}\marg{parrot, + \field{name}=\marg{parrot}, + \field{description}=\marg{mainly tropical bird with bright plumage} +} +\end{codeenv} +and the document \filefmt{test.tex} contains: +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt[dot]{postpunc}, + \styopt{nostyles}, + \styopt[tree,bookindex]{stylemods}, + \styopt[bookindex]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[hyperbf,hyperemph]{primary-location-formats}, + \csopt[remove]{save-primary-locations} +} +\strut +\cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{primarylocations}}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \ics{glsxtrprelocation} + \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\idx{param}1}\marg{;}\marg{}\comment{} + }\comment{} + \marg{}\comment{} + \cs{glsxtrprelocation} +} +\strut +\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Sample} +\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Another Sample} +\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample Again} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. +\strut +\ics{printunsrtglossary*}\oarg{\printglossopt[\iglostyle{tree}]{style},\printglossopt{nonumberlist}}\marg{\comment{} + \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} +} +\strut +\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} +\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 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 main glossary 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 +\LaTeX\ run: +\begin{verbatim} +pdflatex test +bib2gls --group test +pdflatex test +bib2gls --group test +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 +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}) +that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets +up a hook that automatically inserts: +\begin{codeenv*} +\ics{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\margm{label} +\end{codeenv*} +on each instance of \code{\cs{gls}\oarg{\glsopt[primaryfmt]{format}}\margm{label}} (or +similar). This means that the entry is indexed twice when this particular +format is used: first with the \encap{hyperrm} format and \counter{chapter} +counter (from the \cs{glsadd} command in the hook), and then with the +\code{primaryfmt} format and the default counter (as per normal behaviour): +\begin{codeenv} +\cmd{documentclass}\marg{report} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{ + \styopt[nameref]{record}, + \styopt[dot]{postpunc}, + \styopt{nostyles}, + \styopt[tree,bookindex]{stylemods}, + \styopt[bookindex]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[topics]{src}, + \csopt[hyperrm]{primary-location-formats}, + \csopt[remove]{save-primary-locations}, + \csopt[false]{save-loclist} +} +\strut +\cmd{newcommand}\marg{\cmd{primaryfmt}}\oarg{1}\marg{\cs{hyperbf}\marg{\idx{param}1}} +\strut +\ics{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}} +\strut +\gls{glsxtrnewglslike}\oarg{\glsaddopt[primaryfmt]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}} +\strut +\cmd{begin}\marg{document} +\cmd{chapter}\marg{Sample} +\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Another Sample} +\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}. +\strut +\cmd{chapter}\marg{Yet Another Sample Again} +\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}. +\strut +\ics{printunsrtglossary*}\oarg{\printglossopt[\glostyle{tree}]{style},\printglossopt[Summary]{title}}\marg{\comment{} + \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{} + \cmd{renewcommand}\marg{\ics{GlsXtrLocationField}}\marg{\field{primarylocations}}\comment{} +} +\strut +\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}} +\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. + +An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply +define the custom commands as follows: +\begin{codeenv} +\cmd{newcommand}\marg{\cmd{primary}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{primarypl}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{Primary}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{Gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\cmd{newcommand}\marg{\cmd{Primarypl}}[2][]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{} + \cs{Glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{} +} +\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 +ranges in the index. + \optsection{min-loc-range} By default, three or more consecutive locations \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 \csref{bibglsdelimN}. As mentioned -above, these aren't merged with explicit range formations. +the locations 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 @@ -8351,9 +9972,9 @@ integer greater than one indicating how many consecutive locations should be converted into a range. \bibgls\ determines if one location -\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2} +\code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}} is one unit more than another location -\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} +\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 @@ -8365,7 +9986,8 @@ then the locations 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 regular expression will match any digits in the -Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set.} +Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic +characters outside the Basic Latin set.} \begin{verbatim} (.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit} \p{javaAlphabetic}]+)\} @@ -8439,27 +10061,27 @@ consecutive. Examples: \begin{enumerate} \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\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 the \hyperref[itm:decmatch]{decimal pattern} and the test in step~\ref{itm:decgrp3} passes. \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1} -\glsxtr@record{gls.sample}{}{page}{textbf}{2} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{textbf}}\marg{2} +\end{codeenv} These records aren't consecutive since the formats are different. \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{A.i} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{A.ii} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.i} +\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 the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where @@ -8469,10 +10091,10 @@ the test is retried with the locations set to 1 and 2, respectively. This now passes the decimal pattern test (step~\ref{itm:decgrp3}). \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{i.A} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{ii.A} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{i.A} +\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 considered to consist of the prefix \code{i}, the separator @@ -8485,10 +10107,10 @@ The test fails because the numbers are equal and the prefixes are different. \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1.0} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2.0} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.0} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.0} +\end{codeenv} 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 @@ -8496,24 +10118,28 @@ the test is retried with the first location set to 1 and the second location set to 2. \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1.1} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2.1} -\end{verbatim} +\begin{codeenv} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.1} +\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.1} +\end{codeenv} These records aren't consecutive as the test branches off into step~\ref{itm:decgrp3nz}. \item -\begin{verbatim} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{\@alph{1}} -\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{\@alph{2}} -\end{verbatim} +\begin{codeenv} +\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 \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. -(Note that \csref{glsxtrresourcefile} changes the category code of -\code{@} to allow for internal commands in locations.) + +In this example, the 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. \end{enumerate} \optsection{max-loc-diff} @@ -8537,7 +10163,8 @@ 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. +This is used in the range formations within the location lists (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}. @@ -8547,9 +10174,9 @@ the location lists 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 -there are one or two gaps in it. +if there are one or two gaps in it. By default, any location ranges that have skipped gaps in this -manner will be followed by \csref{bibglspassim}. The default +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}). @@ -8587,7 +10214,7 @@ The default is \csopt[none]{suffixFF}. 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 still be available in the \field{see} field for use with -\ics{glsxtrusesee}). This option may take the following values: +\ics{glsxtrusesee}). The required \meta{value} must be one of: \begin{itemize} \item \optfmt{omit}: omit the see reference from the location list. @@ -8596,12 +10223,11 @@ list. \item \optfmt{after}: place the see reference after the location list (default). \end{itemize} -The \meta{value} part is required. The separator between the location list and the cross-reference is -provided by \csref{bibglsseesep}. This separator is omitted if the +provided by \gls!{bibglsseesep}. This separator is omitted if the location list is empty. The cross-reference is written to the -\field{location} field using \gls{bibglsusesee}\margm{label}. +\field{location} field using \code{\gls{bibglsusesee}\margm{label}}. \optsection{seealso} @@ -8609,21 +10235,21 @@ This is like \csopt{see} but governs the location of the cross-references provided by the \field{seealso} field. You need at least v1.16 of \sty{glossaries-extra} for this option. The values are the same as for \csopt{see} but the separator is given by -\csref{bibglsseealsosep}. The cross-reference is written to the -\field{location} field using \gls{bibglsuseseealso}\margm{label}. +\gls!{bibglsseealsosep}. The cross-reference is written to the +\field{location} field using \code{\gls{bibglsuseseealso}\margm{label}}. \optsection{alias} This is like \csopt{alias} but governs the location of the cross-references provided by the \field{alias} field. The separator is given by -\csref{bibglsaliassep}. The cross-reference is written to the -\field{location} field using \gls{bibglsusealias}\margm{label}. +\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 may be retained or omitted or transferred to the target entry. -The \meta{value} may be one of: +The required \meta{value} must be one of: \begin{itemize} \item\optfmt{keep}: keep the location list; \item\optfmt{transfer}: transfer the location list; @@ -8638,62 +10264,66 @@ is left unchanged). Note that with \csopt[transfer]{alias-loc}, both the aliased entry and the target entry must be in the same resource set. (That is, both entries have been selected by the same instance of -\csref{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version -1.12, you may need to redefine \ics{glsxtrsetaliasnoindex} to do +\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 -with aliased entries. (This was corrected in version 1.13.) +with aliased entries. (This was corrected in version~1.13.) \optsection{loc-prefix} The \csopt{loc-prefix} setting indicates that the location lists -should begin with \csref{bibglslocprefix}\margm{n}. The \meta{value} may +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 \gls{bibglslocprefix}\margm{n} at the start -of the location lists (default). +\item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the +start of the location lists (default). + \item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}: -insert \gls{bibglslocprefix}\margm{n} (where \meta{n} is the number of +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 definition of \gls{bibglslocprefix} will be appended to the glossary preamble providing an \ics{ifcase} condition: -\begin{alltt} -\csfmt{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\% - \ics{ifcase}\string#1 - \csfmt{or} \meta{prefix-1}\csref{bibglspostlocprefix} - \csfmt{or} \meta{prefix-2}\csfmt{bibglspostlocprefix} +\begin{codeenv} +\cmd{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \ics{ifcase}\idx{param}1 + \cmd{or} \meta{prefix-1}\gls{bibglspostlocprefix} + \cmd{or} \meta{prefix-2}\gls{bibglspostlocprefix} \ldots - \csfmt{else} \meta{prefix-n}\csfmt{bibglspostlocprefix} - \csfmt{fi} + \cmd{else} \meta{prefix-n}\gls{bibglspostlocprefix} + \cmd{fi} } -\end{alltt} +\end{codeenv} + +\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. -\item \optfmt{comma}: -essentially equivalent to \csopt[,~]{loc-prefix} but -avoids confusion with the list format. \item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}. + \item \optfmt{true}: equivalent to -\csopt[\csref{bibglspagename},\csref{bibglspagesname}]{loc-prefix}, +\csopt[\gls{bibglspagename},\gls{bibglspagesname}]{loc-prefix}, where the definitions of \gls{bibglspagename} and -\gls{bibglspagesname} are obtained from the \code{tag.page} and -\code{tag.pages} entries in \bibgls's \langxml. +\gls{bibglspagesname} are obtained from the \idx{tag.page} and +\idx{tag.pages} entries in \bibgls's \langxml. This setting works best if the document's language matches the language file. However, you can redefine these commands within the document's language hooks or in the glossary preamble. + \end{itemize} If \meta{value} is omitted, \optfmt{true} is assumed. Take care not to mix different values of \csopt{loc-prefix} for entries for the same \csopt{type} setting. It's okay to mix \csopt[false]{loc-prefix} with another value, but don't mix non-\optfmt{false} values. -See the description of \csref{bibglslocprefix} for +See the description of \gls!{bibglslocprefix} for further details. For example: -\begin{verbatim} -\GlsXtrLoadResources[type=main,src={entries1},loc-prefix=false] -\GlsXtrLoadResources[type=main,src={entries2},loc-prefix] -\GlsXtrLoadResources[type=symbols,src={entries3},loc-prefix={p.,pp.}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries1]{src},\csopt[false]{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries2]{src},\csopt{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} +\end{codeenv} This works since the conflicting \csopt[p.,pp.]{loc-prefix} and \csopt[true]{loc-prefix} are in different glossaries (assigned through the \csopt{type} key). The entries fetched from \filefmt{entries1.bib} @@ -8706,11 +10336,11 @@ setting the \field{type} field for each entry in the \ext{bib} file.) If the \csopt{type} option isn't used: -\begin{verbatim} -\GlsXtrLoadResources[src={entries1},loc-prefix=false] -\GlsXtrLoadResources[src={entries2},loc-prefix] -\GlsXtrLoadResources[src={entries3},loc-prefix={p.,pp.}] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries1]{src},\csopt[false]{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries2]{src},\csopt{loc-prefix}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}} +\end{codeenv} then \csopt[true]{loc-prefix} takes precedence over \csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from \filefmt{entries1.bib} still won't have a location prefix, but the entries @@ -8731,7 +10361,7 @@ 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). -This option will append \csref{bibglslocsuffix}\margm{n} to location +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 @@ -8751,44 +10381,44 @@ counter to use for the 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: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record,style=tree]{glossaries-extra} - -\GlsXtrLoadResources[ - src={entries}% data in entries.bib -] - -\begin{document} - -\gls{pi}. -\begin{equation} -\gls[counter=equation]{pi} -\end{equation} -\begin{equation} -\gls[counter=equation]{pi} -\end{equation} - -\newpage -\begin{equation} -\gls[counter=equation]{pi} -\end{equation} - -\newpage -\gls{pi}. - -\newpage -\gls{pi}. - -\newpage -\gls{pi}. - -\newpage -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}\comment{data in entries.bib} +} +\strut +\cmd{begin}\marg{document} +\strut +\cs{gls}\marg{pi}. +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{newpage} +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{gls}\marg{pi}. +\strut +\cmd{newpage} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} This results in the location list \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, @@ -8801,17 +10431,17 @@ the comma-separated \meta{list}. If a location has a counter that's not listed in \meta{list}, then the location is discarded. For example: -\begin{verbatim} -\GlsXtrLoadResources[ - loc-counters={equation,page},% group locations by counter - src={entries}% data in entries.bib -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\counter{equation},\counter{page}]{loc-counters},\comment{group locations by counter} + \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 -\csref{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}. -The groups are separated by \csref{bibglslocationgroupsep}. +\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 @@ -8855,17 +10485,17 @@ The \styopt{indexcounter} package option also automatically implements the option \styopt[wrglossary]{counter}, which means that each instance of \code{\ics{gls}\margm{id}} writes the label information to the \iext{aux} file: -\begin{alltt} -\csfmt{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}} -\end{alltt} +\begin{codeenv} +\cmd{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}} +\end{codeenv} (where \meta{page} is the page number) followed by the record: -\begin{alltt} -\cs{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{glsnumberformat}\margm{n} -\end{alltt} +\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} 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 record's location \meta{n} with: \nosecdef{glsxtr@wrglossarylocation} (but it only does this for records that have the \counter{wrglossary} counter). @@ -8897,19 +10527,19 @@ instance of a specific format of the \counter{wrglossary} locations for a given entry. This location is stored in the \field{indexcounter} internal field using: \begin{codeenv} -\ics{GlsXtrSetField}\margm{id}\marg{indexcounter}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} +\ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}} \end{codeenv} Since \gls{glsxtr@wrglossarylocation} simply expands to its first -argument, the corresponding label can be obtained with -\begin{alltt} +argument, the corresponding label can be obtained with: +\begin{codeenv} wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page} -\end{alltt} -For convenience, \sty{glossaries-extra-bib2gls} provides +\end{codeenv} +For convenience, \sty{glossaries-extra-bib2gls} provides: \nosecdef{GlsXtrIndexCounterLink} -which will do -\begin{alltt} -\csfmt{hyperref}\oarg{wrglossary.\meta{value}}\margm{text} -\end{alltt} +which will do: +\begin{codeenv*} +\ics{cs.hyperref.int}\oarg{wrglossary.\meta{value}}\margm{text} +\end{codeenv*} where \meta{value} is the value of the \field{indexcounter} field if it has been set. If the \field{indexcounter} field hasn't been set (or if \sty{hyperref} hasn't been loaded) then just \meta{text} is @@ -8920,53 +10550,53 @@ the glossary so that it links back to the first \counter{wrglossary} entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary} entry. This encapsulation can be done by providing a new glossary style or more simply by redefining \ics{glsnamefont}: -\begin{verbatim} -\renewcommand{\glsnamefont}[1]{% - \GlsXtrIndexCounterLink{#1}{\glscurrententrylabel}} -\end{verbatim} +\begin{codeenv} +\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} + \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} +\end{codeenv} Here's a complete example: -\begin{verbatim} -\documentclass{article} - -\usepackage{lipsum}% dummy filler text -\usepackage[colorlinks]{hyperref} -\usepackage[record,indexcounter]{glossaries-extra} - -\newcommand{\primary}[1]{\hyperbf{#1}} - -\GlsXtrLoadResources[ - src={entries},% terms defined in entries.bib - save-index-counter=primary -] - -\renewcommand{\glsnamefont}[1]{% - \GlsXtrIndexCounterLink{#1}{\glscurrententrylabel}} - -\begin{document} - -A \gls{sample}. \lipsum*[1] A \gls{duck}. - +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\marg{lipsum}\comment{dummy filler text} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{indexcounter}}\marg{glossaries-extra} +\strut +\cmd{newcommand}\marg{\cmd{primary}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{terms defined in entries.bib} + \csopt[primary]{save-index-counter} +} +\strut +\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{} + \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}} +\strut +\cmd{begin}\marg{document} +\strut +A \cs{gls}\marg{sample}. \cmd{lipsum}*[1] A \cs{gls}\marg{duck}. +\strut An equation: -\begin{equation} -\gls[counter=equation]{pi} -\end{equation} - -\lipsum[2] - -Another \gls[format=primary]{sample}. \lipsum*[3] Another -\gls{duck}. - -\gls{pi}. \lipsum[4] - -A \gls{sample}. \lipsum*[5] A \gls{duck} and -\gls[format=primary]{pi}. - -\lipsum*[6] A \gls[format=primary]{duck}. - -\printunsrtglossaries -\end{document} -\end{verbatim} -Note that the \glsopt[equation]{counter} entry will have its own +\cmd{begin}\marg{equation} +\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi} +\cmd{end}\marg{equation} +\strut +\cmd{lipsum}[2] +\strut +Another \cs{gls}\oarg{\glsopt[primary]{format}}\marg{sample}. \cmd{lipsum}*[3] Another +\cs{gls}\marg{duck}. +\strut +\cs{gls}\marg{pi}. \cmd{lipsum}[4] +\strut +A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and +\cs{gls}\oarg{\glsopt[primary]{format}}\marg{pi}. +\strut +\cmd{lipsum}*[6] A \cs{gls}\oarg{\glsopt[primary]{format}}\marg{duck}. +\strut +\cs{printunsrtglossaries} +\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 difference between 1 (the equation reference) and 1 (the page reference) in the location list for the \code{pi} entry. @@ -8999,51 +10629,52 @@ document. (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: -\begin{verbatim} -@entry{sample, - name={sample}, - description="an example entry" -} - -@abbreviation{html, - short="html", - long={hypertext markup language} -} -@abbreviation{ssi, - short="ssi", - long="server-side includes" -} - -@index{goose,plural="geese"} -\end{verbatim} +\begin{codeenv} +\atentry{entry}\marg{sample, + \field{name}=\marg{sample}, + \field{description}=\qtdelim{an example entry} +} +\strut +\atentry{abbreviation}\marg{html, + \field{short}=\qtdelim{html}, + \field{long}=\marg{hypertext markup language} +} +\strut +\atentry{abbreviation}\marg{ssi, + \field{short}=\qtdelim{ssi}, + \field{long}=\qtdelim{server-side includes} +} +\strut +\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}} +\end{codeenv} Now suppose the supplementary document is contained in the file \filefmt{suppl.tex}: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record,counter=section]{glossaries-extra} - -\GlsXtrLoadResources[src=entries] - -\renewcommand{\thesection}{S\arabic{section}} -\renewcommand{\theHsection}{\thepart.\thesection} - -\begin{document} -\part{Sample Part} -\section{Sample Section} -\gls{goose}. \gls{sample}. - -\part{Another Part} -\section{Another Section} -\gls{html}. -\gls{ssi}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt[section]{counter}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\cmd{renewcommand}\marg{\cmd{thesection}}\marg{S\cmd{arabic}\marg{section}} +\cmd{renewcommand}\marg{\cmd{theHsection}}\marg{\cmd{thepart}.\cmd{thesection}} +\strut +\cmd{begin}\marg{document} +\cmd{part}\marg{Sample Part} +\cmd{section}\marg{Sample Section} +\cs{gls}\marg{goose}. \cs{gls}\marg{sample}. +\strut +\cmd{part}\marg{Another Part} +\cmd{section}\marg{Another Section} +\cs{gls}\marg{html}. +\cs{gls}\marg{ssi}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} This uses the \counter{section} counter for the locations and has a -prefix (\verb|\thepart.|) for the section hyperlinks. +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 @@ -9051,7 +10682,7 @@ location (S1) from the supplementary document. 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} -and \glsaddopt[glsxtrsupphypernumber]{format}. +and \glsaddopt[\encap{glsxtrsupphypernumber}]{format}. This can be simplified with \bibgls\ by using the \optfmt{supplemental-locations} option, described below. @@ -9069,7 +10700,7 @@ location encapsulator as appropriate. If \bibgls\ detects an older version of \sty{glossaries-extra}, it will only allow one external supplemental source, and will set the \catattr{externallocation} attribute and use -the \optfmt{glsxtrsupphypernumber} format. Otherwise \bibgls\ +the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\ will allow multiple sources and use the newer method. \optsection{supplemental-locations} @@ -9083,27 +10714,26 @@ detected, \bibgls\ will issue a warning and only accept the first element of the list. For example: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[ - supplemental-locations=suppl,% fetch records from suppl.aux - src=entries] - -\begin{document} -\Gls{sample} document. - -\printunsrtglossaries - -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations},\comment{fetch records from suppl.aux} + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\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). -With \sty{glossaries-extra} v1.36+, the location from the +With \sty{glossaries-extra} v1.36+, a regular location from the supplementary document will be encapsulated with: \nosecdef{glsxtrdisplaysupploc} By default, this simply creates an external hyperlink to the @@ -9111,30 +10741,30 @@ supplementary document with the 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 -this case. The actual formatting is done via +this case. The actual formatting is done via: \nosecdef{glsxtrmultisupplocation} which ignores the \meta{format} argument by default. Its definition is simply: -\begin{verbatim} -\newcommand*{\glsxtrmultisupplocation}[3]{% - {% scope required to localise changes - \def\glsxtrsupplocationurl{#2}% - \glshypernumber{#1}% - }% +\begin{codeenv} +\cmd{newcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} + \marg{\comment{scope required to localise changes} + \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} + \cs{glshypernumber}\marg{\idx{param}1}\comment{} + }\comment{} } -\end{verbatim} -which locally sets the command checked by \ics{glshypernumber} -to establish an external rather than internal link. You can -redefine this command to retain the original formatting -command used in the target document: -\begin{verbatim} -\renewcommand*{\glsxtrmultisupplocation}[3]{% - {% scope required to localise changes - \def\glsxtrsupplocationurl{#2}% - \csuse{#3}{#1}% - }% +\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 +\idx{encap} used in the target document: +\begin{codeenv} +\cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{} + \marg{\comment{scope required to localise changes} + \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{} + \ics{csuse}\marg{\idx{param}3}\marg{\idx{param}1}\comment{} + }\comment{} } -\end{verbatim} +\end{codeenv} but remember that if a hyperlink is required, the identified control sequence name must correspond to a command that uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you @@ -9142,17 +10772,41 @@ will lose the hyperlink. With older versions of \sty{glossaries-extra}, the original location format from the supplementary document -will be replaced by \optfmt{glsxtrsupphypernumber}, which +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 \csopt{supplemental-category}) to identify the external document. 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. -(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.) +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 +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 +\longarg{merge-nameref-on}) are still identified with +\gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now +be set. + +As from \bibgls\ v1.7, any awkward characters in the file path are +replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII} characters when +\sty{fontspec} is loaded) \gls{bibglshrefunicode}. Both commands +take two arguments: the hexadecimal character code and the actual +character. In the case of \gls{bibglshrefchar}, the second +argument is ignored, and the first is preceded by a literal percent +character, so \filefmt{file name.pdf} will be converted to: +\begin{codeenv} +file\gls{bibglshrefchar}\marg{20}\marg{ }name.pdf +\end{codeenv} +which will expand to \verb|file%20name.pdf|. +In the case of \gls{bibglshrefunicode}, the first argument is +ignored, so \filefmt{skr\'aarnafn.pdf} will be converted to: +\begin{codeenv} +skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf +\end{codeenv} +which will expand to \code{skr\'aarnafn.pdf}. + The supplementary locations lists are encapsulated within \gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+, @@ -9161,24 +10815,25 @@ this command will encapsulate the sub-lists with 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 -\begin{verbatim} -\bibglssupplemental{1}{\setentrycounter[I]{section}\glsxtrsupphypernumber{S1}} -\end{verbatim} +of one location) to: +\begin{codeenv} +\gls{bibglssupplemental} +\marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}} +\end{codeenv} and the external target must be supplied through the \catattr{externallocation} attribute, which can be set with the \csopt{supplemental-category} option. -Whereas with at least version 1.36, the list will be -\begin{verbatim} -\bibglssupplemental{1}{\bibglssupplementalsublist{1}{suppl.pdf} -{\glsxtrdisplaysupploc{I}{section}{glsnumberformat}{suppl.pdf}{S1}}} -\end{verbatim} +Whereas with at least version 1.36, the list will be: +\begin{codeenv} +\gls{bibglssupplemental}\marg{1}\marg{\gls{bibglssupplementalsublist}\marg{1}\marg{suppl.pdf} +\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 -will be separated by \csref{bibglssupplementalsep}. The sub-lists -(when supported) are separated by \csref{bibglssupplementalsubsep}. +will be separated by \gls!{bibglssupplementalsep}. The sub-lists +(when supported) are separated by \gls{bibglssupplementalsubsep}. \optsection{supplemental-selection} @@ -9210,24 +10865,23 @@ by the current resource set (through the \ext{bib} files listed in account when including supplementary locations. For example: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[ - supplemental-locations=suppl, - supplemental-selection={html,ssi}, - src=entries] - -\begin{document} -\Gls{sample} document. - -\printunsrtglossaries - -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations}, + \csopt[html,ssi]{supplemental-selection}, + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\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 @@ -9240,65 +10894,56 @@ 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 identifier (as per \csopt{category}) or the category label. For example: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[ - supplemental-locations=suppl, - supplemental-selection={html,ssi}, - supplemental-category={supplemental}, - src=entries] - -\begin{document} -\Gls{sample} document. - -\printunsrtglossaries - -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[suppl]{supplemental-locations}, + \csopt[html,ssi]{supplemental-selection}, + \csopt[supplemental]{supplemental-category}, + \csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{Gls}\marg{sample} document. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} \section{Sorting} \label{sec:sortingopts} -Entries are typically sorted (for example, alphabetically -or in order of use), but the \styfmt{glossaries-extra} package -is versatile enough to be used in wider contexts than simple -terms, symbols or abbreviations. For example, entries could -contain theorems or problems where the \field{name} supplies -the title and the \field{description} provides a description -of the theorem or problem. Another field might then 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. - -\optsection{sort} - -The \csopt{sort} key indicates how entries should be sorted. -If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the -\csopt{sort} option isn't used then \csopt[locale]{sort} is assumed. -The reverse sort methods reverse the algorithm used by the -comparators. This means that -\optfmt{\meta{method}\dhyphen reverse} -may not produce a list that's the exact reverse of the -underlying non-reversed \meta{method}. The reverse sorts maintain -hierarchy, so sub-entries will still be listed after the parent -entry. +Entries are typically displayed in an ordered list, but the +\styfmt{glossaries-extra} package is versatile enough to be used in +wider contexts than simple terms, symbols or abbreviations. For +example, entries could contain theorems or problems where the +\field{name} supplies the title and the \field{description} provides +a description of the theorem or problem. Another field might then +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). Remember that you can have \atentry{preamble} definitions that can be hidden from \bibgls's interpreter. For example, \exfile{no-interpret-preamble.bib} might contain: -\begin{verbatim} -@preamble{"\providecommand{\sortop}[2]{#1 #2}"} -\end{verbatim} -which is loaded using -\begin{verbatim} -\GlsXtrLoadResources[src={no-interpret-preamble}, - interpret-preamble=false] -\end{verbatim} -This provides a custom command +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}1 \idx{param}2}}} +\end{codeenv} +which is loaded using: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[no-interpret-preamble]{src}, + \csopt[false]{interpret-preamble}} +\end{codeenv} +This provides a custom command: \nosecdef{sortop} for internal use in the document. (Remember it won't be defined on the first \LaTeX\ run before the \iext{glstex} file has been @@ -9306,28 +10951,62 @@ created and so is only used within entry fields.) Another file, say, \filefmt{interpret-preamble.bib} may provide a definition for \bibgls: -\begin{verbatim} -@preamble{"\providecommand{\sortop}[2]{#2, #1}"} -\end{verbatim} -which can be identified with: -\begin{verbatim} -\GlsXtrLoadResources[src={interpret-preamble}] -\end{verbatim} -This definition swaps the two arguments around for the sorting, but -doesn't affect the document since \LaTeX\ has already defined -\csfmt{sortop} from the first resource set. - -For example: -\begin{verbatim} -@entry{caesar, - name={\sortop{Gaius Julius}{Caesar}}, - first={Julius Caesar}, - text={Caesar}, - description={Roman politician and general} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}2, \idx{param}1}}} +\end{codeenv} +which can be processed with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble]{src}} +\end{codeenv} +to provide \bibgls\ with this definition. +The \filefmt{entries.bib} file could contain: +\begin{codeenv} +\atentry{entry}\marg{caesar, + \field{name}=\marg{\gls{sortop}\marg{Gaius Julius}\marg{Caesar}}, + \field{first}=\marg{Julius Caesar}, + \field{text}=\marg{Caesar}, + \field{description}=\marg{Roman politician and general} } -\end{verbatim} -If \bibgls\ only recognises the second definition of \csfmt{sortop} then -the sort value becomes \code{Caesar, Gaius Julius}. +\end{codeenv} +and then be processed with: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} + +The definition provided in \filefmt{interpret-preamble.bib}, which +swaps the two arguments around, is now picked up by \bibgls, so the +sort value becomes \code{Caesar, Gaius Julius}, but this new +definition doesn't affect the document since \LaTeX\ has already +defined \gls{sortop} from the first resource set, so the name will +appear as \qt{Gaius Julius Caesar} in the glossary. (If you have +\cs{renewcommand} rather than \cs{providecommand}, you can prevent +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}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}} +\end{codeenv} +Another possibility is to provide a custom package that contains the +command definitions for the \bibgls\ interpreter and load it with +\longarg{custom-packages} instead of having the +\filefmt{interpret-preamble.bib} file. + +\optsection{sort} + +The \csopt{sort} key indicates how primary entries 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}, +otherwise \csopt[locale]{sort} is assumed. + +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 +can affect the order. \begin{table}[p] \caption{Summary of Available Sort Options: No Actual Sorting} @@ -9336,7 +11015,8 @@ the sort value becomes \code{Caesar, Gaius Julius}. \begin{tabular}{ll} \optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline \optfmt{random} & shuffle entries\tabularnewline -\optfmt{use} & order of use +\optfmt{use} & order of use\tabularnewline +\optfmt{use-reverse} & reverse order of use \end{tabular} \end{table} @@ -9362,7 +11042,7 @@ rule}]{sort-rule}\tabularnewline \end{table} \begin{table}[p] -\caption{Summary of Available Sort Options: Letter (Unicode Order)} +\caption{Summary of Available Sort Options: Letter (Non-Locale)} \label{tab:sortoptionsletter} \centering \begin{tabular}{ll} @@ -9474,6 +11154,14 @@ by the records 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. +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. + +\item \optfmt{use-reverse}: reverses the order that would be +obtained with \csopt[use]{sort} without reference to hierarchy. + \end{itemize} \subsubsection{Alphabet} @@ -9482,38 +11170,8 @@ The sort methods listed in \tableref{tab:sortoptionsrule} are for alphabets that are defined by a rule. These usually ignore most punctuation and may ignore modifiers (such as accents). Use with \csopt{break-at} to determine whether or not to split at word -boundaries. - -Note that \csopt[locale]{sort} can provide more detail about the -locale than \csopt[doc]{sort}, depending on how the document -language has been specified. For example, with: -\begin{verbatim} -\documentclass{article} -\usepackage[ngerman]{babel} -\usepackage[record]{glossaries} -\GlsXtrLoadResources[src={german-terms}] -\end{verbatim} -the language tag will be \code{de-1996}, which doesn't have an -associated region. Whereas with -\begin{verbatim} -\documentclass[de-DE-1996]{article} -\usepackage[ngerman]{babel} -\usepackage[record]{glossaries} -\GlsXtrLoadResources[src={german-terms}] -\end{verbatim} -the language tag will be \code{de-DE-1996} because \isty{tracklang} -has picked up the locale from the document class options. This is -only likely to cause a difference if a language has different -sorting rules according to the region or if the language may be -written in multiple scripts. - -A multilingual document will need to have the \csopt{sort} specified -when loading the resource to ensure the correct language is chosen. -For example: -\begin{verbatim} -\GlsXtrLoadResources[src={english-terms},sort={en-GB}] -\GlsXtrLoadResources[src={german-terms},sort={de-DE-1996}] -\end{verbatim} +boundaries. The collation rules (except for the custom options) are obtained +from the \idx{localeprovider} (see page~\pageref{locale.provider}). \begin{itemize} \item \meta{lang tag}: sort according to the rules of the locale @@ -9549,12 +11207,58 @@ rule provided by \csopt{sort-rule}. rule provided by \csopt{sort-rule}. \end{itemize} -\subsubsection{Letter Case (Unicode Order)} +Note that \csopt[\meta{locale}]{sort} can provide more detail about the +given locale than \csopt[doc]{sort}, depending on how the document +language has been specified. For example, with: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{ngerman}\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be \code{de-1996}, which doesn't have an +associated region, so this is equivalent to using \csopt[de-1996]{sort}. +Whereas with: +\begin{codeenv} +\cmd{documentclass}\oarg{de-DE-1996}\marg{article} +\cmd{usepackage}\oarg{ngerman}\marg{babel} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be \code{de-DE-1996} because \isty{tracklang} +has picked up the locale from the document class options, so this is +equivalent to using \csopt[de-DE-1996]{sort}. This is +only likely to cause a difference if a language has different +sorting rules according to the region or if the language may be +written in multiple scripts. + +If no language package is loaded then the default is \csopt[locale]{sort} +rather than \csopt[doc]{sort}. For example, with: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}} +\end{codeenv} +the language tag will be whatever is the default locale for the \idx{JVM}. +For a user in Germany, this could be \code{de-DE-1996} and for a user +in Austria this could be \code{de-AT-1996}. + +A multilingual document will need to have the \csopt{sort} specified +when loading the \idx{resourceset} to ensure the correct language is chosen. +For example: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[english-terms]{src},\csopt[en-GB]{sort}} +\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}} +\end{codeenv} + +\subsubsection{Letter (Non Locale)} The sort methods listed in \tableref{tab:sortoptionsletter} -use letter case comparators. These simply compare the +use letter comparators. These simply compare the character codes. The \optfmt{-nocase} options first convert the -\field{sort} field to \idx{lowercase} before performing the sort. +\field{sort} field to \idx{lowercase} before performing the sort to +provide a case-insensitive comparison. + Punctuation isn't ignored. Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to emulate \idx!{xindy}['s] locale letter ordering. The examples below @@ -9565,15 +11269,22 @@ show the ordering of the list \code{antelope}, \code{bee}, \code{Africa}, \Idx{uppercase} and \idx{lowercase} are in separate letter groups. Example: -\code{Africa} (letter group \qt{A}), \code{Brazil} -(letter group \qt{B}), \code{aardvark} (letter group \qt{a}), -\code{antelope} (letter group \qt{a}), \code{bee} (letter group \qt{b}). +\code{Africa} (letter group \idx{uppercase} \qt{A}), \code{Brazil} +(letter group \idx{uppercase} \qt{B}), \code{aardvark} (letter group +\idx{lowercase} \qt{a}), \code{antelope} (letter group +\idx{lowercase} \qt{a}), \code{bee} (letter group \idx{lowercase} \qt{b}). \item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort. +Example: + +\code{bee} (letter group \idx{lowercase} \qt{b}), \code{antelope} +(letter group \idx{lowercase} \qt{a}), \code{aardvark} (letter group +\idx{lowercase} \qt{a}) \code{Brazil} (letter group \idx{uppercase} +\qt{B}), \code{Africa} (letter group \idx{uppercase} \qt{A}). \item \optfmt{letter-nocase}: case-insensitive letter sort. (All \idx{uppercase} characters will have first been converted to -\idx{lowercase}.) +\idx{lowercase} in the sort value.) Example: \code{aardvark} (letter group \qt{A}), \code{Africa} @@ -9582,6 +11293,11 @@ Example: \code{Brazil} (letter group \qt{B}). \item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort. +Example: + +\code{Brazil} (letter group \qt{B}), \code{bee} (letter group +\qt{B}), \code{antelope} (letter group \qt{A}), \code{Africa} +(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). \item \optfmt{letter-upperlower}: each character pair is first compared according to their \idx{lowercase} values. If these are equal, @@ -9594,6 +11310,12 @@ Example: (letter group \qt{B}), \code{bee} (letter group \qt{B}). \item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort. +This now puts the \idx{lowercase} letters first within the letter group. +Example: + +\code{bee} (letter group \qt{B}), \code{Brazil} (letter group +\qt{B}), \code{antelope} (letter group \qt{A}), \code{aardvark} +(letter group \qt{A}), \code{Africa} (letter group \qt{A}). \item \optfmt{letter-lowerupper}: each character pair is first compared according to their \idx{lowercase} values. If these are equal, @@ -9602,13 +11324,21 @@ then they are compared according to case. This puts Example: \code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}), - \code{Africa} (letter group \qt{A}), \code{bee} (letter group +\code{Africa} (letter group \qt{A}), \code{bee} (letter group \qt{B}), \code{Brazil} (letter group \qt{B}). \item \optfmt{letter-lowerupper-reverse}: reverse lower-upper letter sort. +This now puts the \idx{uppercase} letters first within the letter group. +Example: + +\code{Brazil} (letter group \qt{B}), \code{bee} (letter group +\qt{B}), \code{Africa} (letter group \qt{A}), \code{antelope} +(letter group \qt{A}), \code{aardvark} (letter group \qt{A}). + \end{itemize} \subsubsection{Letter-Number} +\label{sec:letternumber} The sort methods listed in \tableref{tab:sortoptionsletternumber} use a letter-integer hybrid. They behave in a similar way to the @@ -9727,18 +11457,25 @@ following: category. If both characters are white space, then they are compared according to their Unicode values otherwise they are ordered according to the \csopt{letter-number-punc-rule} setting. + \item letter: belongs to one of the Unicode categories \idx{letteruppercase}, \idx{letterlowercase}, \idx{lettertitlecase}, \idx{lettermodifier} or \idx{letterother}. If both characters -are letters, then they are compared in the same way as the +are letters then, for sort method \optfmt{letternumber-\meta{modifier}}, +the characters are compared in the same way as the corresponding \optfmt{letter-\meta{modifier}} sort method otherwise they are ordered according to the \csopt{letter-number-punc-rule} setting. + \item punctuation: everything else. If both characters are punctuation, then they are compared according to their Unicode value otherwise they are ordered according to the \csopt{letter-number-punc-rule} setting. \end{itemize} +For simplicity, the actual sort value used during sorting isn't a +simple string but is converted into a list of objects that represent +one of: letter, integer, space or other (punctuation). This reduces +the amount of parsing of substrings that needs to be performed. The examples below show the ordering of the list: \code{CH\textsubscript{2}O}, @@ -9746,6 +11483,7 @@ The examples below show the ordering of the list: \code{C\textsubscript{5}H\textsubscript{4}NCOOH}, \code{CO}, \code{Cl}, \code{Co}, \code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, \code{CO\textsubscript{2}}, \code{CoMoO\textsubscript{4}} and \code{CoCl\textsubscript{2}}, for the setting \csopt[between]{letter-number-rule}, where the subscripts are @@ -9757,16 +11495,32 @@ letter-number sort. Example: \code{CH\textsubscript{2}O}, \code{CO}, +\code{CO\textsubscript{2}}, \code{C\textsubscript{5}H\textsubscript{4}NCOOH}, \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{Cl}, \code{Co}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}, +\code{Co\textsubscript{2}}, \code{Co\textsubscript{2}O\textsubscript{3}}. +(Order determined by: $\mathtt{H} < \mathtt{O} < 5 < 10 < \mathtt{l} < \mathtt{o}$.) + \item \optfmt{letternumber-case-reverse}: reverse case-sensitive -letter-number sort. +letter-number sort. Example: + +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co}, +\code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CO\textsubscript{2}}, +\code{CO}, +\code{CH\textsubscript{2}O}. \item \optfmt{letternumber-nocase}: case-insensitive letter-number sort. The sort value is first converted to lower @@ -9778,36 +11532,56 @@ the sort value, so numbers will always come before letters. Example: \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{CH\textsubscript{2}O}, \code{Cl}, -\code{Co}, \code{CO}, +\code{Co}, +\code{CO\textsubscript{2}}, +\code{Co\textsubscript{2}}, \code{Co\textsubscript{2}O\textsubscript{3}}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}. +(Order determined by: $5 < 10 < \mathtt{h} < \mathtt{l} < \mathtt{o}$.) + \item \optfmt{letternumber-nocase-reverse}: reverse case-insensitive -letter-number sort. +letter-number sort, so numbers will now always come after letters. Example: + +\code{CoMoO\textsubscript{4}}, +\code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, +\code{CO\textsubscript{2}}, +\code{Co}, +\code{CO}, +\code{Cl}, +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}. \item \optfmt{letternumber-upperlower}: upper-lower letter-number sort. This behaves slightly differently to \optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule} -as it will segregate the \idxlink{uppercase}{upper} and -\idx{lowercase} characters if there -are any numerical sub-strings. Example: +and has a more complicated rule that's determined by the character +following the number and implied numbers inserted between letters. +(There was a bug in earlier versions that has been corrected in v1.8 +so you may find a slightly different ordering when upgrading.) +Example: \code{CH\textsubscript{2}O}, -\code{CO}, \code{C\textsubscript{5}H\textsubscript{4}NCOOH}, \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{Cl}, +\code{CO}, +\code{CO\textsubscript{2}}, \code{Co}, +\code{Co\textsubscript{2}}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}, \code{Co\textsubscript{2}O\textsubscript{3}}. -The \csopt[between]{letter-number-rule} setting enforces numbers -after \idx{uppercase} (for the case-sensitive and upper-lower methods) -which makes the \code{\textsubscript{5}} come after the \idx{uppercase} -\code{O} and forces the \idx{lowercase} characters to come after it. +(Order determined by: $\mathtt{H} < 5\mathtt{H} < 10\mathtt{H} < +\mathtt{l} < \mathtt{O} < \mathtt{o}$, and for the terms starting +with \code{CO} or \code{Co}: 2 comes after null and $\mathtt{C} < +\mathtt{M} < 2\mathtt{O}$.) Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9817,78 +11591,64 @@ results in the order: \code{CH\textsubscript{2}O}, \code{Cl}, \code{CO}, +\code{CO\textsubscript{2}}, \code{Co}, +\code{Co\textsubscript{2}}, \code{Co\textsubscript{2}O\textsubscript{3}}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}. - \item \optfmt{letternumber-upperlower-reverse}: reverse upper-lower -letter-number sort. Note that with -\csopt[between]{letter-number-rule}, this can result in an order -that isn't the actual reverse of \optfmt{letternumber-upperlower}. -Example: +letter-number sort. Example (with \csopt[between]{letter-number-rule}): \code{Co\textsubscript{2}O\textsubscript{3}}, \code{CoMoO\textsubscript{4}}, \code{CoCl\textsubscript{2}}, +\code{Co\textsubscript{2}}, \code{Co}, -\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, -\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CO\textsubscript{2}}, \code{CO}, \code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, \code{CH\textsubscript{2}O}. -The algorithm is reversed which means that when two letters are -compared then, if both letters have the same \idx{lowercase} version, -the upper-lower rule is reversed and \idx{lowercase} comes before -\idx{uppercase}. This means that \code{o} comes before \code{O}. -If their \idx{lowercase} versions aren't identical, the letter -with the higher \idx{lowercase} Unicode value comes first. This means -that both \code{o} and \code{O} come before \code{l} which comes -before \code{H}. So far, this gives the order: -\code{o}, \code{O}, \code{l}, \code{H}. -The \csopt[between]{letter-number-rule} setting inserts numbers between -\idxlink{uppercase}{upper} and \idx{lowercase} letters. This puts the numbers (in reverse -order) between \code{o} and \code{O}. - Compare this with \csopt[before letter]{letter-number-rule} which results in the order: \code{CoMoO\textsubscript{4}}, \code{CoCl\textsubscript{2}}, \code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, \code{Co}, +\code{CO\textsubscript{2}}, \code{CO}, \code{Cl}, \code{CH\textsubscript{2}O}, \code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{C\textsubscript{5}H\textsubscript{4}NCOOH}. -Remember that the associated settings as reversed -well. So \csopt[before letter]{letter-number-rule} is +Remember that the associated settings are reversed +well. So \csopt[before letter]{letter-number-rule} results in numbers \emph{after} letters. -\item \optfmt{letternumber-lowerupper}: lower-upper -letter-number sort. As with the upper-lower version, this behaves -slightly differently to the corresponding -\optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule}. +\item \optfmt{letternumber-lowerupper}: lower-upper letter-number +sort. As with the upper-lower option, this behaves slightly differently to +\optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule} +and has a more complicated rule. Example: +\code{CH\textsubscript{2}O}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, \code{Cl}, \code{Co}, -\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}, -\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, -\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, -\code{CH\textsubscript{2}O}, -\code{CO}. - -The \csopt[between]{letter-number-rule} setting enforces numbers -after \idx{lowercase} (for the lower-upper method) -so the \code{\textsubscript{5}} is put after \code{o}, and forces -the \idx{uppercase} characters after the numbers. +\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{CO}, +\code{CO\textsubscript{2}}. Compare this with \csopt[before letter]{letter-number-rule} which results in the order: @@ -9898,30 +11658,32 @@ results in the order: \code{CH\textsubscript{2}O}, \code{Cl}, \code{Co}, +\code{Co\textsubscript{2}}, \code{Co\textsubscript{2}O\textsubscript{3}}, \code{CoCl\textsubscript{2}}, \code{CoMoO\textsubscript{4}}, -\code{CO}. +\code{CO}, +\code{CO\textsubscript{2}}. \item \optfmt{letternumber-lowerupper-reverse}: reverse lower-upper -letter-number sort. Again with -\csopt[between]{letter-number-rule}, this can result in an order -that isn't the actual reverse of \optfmt{letternumber-lowerupper}, -although for this example it does happen to be the actual reverse: +letter-number sort. Example (with \csopt[between]{letter-number-rule}): +\code{CO\textsubscript{2}}, \code{CO}, -\code{CH\textsubscript{2}O}, -\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, -\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{Co\textsubscript{2}O\textsubscript{3}}, \code{CoMoO\textsubscript{4}}, \code{CoCl\textsubscript{2}}, -\code{Co\textsubscript{2}O\textsubscript{3}}, +\code{Co\textsubscript{2}}, \code{Co}, -\code{Cl}. +\code{Cl}, +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}}, +\code{C\textsubscript{5}H\textsubscript{4}NCOOH}, +\code{CH\textsubscript{2}O}. \end{itemize} \subsubsection{Numerical} +\label{sec:numerical} The sort methods listed in \tableref{tab:sortoptionsnumerical} use numeric comparisons. The sort value is expected to @@ -9930,7 +11692,9 @@ be a numeric value. If it can't be parsed then it's treated as 0 These all recognise the digits in the Unicode \qt{Number, Decimal Digit} category but, unlike the hybrid letter-number comparators above, they don't recognise the superscript or subscript -digits. +digits. The \qt{non-locale} in some of the descriptions below +indicates that the method doesn't recognise locale-sensitive +formatting, such as group separators. \begin{itemize} \item \optfmt{integer}: integer sort. This is for non-locale integer sort values. @@ -10054,24 +11818,24 @@ 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. -For example, suppose my \ext{bib} file contains -\begin{verbatim} -@entry{journalentry, - name={10 Jan 2017}, - description={an interesting journal entry} +For example, suppose my \ext{bib} file contains: +\begin{codeenv} +\atentry{entry}\marg{journalentry, + \field{name}=\marg{10 Jan 2017}, + \field{description}=\marg{an interesting journal entry} } -\end{verbatim} +\end{codeenv} The \field{name} field uses an abbreviated UK date format. If all my other entries also use this format in the \field{name} then I can sort them chronologically: -\begin{verbatim} -\GlsXtrLoadResources[ - src=entries,% data in entries.bib - sort=date, - date-sort-locale={en-GB}, - date-sort-format={medium} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[date]{sort}, + \csopt[en-GB]{date-sort-locale}, + \csopt[medium]{date-sort-format} +} +\end{codeenv} (The medium format is actually the default for this locale, and the locale matches my system locale, so I could omit both \csopt{date-sort-locale} and \csopt{date-sort-format}.) @@ -10111,47 +11875,56 @@ be an integer used as a seed for the random number generator. \optsection{sort-field} The \csopt{sort-field} key indicates which field provides the sort -value. The default is the \field{sort} field. For example +value. The \meta{field} must be a recognised field name or you +may use \csopt[id]{sort-field} to sort according to the label. +The default value is the \field{sort} field (which is typically +inferred rather than explicitly set). + +Example: \begin{codeenv} -\gls!{GlsXtrLoadResources}\oarg{ - \csopt[entries-terms]{src},\idx!{commentchar} data in entries-terms.bib - \csopt[category]{sort-field},\idx!{commentchar} sort by 'category' field - \csopt[letter-case]{sort}\idx!{commentchar} case-sensitive letter sort +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-terms]{src},\comment{data in entries-terms.bib} + \csopt[category]{sort-field},\comment{sort by 'category' field} + \csopt[letter-case]{sort}\comment{case-sensitive letter sort} } \end{codeenv} This sorts the entries according to the \field{category} field using a case-sensitive letter comparison. -You may also use \csopt[id]{sort-field} to sort according to -the label. If an entry is missing a value for \meta{field}, then the value of the fallback field will be used instead. If \csopt{missing-sort-fallback} is set, then that's used as the fallback, otherwise it depends on the entry type. +If no fallback field can be found, the entry's label will be used. -For example, with the default \csopt[sort]{sort-field}, then for an -entry defined with \atentry{entry}, if the \field{sort} field is -missing the fallback field will be the \field{name} (or the -\field{parent} field if the \field{name} field is missing). - -If the entry is instead defined with an abbreviation type (for -example, \atentry{abbreviation} or -\atentry{acronym}) then if the \field{sort} field is missing, -\bibgls\ will fallback on the field given by -\csopt{abbreviation-sort-fallback}. This is only used with -\csopt[sort]{sort-field}. - -The symbol-like entry types fallback on the field given by -\csopt{symbol-sort-fallback} if the \field{sort} is missing. This -is only used with \csopt[sort]{sort-field}. +For the specific case with the default \csopt[sort]{sort-field} +setting, the fallback for the \field{sort} field is governed not +only by the entry type but also by some associated settings: -Entries defined using \atentry{bibtexentry} fallback on the field +\begin{itemize} +\item For entries types like \atentry{entry} or \atentry{index}, +then if the \field{sort} field is missing the value is obtained from +the \field{name} field. If that field is also missing, then the +value is obtained from the particular entry type's fallback for the +\field{name} field. (For example, \field{parent} for +\atentry{entry}.) + +\item If the entry is defined with an abbreviation type (for +example, \atentry{abbreviation} or \atentry{acronym}) then if the +\field{sort} field is missing, \bibgls\ will fallback on the field +given by \csopt{abbreviation-sort-fallback}. + +\item The symbol-like entry types fallback on the field given by +\csopt{symbol-sort-fallback} if the \field{sort} field is missing. + +\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 \atentry{index}. -If no fallback field can be found, the entry's label will be used. +\end{itemize} +Use \csopt{dual-sort-field} when sorting dual entries. \optsection{missing-sort-fallback} @@ -10244,11 +12017,11 @@ This option may be used to perform regular expression substitutions on the sort value and has the same syntax as \csopt{labelify-replace}. This action is done after the interpreter parses the sort value (if applicable) and before \csopt{sort-number-pad} (if -applicable). For example, suppose the sort value is -\begin{verbatim} -\ensuremath{\approx 3.14} -\end{verbatim} -then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but +applicable). For example, suppose the sort value is: +\begin{codeenv} +\cs{ensuremath}\marg{\ics{approx} 3.14} +\end{codeenv} +then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but: \begin{codeenv} \csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace} \end{codeenv} @@ -10284,51 +12057,51 @@ to produce a literal backslash (\idx{backslashchar}) and tilde You can also use \stringu\meta{hex} (where \meta{hex} is a hexadecimal code) to represent a Unicode character. For example: -\begin{verbatim} -\GlsXtrLoadResources[ - sort={custom}, - sort-rule={< a,A < b,B < c,C < ch,Ch,CH < d,D +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[custom]{sort}, + \csopt[< a,A < b,B < c,C < ch,Ch,CH < d,D < dd,Dd,DD < e,E < f,F < ff,Ff,FF < g,G < ng,Ng,NG < h,H < ij,Ij,IJ < i,I < j,J < k,K < l,L < ll,Ll,LL < m,M < n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH < s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z - < \string\u00E6,\string\u00C6} -] -\end{verbatim} + < \stringu00E6,\stringu00C6]{sort-rule} +} +\end{codeenv} It's best to use \ics{cs.string} rather than \ics{protect} to avoid unwanted spaces interfering with \meta{hex}. Note that \sty{glossaries-extra} v1.21+ provides\footnote{The command definition was moved to \isty{glossaries-extra-bib2gls} from version 1.27 since it's only needed with \bibgls.}\ \ics{glshex} which just does \stringu\ so you can do -\verb|\glshex 00E6| instead of \verb|\string\u00E6|. +\code{\ics{glshex} 00E6} instead of \code{\stringu00E6}. This is only one character different, but you can redefine \ics{glsxtrresourceinit} to locally set \ics{u} to \ics{glshex} while the protected write is performed. For example: -\begin{verbatim} -\renewcommand*{\glsxtrresourceinit}{\let\u\glshex} -\end{verbatim} -Then you can just do \verb|\u00E6| instead of \verb|\string\u00E6|. +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}} +\end{codeenv} +Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}. The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by the \styopt{record} option) provides some commands for common rule blocks that may be used in the construction of custom rules. For example: -\begin{verbatim} -sort-rule={\glsxtrcontrolrules - ;\glsxtrspacerules - ;\glsxtrnonprintablerules - ;\glsxtrcombiningdiacriticrules - ,\glsxtrhyphenrules - <\glsxtrgeneralpuncrules - <\glsxtrdigitrules - <\glsxtrfractionrules - <\glsxtrMathItalicGreekIrules - <\glsxtrGeneralLatinIVrules - <\glsxtrLatinAA - <\glsxtrLatinOslash -} -\end{verbatim} +\begin{codeenv} +\csopt[\ics{glsxtrcontrolrules} + ;\ics{glsxtrspacerules} + ;\ics{glsxtrnonprintablerules} + ;\ics{glsxtrcombiningdiacriticrules} + ,\ics{glsxtrhyphenrules} + <\ics{glsxtrgeneralpuncrules} + <\ics{glsxtrdigitrules} + <\ics{glsxtrfractionrules} + <\ics{glsxtrMathItalicGreekIrules} + <\ics{glsxtrGeneralLatinIVrules} + <\ics{glsxtrLatinAA} + <\ics{glsxtrLatinOslash} +]{sort-rule} +\end{codeenv} This places the Greek maths symbols (such as \ics{alpha}) before the Latin block. See the \sty{glossaries-extra} documentation for further details of these commands. @@ -10336,59 +12109,78 @@ further details of these commands. You might find it convenient to provide similar commands in a package for rules you may often need. For example, suppose I have a package called, say, \styfmt{mapsymbols} for providing map symbols: -\begin{verbatim} -\NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{mapsymbols} -% some package or font loading stuff here to provide -% the appropriate symbols -\newcommand{\Stadium}{...} -\newcommand{\Battlefield}{...} -\newcommand{\Harbour}{...} -% etc - -% Provide a rule block: -\newcommand{\MapSymbolOrder}{% - \glshex 2694 % crossed-swords 0x2694 - < \glshex 2693 % anchor 0x2693 - < \glshex 26BD % football 0x26BD +\begin{codeenv} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{mapsymbols} +\comment{some package or font loading stuff here to provide} +\comment{the appropriate symbols} +\cmd{newcommand}\marg{\cmd{Stadium}}\marg{\ldots} +\cmd{newcommand}\marg{\cmd{Battlefield}}\marg{\ldots} +\cmd{newcommand}\marg{\cmd{Harbour}}\marg{\ldots} +\comment{etc} +\strut +\comment{Provide a rule block:} +\cmd{newcommand}\marg{\cmd{MapSymbolOrder}}\marg{\comment{} + \cs{glshex} 2694 \comment{crossed-swords 0x2694} + < \cs{glshex} 2693 \comment{anchor 0x2693} + < \cs{glshex} 26BD \comment{football 0x26BD} } -\end{verbatim} +\end{codeenv} In addition to \filefmt{mapsymbols.sty}, I also need to create -\filefmt{mapssymbols.bib} to provide the appropriate definitions for +\filefmt{mapsymbols.bib} to provide the appropriate definitions for \bibgls: -\begin{verbatim} -@preamble{"\glsxtrprovidecommand{\Harbour}{\char"2693} -\glsxtrprovidecommand{\Battlefield}{\char"2694} -\glsxtrprovidecommand{\Stadium}{\char"26BD}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\icharhex{2693}} +\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}} +\end{codeenv} The use of \ics{glsxtrprovidecommand} will override any previous definitions of these commands in \bibgls's interpreter but will act like \ics{providecommand} within the document, and so won't interfere with the commands defined in \filefmt{mapsymbols.sty}. -Now I can just do -\begin{verbatim} -\usepackage{mapsymbols}% my custom package -\usepackage[record]{glossaries-extra} +Now I can just do: +\begin{codeenv} +\cmd{usepackage}\marg{mapsymbols}\comment{my custom package} +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[mapsymbols,\comment{<--- my custom mapsymbols.bib} + entries\comment{data in entries.bib} + ]{src}, + \csopt[custom]{sort}, + \csopt[\cs{glsxtrcontrolrules} + ;\cs{glsxtrspacerules} + ;\cs{glsxtrnonprintablerules} + ;\cs{glsxtrcombiningdiacriticrules} + ,\cs{glsxtrhyphenrules} + <\cs{glsxtrgeneralpuncrules} + <\cs{glsxtrdigitrules} + <\cs{glsxtrfractionrules} + <\cmd{MapSymbolOrder} \comment{<--- custom map symbols} + <\cs{glsxtrMathItalicGreekIrules} + <\ics{glsxtrGeneralLatinIrules} + ]{sort-rule} +} +\end{codeenv} -\GlsXtrLoadResources[ - src={mapsymbols,% <--- my custom mapsymbols.bib - entries% data in entries.bib - }, - sort={custom}, - sort-rule={\glsxtrcontrolrules % control codes - ;\glsxtrspacerules % space characters - ;\glsxtrnonprintablerules % non-printable characters - ;\glsxtrcombiningdiacriticrules % combining diacritics - ,\glsxtrhyphenrules % hyphens - <\glsxtrgeneralpuncrules % general punctuation - <\glsxtrdigitrules % 0, ..., 9 - <\glsxtrfractionrules % fraction symbols - <\MapSymbolOrder % <--- custom map symbols - <\glsxtrMathItalicGreekIrules % math-greek symbols - <\glsxtrGeneralLatinIrules % Latin letters - } -] -\end{verbatim} +An alternative to providing \filefmt{mapsymbols.bib} is to provide a +custom package just for \bibgls' use. For example, +\filefmt{mapsymbols-bib2gls.sty}: +\begin{codeenv} +\comment{Provided for \bibgls\ only.} +\comment{Use \cmd{usepackage}\marg{mapsymbols} in the document.} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{mapsymbols-bib2gls} +\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}} +\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}} +\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}} +\cmd{endinput} +\end{codeenv} +and instruct \bibgls\ to parse it with +\code{\longarg{custom-packages} mapsymbols-bib2gls} (and use +\filefmt{mapsymbols.sty} in the document). Remember that \bibgls\ +isn't a \TeX\ engine so make sure to only use simple commands in +this file. \optsection{break-at} @@ -10404,7 +12196,7 @@ sort options are naturally in a letter order, similar to \csopt[letter-nocase]{sort}, which just sorts according to the Unicode value not according to a particular alphabet.) -In order to replicate \idx{makeindex} and \idx{xindy}['s] default word +In order to replicate \idx!{makeindex} and \idx!{xindy}['s] default word order, \bibgls\ splits up the sort value at word boundaries and inserts a marker (identified by \csopt{break-marker}). For example, if the sort value is \qt{sea lion} then it's actually @@ -10416,7 +12208,7 @@ after the ignored characters, such as spaces and hyphens. Note that this action removes non-letters, so for example, if the sort value is \verb"# (parameter)" then it will be converted to \verb"parameter|" (hash, space and parentheses removed). -If you only want to break at spaces (optionally following a command) +If you only want to break at spaces (optionally following a comma) use the following instead: \begin{codeenv} \csopt[none]{break-at}, @@ -10453,9 +12245,13 @@ emulate \idx{makeindex} or \idx{xindy}'s letter ordering, or combine with \csopt{sort-replace} to insert custom break points. \end{itemize} -This option is ignored when used with the non-alphabetic \csopt{sort} options. -Use the \longarg{debug} switch to show the break points. -(This will also show the collation rule.) +This option is ignored when used with the non-alphabetic +\csopt{sort} options. You can find the break points in the +\field{sort} field for the entry's definition in the \ext{glstex} +file (which is provided for information rather than for use in the +document). Alternatively, use the \longarg{debug} switch to show +the break points in the transcript. (This will also show the +collation rule.) \optsection{break-marker} @@ -10604,7 +12400,7 @@ 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.) -This message will then be followed by +This message will then be followed by: \begin{alltt} Appending suffix '\meta{suffix}' to the sort value '\meta{sort}' for entry '\meta{id}'. @@ -10617,133 +12413,130 @@ been appended. For example, suppose in my document I want to write about \appfmt{makeglossaries} (the application) and \csfmt{makeglossaries} (the command). I might decide to define semantic commands: -\begin{verbatim} -\newcommand*{\application}[1]{\texttt{#1}} -\newcommand*{\command}[1]{\texttt{\char92 #1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\ics{texttt}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} +\end{codeenv} In my \ext{bib} file I might have: -\begin{verbatim} -@entry{cs.makeglossaries, - name={\command{makeglossaries}}, - category={command}, - description={opens glossary files} +\begin{codeenv} +\atentry{entry}\marg{cs.makeglossaries, + \field{name}=\marg{\cmd{command}\marg{makeglossaries}}, + \field{category}=\marg{command}, + \field{description}=\marg{opens glossary files} } - -@entry{ap.makeglossaries, - name={\application{makeglossaries}}, - category={application}, - description={Perl script} +\strut +\atentry{entry}\marg{ap.makeglossaries, + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{category}=\marg{application}, + \field{description}=\marg{Perl script} } -\end{verbatim} +\end{codeenv} If \bibgls\ is provided with the definitions of \csfmt{application} -and \csfmt{command} (by interpreting the \atentry{preamble}) then it will +and \csfmt{command} (by interpreting the \atentry{preamble} or a +package provided with \longarg{custom-packages}) then it will determine that the sort value for \code{cs.makeglossaries} is -\verb|\makeglossaries| and the sort value for +\csfmt{makeglossaries} and the sort value for \code{ap.makeglossaries} is just \code{makeglossaries}. These are two distinct sort values from \bibgls's point of view although the sort rule may consider them identical if the rule ignores the -\verb|\| character (such as the locale sort methods), in which case, +\idx{escchar} character (such as the locale sort methods), in which case, \bibgls\ will then act according to \csopt{identical-sort-action}. If \bibgls\ isn't provided with these custom definitions, then it -will ignore them and both entries will end up with the sort value -\code{makeglossaries}. The second instance will be recognised as a -duplicate and the sort value will be converted to +will ignore those semantic commands and both entries will end up with +the sort value \code{makeglossaries}. The second instance will be +recognised as a duplicate and the sort value will be converted to \code{makeglossaries1} (where the automated suffix is \code{1} and -the suffix marker, see below, is the empty string). With -\csopt[.]{sort-suffix-marker} then the sort value would become +the suffix marker, see below, is the empty string). Whereas with, +say, \csopt[.]{sort-suffix-marker}\ then the sort value would become \code{makeglossaries.1}. For comparison, consider the following document: -\begin{verbatim} -\documentclass{article} - -\usepackage[style=indexgroup]{glossaries} - -\makeglossaries - -\newcommand*{\application}[1]{\texttt{#1}} -\newcommand*{\command}[1]{\texttt{\char92 #1}} - -\newglossaryentry{cs.makeglossaries}{% - name={\command{makeglossaries}}, - description={opens glossary files}} - -\newglossaryentry{ap.makeglossaries}{% - name={\application{makeglossaries}}, - description={Perl script}} - -\begin{document} - -\gls{cs.makeglossaries} and \gls{ap.makeglossaries}. - -\printglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt[indexgroup]{style}]\marg{glossaries} +\strut +\ics{cs.makeglossaries} +\strut +\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}} +\strut +\gls{newglossaryentry}\marg{cs.makeglossaries}\marg{\comment{} + \field{name}=\marg{\cmd{command}\marg{makeglossaries}}, + \field{description}=\marg{opens glossary files}} +\strut +\gls{newglossaryentry}\marg{ap.makeglossaries}\marg{\comment{} + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{description}=\marg{Perl script}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. +\ics{printglossaries} +\cmd{end}\marg{document} +\end{codeenv} This uses \idx{makeindex}, which puts both entries in the -\qt{Symbols} group (since they both start with \verb|\| from the -start of \verb|\command| and \verb|\application|, respectively). +\qt{Symbols} group (since they both start with \idx{escchar} from the +start of \csfmt{command} and \csfmt{application}, respectively). The ordering is \appfmt{makeglossaries}, \csfmt{makeglossaries} because \qt{a} (second character of \csfmt{application}) comes before \qt{c} (second character of \csfmt{command}). -The switch to \idx{xindy} just involves adding the \styoptfmt{xindy} +The switch to \idx{xindy} just involves adding the \styopt{xindy} package option: -\begin{verbatim} -\usepackage[xindy,style=indexgroup]{glossaries} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}[\styopt{xindy},\styopt[indexgroup]{style}]\marg{glossaries} +\end{codeenv} This results in a glossary that only contains one entry, \csfmt{makeglossaries}, because \idx{xindy} merges entries with duplicate sort values and the sort values end up as duplicates -because \idx{xindy} discards the control sequences. Although -\bibgls\ also ignores unknown control sequences, it doesn't perform -this merger. +because \idx{xindy} discards the \csfmt{application} and +\csfmt{command} control sequences. Although \bibgls\ also ignores +unknown control sequences, it doesn't perform this merger. -If I add -\begin{verbatim} -@preamble{"\providecommand*{\application}[1]{\texttt{#1}} -\providecommand{\command}[1]{\texttt{\char92 #1}}"} -\end{verbatim} +If I add: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}} +\cs{providecommand}\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}}} +\end{codeenv} to the earlier \ext{bib} file (called, say, \filefmt{entries.bib}) then the document can be altered to use \bibgls: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources{src=entries.bib, - sort-suffix=non-unique, - identical-sort-action=none -} - -\begin{document} - -\gls{cs.makeglossaries} and \gls{ap.makeglossaries}. - -\printunsrtglossaries -\end{document} -\end{verbatim} -This uses the default \csopt[locale]{sort} which considers \verb|\| +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}, + \csopt[non-unique]{sort-suffix}, + \csopt[none]{identical-sort-action} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}. +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +This uses the default \csopt[locale]{sort} which considers \idx{escchar} an ignored (punctuation) character, so both \csfmt{makeglossaries} and \appfmt{makeglossaries} are listed in the \qt{M} letter group, even though the interpreter has determined that the sort value for -\code{cs.makeglossaries} is the literal string \verb|\makeglossaries|. +\code{cs.makeglossaries} is the literal string \csfmt{makeglossaries}. Note that in this case \bibgls\ doesn't detect duplicate sort values since it only uses a simple string comparison to detect duplicates rather than using the collator. If I switch to using a letter-based sort rule instead, for example \csopt[letter-nocase]{sort}, then \csfmt{makeglossaries} will be -listed in the \qt{Symbols} letter group since the leading \verb|\| +listed in the \qt{Symbols} letter group since the leading \idx{escchar} from the sort value \csfmt{makeglossaries} isn't ignored with this rule. Now let's suppose I use \csopt[false]{interpret-preamble} to prevent \bibgls\ from interpreting the preamble: -\begin{verbatim} -\GlsXtrLoadResources{src=entries.bib,interpret-preamble=false} -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[false]{interpret-preamble}} +\end{codeenv} This means that the custom commands won't be recognised and will therefore be ignored, so both entries will have their sort values reduced to \code{makeglosssaries}. @@ -10769,30 +12562,30 @@ Both entries are listed in the \qt{M} letter group in the order \csfmt{makeglossaries}, \appfmt{makeglossaries}. If the records are reversed: -\begin{verbatim} -\gls{ap.makeglossaries} and \gls{cs.makeglossaries}. -\end{verbatim} +\begin{codeenv} +\cs{gls}\marg{ap.makeglossaries} and \cs{gls}\marg{cs.makeglossaries}. +\end{codeenv} then the sort value for \code{cs.makeglossaries} is now considered the duplicate and the order is reversed: \appfmt{makeglossaries}, \csfmt{makeglossaries}. Suppose now I modify the \ext{bib} file so that \code{ap.makeglossaries} is defined as: -\begin{verbatim} -@entry{ap.makeglossaries, - name={\application{makeglossaries}}, - category={application}, - description={Perl script (must be used with \gls{cs.makeglossaries})} +\begin{codeenv} +\atentry{entry}\marg{ap.makeglossaries, + \field{name}=\marg{\cmd{application}\marg{makeglossaries}}, + \field{category}=\marg{application}, + \field{description}=\marg{Perl script (must be used with \cs{gls}\marg{cs.makeglossaries})} } -\end{verbatim} +\end{codeenv} and suppose the document only contains an explicit reference to \code{ap.makeglossaries}: -\begin{verbatim} -\begin{document} -\gls{ap.makeglossaries} -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{begin}\marg{document} +\cs{gls}\marg{ap.makeglossaries} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} Now \code{ap.makeglossaries} is the first entry to be selected because entries with records are always selected before any (unrecorded) dependencies. In this case \code{cs.makeglossaries} is @@ -10804,13 +12597,13 @@ This means that the ordering in the glossary is now: An oddity occurs if the glossary is moved to the start of the document: -\begin{verbatim} -\begin{document} -\printunsrtglossaries -\gls{ap.makeglossaries} -\end{document} -\end{verbatim} -In this case, the first document build +\begin{codeenv} +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cs{gls}\marg{ap.makeglossaries} +\cmd{end}\marg{document} +\end{codeenv} +In this case, the first document build: \begin{verbatim} pdflatex myDoc bibgls --group --verbose myDoc @@ -10827,20 +12620,20 @@ In this type of situation you might be better off with the \csopt[id]{identical-sort-action} option instead. Remember that you can temporarily switch off the indexing by locally -setting -\begin{alltt} -\ics{GlsXtrSetDefaultGlsOpts}\marg{noindex} -\end{alltt} +setting: +\begin{codeenv*} +\ics{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}} +\end{codeenv*} Since the glossary preamble is scoped, you can simply do -\begin{verbatim} -\appto\glossarypreamble{\GlsXtrSetDefaultGlsOpts{noindex}} -\end{verbatim} +\begin{codeenv} +\ics{appto}\ics{glossarypreamble}\marg{\cs{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}} +\end{codeenv} to switch off the indexing within the glossary (or use \ics{apptoglossarypreamble}). Note that this is -different to using -\begin{alltt} -\ics{GlsXtrSetDefaultNumberFormat}\marg{glsignore} -\end{alltt} +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 the selection order and the record count. @@ -10855,11 +12648,13 @@ If a suffix is appended to the sort value (see above) then it will be separated by the suffix marker, which can be set with \csopt[\meta{value}]{sort-suffix-marker} where \meta{value} is the marker. By default the marker is empty. You can use \stringu\meta{hex} -to indicate Unicode characters outside the ASCII range. -If, for some reason, you want to use a special character, such as -\idx{param}, you will need to precede it with \ics{cs.string} (for example -\verb|\string#|). If you use \ics{cs.hash} it will be treated as a -literal string containing a backslash followed by a hash character. +or \cs{glshex}\meta{hex} to indicate Unicode characters outside the +\idx{ASCII} range. If, for some reason, you want to use a special +character, such as \idx{param}, you will need to precede it with +\ics{cs.string} (for example \code{\cs{cs.string}\idx{param}}) or +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{strength} @@ -10877,44 +12672,37 @@ assignment is locale dependent. See the documentation for Java's class}~\cite{collator} for further details. For example, suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@index{resume} - -@index{RESUME} - -@index{resumee, - name={r\'esum\'e}} - -@index{rat} - -@index{rot} - -@index{aardvark} - -@index{zoo} -\end{verbatim} +\begin{codeenv} +\atentry{index}\marg{resume} +\atentry{index}\marg{RESUME} +\atentry{index}\marg{resumee, \field{name}=\marg{r\ics{acute}esum\cs{acute}e}} +\atentry{index}\marg{rat} +\atentry{index}\marg{rot} +\atentry{index}\marg{aardvark} +\atentry{index}\marg{zoo} +\end{codeenv} and the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[record]{glossaries-extra} - -\GlsXtrLoadResources[sort={en},src={entries}] - -\begin{document} -\gls{resumee}, \gls{resume}, \gls{RESUME}, -\gls{aardvark}, \gls{rat}, \gls{rot}, \gls{zoo}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{resumee}, \cs{gls}\marg{resume}, \cs{gls}\marg{RESUME}, +\cs{gls}\marg{aardvark}, \cs{gls}\marg{rat}, \cs{gls}\marg{rot}, \cs{gls}\marg{zoo}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} then this uses the default \csopt[primary]{strength}, so the entries are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo. If the strength is changed to \optfmt{secondary}: -\begin{verbatim} -\GlsXtrLoadResources[sort={en},src={entries},strength=secondary] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src},\csopt[secondary]{strength}} +\end{codeenv} then the entries are listed as aardvark, rat, resume, RESUME, r\'esum\'e, rot, zoo. @@ -10956,18 +12744,22 @@ one of: \begin{itemize} \item\optfmt{before letter}: numbers are considered less than any letter. + \item\optfmt{after letter}: numbers are considered greater than any letter. + \item\optfmt{between}: (default) numbers come between letter cases. -With the \optfmt{-case} or \optfmt{-upperlower} sort options, -this will put numbers after \idx{uppercase} and before -\idx{lowercase}. -With the \optfmt{-lowerupper} sort option, this will put numbers -after \idx{lowercase} and before \idx{uppercase}. This setting doesn't make -much sense with the \optfmt{-nocase} option but, if used, this will put -numbers before letters. +With the \optfmt{letternumber\dhyphen case} sort option, this will put +numbers after \idx{uppercase} and before \idx{lowercase}. This +setting doesn't make much sense with the +\optfmt{letternumber\dhyphen nocase} option but, if used, this will put +numbers before letters. The \optfmt{letternumber\dhyphen upperlower} and +\optfmt{letternumber\dhyphen lowerupper} options are more complicated. See +\sectionref{sec:letternumber} for more detail. + \item\optfmt{first}: numbers are considered less than all characters (including punctuation and spaces). + \item\optfmt{last}: numbers are considered greater than all characters (including punctuation and spaces). \end{itemize} @@ -11022,10 +12814,10 @@ and white space is replaced by the digit~\code{0} (\hex{30}); and white space is replaced by the digit~\code{0} (\hex{30}). \item\optfmt{punc-first-space-zero-match-next}: punctuation comes first (although numbers may come before) -and white space is replaced by zero; +and white space is replaced by the appropriate zero character (see below); \item\optfmt{punc-last-space-zero-match-next}: punctuation comes last (although numbers may come after) -and white space is replaced by zero. +and white space is replaced by the appropriate zero character (see below). \end{itemize} Remember that the reverse sort methods will invert order governed by this setting. @@ -11061,16 +12853,16 @@ The \TeX\ parser library used by \bibgls\ recognises the standard \ics{textsubscript}\margm{text} and will use the Unicode superscript or subscript characters if they cover every character in \meta{text}, otherwise HTML markup is used, but that's -then stripped by \bibgls. This means that -\begin{verbatim} -C\textsubscript{10}H\textsubscript{10}O\textsubscript{4} -\end{verbatim} -will be converted to -\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but -\begin{verbatim} -X\textsubscript{1, 2} -\end{verbatim} -will be converted to +then stripped by \bibgls. This means that: +\begin{codeenv} +C\cs{textsubscript}\marg{10}H\cs{textsubscript}\marg{10}O\cs{textsubscript}\marg{4} +\end{codeenv} +will be converted to: +\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but: +\begin{codeenv} +X\cs{textsubscript}\marg{1, 2} +\end{codeenv} +will be converted to: \begin{verbatim} X<sub>1, 2</sub> \end{verbatim} @@ -11088,12 +12880,13 @@ If you use the custom \csopt[numberformat]{sort} or specify the format pattern with this option where \meta{value} is a pattern recognised by Java's \href{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}{\code{java.text.DecimalFormat}} -class~\cite{decimalformat}. You can use \stringu\meta{hex} to -indicate Unicode characters by their hexadecimal code. You can also -use \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp}, -\ics{cs.openbrace} and \ics{cs.closebrace} to indicate -\idx{hashchar}, \idx{percentchar}, \idx{underscorechar}, -\idx{ampchar}, \idx{openbracechar} and \idx{closebracechar}. +class~\cite{decimalformat}. You can use \stringu\meta{hex} or +\cs{glshex}\meta{hex} to indicate Unicode characters by their +hexadecimal code. You can also use \ics{cs.hash}, \ics{cs.percent}, +\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and +\ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar}, +\idx{underscorechar}, \idx{ampchar}, \idx{openbracechar} and +\idx{closebracechar}. Where the dual or secondary sort uses \optfmt{numberformat} or \optfmt{numberformat-reverse}, use \csopt{dual-numeric-sort-pattern} for @@ -11103,7 +12896,7 @@ for \csopt{secondary}. \optsection{numeric-locale} If you use any of the locale-sensitive numeric sort methods -(\tableref{tab:sortoptionsnumerical}), +described in \sectionref{sec:numerical}, such as \csopt[numeric]{sort}, use this option to set the locale. The value may be: \begin{itemize} @@ -11146,61 +12939,62 @@ The \meta{value} may be one of: \item\meta{pattern}: provide a custom pattern. This should match the specifications for Java's \href{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}{\code{SimpleDateFormat}} -class~\cite{simpledateformat}. You may use \stringu\meta{hex} to indicate Unicode characters +class~\cite{simpledateformat}. You may use \stringu\meta{hex} or +\code{\cs{glshex} \meta{hex}} to indicate Unicode characters or \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and \ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar}, \idx{underscorechar}, -\idx{ampchar}, \idx{openbracechar} and \idx{closebracechar}. +\idx{ampchar}, \idx{openbracechar} and~\idx{closebracechar}. \end{itemize} With the custom setting, if the pattern only contains date (but not time) information, then it must be used with \csopt[date]{sort} or \csopt[date-reverse]{sort}. If the pattern only contains time (but not date) information, then it must be used with -\csopt[time]{sort} or \csopt[time-reverse]{sort}. If the pattern +\csopt[time]{sort} or \csopt[time\dhyphen reverse]{sort}. If the pattern contains date and time information, then it must be used with \csopt[datetime]{sort} or \csopt[datetime-reverse]{sort}. For example, suppose each entry provides information about a person and the \field{user1} field is used to store their date of birth: -\begin{verbatim} -@entry{caesar, - name={Gaius Julius Caesar}, - first={Julius Caesar}, - text={Caesar}, - description={Roman politician and general}, - user1={13 July 100 BC} -} - -@entry{wellington, - name={Arthur Wellesley, 1st Duke of Wellington}, - first={Arthur Wellesley (Duke of Wellington)}, - text={Wellington}, - description={Anglo-Irish soldier and statesman}, - user1={1 May 1769 AD} +\begin{codeenv} +\atentry{entry}\marg{caesar, + \field{name}=\marg{Gaius Julius Caesar}, + \field{first}=\marg{Julius Caesar}, + \field{text}=\marg{Caesar}, + \field{description}=\marg{Roman politician and general}, + \field{user1}=\marg{13 July 100 BC} +} +\strut +\atentry{entry}\marg{wellington, + \field{name}=\marg{Arthur Wellesley, 1st Duke of Wellington}, + \field{first}=\marg{Arthur Wellesley (Duke of Wellington)}, + \field{text}=\marg{Wellington}, + \field{description}=\marg{Anglo-Irish soldier and statesman}, + \field{user1}=\marg{1 May 1769 AD} } -\end{verbatim} +\end{codeenv} Then the entries can be sorted by date of birth using: -\begin{verbatim} -\GlsXtrLoadResources[ - src={entries}, % data in entries.bib - sort-field={user1}, - sort={date}, - date-sort-format={d MMM y G} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{data in entries.bib} + \csopt[user1]{sort-field}, + \csopt[date]{sort}, + \csopt[d MMM y G]{date-sort-format} +} +\end{codeenv} The \code{G} (era) date pattern specifier expects a string, such as \qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you -have \verb|\textsc{ad}| the interpreter will convert this to +have \code{\cs{textsc}\marg{ad}} the interpreter will convert this to \code{ad} (stripping the text-block command). However, in general it's best to supply a semantic command that ensures that the interpreted result matches the required format. For example, if \csfmt{era} is provided with: -\begin{verbatim} -@preamble{"\providecommand{\era}[1]{\textsc{\MakeLowercase{#1}}}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{era}}[1]\marg{\cs{textsc}\marg{\cs{MakeLowercase}\marg{\idx{param}1}}}}} +\end{codeenv} If the definition is hidden from the interpreter (\csopt[false]{interpret-preamble}) and the field value contains \verb|\era{AD}| then the custom command will simply be stripped @@ -11216,27 +13010,27 @@ interpreter. Here's a complete document that changes the \field{group} fields to use the year and era: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,style=indexgroup]{glossaries-extra} - -\newcommand{\bibglsdategroup}[7]{#1#4#7} -\newcommand{\bibglsdategrouptitle}[7]{\number#1\ #4} - -\GlsXtrLoadResources[ - src={entries}, - sort-field={user1}, - sort={date}, - date-sort-format={d MMM y G}, - selection=all -] - -\begin{document} -\printunsrtglossaries -\end{document} -\end{verbatim} -(The use of \csfmt{number} strips the leading zero from the year.) +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} +\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\ics{number}\idx{param}1\cs{cs.space}\idx{param}4} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[user1]{sort-field}, + \csopt[date]{sort}, + \csopt[d MMM y G]{date-sort-format}, + \csopt[all]{selection} +} +\strut +\cmd{begin}\marg{document} +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} +(The use of \ics{number} strips the leading zero from the year.) \optsection{group-formation} @@ -11249,19 +13043,19 @@ the sort method's default group formation. This is the default setting. \item\optfmt{codepoint}: the group is set to -\icswithargs{bibglsunicodegroup}, where the first argument is the -first significant character (converted to \idx{lowercase} and decomposed, +\format{bibglsunicodegroup}, where the first argument is the first +significant character (converted to \idx{lowercase} and decomposed, if applicable) of the sort value. \item\optfmt{unicode category}: the group is set to -\icswithargs{bibglsunicodegroup}, where the first argument is the -label identifying the Unicode category of the first significant -character of the sort value. For example, the label \code{Ll} -signifies a \idx!{lowercase} letter and \code{Lu} signifies an -\idx!{uppercase} letter. +\format{bibglsunicodegroup}, where the first argument is the label +identifying the Unicode category of the first significant character +of the sort value. For example, the label \code{Ll} signifies a +\idx!{lowercase} letter and \code{Lu} signifies an \idx!{uppercase} +letter. \item\optfmt{unicode script}: the group is set to -\icswithargs{bibglsunicodegroup}, where the first argument is the +\format{bibglsunicodegroup}, where the first argument is the label identifying the Unicode script of the first significant character of the sort value. For example, the label \code{LATIN} indicates Latin, \code{GREEK} indicates Greek and \code{COMMON} @@ -11269,7 +13063,7 @@ indicates common characters (such as mathematical Greek characters that are often used with non-Greek scripts). \item\optfmt{unicode category and script}: the group is set to -\icswithargs{bibglsunicodegroup}, where the first argument is the +\format{bibglsunicodegroup}, where the first argument is the label corresponding to the Unicode category and script of the first significant character of the sort value. For example, the label \code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter. @@ -11300,7 +13094,7 @@ command with the same selection criteria. A simpler method is to use a single \gls{GlsXtrLoadResources} with the \csopt{secondary} option. The value -(which must be supplied) should be in the format +(which must be supplied) should be in the format: \begin{definition} \meta{sort}:\meta{field}:\meta{type} \end{definition} @@ -11352,31 +13146,31 @@ the existing entries aren't re-ordered. The new entries are simply appended to the list. For example, suppose the \ext{bib} file contains entries like: -\begin{verbatim} -@entry{quartz, - name={quartz}, - description={hard mineral consisting of silica}, - category={mineral} -} - -@entry{cabbage, - name={cabbage}, - description={vegetable with thick green or purple leaves}, - category={vegetable} -} - -@entry{waterfowl, - name={waterfowl}, - description={any bird that lives in or about water}, - category={animal} +\begin{codeenv} +\atentry{entry}\marg{quartz, + \field{name}=\marg{quartz}, + \field{description}=\marg{hard mineral consisting of silica}, + \field{category}=\marg{mineral} +} +\strut +\atentry{entry}\marg{cabbage, + \field{name}=\marg{cabbage}, + \field{description}=\marg{vegetable with thick green or purple leaves}, + \field{category}=\marg{vegetable} +} +\strut +\atentry{entry}\marg{waterfowl, + \field{name}=\marg{waterfowl}, + \field{description}=\marg{any bird that lives in or about water}, + \field{category}=\marg{animal} } -\end{verbatim} +\end{codeenv} and the document preamble contains: -\begin{verbatim} -\GlsXtrLoadResources[src={entries},sort={en-GB}, - secondary={en-GB:category:topic} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en-GB]{sort}, + \csopt[en-GB:category:topic]{secondary} +} +\end{codeenv} This sorts the primary entries according to the default \csopt{sort-field} and then sorts the entries according to the \field{category} field and copies this list to @@ -11387,49 +13181,49 @@ off to prevent duplicates. The cross-references will link to the original glossary. For example: -\begin{verbatim} -\printunsrtglossary[title={Summary (alphabetical)}] -\printunsrtglossary[title={Summary (by topic)},target=false] -\end{verbatim} +\begin{codeenv*} +\ics{printunsrtglossary}\oarg{\printglossopt[Summary (alphabetical)]{title}} +\ics{printunsrtglossary}\oarg{\printglossopt[Summary (by topic)]{title},\printglossopt[false]{target}} +\end{codeenv*} The alternative (or if more than two lists are required) is to reload the same \ext{bib} file with different label prefixes. For example, if the entries are stored in \filefmt{entries.bib}: -\begin{verbatim} -\newglossary*{nosort}{Symbols (Unsorted)} -\newglossary*{byname}{Symbols (Letter Order)} -\newglossary*{bydesc}{Symbols (Ordered by Description)} -\newglossary*{byid}{Symbols (Ordered by Label)} - -\GlsXtrLoadResources[ - src={entries},% entries.bib - sort={unsrt}, - type={nosort} -] - -\GlsXtrLoadResources[ - src={entries},% entries.bib - sort={letter-case}, - type={byname}, - label-prefix={byname.} -] - -\GlsXtrLoadResources[ - src={entries},% entries.bib - sort={locale}, - sort-field={description}, - type={bydesc}, - label-prefix={bydesc.} -] - -\GlsXtrLoadResources[ - src={entries},% entries.bib - sort={letter}, - sort-field={id}, - type={byid}, - label-prefix={byid.} -] -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{nosort}\marg{Symbols (Unsorted)} +\cs{newglossary*}\marg{byname}\marg{Symbols (Letter Order)} +\cs{newglossary*}\marg{bydesc}\marg{Symbols (Ordered by Description)} +\cs{newglossary*}\marg{byid}\marg{Symbols (Ordered by Label)} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[unsrt]{sort}, + \csopt[nosort]{type} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[letter-case]{sort}, + \csopt[byname]{type}, + \csopt[byname.]{label-prefix} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[locale]{sort}, + \csopt[description]{sort-field}, + \csopt[bydesc]{type}, + \csopt[bydesc.]{label-prefix} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src},\comment{entries.bib} + \csopt[letter]{sort}, + \csopt[id]{sort-field}, + \csopt[byid]{type}, + \csopt[byid.]{label-prefix} +} +\end{codeenv} \optsection{secondary-missing-sort-fallback} @@ -11531,6 +13325,12 @@ Any references to dual entries within the \ext{bib} file should use the prefix \idprefix{dual} which will be replaced by \meta{value} when the \ext{bib} file is parsed. +As from version 1.8, the dual label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglsdualprefixlabel} +\end{codeenv} + \optsection[\subsubsection]{primary-dual-dependency} This is a boolean setting that determines whether or not primary and @@ -11544,13 +13344,8 @@ used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or \optsection[\subsubsection]{combine-dual-locations} -You can merge the location lists for each primary entry -with that of the corresponding dual entry. This setting -allows you to specify this and determine whether both primary and -dual entries should have the combined location list or -whether only the primary or the dual should be assigned the -combined list. - +This setting allows the location lists for each primary entry +to be merged with that of the corresponding dual entry. The \meta{value} may be one of: \begin{itemize} \item\optfmt{false} This is the default setting. The location lists @@ -11564,52 +13359,52 @@ location list. The dual's location list is emptied. \end{itemize} For example, suppose the file \filefmt{entries.bib} contains: -\begin{verbatim} -@dualindexentry{array, - description={ordered list of values} +\begin{codeenv} +\atentry{dualindexentry}\marg{array, + \field{description}=\marg{ordered list of values} } - -@dualindexentry{vector, - name={vector}, - description={column or row of values} +\strut +\atentry{dualindexentry}\marg{vector, + \field{name}=\marg{vector}, + \field{description}=\marg{column or row of values} } - -@dualindexentry{set, - description={collection of values} +\strut +\atentry{dualindexentry}\marg{set, + \field{description}=\marg{collection of values} } - -@dualindexentry{matrix, - plural={matrices}, - description={rectangular array of values} +\strut +\atentry{dualindexentry}\marg{matrix, + \field{plural}=\marg{matrices}, + \field{description}=\marg{rectangular array of values} } -\end{verbatim} +\end{codeenv} and the document contains: -\begin{verbatim} -\documentclass{article} - -\usepackage[colorlinks]{hyperref} -\usepackage[record,index,style=indexgroup]{glossaries-extra} - -\GlsXtrLoadResources[ - src={entries}, - type=index, - label-prefix={idx.}, - dual-prefix={gls.}, - dual-type=main -] - -\begin{document} -\gls{gls.array}, \gls{gls.vector}, \gls{gls.set}, \gls{gls.matrix}. - -\newpage -\gls{gls.array}, \gls{idx.vector}, \gls{idx.set}, \gls{gls.matrix}. - -\newpage -\gls{gls.array}, \gls{gls.vector}, \gls{gls.set}, \gls{gls.matrix}. - -\printunsrtglossaries -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[colorlinks]\marg{hyperref} +\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[indexgroup]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries]{src}, + \csopt[index]{type}, + \csopt[idx.]{label-prefix}, + \csopt[gls.]{dual-prefix}, + \csopt[main]{dual-type} +} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{idx.vector}, \cs{gls}\marg{idx.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cmd{newpage} +\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}. +\strut +\cs{printunsrtglossaries} +\cmd{end}\marg{document} +\end{codeenv} In this case, the primary entries 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 @@ -11622,11 +13417,11 @@ 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 \verb|\gls{gls.array}|, -\verb|\gls{gls.vector}|, \verb|\gls{gls.set}| and -\verb|\gls{gls.matrix}|) and some of the locations are in the -\code{index} glossary (corresponding to \verb|\gls{idx.vector}| -and \verb|\gls{idx.set}|). +\code{main} glossary (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{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 @@ -11647,9 +13442,8 @@ hyperlink can point to the definition in the \code{main} glossary. This option sets the \field{type} field for all dual entries. (The primary entries 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. - -The \meta{value} may be: +file (or created through a mapping). The \meta{value} is required and +should be one of: \begin{itemize} \item \optfmt{same as entry}: sets the \field{type} to the entry type (\idx!{lowercase} and without @@ -11680,34 +13474,31 @@ unchanged. Remember that the glossary with that label must have already been defined (see \sectionref{sec:newglossary}). - For example: -\begin{verbatim} -\newglossary*{english}{English} -\newglossary*{french}{French} - -\GlsXtrLoadResources[src={entries},sort={en},dual-sort={fr}, - type=english, - dual-type=french] -\end{verbatim} - +\begin{codeenv} +\cs{newglossary*}\marg{english}\marg{English} +\cs{newglossary*}\marg{french}\marg{French} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, + \csopt[english]{type}, + \csopt[french]{dual-type}} +\end{codeenv} Alternatively: -\begin{verbatim} -\newglossary*{dictionary}{Dictionary} - -\GlsXtrLoadResources[src={entries},sort={en},dual-sort={fr}, - type=dictionary, - dual-type={same as primary}] -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{dictionary}\marg{Dictionary} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort}, + \csopt[dictionary]{type}, + \csopt[same as primary]{dual-type}} +\end{codeenv} \optsection[\subsubsection]{dual-category} This option sets the \field{category} field for all dual entries. (The primary entries 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. - -The \meta{value} may be: +file (or created through a mapping). The \meta{value} may be empty or +one of: \begin{itemize} \item \optfmt{same as entry}: sets the \field{category} to the entry type (\idx{lowercase} and without @@ -11753,51 +13544,57 @@ entry. As \csopt{short-case-change} but applies to the \field{dualshort} field instead. +\optsection[\subsubsection]{dual-long-case-change} + +As \csopt{long-case-change} but applies to the \field{duallong} +field instead. + \optsection[\subsubsection]{dual-field} If this option is used, this will add \ics{glsxtrprovidestoragekey} to the start of the \iext{glstex} file providing the key given by -\meta{value}. Any entries defined using \atentry{dualentry} -will be written to the \ext{glstex} file with an extra field called -\meta{value} that is set to the mirror entry. If \meta{value} is -omitted \csopt[dual]{dual-field} is assumed. If you use a different -value, you will need to redefine \gls{GlsXtrDualField} (either -locally or globally). - -For example, if the \ext{bib} file contains -\begin{verbatim} -@dualentry{child, - name={child}, - plural={children}, - description={enfant} +\meta{value}. Any entries defined using a dual entry type, such as +\atentry{dualentry}, will be written to the \ext{glstex} file with +an extra field called \meta{value} that is set to the mirror entry. +If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If +you use a different value, you will need to redefine +\gls{GlsXtrDualField} (either locally or globally). + +For example, if the \ext{bib} file contains: +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} } -\end{verbatim} -Then with \csopt[dualid]{dual-field} this will first add the line -\begin{verbatim} -\glsxtrprovidestoragekey{dualid}{}{} -\end{verbatim} -at the start of the file and will include the line -\begin{verbatim} -dualid={dual.child}, -\end{verbatim} -for the primary entry (\code{child}) and the line -\begin{verbatim} -dualid={child}, -\end{verbatim} +\end{codeenv} +Then with \csopt[dual]{dual-field} (or simply \csopt{dual-field} +without a value) this will first add the line: +\begin{codeenv} +\cs{glsxtrprovidestoragekey}\marg{\field{dual}}\marg{}\marg{} +\end{codeenv} +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: +\begin{codeenv} +\field{dual}=\marg{child}, +\end{codeenv} for the dual entry (\code{dual.child}). It's then possible to reference one entry from the other. For example, the post-description hook could contain: -\begin{verbatim} - \ifglshasfield{dualid}{\glscurrententrylabel} - {% - \space - (\glshyperlink{\glsxtrusefield{\glscurrententrylabel}{dualid}})% - }% - {}% -\end{verbatim} +\begin{codeenv} + \cs{ifglshasfield}\marg{\field{dual}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{} + \cs{space} + (\cs{glshyperlink}\marg{\cs{glscurrentfieldvalue}})\comment{} + }\comment{} + \marg{}\comment{} +\end{codeenv} Note that this new field won't be available for use within the \iext{bib} file (unless it was previously defined in the document -before \csref{glsxtrresourcefile}). +before \gls!{glsxtrresourcefile}). \optsection[\subsubsection]{dual-date-time-field-format} @@ -11840,28 +13637,27 @@ entries are sorted separately according to \meta{value} (as per \csopt{sort}) and the dual entries 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 according to the +If \csopt[custom]{dual-sort}, then the dual entries are sorted according to the rule provided by \csopt{dual-sort-rule}. - For example: -\begin{verbatim} -\GlsXtrLoadResources[ - src={entries-dual}, - sort={en}, - dual-sort={de-CH-1996} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual]{src}, + \csopt[en]{sort}, + \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} (Swiss German new orthography) whereas: -\begin{verbatim} -\GlsXtrLoadResources[ - src={entries-dual}, - sort={en-GB}, - dual-sort={combine} -] -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[entries-dual]{src}, + \csopt[en-GB]{sort}, + \csopt[combine]{dual-sort} +} +\end{codeenv} will combine the dual entries with the primary entries and sort them all according to the \optfmt{en-GB} locale (British English). @@ -11977,60 +13773,59 @@ entry from the primary one. Note that the \field{alias} field can't be mapped. The default setting is: -\begin{verbatim} -dual-entry-map= -{ - {name,plural,description,descriptionplural}, - {description,descriptionplural,name,plural} -} -\end{verbatim} +\begin{codeenv} +\csopt[ + \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, + \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 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. - For example: -\begin{verbatim} -@dualentry{cat, - name={cat}, - description={chat}, - see={dog} +\begin{codeenv} +\atentry{dualentry}\marg{cat, + \field{name}=\marg{cat}, + \field{description}=\marg{chat}, + \field{see}=\marg{dog} } -\end{verbatim} -defines two entries. The primary entry is essentially like -\begin{verbatim} -@entry{cat, - name={cat}, - plural={cat\glspluralsuffix }, - description={chat}, - descriptionplural={chat\glspluralsuffix }, - see={dog} +\end{codeenv} +defines two entries. The primary entry is essentially like: +\begin{codeenv} +\atentry{entry}\marg{cat, + \field{name}=\marg{cat}, + \field{plural}=\marg{cat\cs{glspluralsuffix} }, + \field{description}=\marg{chat}, + \field{descriptionplural}=\marg{chat\cs{glspluralsuffix} }, + \field{see}=\marg{dog} } -\end{verbatim} -and the dual entry is essentially like -\begin{verbatim} -@entry{dual.cat, - description={cat}, - descriptionplural={cat\glspluralsuffix }, - name={chat}, - plural={chat\glspluralsuffix }, - see={dog} +\end{codeenv} +and the dual entry is essentially like: +\begin{codeenv} +\atentry{entry}\marg{dual.cat, + \field{description}=\marg{cat}, + \field{descriptionplural}=\marg{cat\cs{glspluralsuffix} }, + \field{name}=\marg{chat}, + \field{plural}=\marg{chat\cs{glspluralsuffix} }, + \field{see}=\marg{dog} } -\end{verbatim} +\end{codeenv} (except they're defined using \gls{bibglsnewdualentry} instead of \gls{bibglsnewentry}, and each is considered dependent on the other.) The \field{see} field isn't listed in \csopt{dual-entry-map} so its value is simply copied directly over to the \field{see} field in the -dual entry. Note that the missing plural fields (\field{plural} and -\field{descriptionplural}) have been filled in. +dual entry. Note that the missing \field{plural} and +\field{descriptionplural} fields have been filled in using their +fallback values. In general \bibgls\ doesn't try to supply missing fields, but in the dual entry cases it needs to do this for the mapped fields. This is because the shuffled fields might have different default values from the \styfmt{glossaries-extra} package's point of view. For example, \gls{longnewglossaryentry} doesn't provide a default for -\field{descriptionplural} if if hasn't been set. +\field{descriptionplural} if it hasn't been set. \optsection[\subsubsection]{dual-abbrv-map} @@ -12038,15 +13833,14 @@ This is like \csopt{dual-entry-map} but applies to \atentry{dualabbreviation} rather than \atentry{dualentry}. Note that the \field{alias} field can't be mapped. The default setting is: -\begin{verbatim} -dual-abbrv-map= -{ - {short,shortplural,long,longplural,dualshort,dualshortplural, - duallong,duallongplural}, - {dualshort,dualshortplural,duallong,duallongplural,short,shortplural, - long,longplural} -} -\end{verbatim} +\begin{codeenv} +\csopt[ + \marg{\field{short},\field{shortplural},\field{long},\field{longplural},\field{dualshort},\field{dualshortplural}, + \field{duallong},\field{duallongplural}}, + \marg{\field{dualshort},\field{dualshortplural},\field{duallong},\field{duallongplural},\field{short},\field{shortplural}, + \field{long},\field{longplural}} +]{dual-abbrv-map} +\end{codeenv} This essentially flips the \field{short} field with the \field{dualshort} field and the \field{long} field with the @@ -12059,13 +13853,12 @@ This is like \csopt{dual-entry-map} but applies to \atentry{dualabbreviationentry} rather than \atentry{dualentry}. Note that the \field{alias} field can't be mapped. The default setting is: -\begin{verbatim} -dual-abbrventry-map= -{ - {long,short,shortplural}, - {name,text,plural} -} -\end{verbatim} +\begin{codeenv} +\csopt[ + \marg{\field{long},\field{short},\field{shortplural}}, + \marg{\field{name},\field{text},\field{plural}} +]{dual-abbrventry-map} +\end{codeenv} See \atentry{dualabbreviationentry} for further details. @@ -12075,14 +13868,12 @@ This is like \csopt{dual-entry-map} but applies to \atentry{dualsymbol} rather than \atentry{dualentry}. Note that the \field{alias} field can't be mapped. The default setting is: -\begin{verbatim} -dual-symbol-map= -{ - {name,plural,symbol,symbolplural}, - {symbol,symbolplural,name,plural} -} -\end{verbatim} - +\begin{codeenv} +\csopt[ + \marg{\field{name},\field{plural},\field{symbol},\field{symbolplural}}, + \marg{\field{symbol},\field{symbolplural},\field{name},\field{plural}} +]{dual-symbol-map} +\end{codeenv} This essentially flips the \field{name} field with the \field{symbol} field. @@ -12090,17 +13881,41 @@ This essentially flips the \field{name} field with the This is like \csopt{dual-entry-map} but applies to \atentry{dualindexentry} rather than \atentry{dualentry}. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name}}, + \marg{\field{name}} +]{dual-indexentry-map} +\end{codeenv} +Note that there must always be at least one pair, even if it's the +same field, since this identifies the field to use for the backlink, +if set. \optsection[\subsubsection]{dual-indexsymbol-map} This is like \csopt{dual-entry-map} but applies to both \atentry{dualindexsymbol} and \atentry{dualindexnumber}. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{symbol},\field{name},\field{symbolplural},\field{plural}}, + \marg{\field{name},\field{symbol},\field{plural},\field{symbolplural}} +]{dual-indexsymbol-map} +\end{codeenv} \optsection[\subsubsection]{dual-indexabbrv-map} This is like \csopt{dual-entry-map} but applies to both the dual \atentry{dualindexabbreviation} and tertiary \atentry{tertiaryindexabbreviationentry} entry types. +The default setting is: +\begin{codeenv} +\csopt[ + \marg{\field{name}}, + \marg{\field{name}} +]{dual-indexabbrv-map} +\end{codeenv} \subsection{Dual Back-Links} \label{sec:dualoptsbacklinks} @@ -12116,32 +13931,32 @@ with \gls{bibglshyperlink}. The field is obtained from the first mapping listed in \csopt{dual-entry-map}. For example, if the document contains: -\begin{verbatim} -\GlsXtrLoadResource[dual-entry-backlink, - dual-entry-map={ - {name,plural,description,descriptionplural}, - {description,descriptionplural,name,plural} - }, - src={entries-dual}] -\end{verbatim} -and if the \ext{bib} file contains -\begin{verbatim} -@dualentry{child, - name={child}, - plural={children}, - description={enfant} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt{dual-entry-backlink}, + \csopt[ + \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}}, + \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}} + ]{dual-entry-map}, + \csopt[entries-dual]{src}} +\end{codeenv} +and if the \ext{bib} file contains: +\begin{codeenv} +\atentry{dualentry}\marg{child, + \field{name}=\marg{child}, + \field{plural}=\marg{children}, + \field{description}=\marg{enfant} } -\end{verbatim} +\end{codeenv} Then the definition of the primary entry (\code{child}) in the -\ext{glstex} file will set the \field{description} field to -\begin{verbatim} -\bibglshyperlink{enfant}{dual.child} -\end{verbatim} +\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 -\field{description} field set to -\begin{verbatim} -\bibglshyperlink{child}{child} -\end{verbatim} +\field{description} field set to: +\begin{codeenv} +\gls{bibglshyperlink}\marg{child}\marg{child} +\end{codeenv} This use of the wrapper \gls{bibglshyperlink} (rather than explicitly using \ics{glshyperlink}) and inserting the actual field value (rather than using commands like \ics{glsentryname}) allows it @@ -12184,24 +13999,24 @@ use \csopt{dual-field} (or \csopt[dual]{dual-field}) to store the dual label in the \field{dual} field, and then use a style that checks for this field and adds the backlink. -With \sty{glossaries-extra} v1.30+ you can use +With \sty{glossaries-extra} v1.30+ you can use: \nosecdef{GlsXtrDualBackLink} 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 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 need to redefine \gls{GlsXtrDualField} as appropriate. For example: -\begin{verbatim} -\renewcommand*{\glsuserdescription}[2]{% - \GlsXtrDualBackLink{\glslonguserfont{#1}}{#2}% +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsuserdescription}}[2]\marg{\comment{} + \gls{GlsXtrDualBackLink}\marg{\ics{glslonguserfont}\marg{\idx{param}1}}\marg{\idx{param}2}\comment{} } -\setabbreviationstyle{long-short-user} -\GlsXtrLoadResources[src={entries},dual-field] -\end{verbatim} +\cs{setabbreviationstyle}\marg{\abbrstyle{long-short-user}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{dual-field}} +\end{codeenv} \optsection[\subsubsection]{dual-entryabbrv-backlink} @@ -12247,6 +14062,12 @@ Shortcut for: This option indicates the prefix to use for the tertiary entries. The default value is \idprefix{tertiary} (including the terminating period). +As from version 1.8, the tertiary label prefix is identified +in the \ext{glstex} file with: +\begin{codeenv} +\format{bibglstertiaryprefixlabel} +\end{codeenv} + \optsection{tertiary-type} This option indicates that the tertiary entries should have @@ -12267,15 +14088,27 @@ recognised keywords. \label{sec:bibglscs} When \bibgls\ creates the \iext{glstex} file, it writes some -definitions for custom commands in the form \csfmt{bibgls...} which +definitions for custom commands in the form \csfmt{bibgls\ldots} which may be changed as required. The command definitions all use \ics{providecommand} which means that you can define the command with \ics{newcommand} before the resource file is loaded. +Note that if you try to redefine any of these commands after the +resource file has been loaded with \ics{renewcommand}, you will get +an error on the first \LaTeX\ run when the \ext{glstex} file doesn't +exist. You may prefer to use \ics{glsrenewcommand} instead, which +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} +if adjustments are necessary. + + \section{Entry Definitions} \label{sec:newentrydefs} -This section lists the commands (\csfmt{bibglsnew...}) used to +This section lists the commands (\csfmt{bibglsnew\ldots}) used to define entries. Note that the entry definition commands are actually used when \TeX\ inputs the resource file, so redefining them after the resource file is loaded won't have an effect on the @@ -12285,9 +14118,16 @@ the \ext{glstex} file immediately before the first entry that requires it, so only the commands that are actually needed are provided. -After each entry is defined, if it has any associated locations, the -locations are added using +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}. + +After each entry is defined, if it has any associated locations and +the default \csopt[true]{save-loclist} is set, then the +locations are added using: \nosecformatdef{glsxtrfieldlistadd} +Any additional fields that don't have associated keys are then set (if +required) with \ics{GlsXtrSetField}. \cssection{bibglsnewentry} @@ -12295,11 +14135,11 @@ locations are added using This command is used to define terms identified with the \atentry{entry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} This uses the starred form \ics{longnewglossaryentry*} that doesn't automatically append \ics{nopostdesc} (which interferes with the post-description hooks provided by category attributes). @@ -12310,11 +14150,11 @@ the post-description hooks provided by category attributes). This command is used to define terms identified with the \atentry{symbol} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewsymbol}[4]{% - \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} Note that this sets the \field{sort} field to the label, but this may be overridden by the \meta{options} if the \field{sort} field was supplied or if \bibgls\ has determined the value whilst sorting @@ -12331,11 +14171,11 @@ overridden with \csopt[\meta{value}]{category}. This command is used to define terms identified with the \atentry{number} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewnumber}[4]{% - \longnewglossaryentry*{#1}{name={#3},sort={#1},category={number},#2}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewnumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{number},\idx{param}2}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} This is much the same as \gls{bibglsnewsymbol} above but sets the \field{category} to \optfmt{number}. Again the \field{sort} and \field{category} keys may be overridden by \meta{options}. @@ -12346,11 +14186,11 @@ This is much the same as \gls{bibglsnewsymbol} above but sets the This command is used to define terms identified with the \atentry{index} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand*{\bibglsnewindex}[2]{% - \newglossaryentry{#1}{name={#1},category={index},description={},#2}% +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglsnewindex}}[2]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}=\marg{index},\field{description}=\marg{},\idx{param}2}\comment{} } -\end{verbatim} +\end{codeenv} This makes the \field{name} default to the \meta{label}, assigns the \field{category} to \code{index} and sets an empty \field{description}. These settings may be overridden by @@ -12366,11 +14206,11 @@ category attributes. This command is used to define terms identified with the \atentry{indexplural} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewindexplural}[3]{% - \newglossaryentry{#1}{name={#3},category={indexplural},description={},#2}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewindexplural}}[3]\marg{\comment{} + \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{} } -\end{verbatim} +\end{codeenv} This assigns the \field{category} to \code{indexplural} and sets an empty \field{description}. These settings may be overridden by \meta{options}. @@ -12380,11 +14220,11 @@ This assigns the \field{category} to \code{indexplural} and sets an empty This command is used to define terms identified with the \atentry{abbreviation} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewabbreviation}[4]{% - \newabbreviation[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} Since this uses \gls{newabbreviation}, it obeys the abbreviation style for its given \field{category} (which may have been set in \meta{options}, either from the \field{category} field @@ -12399,11 +14239,11 @@ the value is supplied in the \ext{bib} file or through the This command is used to define terms identified with the \atentry{acronym} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewacronym}[4]{% - \newacronym[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} This works in much the same way as \gls{bibglsnewabbreviation}. Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} is redefined to just use \gls{newabbreviation} with the default \field{type} @@ -12416,11 +14256,11 @@ set to \ics{acronymtype} and the default \field{category} set to This command is used to define terms identified with the \atentry{dualentry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewdualindexentry} @@ -12428,11 +14268,11 @@ file is: This command is used to define primary terms identified with the \atentry{dualindexentry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexentry}[4]{% - \longnewglossaryentry*{#1}{name={#3},category={index},#2}{}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}\marg{}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexentrysecondary} @@ -12441,11 +14281,11 @@ Note that this definition ignores the \meta{description} argument. This command is used to define secondary terms identified with the \atentry{dualindexentry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexentrysecondary}[4]{% - \longnewglossaryentry*{#1}{name={#3},#2}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexentrysecondary}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewdualindexsymbol} @@ -12453,11 +14293,11 @@ file is: This command is used to define primary terms identified with the \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexsymbol}[5]{% - \longnewglossaryentry*{#1}{name={#3},category={index},symbol={#4},#2}{}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbol}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexsymbolsecondary} @@ -12466,12 +14306,11 @@ Note that this definition ignores the \meta{description} argument. This command is used to define secondary terms identified with the \atentry{dualindexsymbol} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexsymbolsecondary}[5]{% - \longnewglossaryentry*{#1}{name={#3},category={symbol},symbol={#4},#2}% - {#5}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{symbol},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewdualindexnumber} @@ -12479,11 +14318,11 @@ file is: This command is used to define primary terms identified with the \atentry{dualindexnumber} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexnumber}[5]{% - \longnewglossaryentry*{#1}{name={#3},category={index},symbol={#4},#2}{}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexnumber}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualindexnumbersecondary} @@ -12492,12 +14331,11 @@ Note that this definition ignores the \meta{description} argument. This command is used to define secondary terms identified with the \atentry{dualindexnumber} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexnumbersecondary}[5]{% - \longnewglossaryentry*{#1}{name={#3},category={number},symbol={#4},#2}% - {#5}% +\begin{codeenv} +\cs{providecommand}\marg{\cs{bibglsnewdualindexnumbersecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{number},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewdualindexabbreviation} @@ -12505,27 +14343,28 @@ file is: 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{verbatim} -\providecommand{\bibglsnewdualindexabbreviation}[7]{% - \longnewglossaryentry*{#1}{% - name={\protect\bibglsuseabbrvfont{#4}{\glscategory{#2}}},% - category={index},#3}{}% -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \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 to fetch the category label in \gls{bibglsuseabbrvfont}. (The -\field{category} field for the dual isn't used as a custom +\field{category} field for the dual isn't used since a custom definition of -\csref{bibglsnewdualindexabbreviationsecondary} may override the +\gls!{bibglsnewdualindexabbreviationsecondary} may override the value known to \bibgls.) Note that (as shown above) with the default -\csopt[short]{abbreviation-name-fallback} the \field{name} uses +\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 \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 +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. @@ -12535,15 +14374,14 @@ long form for the dual abbreviation. \formatdef{bibglsnewdualindexabbreviationsecondary} This command is used to define secondary terms identified with the \atentry{dualindexabbreviation} entry type. -The definition provided in the -\ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualindexabbreviationsecondary}[6]{% - \ifstrempty{#6}% - {\newabbreviation[#2]{#1}{#4}{#5}}% - {\newabbreviation[#2,description={#6}]{#1}{#4}{#5}}% +The definition provided in the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{} + \cs{ifstrempty}\marg{\idx{param}6}\comment{} + \marg{\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} + \marg{\gls{newabbreviation}\oarg{\idx{param}2,\field{description}=\marg{\idx{param}6}}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{} } -\end{verbatim} +\end{codeenv} This ensures that a missing or empty \field{description} doesn't interfere with the abbreviation style. @@ -12553,11 +14391,11 @@ interfere with the abbreviation style. This command is used to define primary terms identified with the \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualabbreviationentry}[5]{% - \newabbreviation[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentry}}[5]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualabbreviationentrysecondary} @@ -12566,11 +14404,11 @@ Note that this definition ignores the \meta{description} argument. This command is used to define secondary terms identified with the \atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualabbreviationentrysecondary}[5]{% - \longnewglossaryentry*{#1}{#2}{#5}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentrysecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{short} and \meta{long} arguments (which will typically be empty unless the default mappings are changed). @@ -12582,11 +14420,11 @@ 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: -\begin{verbatim} -\providecommand{\bibglsnewdualentryabbreviation}[5]{% - \newabbreviation[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviation}}[5]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{description} argument. \cssection{bibglsnewdualentryabbreviationsecondary} @@ -12596,11 +14434,11 @@ This command is used to define secondary terms identified with the (now deprecated) entry type \atentry{dualentryabbreviation}. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualentryabbreviationsecondary}[5]{% - \longnewglossaryentry*{#1}{#2}{#5}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviationsecondary}}[5]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{} } -\end{verbatim} +\end{codeenv} Note that this definition ignores the \meta{short} and \meta{long} arguments (which will typically be empty unless the default mappings are changed). @@ -12611,10 +14449,10 @@ are changed). This command is used to define terms identified with the \atentry{dualsymbol} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualsymbol}[4]{% - \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualsymbol}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} \cssection{bibglsnewdualnumber} @@ -12622,10 +14460,10 @@ file is: This command is used to define terms identified with the \atentry{dualnumber} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualnumber}[4]{% - \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualnumber}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}} +\end{codeenv} \cssection{bibglsnewdualabbreviation} @@ -12635,11 +14473,11 @@ This command is used to define terms identified with the is swapped with the \field{long} field and the \field{dualshort} field is swapped with the \field{short} field. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualabbreviation}[4]{% - \newabbreviation[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualabbreviation}}[4]\marg{\comment{} + \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewdualacronym} @@ -12647,11 +14485,11 @@ field is swapped with the \field{short} field. The definition provided in the This command is used to define terms identified with the \atentry{dualacronym} type. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewdualacronym}[4]{% - \newacronym[#2]{#1}{#3}{#4}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewdualacronym}}[4]\marg{\comment{} + \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{} } -\end{verbatim} +\end{codeenv} This works in much the same way as \gls{bibglsnewdualabbreviation}. Remember that with the \styfmt{glossaries-extra} package \gls{newacronym} is redefined to just use \gls{newabbreviation} with the default \field{type} @@ -12663,15 +14501,15 @@ set to \ics{acronymtype} and the default \field{category} set to \formatdef{bibglsnewtertiaryindexabbreviationentry} This is used to define primary terms identified with the \atentry{tertiaryindexabbreviationentry} type. It's essentially -the same as \csref{bibglsnewdualindexabbreviation}. +the same as \gls!{bibglsnewdualindexabbreviation}. The definition provided in the \ext{glstex} file is: -\begin{verbatim} -\providecommand{\bibglsnewtertiaryindexabbreviationentry}[7]{% - \longnewglossaryentry*{#1}{% - name={\protect\bibglsuseabbrvfont{#4}{\glscategory{#2}}},% - category={index},#3}{}% +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentry}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{category}=\marg{index},\idx{param}3}{}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglsnewtertiaryindexabbreviationentrysecondary} @@ -12680,14 +14518,14 @@ This command is used to define both the secondary and tertiary terms identified \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: -\begin{verbatim} -\providecommand{\bibglsnewtertiaryindexabbreviationentrysecondary}[8]{% - \newabbreviation[#3]{#1}{#6}{#7}% - \longnewglossaryentry*{#2}% - {name={\protect\bibglsuselongfont{#7}{\glscategory{#1}}},#4}% - {#8}% +\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{} + \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{} + \marg{\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\cs{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{} + \marg{\idx{param}8}\comment{} } -\end{verbatim} +\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 @@ -12704,6 +14542,12 @@ replicate that command. \formatdef{bibglsnewbibtexentry} This command is used to define the main term identified with \atentry{bibtexentry}. +The definition written to the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} \cssection{bibglsnewcontributor} @@ -12711,6 +14555,12 @@ This command is used to define the main term identified with This command is used to define terms identified with \atentry{contributor} (typically implicitly created through \atentry{bibtexentry}). +The definition written to the \ext{glstex} file is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsnewcontributor}}[4]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{} +} +\end{codeenv} \section{Location Lists and Cross-References} \label{sec:loclistdefs} @@ -12730,19 +14580,19 @@ location list (unless there are no locations, in which case just the \field{see} part is displayed without \gls{bibglsseesep}). This command is provided with: -\begin{verbatim} -\providecommand{\bibglsseesep}{, } -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsseesep}}\marg{, } +\end{codeenv} You can define this before you load the \ext{bib} file: -\begin{verbatim} -\newcommand{\bibglsseesep}{; } -\GlsXtrLoadResources[src={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsseesep}}\marg{; } +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} Or you can redefine it afterwards: -\begin{verbatim} -\GlsXtrLoadResources[src={entries}] -\renewcommand{\bibglsseesep}{; } -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsrenewcommand}\marg{\gls{bibglsseesep}}\marg{; } +\end{codeenv} \cssection{bibglsseealsosep} @@ -12787,43 +14637,43 @@ This defaults to \ics{delimN}. \formatdef{bibglslastDelimN} Separator between penultimate and final individual locations. -This defaults to \verb|,~| to discourage lonely locations. +This defaults to \code{,\idx{nbspchar}} to discourage lonely locations. \cssection{bibglspassim} \formatdef{bibglspassim} -If \csopt{max-loc-diff} is greater than 1, then any ranges that have +If \csopt{max-loc-diff} is greater than~1, then any ranges that have skipped over gaps will be followed by \gls{bibglspassim}, which is defined as: -\begin{verbatim} -\providecommand{\bibglspassim}{ \bibglspassimname} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}} +\end{codeenv} You can define this before you load the \ext{bib} file: -\begin{verbatim} -\newcommand{\bibglspassim}{} -\GlsXtrLoadResources[src={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglspassim}}\marg{} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} Or you can redefine it afterwards: -\begin{verbatim} -\GlsXtrLoadResources[src={entries}] -\renewcommand{\bibglspassim}{} -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsrenewcommand}\marg{\gls{bibglspassim}}\marg{} +\end{codeenv} \cssection{bibglspassimname} \formatdef{bibglspassimname} -The default definition is obtained from the \langxml. For example, with \file{bib2gls-en.xml} the provided -definition is -\begin{verbatim} -\providecommand{\bibglspassimname}{passim} -\end{verbatim} +The default definition is obtained from the \langxml. For example, with +\file{bib2gls-en.xml} the provided definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspassimname}}\marg{passim} +\end{codeenv} \cssection{bibglsrange} \formatdef{bibglsrange} -Explicit ranges formed using \glsopt[(]{format} and -\glsopt[)]{format} or \glsopt[(\meta{csname}]{format} and -\glsopt[)\meta{csname}]{format} (where \meta{csname} matches and is a +Explicit ranges formed using \glsopt[\idx{openrange}]{format} and +\glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and +\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a 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 @@ -12836,31 +14686,31 @@ consecutive locations. If an explicit range conflicts with a record, a warning will be issued and the conflicting record will be shifted to the front of the range inside the argument of \gls{bibglsinterloper}. -The default definition just does \meta{location}\csref{bibglsdelimN} +The default definition just does \meta{location}\gls!{bibglsdelimN} so that it fits neatly into the list. -For example, suppose on page~4 of my document I start a range with -\begin{verbatim} -\glsadd[format={(}]{sample} -\end{verbatim} -and end it on page~9 with -\begin{verbatim} -\glsadd[format={)}]{sample} -\end{verbatim} +For example, suppose on page~4 of my document I start a range with: +\begin{codeenv*} +\cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample} +\end{codeenv*} +and end it on page~9 with: +\begin{codeenv*} +\cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample} +\end{codeenv*} This forms an explicit range, but let's suppose on page~6 I -have -\begin{verbatim} -\gls[format={hyperbf}]{sample} -\end{verbatim} +have: +\begin{codeenv} +\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} +\end{codeenv} This record conflicts with the explicit range (which doesn't include -\code{hyperbf} in the format). This causes a warning and +\encap{hyperbf} in the format). This causes a warning and the conflicting entry will be moved before the start of the explicit range resulting in \textbf{6}, 4--9. Note that implicit ranges can't be formed from interlopers (nor can implicit ranges be merged with explicit ones), -so if \verb|\gls[format={hyperbf}]{sample}| also occurs -on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, +so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}} +also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, \textbf{8}, 4--9. Either remove the explicit range or remove the conflicting entries. (Alternatively, redefine \gls{bibglsinterloper} to ignore its argument, which will @@ -12869,23 +14719,24 @@ discard the conflicting entries.) \cssection{bibglspostlocprefix} \formatdef{bibglspostlocprefix} -If the \csopt{loc-prefix} option is on, \csref{bibglslocprefix} will -be inserted at the start of location lists. The command \gls{bibglspostlocprefix} -is placed after the prefix text. This command is provided with: -\begin{verbatim} -\providecommand{\bibglspostlocprefix}{\ } -\end{verbatim} +If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will +be inserted at the start of location lists, 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. You can define this before you load the \ext{bib} file: -\begin{verbatim} -\newcommand{\bibglspostlocprefix}{: } -\GlsXtrLoadResources[src={entries},loc-prefix] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} +\end{codeenv} Or you can redefine it afterwards: -\begin{verbatim} -\GlsXtrLoadResources[src={entries},loc-prefix] -\renewcommand{\bibglspostlocprefix}{: } -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}} +\cs{glsrenewcommand}\marg{\gls{bibglspostlocprefix}}\marg{: } +\end{codeenv} \cssection{bibglslocprefix} @@ -12895,52 +14746,52 @@ provided. If the glossary type has been provided by \csopt{type} (and \csopt{dual-type} if there are any dual entries) then the definition of \gls{bibglslocprefix} will be appended to the glossary preamble for the given type (or types if there are dual entries). -For example, if the document has -\begin{verbatim} -\GlsXtrLoadResources[type=main,loc-prefix={p.,pp.},src={entries}] -\end{verbatim} +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 the \ext{glstex} file: -\begin{verbatim} -\apptoglossarypreamble[main]{% - \providecommand{\bibglslocprefix}[1]{% - \ifcase##1 - \or p.\bibglspostlocprefix - \else pp.\bibglspostlocprefix - \fi - }% +\begin{codeenv} +\cs{apptoglossarypreamble}\oarg{main}\marg{\comment{} + \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \cs{ifcase}\idx{param}\idx{param}1 + \cmd{or} p.\gls{bibglspostlocprefix} + \cmd{else} pp.\gls{bibglspostlocprefix} + \cmd{fi} + }\comment{} } -\end{verbatim} +\end{codeenv} However, if the \csopt{type} key is missing, then the following will be added instead: -\begin{verbatim} -\appto\glossarypreamble{% - \providecommand{\bibglslocprefix}[1]{% - \ifcase#1 - \or p.\bibglspostlocprefix - \else pp.\bibglspostlocprefix - \fi - }% +\begin{codeenv} +\cs{appto}\cs{glossarypreamble}\marg{\comment{} + \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{} + \cs{ifcase}\idx{param}1 + \cmd{or} p.\gls{bibglspostlocprefix} + \cmd{else} pp.\gls{bibglspostlocprefix} + \cmd{fi} + }\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglspagename} \formatdef{bibglspagename} If \csopt[true]{loc-prefix} is used, then this command is provided -using the value of \code{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: -\begin{verbatim} -\providecommand{\bibglspagename}{Page} -\end{verbatim} +using the value of \idx{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspagename}}\marg{Page} +\end{codeenv} \cssection{bibglspagesname} \formatdef{bibglspagesname} If \csopt[true]{loc-prefix} is used, then this command is provided -using the value of \code{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: -\begin{verbatim} -\providecommand{\bibglspagesname}{Pages} -\end{verbatim} +using the value of \idx{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglspagesname}}\marg{Pages} +\end{codeenv} \cssection{bibglslocsuffix} @@ -12955,22 +14806,32 @@ This commands definition depends on the value provided by \csopt{loc-suffix}. For example, with \csopt[\ics{at}{\idx{periodchar}}]{loc-suffix} the command is defined as: -\begin{verbatim} -\providecommand{\bibglslocsuffix}[1]{\@.} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\ics{at}.} +\end{codeenv} (which ignores the argument). Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix} the command is defined as: -\begin{verbatim} -\providecommand{\bibglslocsuffix}[1]{\ifcase#1 A\or B\else C\fi} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\cs{ifcase}\idx{param}1 \meta{A}\cmd{or} \meta{B}\cmd{else} \meta{C}\cmd{fi}} +\end{codeenv} 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. +\cssection{bibglsprimary} + +\formatdef{bibglsprimary} +When the \csopt{save-primary-locations} option is used, the primary +locations 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 +formatted in the usual way. The default definition is to ignore the +first argument and simply do the second. + \cssection{bibglslocationgroup} \formatdef{bibglslocationgroup} @@ -12986,42 +14847,42 @@ defined (before the resources are loaded) or redefined (after the resources are loaded) as required. For example: -\begin{verbatim} -\newcommand*{\bibglslocationgroup}[3]{% - \ifnum#1=1 - #2: - \else - #2s: - \fi - #3% +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} + \cs{ifnum}\idx{param}1=1 + \idx{param}2: + \cmd{else} + \idx{param}2s: + \cmd{fi} + \idx{param}3\comment{} +} +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} } - -\GlsXtrLoadResources[ - loc-counters={equation,page},% group locations by counter - src={entries}% data in entries.bib -] -\end{verbatim} +\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. There are various ways to adapt this to translate the counter name to a different textual label, such as: -\begin{verbatim} -\providecommand{\pagename}{Page} -\providecommand{\pagesname}{Pages} -\providecommand{\equationname}{Equation} -\providecommand{\equationsname}{Equations} - -\newcommand*{\bibglslocationgroup}[3]{% - \ifnum#1=1 - \ifcsdef{#2name}{\csuse{#2name}}{#2}: - \else - \ifcsdef{#2sname}{\csuse{#2sname}}{#2s}: - \fi - #3% +\begin{codeenv} +\cs{providecommand}\marg{\cmd{pagename}}\marg{Page} +\cs{providecommand}\marg{\cmd{pagesname}}\marg{Pages} +\cs{providecommand}\marg{\cmd{equationname}}\marg{Equation} +\cs{providecommand}\marg{\cmd{equationsname}}\marg{Equations} +\strut +\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{} + \ics{ifnum}\idx{param}1=1 + \ics{ifcsdef}\marg{\idx{param}2name}\marg{\cs{csuse}\marg{\idx{param}2name}}\marg{\idx{param}2}: + \cmd{else} + \cs{ifcsdef}\marg{\idx{param}2sname}\marg{\cs{csuse}\marg{\idx{param}2sname}}\marg{\idx{param}2s}: + \cmd{fi} + \idx{param}3\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglslocationgroupsep} @@ -13029,23 +14890,23 @@ name to a different textual label, such as: When the \csopt{loc-counters} option is set, this command is used to separate each location sub-group. It may be defined before the resources are loaded: -\begin{verbatim} -\newcommand*{\bibglslocationgroupsep}{; } - -\GlsXtrLoadResources[ - loc-counters={equation,page},% group locations by counter - src={entries}% data in entries.bib -] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\end{codeenv} or redefined after the resources are loaded: -\begin{verbatim} -\GlsXtrLoadResources[ - loc-counters={equation,page},% group locations by counter - src={entries}% data in entries.bib -] - -\renewcommand*{\bibglslocationgroupsep}{; } -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[equation,page]{loc-counters},\comment{group locations by counter} + \csopt[entries]{src}\comment{data in entries.bib} +} +\strut +\cs{glsrenewcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; } +\end{codeenv} \cssection{bibglssupplemental} @@ -13075,29 +14936,40 @@ is the list of supplementary locations in \meta{external document}. \formatdef{bibglssupplementalsep} The separator between the main location list and the supplementary -location list. By default this is just \csref{bibglsdelimN}. This may be +location list. By default this is just \gls!{bibglsdelimN}. This may be defined before the resources are loaded: -\begin{verbatim} -\newcommand{\bibglssupplementalsep}{; } - -\GlsXtrLoadResources[ - supplemental-locations=supplDoc, - src={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } +\strut +\gls{GlsXtrLoadResources}\oarg{ + \csopt[supplDoc]{supplemental-locations}, + \csopt[entries]{src}} +\end{codeenv} or redefined after the resources are loaded: -\begin{verbatim} -\GlsXtrLoadResources[ - supplemental-locations=supplDoc, - src={entries}] - -\renewcommand{\bibglssupplementalsep}{; } -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[supplDoc]{supplemental-locations}, + \csopt[entries]{src}} +\strut +\cs{glsrenewcommand}\marg{\gls{bibglssupplementalsep}}\marg{; } +\end{codeenv} \cssection{bibglssupplementalsubsep} \formatdef{bibglssupplementalsubsep} The separator between the supplementary -location sub-lists. By default this is just \csref{bibglsdelimN}. +location sub-lists. By default this is just \gls!{bibglsdelimN}. + +\cssection{bibglshrefchar} + +\formatdef{bibglshrefchar} +Expands to a literal percent character followed by \meta{hex}. The +second argument is ignored. + +\cssection{bibglshrefunicode} + +\formatdef{bibglshrefunicode} +Expands to the second argument. The first argument is ignored. \section{Letter Groups} \label{sec:lettergroupdefs} @@ -13111,18 +14983,18 @@ afterwards. The base \isty{glossaries} package determines group titles through a fairly simplistic rule. Both \idx!{makeindex} and \idx!{xindy} write the -line +line: \nosecformatdef{glsgroupheading} to the associated glossary file at the start of each new letter group. For example, the \qt{A} letter group will be written as: -\begin{verbatim} -\glsgroupheading{A} -\end{verbatim} +\begin{codeenv} +\gls{glsgroupheading}\marg{A} +\end{codeenv} This is quite straightforward and the heading title can just be -\qt{A}. The \qt{Symbols} group is written as -\begin{verbatim} -\glsgroupheading{glssymbols} -\end{verbatim} +\qt{A}. The \qt{Symbols} group is written as: +\begin{codeenv} +\gls{glsgroupheading}\marg{glssymbols} +\end{codeenv} To allow for easy translation, the base \sty{glossaries} package has the simple rule: \begin{itemize} @@ -13140,7 +15012,7 @@ name. A problem arises when active characters occur in \meta{heading}, which happens with extended characters and \isty{inputenc}. -The \sty{glossaries-extra} package (as from version 1.14) provides +The \sty{glossaries-extra} package (as from version 1.14) provides: \nosecformatdef{glsxtrsetgrouptitle} to set the title for a group with the given label. The internal workings of \gls{glsgroupheading} are modified to use a slightly @@ -13159,12 +15031,12 @@ 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 -\idx{makeindex}, and with \idx{xindy} it requires a custom language +\idx!{makeindex}, and with \idx!{xindy} it requires a custom language module, which isn't a trivial task. With \bibgls, a different approach is used. The \iext{glstex} file created isn't comparable to the \iext{gls} file created by -\idx{makeindex} or \idx{xindy}. There's nowhere for \bibgls\ to +\idx!{makeindex} or \idx!{xindy}. There's nowhere for \bibgls\ to write the \gls{glsgroupheading} line as it isn't creating the code that typesets the glossary list. Instead it's creating the code that defines the entries. The actual group heading is inserted by @@ -13172,11 +15044,11 @@ defines the entries. The actual group heading is inserted by the entry has a \field{group} field and comparing it to the previous entry's \field{group} field. -The default behaviour of the group formation implemented by the sort +The behaviour of the group formation implemented by the sort methods may be changed with \csopt{group-formation}. With any setting other than \csopt[default]{group-formation}, the group label -is set to \cs{bibglsunicodegroup} and the title is set to -\cs{bibglsunicodegrouptitle} (see below) otherwise the label and +is set to \format{bibglsunicodegroup} and the title is set to +\format{bibglsunicodegrouptitle} (see below) otherwise the label and title are determined by the sort method. The collators used by the locale and letter-based rules save the @@ -13187,7 +15059,7 @@ according to the rule): \item \meta{title} The group's title. This is typically title-cased. For example, if the rule recognises the digraph \qt{dz}, then the title is \qt{Dz}. Exceptions to this are included in the \langxml. -If the key \code{grouptitle.case.\meta{lc}} exists, where +If the key \idx{grouptitle.case.lc} exists, where \meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value of that key is used instead. For example, the Dutch digraph \qt{ij} should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: @@ -13203,16 +15075,16 @@ or the code point for the given letter, depending on the sort method. \item \meta{type} The entry's glossary type. If not known, this will be empty. (\bibgls\ won't know if you've modified the associated -\csfmt{bibglsnew...} command to set the \field{type}. It can only +\csfmt{bibglsnew\ldots} command to set the \field{type}. It can only know the type if it's in the original \ext{bib} definition or is set using resource options such as \csopt{type}.) \end{itemize} The \field{group} field is then set using: -\begin{alltt} -group=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}} -\end{alltt} -This field needs to expand to a simple label, which \csref{bibglslettergroup} +\begin{codeenv} +\field{group}=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}} +\end{codeenv} +This field needs to expand to a simple label, which \gls!{bibglslettergroup} is designed to do. Note that non-letter groups are dealt with separately (see below). @@ -13233,55 +15105,55 @@ the \field{group} assignment for one of the entries in that group). The \meta{cs} argument is the control sequence used in the \field{group} field to obtain the label from \meta{specs}. For -example, if the highest \meta{id} is 2147418112 from +example, if the highest \meta{id} is 2147418112 from: \begin{codeenv} \field{group}=\marg{\gls{bibglslettergroup}\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} \end{codeenv} -then the last group is identified with -\begin{verbatim} -\bibglssetlastgrouptitle{\bibglslettergroup}{{Ø}{Ø}{2147418112}{}} -\end{verbatim} +then the last group is identified with: +\begin{codeenv} +\gls{bibglssetlastgrouptitle}\marg{\gls{bibglslettergroup}}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}} +\end{codeenv} 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: -\begin{verbatim} -\newcommand*{\bibglssetlastgrouptitle}[2]{% - \glsxtrsetgrouptitle{#1#2}{Foreign Words}} - -\GlsXtrLoadResources[sec={entries}] -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\end{codeenv} If you need to change a particular group title, then it has to be done after the \idx{resourceset}: -\begin{verbatim} -\GlsXtrLoadResources[sec={entries}] - -\glsxtrsetgrouptitle - {\bibglslettergroup{{Ø}{Ø}{2147418112}{}}}% label - {Foreign Words}% title -\end{verbatim} +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\cs{glsxtrsetgrouptitle} + \marg{\gls{bibglslettergroup}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}}\comment{label} + \marg{Foreign Words}\comment{title} +\end{codeenv} \cssection{bibglssetlettergrouptitle} For each \idx{lettergroup} that's detected, \bibgls\ will write the line: \formatdef{bibglssetlettergrouptitle} -in the \ext{glstex} file, which sets the group's title using +in the \ext{glstex} file, which sets the group's title using: +\begin{codeenv} \format{glsxtrsetgrouptitle} +\end{codeenv} where the \meta{group label} part matches the corresponding \field{group} value. Note that \gls{bibglssetlettergrouptitle} only has a single argument, but that argument contains the four arguments needed by -\csref{bibglslettergroup} and \csref{bibglslettergrouptitle}. +\gls!{bibglslettergroup} and \gls!{bibglslettergrouptitle}. These arguments are as described above. If \gls{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra} version 1.14 onwards), then \gls{bibglssetlettergrouptitle} will be -defined as -\begin{verbatim} -\providecommand{\bibglssetlettergrouptitle}[1]{% - \glsxtrsetgrouptitle{\bibglslettergroup#1}{\bibglslettergrouptitle#1}} -\end{verbatim} +defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetlettergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglslettergroup}\idx{param}1}\marg{\gls{bibglslettergrouptitle}\idx{param}1}} +\end{codeenv} If an earlier version of \sty{glossaries-extra} is used, then this function can't be supported and the command will be defined to simply ignore its argument. This will fall back on the original @@ -13294,17 +15166,17 @@ modification. After the resource file has been loaded, you can adjust the title of a specific group, but you'll need to check the \ext{glstex} file for the appropriate arguments. For example, if the \ext{glstex} file contains: -\begin{alltt} +\begin{codeenv} \gls{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}} -\end{alltt} +\end{codeenv} but you actually want the group title to appear as \qt{\AE\ (AE)} instead of just \qt{\AE}, then after the resource file has been loaded you can do: -\begin{alltt} +\begin{codeenv} \gls{glsxtrsetgrouptitle} - \marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\% label - \marg{\AE\ (AE)}\% title -\end{alltt} + \marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\comment{label} + \marg{\AE\ (AE)}\comment{title} +\end{codeenv} \cssection{bibglslettergroup} @@ -13325,98 +15197,95 @@ against any expansion issues that may arise with characters outside the basic Latin set. For example: -\begin{verbatim} -@entry{angstrom, - name={\AA ngstr\"om} - description={a unit of length equal to one hundred-millionth +\begin{codeenv} +\atentry{entry}\marg{angstrom, + \field{name}=\marg{\cs{AA} ngstr\cs{umlaut}om} + \field{description}=\marg{a unit of length equal to one hundred-millionth of a centimetre} } -\end{verbatim} +\end{codeenv} The \field{sort} value is \qtt{\AA ngstr\"om}. With \csopt[en]{sort} the \meta{title} part will be \code{A} but with \csopt[sv]{sort} the \meta{title} part will be \code{\AA}. In both cases the \meta{letter} argument will be \code{\AA}. Take care if you are using a script that needs encapsulating. For -example, with the \isty{CJKutf8} package the CJK characters need to +example, with the \isty{CJKutf8} package the \idx{CJK} characters need to be placed within the \env{CJK} environment, so any letter group -titles that contain CJK characters will need special attention. +titles that contain \idx{CJK} characters will need special attention. For example, suppose the \ext{bib} file contains entries in the form: -\begin{alltt} +\begin{codeenv} \atentry{dualentry}\marg{\meta{label}, - name = \marg{\ics{cjkname}\margm{CJK characters}}, - description = \margm{English description} + \field{name} = \marg{\ics{cjkname}\margm{\idx{CJK} characters}}, + \field{description} = \margm{English translation} } -\end{alltt} +\end{codeenv} and the document contains: -\begin{verbatim} -\usepackage{CJKutf8} -\usepackage[record,style=indexgroup,nomain]{glossaries-extra} - -\newglossary*{japanese}{Japanese to English} -\newglossary*{english}{English to Japanese} - -\newrobustcmd{\cjkname}[1]{\begin{CJK}{UTF8}{min}#1\end{CJK}} -\glsnoexpandfields - -\GlsXtrLoadResources[ - src=testcjk,% bib file - sort={ja-JP},% locale used to sort primary entries - dual-sort={en-GB},% locale used to sort secondary entries - type=japanese,% put the primary entries in the 'japanese' glossary - dual-type=english,% put the primary entries in the 'english' glossary - dual-prefix={en.} -] -\end{verbatim} -then CJK characters will appear in the \meta{title} argument of +\begin{codeenv} +\cmd{usepackage}\marg{CJKutf8} +\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style},\styopt{nomain}]\marg{glossaries-extra} +\strut +\cs{newglossary*}\marg{japanese}\marg{Japanese to English} +\cs{newglossary*}\marg{english}\marg{English to Japanese} +\strut +\ics{newrobustcmd}\marg{\cmd{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}} +\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[en.]{dual-prefix} +} +\end{codeenv} +then \idx{CJK} characters will appear in the \meta{title} argument of \gls{bibglslettergrouptitle} which causes a problem because they need to be encapsulated within the \env{CJK} environment. This can be more -conveniently done with the user supplied \csfmt{cjkname}, but the CJK +conveniently done with the user supplied \csfmt{cjkname}, but the \idx{CJK} characters need to be protected from expansion so \ics{unexpanded} is also needed. The new definition of \gls{bibglslettergrouptitle} needs to be defined before \gls{GlsXtrLoadResources}. For example: -\begin{verbatim} -\newcommand{\bibglslettergrouptitle}[4]{\unexpanded{\cjkname{#1}}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\cmd{cjkname}\marg{\idx{param}1}}} +\end{codeenv} There's a slight problem here in that the English letter group titles also end up encapsulated. An alternative approach is to use the \meta{type} part to provide different forms. For example: -\begin{verbatim} -\newcommand*{\englishlettergroup}[1]{#1} -\newcommand*{\japaneselettergroup}[1]{\cjkname{#1}} -\newcommand{\bibglslettergrouptitle}[4]{% - \unexpanded{\csuse{#4lettergroup}{#1}}} -\end{verbatim} -(\csfmt{csuse} is provided by \sty{etoolbox}, which is automatically -loaded by the \styfmt{glossaries} package.) +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1} +\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\cmd{cjkname}\marg{\idx{param}1}} +\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{} + \cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}} +\end{codeenv} \cssection{bibglssetothergrouptitle} The label and title for \idxpl{symbolgroup} are dealt with in a similar way to the \idxpl!{lettergroup}, but in this -case the title is set using +case the title is set using: \formatdef{bibglssetothergrouptitle} This is defined in an analogous manner: -\begin{verbatim} -\providecommand{\bibglssetothergrouptitle}[1]{% - \glsxtrsetgrouptitle{\bibglsothergroup#1}{\bibglsothergrouptitle#1}} -\end{verbatim} -where the group label is obtained using \csref{bibglsothergroup} and -the group title is obtained from \csref{bibglsothergrouptitle}. +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetothergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsothergroup}\idx{param}1}\marg{\gls{bibglsothergrouptitle}\idx{param}1}} +\end{codeenv} +where the group label is obtained using \gls!{bibglsothergroup} and +the group title is obtained from \gls!{bibglsothergrouptitle}. Note that since non-alphabetic characters don't have upper or lower case versions, there are only three arguments. The other difference between this and the letter group version is that the \meta{id} is given in hexadecimal format (corresponding to the character code). For example, suppose my \ext{bib} file contains: -\begin{verbatim} -@entry{sauthor, - name={/Author}, - description = {author string} +\begin{codeenv} +\atentry{entry}\marg{sauthor, + \field{name}=\marg{/Author}, + \field{description} = \marg{author string} } -\end{verbatim} +\end{codeenv} If a locale sort is used, the leading slash \code{/} will be ignored and this entry will belong to the \qt{A} letter group using the letter commands described above. If, instead, one of the @@ -13424,9 +15293,9 @@ character code sort methods are used, such as \csopt[letter-case]{sort}, then this entry will be identified as belonging to a symbol (or \qt{other}) group and the title will be set using: -\begin{verbatim} -\bibglssetothergrouptitle{{/}{2F}{}} -\end{verbatim} +\begin{codeenv} +\gls{bibglssetothergrouptitle}\marg{\marg{/}\marg{2F}\marg{}} +\end{codeenv} \cssection{bibglsothergroup} @@ -13444,9 +15313,11 @@ expands to \ics{glssymbolsgroupname} by default. \cssection{bibglssetemptygrouptitle} -Used when the sort value devolves to an empty string. This command +Used when the sort value degenerates to an empty string. This command sets the label and title. \formatdef{bibglssetemptygrouptitle} +(Note the inner group, as with the other similar +\csfmt{bibglsset\ldots grouptitle} commands.) \cssection{bibglsemptygroup} @@ -13470,11 +15341,11 @@ or symbol groups. These behave in an analogous way to the above. \formatdef{bibglssetnumbergrouptitle} In this case \meta{value} is the actual numeric sort value, and \meta{id} is a decimal number obtained from converting \meta{value} -to an integer. This command is defined as -\begin{verbatim} -\providecommand{\bibglssetnumbergrouptitle}[1]{% - \glsxtrsetgrouptitle{\bibglsnumbergroup#1}{\bibglsnumbergrouptitle#1}} -\end{verbatim} +to an integer. This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetnumbergrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsnumbergroup}\idx{param}1}\marg{\gls{bibglsnumbergrouptitle}\idx{param}1}} +\end{codeenv} \cssection{bibglsnumbergroup} @@ -13488,6 +15359,20 @@ The \idx{numbergroup} title is obtained from: \formatdef{bibglsnumbergrouptitle} This just defaults to \ics{glsnumbersgroupname}. +\cssection{bibglssetdatetimegrouptitle} + +The date-time sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{datetimegroup}. These behave in an analogous way to the above. +\formatdef{bibglssetdatetimegrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetdatetimegrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle} + \marg{\gls{bibglsdatetimegroup}\idx{param}1}\comment{} + \marg{\gls{bibglsdatetimegrouptitle}\idx{param}1}\comment{} +} +\end{codeenv} + \cssection{bibglsdatetimegroup} \formatdef{bibglsdatetimegroup} @@ -13495,11 +15380,12 @@ This just defaults to \ics{glsnumbersgroupname}. This command is used for \idx{datetimegroup} labels with \optfmt{datetime} sorting (\tableref{tab:sortoptionsdatetime}). This has ten arguments, which means a little trickery is needed to deal with the tenth argument. -The default definition is -\begin{verbatim} -\providecommand{\bibglsdatetimegroup}[9]{#1#2#3\@firstofone} -\end{verbatim} -This forms the group label from the year, month, day and \meta{type}. +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdatetimegroup}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\ics{@firstofone}} +\end{codeenv} +This forms the group label from the year \meta{YYYY}, month \meta{MM}, +day \meta{DD} and \meta{type}. \cssection{bibglsdatetimegrouptitle} @@ -13507,23 +15393,35 @@ This forms the group label from the year, month, day and \meta{type}. This command is used for \idx{datetimegroup} titles with \optfmt{datetime} sorting (\tableref{tab:sortoptionsdatetime}). -The default definition is -\begin{verbatim} -\providecommand{\bibglsdatetimegrouptitle}[9]{#1-#2-#3\@gobble} -\end{verbatim} +The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdatetimegrouptitle}}[9]\marg{\idx{param}1-\idx{param}2-\idx{param}3\ics{@gobble}} +\end{codeenv} This sets the title to the numeric \code{\meta{YYYY}-\meta{MM}-\meta{DD}} but may be redefined as appropriate. +\cssection{bibglssetdategrouptitle} + +The date sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{dategroup} (the time isn't included). These behave in an +analogous way to the above. +\formatdef{bibglssetdategrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssetdategrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsdategroup}\idx{param}1}\marg{\gls{bibglsdategrouptitle}\idx{param}1}} +\end{codeenv} + \cssection{bibglsdategroup} \formatdef{bibglsdategroup} This command is used for \idx{dategroup} labels with \optfmt{date} (no time) sorting -(\tableref{tab:sortoptionsdatetime}). The default definition is -\begin{verbatim} -\providecommand{\bibglsdategroup}[7]{#1#2#4#7} -\end{verbatim} +(\tableref{tab:sortoptionsdatetime}). The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7} +\end{codeenv} This forms the group label from the year, month, era and type. In this case, the era is a textual representation not the numeric value used in calculating the sort value. @@ -13532,18 +15430,34 @@ value used in calculating the sort value. \formatdef{bibglsdategrouptitle} This command is used for \idx{dategroup} titles with \optfmt{date} (no time) sorting -(\tableref{tab:sortoptionsdatetime}). The default definition is -\begin{verbatim} -\providecommand{\bibglsdategrouptitle}[7]{#1-#2} -\end{verbatim} +(\tableref{tab:sortoptionsdatetime}). The default definition is: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\idx{param}1-\idx{param}2} +\end{codeenv} This just sets the title to the numeric year-month form \code{\meta{YYYY}-\meta{MM}}. +\cssection{bibglssettimegrouptitle} + +The time sort methods (\tableref{tab:sortoptionsdatetime}) +create \idxpl{timegroup} (the date isn't included). These behave in an +analogous way to the above. +\formatdef{bibglssettimegrouptitle} +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglssettimegrouptitle}}[1]\marg{\comment{} + \cs{glsxtrsetgrouptitle}\marg{\gls{bibglstimegroup}\idx{param}1}\marg{\gls{bibglstimegrouptitle}\idx{param}1}} +\end{codeenv} + \cssection{bibglstimegroup} \formatdef{bibglstimegroup} This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sorting (\tableref{tab:sortoptionsdatetime}). +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglstimegroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}7} +\end{codeenv} \cssection{bibglstimegrouptitle} @@ -13551,6 +15465,10 @@ This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sor This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting (\tableref{tab:sortoptionsdatetime}). +This command is defined as: +\begin{codeenv} +\cs{providecommand}\marg{\gls{bibglstimegrouptitle}}[7]\marg{\idx{param}1} +\end{codeenv} \cssection{bibglssetunicodegrouptitle} @@ -13558,8 +15476,8 @@ This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sor This command is used to assign the group titles when the group formation is set to any value other than the default. For example, this command will be used with \csopt[codepoint]{group-formation}. -The label is obtained from \cs{bibglsunicodegroup} and the title is -obtained from \cs{bibglsunicodegrouptitle}. +The label is obtained from \gls{bibglsunicodegroup} and the title is +obtained from \gls{bibglsunicodegrouptitle}. \cssection{bibglsunicodegroup} @@ -13585,50 +15503,51 @@ identifies both the Unicode category and script associated with The \meta{character} is the first significant character of the sort value. The \meta{id} is the hexadecimal code of (possibly decomposed) -\meta{character}. +\meta{character}. The case of codepoint \meta{id} may or may not correspond +to the case of \meta{character}. For example, with \csopt[codepoint]{group-formation}, an unset \field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a significant character distinct from \qt{A} then the \field{group} field will be assigned using: -\begin{verbatim} -group={\bibglsunicodegroup{å}{Å}{C5}{}} -\end{verbatim} +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{å}\marg{Å}\marg{C5}\marg{}} +\end{codeenv} whereas with \csopt[unicode category and script]{group-formation} it will be: -\begin{verbatim} -group={\bibglsunicodegroup{Lu.LATIN}{Å}{C5}{}} -\end{verbatim} +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{Lu.LATIN}\marg{Å}\marg{C5}\marg{}} +\end{codeenv} (\idx!{uppercase} Latin letter). If instead \qt{\AA} is considered equivalent to \qt{A} according to the collator, then with \csopt[codepoint]{group-formation}, the value will be: -\begin{verbatim} -group={\bibglsunicodegroup{a}{Å}{61}{}} -\end{verbatim} -Note that the \meta{id} is now \hex{61} (the decomposed \qt{A}) not -\hex{C5}. +\begin{codeenv} +\field{group}=\marg{\gls{bibglsunicodegroup}\marg{a}\marg{Å}\marg{61}\marg{}} +\end{codeenv} +Note that the \meta{id} is now \hex{61} (the decomposed \qt{A} +converted to \idx{lowercase}) not \hex{C5}. \cssection{bibglsunicodegrouptitle} \formatdef{bibglsunicodegrouptitle} -The title for Unicode group formations by default simply expands to +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}): -\begin{verbatim} -\newcommand{\bibglsunicodegrouptitle}[4]{% - \ifnum"#3>64 - \ifnum"#3 < 91 - A--Z% - \else - \ifnum"#3 > 96 - \ifnum"#3 < 123 - A--Z% - \fi - \fi - \fi - \fi +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{} + \ifnumhex{\idx{param}3}>64 + \ifnumhex{\idx{param}3} < 91 + A-{}-Z\comment{} + \cmd{else} + \ifnumhex{\idx{param}3} > 96 + \ifnumhex{\idx{param}3} < 123 + A-{}-Z\comment{} + \cmd{fi} + \cmd{fi} + \cmd{fi} + \cmd{fi} } -\end{verbatim} +\end{codeenv} This will make the title \qt{A--Z} if \meta{id} is greater than 64 and less than 91 or greater than 96 and less than 123 (and will be empty otherwise). @@ -13637,12 +15556,12 @@ Note that this setting can create an odd effect if the sorting causes the groups to be split up. For example, if some of the sort values start with extended or non-Latin characters this can break up the groups. First check how the group labels are assigned using: -\begin{verbatim} -\newcommand{\bibglsunicodegrouptitle}{\bibglsunicodegroup} -\end{verbatim} -then adjust the definition of \cs{bibglsunicodegroup} until the +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}\marg{\gls{bibglsunicodegroup}} +\end{codeenv} +then adjust the definition of \gls{bibglsunicodegroup} until the grouping is correct, and then change the definition of -\cs{bibglsunicodegrouptitle} so that the title is correct. +\gls{bibglsunicodegrouptitle} so that the title is correct. \cssection{bibglshypergroup} @@ -13667,35 +15586,35 @@ The default definition simply does \meta{name}. This command is used if the child and parent name's are identical. For example, suppose the \ext{bib} file contains: -\begin{verbatim} -@index{super.glossary, name={glossary}} - -@entry{glossarycol, - parent={super.glossary}, - description={collection of glosses} +\begin{codeenv} +\atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}} +\strut +\atentry{entry}\marg{glossarycol, + \field{parent}=\marg{super.glossary}, + \field{description}=\marg{collection of glosses} } - -@entry{glossarylist, - parent={super.glossary}, - description={list of technical words} +\strut +\atentry{entry}\marg{glossarylist, + \field{parent}=\marg{super.glossary}, + \field{description}=\marg{list of technical words} } -\end{verbatim} +\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: -\begin{verbatim} -\documentclass{article} - -\usepackage[record,subentrycounter,style=treenoname]{glossaries-extra} - -\GlsXtrLoadResources[src={entries}] - -\begin{document} -\gls{glossarycol} (collection) vs \gls{glossarylist} (list). - -\printunsrtglossary -\end{document} -\end{verbatim} +\begin{codeenv} +\cmd{documentclass}\marg{article} +\strut +\cmd{usepackage}[\styopt{record},\istyopt{subentrycounter},\styopt[treenoname]{style}]\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}} +\strut +\cmd{begin}\marg{document} +\cs{gls}\marg{glossarycol} (collection) vs \cs{gls}\marg{glossarylist} (list). +\strut +\cs{printunsrtglossary} +\cmd{end}\marg{document} +\end{codeenv} This uses one of the glossary styles designed for homographs and the glossary has the structure: \begin{flushleft} @@ -13715,10 +15634,10 @@ the child is moved up a hierarchical level. With 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 appear as \qt{glossary, glossary} so instead the name is -set to -\begin{verbatim} -\bibglsflattenedhomograph{glossary}{super.glossary} -\end{verbatim} +set to: +\begin{codeenv} +\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). @@ -13737,9 +15656,9 @@ Used by the \csopt[presort]{flatten-lonely} option. This defaults to just \meta{child name}. If you want to change this, remember that you can let the interpreter know by adding the definition to \atentry{preamble}. For example: -\begin{verbatim} -@preamble{"\providecommand{\bibglsflattenedchildpresort}[2]{#1 (#2)}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}} +\end{codeenv} \cssection{bibglsflattenedchildpostsort} @@ -13754,9 +15673,9 @@ upper-casing. If either command is redefined to alter the ordering, then this can confuse the case-changing mechanism, in which case you may want to consider switching on the expansion of the \field{name} field using: -\begin{verbatim} -\glssetexpandfield{name} -\end{verbatim} +\begin{codeenv} +\gls{glssetexpandfield}\marg{name} +\end{codeenv} (before \gls{GlsXtrLoadResources}). \section{Other} @@ -13765,10 +15684,10 @@ field using: \formatdef{bibglshyperlink} Used by the \hyperref[sec:dualoptsbacklinks]{back link options}, -this just defaults to -\begin{alltt} +this just defaults to: +\begin{codeenv} \ics{glshyperlink}\oargm{text}\margm{label} -\end{alltt} +\end{codeenv} \cssection{bibglssetwidest} @@ -13776,15 +15695,18 @@ this just defaults to 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. This is defined as: -\begin{verbatim} -\providecommand*{\bibglssetwidest}[2]{\glsupdatewidest[#1]{#2}} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} +if \ics{glsxtrSetWidest} has been defined, or: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsupdatewidest}\oarg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} if \ics{glsupdatewidest} is defined, otherwise it will be -defined to use -\ics{glssetwidest}: -\begin{verbatim} -\providecommand*{\bibglssetwidest}[2]{\glssetwidest[#1]{#2}} -\end{verbatim} +defined to use \ics{glssetwidest}: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glssetwidest}\oarg{\idx{param}1}\marg{\idx{param}2}} +\end{codeenv} Since this isn't scoped, this will affect other glossaries. In general, if you have more than one glossary it's best to set the \field{type} using options like \csopt{type}. @@ -13795,18 +15717,24 @@ set the \field{type} using options like \csopt{type}. This is used by \csopt{set-widest} to set the widest name for the given hierarchical level where the glossary type is known. This is defined as: -\begin{verbatim} -\providecommand*{\bibglssetwidestfortype}[3]{% - \apptoglossarypreamble[#1]{\glsupdatewidest[#2]{#3}}% +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{glsxtrSetWidest}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\comment{} } -\end{verbatim} +\end{codeenv} +if \ics{glsxtrSetWidest} has been defined, or: +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glsupdatewidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} +} +\end{codeenv} if \ics{glsupdatewidest} is defined, otherwise it will be defined to use \ics{glssetwidest}: -\begin{verbatim} -\providecommand*{\bibglssetwidestfortype}[3]{% - \apptoglossarypreamble[#1]{\glssetwidest[#2]{#3}}% +\begin{codeenv} +\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{} + \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glssetwidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{} } -\end{verbatim} +\end{codeenv} Since the glossary preamble is scoped, this won't affect other glossaries. @@ -13817,8 +15745,13 @@ This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} when all \field{name} fields end up as an empty string when interpreted by \bibgls. This typically means that all the \field{name} fields contain unknown commands. This fallback command -will use \ics{glsFindWidestLevelTwo}, which sets the widest name for -the top-level and first two sub-levels. +will use: +\begin{codeenv} +\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. \cssection{bibglssetwidestfortypefallback} @@ -13838,8 +15771,12 @@ This is used by \csopt{set-widest} instead of \gls{bibglssetwidest} when all \field{name} fields end up as an empty string when interpreted by \bibgls. This typically means that all the \field{name} fields contain unknown commands. This fallback command -will use \ics{glsFindWidestTopLevelName}, which sets the widest name for -the top-level. +will use: +\begin{codeenv} +\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. \cssection{bibglssetwidesttoplevelfortypefallback} @@ -13858,65 +15795,121 @@ preamble of the given type. This is used when \csopt{bibtex-contributor-fields} is set. The definition depends on whether or not \ics{DTLformatlist} has been defined: -\begin{verbatim} -\ifdef\DTLformatlist -{% datatool v2.28+ - \providecommand*{\bibglscontributorlist}[2]{\DTLformatlist{#1}} -} -{% datatool v2.27 or earlier - \providecommand*{\bibglscontributorlist}[2]{% - \def\bibgls@sep{}% - \@for\bibgls@item:=#1\do{\bibgls@sep\bibgls@item\def\bibgls@sep{, }}% +\begin{codeenv} +\ics{ifdef}\cs{DTLformatlist} +\marg{\comment{datatool v2.28+} + \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\cs{DTLformatlist}\marg{\idx{param}1}} +} +\marg{\comment{datatool v2.27 or earlier} + \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} + \ics{def}\cmd{bibgls@sep}\marg{}\comment{} + \ics{@for}\cmd{bibgls@item}:=\idx{param}1\cmd{do}\marg{\cmd{bibgls@sep}\cmd{bibgls@item}\cs{def}\cmd{bibgls@sep}\marg{, }}\comment{} } } -\end{verbatim} +\end{codeenv} The second argument allows you to provide definitions like: -\begin{verbatim} -\newcommand*{\bibglscontributorlist}[2]{% - \ifcase#2 - \or - name: - \else - names: - \fi - \DTLformatlist{#1}% +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{} + \cs{ifcase}\idx{param}2 + \cmd{or} + name: + \cmd{else} + names: + \cmd{fi} + \cs{DTLformatlist}\marg{\idx{param}1}\comment{} } -\end{verbatim} +\end{codeenv} \cssection{bibglscontributor} \formatdef{bibglscontributor} This is used when \csopt{bibtex-contributor-fields} is set. The -definition depends on \csopt{contributor-order}. Note that if you have multiple -resource sets, that option governs the way \bibgls's version of -\gls{bibglscontributor} behaves. The definition is written to the -\ext{glstex} using \cs{providecommand}, so \LaTeX\ will only pick up -the first definition. +definition depends on the value of \csopt{contributor-order}. Note that if you +have multiple resource sets, that option governs the way \bibgls's version of +\gls{bibglscontributor} behaves. The definition is written to the \ext{glstex} +using \cs{providecommand}, so \LaTeX\ will only pick up the first definition. + +\cssection{bibglsprimaryprefixlabel} + +\formatdef{bibglsprimaryprefixlabel} +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. + +\cssection{bibglsdualprefixlabel} + +\formatdef{bibglsdualprefixlabel} +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. + +\cssection{bibglstertiaryprefixlabel} + +\formatdef{bibglstertiaryprefixlabel} +A hook to pick up the 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. + +\cssection{bibglsexternalprefixlabel} + +\formatdef{bibglsexternalprefixlabel} +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 +loaded. \cssection{bibglshashchar} \formatdef{bibglshashchar} -Expands to a literal hash character (\idx{hashchar}). +Expands to a literal hash character (\,\idx{hashchar}\,). \cssection{bibglsunderscorechar} \formatdef{bibglsunderscorechar} -Expands to a literal underscore character (\idx{underscorechar}). +Expands to a literal underscore character (\,\idx{underscorechar}\,). \cssection{bibglsdollarchar} \formatdef{bibglsdollarchar} -Expands to a literal dollar character (\idx{dollarchar}). +Expands to a literal dollar character (\,\idx{dollarchar}\,). \cssection{bibglsampersandchar} \formatdef{bibglsampersandchar} -Expands to a literal ampersand character (\idx{ampchar}). +Expands to a literal ampersand character (\,\idx{ampchar}\,). \cssection{bibglscircumchar} \formatdef{bibglscircumchar} -Expands to a literal circumflex character (\idx{circumchar}). +Expands to a literal circumflex character (\,\idx{circumchar}\,). + +\cssection{bibglsuppercase} + +\formatdef{bibglsuppercase} +Converts \meta{text} to \idx{uppercase}. This just uses +\ics{MakeTextUppercase} by default. + +\cssection{bibglslowercase} + +\formatdef{bibglslowercase} +Converts \meta{text} to \idx{lowercase}. This just uses +\ics{MakeTextLowercase} by default. + +\cssection{bibglstitlecase} + +\formatdef{bibglstitlecase} +Converts \meta{text} to \idx{titlecase}. This just uses +\ics{capitalisewords} by default. + +\cssection{bibglsfirstuc} + +\formatdef{bibglsfirstuc} +Converts the first letter of \meta{text} to \idx{uppercase}. This just uses +\ics{makefirstuc} by default. \chapter{Converting Existing \iext{tex} to \iext{bib}} \label{sec:gls2bib} @@ -13958,7 +15951,7 @@ If you want to strip the spaces, use an empty string for \meta{replacement}. You'll need to delimit this according to your operating system. For example: \begin{verbatim} -gls2bib --space-sub '' entries.tex entries.bib +convertgls2bib --space-sub '' entries.tex entries.bib \end{verbatim} \item[\longargfmt{ignore-sort}] Ignore the \field{sort} field. @@ -13980,37 +15973,35 @@ quit. information and quit. \end{description} -This application recognises the commands listed below. Avoid any -overly complicated code within the \ext{tex} file. The \TeX\ parser -library isn't a \TeX\ engine! The \ext{tex} file doesn't need to be -a complete document, but if you want certain commands recognised -from packages that the \TeX\ parser library supports, you'll need to -include \ics{usepackage} in the \ext{tex} file. -In all cases below, if \meta{\keyvallist} contains -\begin{alltt} -see=[\ics{seealsoname}]\margm{label(s)} -\end{alltt} -this will be substituted with -\begin{alltt} -seealso=\margm{label(s)} -\end{alltt} +This application recognises the commands listed below. Avoid any overly +complicated code within the \ext{tex} file. The +\hyperref[sec:texparserlib]{\TeX\ parser library} isn't a \TeX\ engine! The +\ext{tex} file doesn't need to be a complete document, but if you want certain +commands recognised from packages that the \TeX\ parser library supports, +you'll need to include \ics{usepackage} in the \ext{tex} file. +In all cases below, if \meta{\keyvallist} contains: +\begin{codeenv*} +\field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}} +\end{codeenv*} +this will be substituted with: +\begin{codeenv*} +\field{seealso}=\margm{label(s)} +\end{codeenv*} For example: -\begin{verbatim} -\newterm[see={[\seealsoname]goose}]{duck} -\end{verbatim} -will be written as -\begin{verbatim} -@index{duck, - seealso = {goose} +\begin{codeenv} +\gls{newterm}\oarg{\field{see}=\marg{[\cs{seealsoname}]goose}}\marg{duck} +\end{codeenv} +will be written as: +\begin{codeenv} +\atentry{index}\marg{duck, + \field{seealso} = \marg{goose} } -\end{verbatim} -(The \field{seealso} key is provided by \sty{glossaries-extra} -v1.16+.) +\end{codeenv} -Additionally, if \meta{\keyvallist} contains -\begin{alltt} -type=\marg{\ics{glsdefaulttype}} -\end{alltt} +Additionally, if \meta{\keyvallist} contains: +\begin{codeenv} +\field{type}=\marg{\ics{glsdefaulttype}} +\end{codeenv} then this field will be ignored. (This \field{type} value is recommended in \meta{\keyvallist} when loading files with \ics{loadglsentries}\oargm{type}\margm{file} to allow the optional @@ -14052,38 +16043,35 @@ fields switched explicitly switched off by default with \cssection[\section]{newglossaryentry} The base \styfmt{glossaries} package provides: \formatdef{newglossaryentry} - This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{entry}\marg{\meta{label}, \meta{\keyvallist} } -\end{alltt} - +\end{codeenv} \ics{newentry} is recognised as a synonym of \gls{newglossaryentry}. \cssection[\section]{provideglossaryentry} The base \styfmt{glossaries} package provides: \formatdef{provideglossaryentry} This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{entry}\marg{\meta{label}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} but only if \meta{label} hasn't already been defined. \cssection[\section]{longnewglossaryentry} The base \styfmt{glossaries} package provides: \formatdef{longnewglossaryentry} This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{entry}\marg{\meta{label}, \meta{\keyvallist}, - description = \margm{description} + \field{description} = \margm{description} } -\end{alltt} - +\end{codeenv} The starred version provided by the \styfmt{glossaries-extra} package is also recognised. The unstarred version strips trailing spaces from \meta{description}. (This doesn't add \ics{nopostdesc}, but @@ -14100,53 +16088,52 @@ As above, but only if \meta{label} hasn't already been defined. The base \styfmt{glossaries} package provides: \formatdef{newterm} (when the \styopt{index} option is used). - This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{index}\marg{\meta{label}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} if the optional argument is present, otherwise it's just converted to: -\begin{alltt} +\begin{codeenv} \atentry{index}\marg{\meta{label}} -\end{alltt} +\end{codeenv} If \longargfmt{space-sub} is used and \meta{label} contains one or more spaces, then \field{name} will be set if not included in \meta{\keyvallist}. For example, if \filefmt{entries.bib} -contains -\begin{verbatim} -\newterm{sea lion} -\newterm[seealso={sea lion}]{seal} -\end{verbatim} -then +contains: +\begin{codeenv} +\gls{newterm}\marg{sea lion} +\gls{newterm}\oarg{\field{seealso}=\marg{sea lion}}\marg{seal} +\end{codeenv} +then: \begin{verbatim} -gls2bib --space-sub '-' entries.bib entries.tex +convertgls2bib --space-sub '-' entries.bib entries.tex \end{verbatim} -will write the terms to \filefmt{entries.tex} as -\begin{verbatim} -@index{sea-lion, - name = {sea lion} +will write the terms to \filefmt{entries.tex} as: +\begin{codeenv} +\atentry{index}\marg{sea-lion, + \field{name} = \marg{sea lion} } - -@index{seal, - seealso = {sea-lion} +\strut +\atentry{index}\marg{seal, + \field{seealso} = \marg{sea-lion} } -\end{verbatim} -whereas just +\end{codeenv} +whereas just: \begin{verbatim} -gls2bib entries.bib entries.tex +convertgls2bib entries.bib entries.tex \end{verbatim} -will write the terms to \filefmt{entries.tex} as -\begin{verbatim} -@index{sea lion} - -@index{seal, - seealso = {sea lion} +will write the terms to \filefmt{entries.tex} as: +\begin{codeenv} +\atentry{index}\marg{sea lion} +\strut +\atentry{index}\marg{seal, + \field{seealso} = \marg{sea lion} } -\end{verbatim} +\end{codeenv} which will cause a problem when the \ext{bib} file is parsed by \bibgls\ (and will probably also cause a problem for bibliographic management systems). @@ -14155,20 +16142,20 @@ bibliographic management systems). The \styfmt{glossaries-extra} package provides: \formatdef{newabbreviation} This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{abbreviation}\marg{\meta{label}, - short = \margm{short}, - long = \margm{long}, + \field{short} = \margm{short}, + \field{long} = \margm{long}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} if the optional argument is present, otherwise it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{abbreviation}\marg{\meta{label}, - short = \margm{short}, - long = \margm{long} + \field{short} = \margm{short}, + \field{long} = \margm{long} } -\end{alltt} +\end{codeenv} \cssection[\section]{newacronym} The base \styfmt{glossaries} package provides: @@ -14183,26 +16170,25 @@ The \styfmt{glossaries-extra} package provides: \formatdef{glsxtrnewsymbol} (when the \styopt{symbols} option is used). This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{symbol}\marg{\meta{label}, - name = \margm{symbol} + \field{name} = \margm{symbol} } -\end{alltt} +\end{codeenv} if the optional argument is missing, otherwise it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{symbol}\marg{\meta{label}, - name = \margm{symbol}, + \field{name} = \margm{symbol}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} unless \meta{\keyvallist} contains the \field{name} field, in which case it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{symbol}\marg{\meta{label}, \meta{\keyvallist} } -\end{alltt} - +\end{codeenv} \ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}. \cssection[\section]{glsxtrnewnumber} @@ -14211,26 +16197,25 @@ The \styfmt{glossaries-extra} package provides: \formatdef{glsxtrnewnumber} (when the \styopt{numbers} option is used). This is converted to: -\begin{alltt} +\begin{codeenv} \atentry{number}\marg{\meta{label}, - name = \margm{label} + \field{name} = \margm{label} } -\end{alltt} +\end{codeenv} if the optional argument is missing, otherwise it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{number}\marg{\meta{label}, - name = \margm{label}, + \field{name} = \margm{label}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} if \field{name} isn't listed in \meta{\keyvallist}, otherwise it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{number}\marg{\meta{label}, \meta{\keyvallist} } -\end{alltt} - +\end{codeenv} \ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}. \cssection[\section]{newdualentry} @@ -14247,70 +16232,68 @@ number of times it crops up on sites like defined using \ics{newcommand} or \ics{renewcommand} in the input file. In which case the default definition will be overridden. -If the command definition isn't overridden, then it's converted to -\begin{alltt} +If the command definition isn't overridden, then it's converted to: +\begin{codeenv} \atentry{dualabbreviationentry}\marg{\meta{label}, - short = \margm{short}, - long = \margm{long}, - description = \margm{description}, + \field{short} = \margm{short}, + \field{long} = \margm{long}, + \field{description} = \margm{description}, \meta{\keyvallist} } -\end{alltt} +\end{codeenv} if \meta{\keyvallist} is supplied, otherwise it's converted to: -\begin{alltt} +\begin{codeenv} \atentry{dualabbreviationentry}\marg{\meta{label}, - short = \margm{short}, - long = \margm{long}, - description = \margm{description} -} -\end{alltt} - -For example, if the original \ext{tex} file contains -\begin{verbatim} -\newcommand*{\newdualentry}[5][]{% - \newglossaryentry{main-#2}{name={#4},% - text={#3\glsadd{#2}},% - description={#5},% - #1 - }% - \newacronym{#2}{#3\glsadd{main-#2}}{#4} + \field{short} = \margm{short}, + \field{long} = \margm{long}, + \field{description} = \margm{description} } +\end{codeenv} -\newdualentry{svm}% label - {SVM}% abbreviation - {support vector machine}% long form - {Statistical pattern recognition technique}% description -\end{verbatim} -then the \ext{bib} file will contain -\begin{verbatim} -@entry{main-svm, - name = {support vector machine}, - description = {Statistical pattern recognition technique}, - text = {SVM\glsadd{svm}} +For example, if the original \ext{tex} file contains: +\begin{codeenv} +\cs{newcommand}*\marg{\gls{newdualentry}}[5][]\marg{\comment{} + \gls{newglossaryentry}\marg{main-\idx{param}2}\marg{\field{name}=\marg{\idx{param}4},\comment{} + \field{text}=\marg{\idx{param}3\cs{glsadd}\marg{\idx{param}2}},\comment{} + \field{description}=\marg{\idx{param}5},\comment{} + \idx{param}1 + }\comment{} + \gls{newacronym}\marg{\idx{param}2}\marg{\idx{param}3\cs{glsadd}\marg{main-\idx{param}2}}\marg{\idx{param}4}\comment{} +} +\strut +\gls{newdualentry}\marg{svm}\comment{label} + \marg{SVM}\comment{abbreviation} + \marg{support vector machine}\comment{long form} + \marg{Statistical pattern recognition technique}\comment{description} +\end{codeenv} +then the \ext{bib} file will contain: +\begin{codeenv} +\atentry{entry}\marg{main-svm, + \field{name} = \marg{support vector machine}, + \field{description} = \marg{Statistical pattern recognition technique}, + \field{text} = \marg{SVM\cs{glsadd}\marg{svm}} } - -@acronym{svm, - short = {SVM\glsadd{main-svm}}, - long = {support vector machine} +\strut +\atentry{acronym}\marg{svm, + \field{short} = \marg{SVM\cs{glsadd}\marg{main-svm}}, + \field{long} = \marg{support vector machine} } -\end{verbatim} +\end{codeenv} since \gls{newdualentry} was defined with \ics{newcommand}. However, if the original file uses \ics{providecommand} or omits the definition of \gls{newdualentry}, then the \ext{bib} file will contain: -\begin{verbatim} -@dualabbreviationentry{svm, - short = {SVM}, - description = {Statistical pattern recognition technique}, - long = {support vector machine} +\begin{codeenv} +\atentry{dualabbreviationentry}\marg{svm, + \field{short} = \marg{SVM}, + \field{description} = \marg{Statistical pattern recognition technique}, + \field{long} = \marg{support vector machine} } -\end{verbatim} +\end{codeenv} \chapter{Examples} \label{sec:examples} \setcounter{secnumdepth}{0} -\lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small}, - commentstyle={\color{gray}}} The example files described here can be found in the \filefmt{examples} sub-directory. The \ext{bib} files are listed @@ -14347,7 +16330,7 @@ definitions and must be loaded first with file can then be loaded to provide alternative definitions for \bibgls's interpreter. -The first command is +The first command is: \nosecdef{sortname} This is used in the \field{name} fields for entries containing information about a person. The aim here is for \bibgls\ to sort @@ -14356,14 +16339,14 @@ glossary to display \meta{first name(s)} \meta{surname}. For names with a \qt{von} part, there's another command: \nosecdef{sortvonname} which has a similar purpose. -The third command is +The third command is: \nosecdef{sortart} This is the same as \gls{sortname} but is designed for titles, phrases or sentences that start with an article (such as \qt{a} or \qt{the}). Although it has the same definition as \gls{sortname} in this file, in the interpreted files the article part is omitted to completely ignore them in the sorting. -The fourth command is +The fourth command is: \nosecdef{sortmediacreator} which again is functionally the same as \gls{sortname}. @@ -14398,7 +16381,7 @@ The contents of \filefmt{interpret-preamble.bib} are as follows: \filesection{interpret-preamble2.bib} An alternative to \exfile{interpret-preamble.bib} with a different -definition of \cs{sortmediacreator}. This uses \cs{renewcommand} +definition of \gls{sortmediacreator}. This uses \cs{renewcommand} instead of \cs{providecommand} so \csopt[false]{write-preamble} is required to prevent \LaTeX\ from picking up the definitions. @@ -14411,52 +16394,52 @@ The \exfile{constants.bib} file contains mathematical constants. These all use a custom entry type \atentryfmt{constant}, which must be aliased otherwise the entries will all be ignored. The entries all have custom fields, which also need to be aliased. -For example +For example: \begin{codeenv} \csopt[constant=entry]{entry-type-aliases}, \csopt[ - constantname=name, - constantsymbol=symbol, - definition=description, - identifier=category, - value=user1 + \fieldfmt{constantname}=\field{name}, + \fieldfmt{constantsymbol}=\field{symbol}, + \fieldfmt{definition}=\field{description}, + \fieldfmt{identifier}=\field{category}, + \fieldfmt{value}=\field{user1} ]{field-aliases} \end{codeenv} This setting means that, for example, -\begin{verbatim} -@constant{root2, - constantname={Pythagoras' constant}, - constantsymbol={\ensuremath{\surd2}}, - definition={the square root of 2}, - value={1.41421}, - identifier={constant} +\begin{codeenv} +\atentryfmt{constant}\marg{root2, + \fieldfmt{constantname}=\marg{Pythagoras' constant}, + \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\ics{surd}2}}, + \fieldfmt{definition}=\marg{the square root of 2}, + \fieldfmt{value}=\marg{1.41421}, + \fieldfmt{identifier}=\marg{constant} } -\end{verbatim} -is treated as though it was defined as -\begin{verbatim} -@entry{root2, - name={Pythagoras' constant}, - symbol={\ensuremath{\surd2}}, - description={the square root of 2}, - user1={1.41421}, - category={constant} +\end{codeenv} +is treated as though it was defined as: +\begin{codeenv} +\atentry{entry}\marg{root2, + \field{name}=\marg{Pythagoras' constant}, + \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, + \field{description}=\marg{the square root of 2}, + \field{user1}=\marg{1.41421}, + \field{category}=\marg{constant} } -\end{verbatim} +\end{codeenv} This use of custom fields and entry types allows more flexibility. For example, I may have another document that uses the same -\ext{bib} file but requires a different definition, for example: -\begin{verbatim} -@number{root2, - description={Pythagoras' constant}, - name={\ensuremath{\surd2}} +\ext{bib} file but requires a different definition: +\begin{codeenv} +\atentry{number}\marg{root2, + \field{description}=\marg{Pythagoras' constant}, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{surd}2}} } -\end{verbatim} -which can be obtained with +\end{codeenv} +which can be obtained with: \begin{codeenv} \csopt[constant=number]{entry-type-aliases}, \csopt[ - constantname=description, - constantsymbol=name + \fieldfmt{constantname}=\field{description}, + \fieldfmt{constantsymbol}=\field{name} ]{field-aliases} \end{codeenv} Since the other custom fields haven't be aliased, they're ignored. @@ -14475,21 +16458,21 @@ 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} -if different notation required. The upright Greek commands require +if different notation is required. The upright Greek commands require the \isty{upgreek} package. If it's likely that there may be a need to sort according to -\fieldfmt{definition}, then it would be better to use \cs{sortart} +\fieldfmt{definition}, then it would be better to use \gls!{sortart} describe above: -\begin{verbatim} -@constant{root2, - constantname={Pythagoras' constant}, - constantsymbol={\ensuremath{\surd2}}, - definition={\sortart{the}{square root of 2}}, - value={1.41421}, - identifier={constant} +\begin{codeenv} +\atentryfmt{constant}\marg{root2, + \fieldfmt{constantname}=\marg{Pythagoras' constant}, + \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}, + \fieldfmt{definition}=\marg{\gls{sortart}\marg{the}\marg{square root of 2}}, + \fieldfmt{value}=\marg{1.41421}, + \fieldfmt{identifier}=\marg{constant} } -\end{verbatim} +\end{codeenv} Remember that this would need \exfile{no-interpret-preamble.bib} to ensure the command is recognised in the document. @@ -14503,9 +16486,9 @@ Each entry has a field that uses \ics{ce} provided by \sty{mhchem} so the document will need to load that package. Since all resource files must be loaded in the preamble, it's possible to ensure that the package is loaded using: -\begin{verbatim} -@preamble{"\usepackage{mhchem}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{usepackage}\marg{mhchem}}} +\end{codeenv} However, it's best just to load it in the document otherwise it won't be available before the \ext{glstex} file has been loaded. Also, \sty{glossaries} (and therefore \sty{glossaries-extra}) must be @@ -14519,7 +16502,7 @@ All entries are defined using a custom entry type \csopt{entry-type-aliases} or the entries will be ignored. For example, to make \atentryfmt{chemical} behave like \atentry{symbol}: \begin{codeenv} -\csopt[chemical=symbol]{entry-type-aliases} +\csopt[\fieldfmt{chemical}=\field{symbol}]{entry-type-aliases} \end{codeenv} Remember that with the \atentry{symbol} type, if the \field{sort} field is omitted \bibgls\ will fallback on the label by default. It @@ -14533,17 +16516,17 @@ entry's \field{name}. All entries only contain custom fields, which will all be ignored by \bibgls\ unless defined or aliased: \fieldfmt{identifier}, which is set to -\code{chemical} for all entries, \fieldfmt{formula}, which set to the -chemical formula, and \fieldfmt{chemicalname}, which set to the chemical +\code{chemical} for all entries, \fieldfmt{formula}, which is set to the +chemical formula, and \fieldfmt{chemicalname}, which is set to the chemical name. This allows the flexibility of determining whether the \field{name} or \field{symbol} field should contain the chemical formula on a per-resource basis. For example: \begin{codeenv} -\csopt[formula=name,chemicalname=description]{field-aliases} +\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} \end{codeenv} or \begin{codeenv} -\csopt[chemicalname=name,formula=symbol]{field-aliases} +\csopt[\fieldfmt{chemicalname}=\field{name},\fieldfmt{formula}=\field{symbol}]{field-aliases} \end{codeenv} The contents of \filefmt{chemicalformula.bib} are as follows: @@ -14568,9 +16551,9 @@ The contents of \filefmt{bacteria.bib} are as follows: The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries are all defined using the custom \atentryfmt{unit} entry type. This must be aliased with \csopt{entry-type-aliases} otherwise -\bibgls\ will ignore all the entries. For example +\bibgls\ will ignore all the entries. For example: \begin{codeenv} -\csopt[unit=symbol]{entry-type-aliases} +\csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases} \end{codeenv} will make \bibgls\ treat the entries as though they were defined using \atentry{symbol}. (Remember that \atentry{symbol} entry types use the label @@ -14578,7 +16561,8 @@ as the fallback field for \field{sort}.) The entries all have custom fields \fieldfmt{unitname}, \fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must -be aliased or copied to \field{name}. The others may be aliased or +be aliased or copied to \field{name} if \atentryfmt{unit} is aliased +to an entry type that requires it. The other custom fields may be aliased or copied to \field{symbol} and \field{description} as required. The \fieldfmt{unitsymbol} fields all use \ics{si} provided by the \isty{siunitx} package, so that package must be loaded in the @@ -14598,7 +16582,7 @@ The contents of \filefmt{baseunits.bib} are as follows: The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib} but contains derived units and in this case the custom entry type -is \atentryfmt{measurement} must be aliased +is \atentryfmt{measurement}, which must be aliased otherwise the entries will all be ignored. The entries all have a custom field \fieldfmt{identifier} set to \code{derivedunit}. This will be ignored by \bibgls\ unless it's @@ -14628,11 +16612,11 @@ unless keys are provided (using \cs{glsaddkey} or \csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died} fields have dates that are \emph{almost} in the default \code{en-GB} locale format with the \idx{JRE} \idx{localeprovider}, but they include a -tilde \verb|~| to prevent awkward line breaks. By default \bibgls's -interpreter converts \verb|~| to the non-breaking space character +tilde \idx{nbspchar} to prevent awkward line breaks. By default \bibgls's +interpreter converts \idx{nbspchar} to the non-breaking space character \hex{A0} which isn't recognised by the date format. This can easily be fixed with the \longarg{break-space} switch which will interpret -\verb|~| as a normal breakable space (\hex{20}), so with that switch +\idx{nbspchar} as a normal breakable space (\hex{20}), so with that switch \csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on either of those fields. However, the \idx{CLDR} has a slightly different default format than the \idx{JRE} for dates with @@ -14642,19 +16626,19 @@ required format. An alternative approach would be to provide a command that can be modified in the document to adjust the date style. For example, the \fieldfmt{born} field could be specified as: -\begin{verbatim} -born={\formatdate{13}{7}{100}{BC}} -\end{verbatim} +\begin{codeenv} +\fieldfmt{born}=\marg{\cmd{formatdate}\marg{13}\marg{7}\marg{100}\marg{BC}} +\end{codeenv} The definition provided for the document could then be, for example: -\begin{verbatim} -\providecommand{\formatdate}[4]{\DTMdisplaydate{#3}{#2}{#1}{-1} #4} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\ics{DTMdisplaydate}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\idx{param}1}\marg{-1} \idx{param}4} +\end{codeenv} (where \ics{DTMdisplaydate} is provided by the \isty{datetime2} package) and a definition could be provided for \bibgls's interpreter, for example: -\begin{verbatim} -\providecommand{\formatdate}[4]{#1/#2/#3 #4} -\end{verbatim} +\begin{codeenv} +\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\idx{param}1/\idx{param}2/\idx{param}3 \idx{param}4} +\end{codeenv} This would need the date format set. For example, \csopt[d/M/y G]{date-sort-format}. @@ -14670,25 +16654,25 @@ ignored with \csopt{ignore-fields} (so all entries will use the option can be used to force the \field{name} field to be copied to the \field{first} field, even if the \field{first} field is already set. Alternatively, with \csopt[true]{replicate-override} and -\csopt[first=name]{replicate-fields}, the \field{first} field be +\csopt[\field{first}=\field{name}]{replicate-fields}, the \field{first} field be copied to the \field{name} field. For consistency, the \field{first} fields use the same custom commands as used in the \field{name} field. There's one name with a \qt{von} part. In this case the \field{name} -field is set to -\begin{verbatim} -\sortvonname{Manfred}{von}{Richthofen} -\end{verbatim} +field is set to: +\begin{codeenv} +\gls{sortvonname}\marg{Manfred}\marg{von}\marg{Richthofen} +\end{codeenv} which will come under the \qt{V} letter group since \gls{sortvonname} is defined as \meta{von} \meta{surname}, \meta{first name(s)} If you prefer that this name should come under \qt{R} instead, then you need to adjust the definition of \gls{sortvonname}: -\begin{verbatim} -@preamble{"\providecommand{\sortname}[2]{#2, #1} -\providecommand{\sortvonname}[3]{#3, #1 #2}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{sortname}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{providecommand}\marg{\cmd{sortvonname}}[3]\marg{\idx{param}3, \idx{param}1 \idx{param}2}}} +\end{codeenv} An alternative approach would be to format the names using \BibTeX's contributor syntax and use \csopt[name]{bibtex-contributor-fields} to convert them. @@ -14751,10 +16735,10 @@ with \idprefixfmt{film} rather than relying on \csopt{label-prefix}. This ensures that both \exfile{books.bib} and \exfile{films.bib} can be loaded in the same resource set (otherwise they'd have to be loaded in separate resource sets with different prefixes). Remember -that you can use \ics{glsxtrnewgls}. For example: -\begin{verbatim} -\glsxtrnewgls{film.}{\film} -\end{verbatim} +that you can use \gls{glsxtrnewgls}. For example: +\begin{codeenv} +\gls{glsxtrnewgls}\marg{film.}\marg{\cmd{film}} +\end{codeenv} This means you can do, for example, just \verb|\film{bladerunner}| if you want to reference a film without worrying about the prefix. @@ -14773,11 +16757,11 @@ The book \qt{Do Androids Dream of Electric Sheep?}\ referenced at the end of the \qt{Blade Runner} film's \field{description} ends with a question mark. (Similarly for \qt{Why Didn't They Ask Evans?}) If the \field{description} field is simply set as: -\begin{verbatim} -description={a film starring Harrison Ford, Rutger Hauer +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer and Sean Young loosely based on the novel - \gls{ext1.doandroidsdreamofelectricsheep}}, -\end{verbatim} + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}}, +\end{codeenv} then the \styopt{postdot} package option will produce an odd result as the inserted \idx{full-stop} immediately follows the question mark. This is an awkward situation. One possibility is to explicitly @@ -14788,19 +16772,19 @@ interferes with the possibility of a category-dependent Another option is to put \ics{nopostdesc} in the problematic entries. For example: -\begin{verbatim} -description={a film starring Harrison Ford, Rutger Hauer +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer and Sean Young loosely based on the novel - \gls{ext1.doandroidsdreamofelectricsheep}\nopostdesc}, -\end{verbatim} + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{nopostdesc}}, +\end{codeenv} Be careful with this as it will completely suppress the \idx{postdescriptionhook}. A third possibility is to use \ics{glsxtrnopostpunc} instead: -\begin{verbatim} -description={a film starring Harrison Ford, Rutger Hauer +\begin{codeenv} +\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer and Sean Young loosely based on the novel - \gls{ext1.doandroidsdreamofelectricsheep}\glsxtrnopostpunc}, -\end{verbatim} + \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{glsxtrnopostpunc}}, +\end{codeenv} This doesn't interfere with the \idx{postdescriptionhook} but if a hook is provided the post-punctuation may then be required. In both of the above two cases, \csopt{strip-trailing-nopost} could be used @@ -14810,11 +16794,11 @@ that only conditionally append text. The best solution is with \styfmt{glossaries-extra} v1.23+ which provides \ics{glsxtrrestorepostpunc} for use in the category -\idxpl{postdescriptionhook} that counter-acts \cs{glsxtrnopostpunc}. +\idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}. This can be placed inside a conditional, as used in \exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc} doesn't occur in the \field{description} field. (Note that -\cs{glsxtrrestorepostpunc} can't be used to counter-act +\cs{glsxtrrestorepostpunc} can't be used to counteract \cs{nopostdesc}, since that completely suppresses the hook.) The contents of \filefmt{films.bib} are as follows: @@ -14824,14 +16808,14 @@ The contents of \filefmt{films.bib} are as follows: The \exfile{citations.bib} file is actually a \BibTeX\ file, but it can be parsed by \bibgls\ if the \BibTeX\ entry types are converted -to \atentry{bibtexentry}, which can easily be done with +to \atentry{bibtexentry}, which can easily be done with: \begin{codeenv} -entry-type-aliases=\marg{\ics{GlsXtrBibTeXEntryAliases}} +\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases} \end{codeenv} The field names will also need to be defined or aliased. For example: \begin{codeenv} -field-aliases=\marg{title=name} +\csopt[\fieldfmt{title}=\field{name}]{field-aliases} \end{codeenv} If \bibgls\ is then run with \longarg{cite-as-record} any \ics{citation} commands found in the \ext{aux} file will be treated @@ -14847,7 +16831,7 @@ The contents of \filefmt{citations.bib} are as follows: \filesection{mathgreek.bib} The \exfile{mathgreek.bib} file contains Greek letters for use in -maths mode. These are all defined use \atentry{symbol}, which means +maths mode. These are all defined with \atentry{symbol}, which means that by default the \field{sort} field will be obtained from the label not from the \field{name} field. However, if you want to sort by the \field{name} field (for example, with \csopt[name]{sort-field}) @@ -14859,31 +16843,31 @@ reproduced with a \idx!{lowercase} Latin \qt{o}). Note that provides all the missing Greek letters (such as \cs{omicron}). The \ext{bib} file could just use \code{o}: -\begin{verbatim} -@symbol{omicron, - name={\ensuremath{o}}, - description={omicron}, - identifier={mathgreek} +\begin{codeenv} +\atentry{symbol}\marg{omicron, + \field{name}=\marg{\cs{ensuremath}\marg{o}}, + \field{description}=\marg{omicron}, + \fieldfmt{identifier}=\marg{mathgreek} } -\end{verbatim} +\end{codeenv} but this means that if \bibgls\ sorts according to the \field{name} field using a letter sort, this entry will come before all the other Greek letters since the character \qt{o} has Unicode value \hex{6F} whereas, for example, mathematical italic small alpha ($\alpha$) has Unicode value \hex{1D6FC}. This means that for sorting purposes it's better to use \ics{omicron}: -\begin{verbatim} -@symbol{omicron, - name={\ensuremath{\omicron}}, - description={omicron}, - identifier={mathgreek} +\begin{codeenv} +\atentry{symbol}\marg{omicron, + \field{name}=\marg{\cs{ensuremath}\marg{\cs{omicron}}}, + \field{description}=\marg{omicron}, + \fieldfmt{identifier}=\marg{mathgreek} } -\end{verbatim} +\end{codeenv} but \LaTeX\ needs a definition for this, so it's provided in the \atentry{preamble}: -\begin{verbatim} -@preamble{"\providecommand{\omicron}{o}"} -\end{verbatim} +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cs{omicron}}\marg{o}}} +\end{codeenv} (With \sty{glossaries-extra} v1.27+, this is no longer needed.) The \TeX\ parser library and \sty{glossaries-extra-bib2gls} similarly provide the missing \idx!{uppercase} @@ -14900,34 +16884,36 @@ that have a large version in display mode. As with \atentry{symbol}. This example file requires the \isty{stix} package as not all of the commands are provided by the \LaTeX\ kernel. This file also has a preamble: -\begin{verbatim} -@preamble{"\providecommand{\bigoperatornamefmt}[1]{% - $\displaystyle#1\textstyle#1$} -\providecommand{\nary}[1]{$#1$-ary}"} -\end{verbatim} -The first command \ics{bigoperatornamefmt} is used in the -\field{name} field to display both the in-line and display versions -of the symbol. The \TeX\ parser library only has a limited ability -to interpret this as not all the symbols have Unicode in-line and large -versions. In some cases, such as the integral symbol $\int$ only has -a small version. (A large version would require construction from -\hex{2320}, \hex{23AE} and \hex{2321}, which is too complicated in -this context.) However, the interpreter works well enough to guess -at the widest name if \csopt{set-widest} is used. There's no -advantage in sorting according to the \field{name} field here, as -the Unicode symbols are scattered about different blocks. Better -approaches are to sort according to document use (\csopt[use]{sort}) -or to sort according to the \field{description} field. - -The other custom command is \ics{nary} to provide semantic markup -for \qt{$n$-ary}. This could be defined without an argument: -\begin{verbatim} -\providecommand{\nary}{$n$-ary} -\end{verbatim} -but providing an argument will allow \verb|\nary{n}| to work -with first letter uppercasing in the event that the +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\cmd{bigoperatornamefmt}}[1]\marg{\comment{} + \idx{mshiftchar}\ics{displaystyle}\idx{param}1\ics{textstyle}\idx{param}1\idx{mshiftchar}} +\cmd{providecommand}\marg{\cmd{nary}}[1]\marg{\idx{mshiftchar}\idx{param}1\idx{mshiftchar}-ary}}} +\end{codeenv} +The first command \inlinedef{bigoperatornamefmt} +is used in the \field{name} field to display both the in-line and display +versions of the symbol. The \TeX\ parser library only has a limited ability to +interpret this as not all the symbols have Unicode in-line and large versions. +In some cases, such as the integral symbol $\int$, there is only a small +version. (A large version would require construction from \hex{2320}, +\hex{23AE} and \hex{2321}, which is too complicated in this context.) +However, the interpreter works well enough to guess at the widest +name if \csopt{set-widest} is used. There's no advantage in sorting +according to the \field{name} field here, unless a custom rule is +provided, as the Unicode symbols are scattered about different +blocks. Better approaches are to sort according to document use +(\csopt[use]{sort}) or to sort according to the \field{description} +field. + +The other custom command is \inlinedef{nary} to provide semantic markup for +\qt{$n$-ary}. This could be defined without an argument: +\begin{codeenv} +\cmd{providecommand}\marg{\cmd{nary}}\marg{\idx{mshiftchar}n\idx{mshiftchar}-ary} +\end{codeenv} +but providing an argument will allow \code{\csfmt{nary}\marg{n}} to work +with first letter upper-casing in the event that the \field{description} field has a case-change applied (otherwise -it would end up as \qt{$N$-ARY}). +it would end up as \qt{$N$-ARY}). Of course, it may be that no case-change +should be applied, but this example is just for illustrative purposes. As with the other sample \ext{bib} files, each entry is given a custom \fieldfmt{identifier} field, which by default will be @@ -14944,10 +16930,11 @@ The \exfile{mathsrelations.bib} file contains mathematical relational symbols. These use the maths shift character \idx{mshiftchar} in the \field{name} field and just the symbol in the \field{text} field. This just illustrates an alternative way of -defining symbols. Since \ics{ensuremath} isn't used, commands +defining symbols. Since \ics{ensuremath} isn't used, commands like \cs{gls} must be explicitly placed in maths mode. For example, -\verb|$\gls{leq}$| rather than simply \verb|\gls{leq}|. The custom -\fieldfmt{identifier} field is set to \code{relation}. +\code{\idx{mshiftchar}\cs{gls}\marg{leq}\idx{mshiftchar}} rather than simply +\code{\cs{gls}\marg{leq}}. The custom \fieldfmt{identifier} field is +set to \code{relation}. The contents of \filefmt{mathsrelations.bib} are as follows: \lstinputlisting[firstline=5]{../examples/mathsrelations.bib} @@ -14965,7 +16952,7 @@ The contents of \filefmt{binaryoperators.bib} are as follows: \filesection{unaryoperators.bib} The \exfile{unaryoperators.bib} file contains mathematical unary -operators. This again uses \atentry{symbol} to define the symbols, +operators. As above, this again uses \atentry{symbol} to define the symbols, but in this case \ics{ensuremath} is used in the \field{name} field and there's no \field{text} field. I've also used \ics{mathord} to ensure the symbol is treated as a unary (rather than binary) @@ -14995,35 +16982,35 @@ which is used to format matrix and vector transposes, \nosecdef{invfmt} which is used to format inverses, \nosecdef{vecfmt} -which is used to format \meta{symbol} as a vector and +which is used to format \meta{symbol} as a vector, and \nosecdef{mtxfmt} which is used to format \meta{symbol} as a matrix. -These commands are intended for use with \ics{glsxtrfmt}, -but \csref{setmembershipfmt} causes a problem as it has two -arguments and \ics{glsxtrfmt} requires the control sequence to +These commands are intended for use with \gls{glsxtrfmt}, +but \gls!{setmembershipfmt} causes a problem as it has two +arguments and \gls{glsxtrfmt} requires the control sequence to have exactly one argument. This means employing a little trick. A command with just one argument is provided: \nosecdef{setmembershiponeargfmt} that requires the actual two arguments to be supplied inside -\verb|#1|. The outer grouping is removed and the two-argument -\csref{setmembershipfmt} command is applied: -\begin{verbatim} -\providecommand{\setmembershiponeargfmt}[1]{\setmembershipfmt#1} -\end{verbatim} +\code{\idx!{param}1}. The outer grouping is removed and the two-argument +\gls!{setmembershipfmt} command is applied: +\begin{codeenv} +\cs{providecommand}\marg{\gls{setmembershiponeargfmt}}[1]\marg{\gls{setmembershipfmt}\idx{param}1} +\end{codeenv} This means that the entry needs to be referenced in the document using: -\begin{alltt} -\csref{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}} -\end{alltt} +\begin{codeenv} +\gls{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}} +\end{codeenv} The simplest thing to do here is to provide a wrapper command in the document, for example: -\begin{verbatim} -\newcommand*{\setmembership}[2]{\glsxtrfmt{setmembership}{{#1}{#2}}} -\end{verbatim} -Now this can be used as -\begin{alltt} -\csfmt{setmembership}\margm{variable(s)}\margm{condition} -\end{alltt} +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{setmembership}}[2]\marg{\gls{glsxtrfmt}\marg{setmembership}\marg{\marg{\idx{param}1}\marg{\idx{param}2}}} +\end{codeenv} +Now this can be used as: +\begin{codeenv} +\cmd{setmembership}\margm{variable(s)}\margm{condition} +\end{codeenv} There are essentially two types of entry defined in this file: entries that demonstrate the formatting for the objects @@ -15031,20 +17018,21 @@ and entries that represent specific objects. In the first case there's a custom \fieldfmt{format} field that's set to the control sequence name of the relevant semantic command. If this field is defined or aliased then it can be used -with \csref{glsxtrfmt} (as in the example above). +with \gls!{glsxtrfmt} (as in the example above). In both cases there's a custom \fieldfmt{identifier} field that -reflects the type of object: \code{numberspace} for number spaces, -\code{set} for sets, \code{matrix} for matrices or vectors. +reflects the type of object: \code{set} for sets, +\code{numberspace} for number spaces, +\code{matrix} for matrices or vectors. Be careful with the set cardinality example. Remember that nested links cause problems and the \sty{glossaries-extra} manual advises -against using commands like \cs{gls} or \csref{glsxtrfmt} within +against using commands like \cs{gls} or \gls!{glsxtrfmt} within link text and that includes within the \meta{text} argument of -\csref{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested +\gls!{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested usage. -Some of the \field{description} fields use \csref{sortart}, so +Some of the \field{description} fields use \gls!{sortart}, so \exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib} are also needed. @@ -15062,19 +17050,19 @@ to provide the weather commands. Unfortunately both packages define you can load \sty{ifsym} without the \styoptfmt{weather} option and use the internal definition of \sty{ifsym}'s \csfmt{Sun} and \csfmt{Lightning} commands: -\begin{verbatim} -@icon{sun, - icon={\textweathersymbol{16}}, - description={sunny}, - identifier={weather} +\begin{codeenv} +\atentryfmt{icon}\marg{sun, + \fieldfmt{icon}=\marg{\ics{textweathersymbol}\marg{16}}, + \fieldfmt{description}=\marg{sunny}, + \fieldfmt{identifier}=\marg{weather} } - -@icon{lightning, - icon={\textweathersymbol{26}}, - description={thunderstorm}, - identifier={weather} +\strut +\atentryfmt{icon}\marg{lightning, + \fieldfmt{icon}=\marg{\cs{textweathersymbol}\marg{26}}, + \field{description}=\marg{thunderstorm}, + \fieldfmt{identifier}=\marg{weather} } -\end{verbatim} +\end{codeenv} This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning} are as defined by \sty{marvosym}. @@ -15082,7 +17070,7 @@ This file uses a custom entry type \atentryfmt{icon}, which must be aliased to a recognised entry identifier otherwise the entries will all be ignored. For example: \begin{codeenv} -\csopt[icon=symbol]{entry-type-aliases} +\csopt[\fieldfmt{icon}=\field{symbol}]{entry-type-aliases} \end{codeenv} There are three types of symbols defined: media controls, information @@ -15127,8 +17115,8 @@ concatenation character \idx{stringconcat}. As with the other sample which will be ignored unless defined or aliased. The empty braces at the start some of the fields are there to -protect against first letter uppercasing, where it might cause a -problem. +protect against first letter uppercasing within \TeX, where it might cause a +problem. (For example, with the \catattr{glossname} attribute.) The contents of \filefmt{markuplanguages.bib} are as follows: \lstinputlisting[firstline=5]{../examples/markuplanguages.bib} @@ -15278,7 +17266,7 @@ The contents of \filefmt{usergroups.bib} are as follows: @abbreviation{ITALIC, short={ITALIC}, long={Irish \TeX\ and \LaTeX\ In-print Community}, - language={en-GB,en-IE}, + language={en-IE,en-GB}, identifier={texusergroup} } @@ -15416,7 +17404,7 @@ The contents of \filefmt{terms.bib} are as follows: This example uses the \exfile{constants.bib} file. The aim here is to just have a list of all the constants defined in the \ext{bib} file. (There are no references in the document.) This means I need -to use +to use: \begin{codeenv} \csopt[all]{selection} \end{codeenv} @@ -15430,12 +17418,12 @@ ignored. I decided to make \atentryfmt{constant} behave like The custom fields also need aliasing: \begin{codeenv} \csopt[ - identifier=category, - constantsymbol=name, - constantname=description, - value=user1, - definition=user2, - alternative=user3, + \fieldfmt{identifier}=\field{category}, + \fieldfmt{constantsymbol}=\field{name}, + \fieldfmt{constantname}=\field{description}, + \fieldfmt{value}=\field{user1}, + \fieldfmt{definition}=\field{user2}, + \fieldfmt{alternative}=\field{user3}, ]{field-aliases} \end{codeenv} I decided to use the \glostyle{altlist} style, so I've instructed @@ -15454,7 +17442,7 @@ numerical value. I've aliased the custom \fieldfmt{value} field to \field{user1}, so I can sort by that field using a numerical comparison: \begin{codeenv} -\csopt[user1]{sort-field}, +\csopt[\field{user1}]{sort-field}, \csopt[double]{sort} \end{codeenv} There are three entries without the \fieldfmt{user1} field (as the @@ -15462,9 +17450,9 @@ custom \fieldfmt{value} field is missing in the \ext{bib} file): \code{zero}, \code{one} and \code{imaginary}. In the case of \code{zero} and \code{one} the exact value can be obtained from the \field{name} field. Since I've change the default \csopt{sort-field}, I -can't use \csopt{symbol-sort-fallback}. Instead I need to use +can't use \csopt{symbol-sort-fallback}. Instead I need to use: \begin{codeenv} -\csopt[name]{missing-sort-fallback} +\csopt[\field{name}]{missing-sort-fallback} \end{codeenv} What happens with the \code{imaginary} entry? It has no real @@ -15492,10 +17480,10 @@ style is no longer available, I need to set a new default with \styopt{postdot}. Don't forget that the \styopt{record} option is always needed when using \bibgls. This means that the \sty{glossaries-extra} package needs to be loaded as follows: -\begin{verbatim} -\usepackage[record,nostyles,postdot,stylemods={tree},style=alttree] - {glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\styopt{nostyles},\styopt{postdot},\styopt[tree]{stylemods},\styopt[alttree]{style}} + \marg{glossaries-extra} +\end{codeenv} I've assigned the custom \fieldfmt{constantname} field to the \field{description} field and the custom \fieldfmt{constantsymbol} field to the \field{name} field. This means that by default the glossary list @@ -15510,62 +17498,72 @@ I've aliased the custom \fieldfmt{identifier} field to \field{category} set to \code{constant}. The \idx{postdescriptionhook} is obtained from \idx{glsxtrpostdesccategory}, so I need to define -the command \csfmt{glsxtrpostdescconstant}. A simple definition is -\begin{verbatim} -\newcommand{\glsxtrpostdescconstant}{% - \space (approximately \glsentryuseri{\glscurrententrylabel})% - : \glsentryuserii{\glscurrententrylabel}% +the command \csfmt{glsxtrpostdescconstant}. A simple definition is: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} + \cs{space} (approximately \cs{glsentryuseri}\marg{\cs{glscurrententrylabel}})\comment{} + : \cs{glsentryuserii}\marg{\cs{glscurrententrylabel}}\comment{} } -\end{verbatim} +\end{codeenv} This is fine if all entries have the \field{user1} and \field{user2} fields set. A more generic approach tests for the existence of these -fields. This can either be done with \idx{ifglshasfield}: -\begin{verbatim} -\newcommand{\glsxtrpostdescconstant}{% - \ifglshasfield{user1}{\glscurrententrylabel}% - { (approximately \glscurrentfieldvalue)}% - {}% - \ifglshasfield{user2}{\glscurrententrylabel}% - {: \glscurrentfieldvalue}% - {}% +fields. This can either be done with \ics{ifglshasfield}: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} } -\end{verbatim} -or with \idx{glsxtrifhasfield}: -\begin{verbatim} -\newcommand{\glsxtrpostdescconstant}{% - \glsxtrifhasfield{useri}{\glscurrententrylabel}% - { (approximately \glscurrentfieldvalue)}% - {}% - \glsxtrifhasfield{userii}{\glscurrententrylabel}% - {: \glscurrentfieldvalue}% - {}% +\end{codeenv} +or with \ics{glsxtrifhasfield}: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} (Note the need to use the internal field label \field{useri} and \field{userii} with \ics{glsxtrifhasfield}.) A modification can be made to also show the alternative representation (obtained from the custom \fieldfmt{alternative} field which has been aliased to \field{user3}): -\begin{verbatim} -\newcommand{\glsxtrpostdescconstant}{% - \glsxtrifhasfield{useriii}{\glscurrententrylabel}% - { (also denoted \glscurrentfieldvalue - \glsxtrifhasfield{useri}{\glscurrententrylabel}% - {, approximately \glscurrentfieldvalue}% - {}% - )% - }% - {% - \glsxtrifhasfield{useri}{\glscurrententrylabel}% - { (approximately \glscurrentfieldvalue)}% - {}% - }% - \glsxtrifhasfield{userii}{\glscurrententrylabel}% - {: \glscurrentfieldvalue}% - {}% +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useriii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (also denoted \cs{glscurrentfieldvalue} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{, approximately \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{: \cs{glscurrentfieldvalue}}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} +If you have at least \styfmt{glossaries-extra} v1.31, it's better to use: +\begin{codeenv} +\ics{glsdefpostdesc}\marg{constant} +\end{codeenv} +instead of: +\begin{codeenv} +\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}} +\end{codeenv} +as it can guard against accidental misspelling of the \code{glsxtrpostdesc} +part of the command name. The complete code is listed below. The document build is: \begin{verbatim} @@ -15606,13 +17604,13 @@ Additionally, the entries only have custom fields, so these also need to be aliased. In this case I want the formula in the \field{name} field and the chemical name in the \field{description} field: \begin{codeenv} -\csopt[formula=name,chemicalname=description]{field-aliases} +\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases} \end{codeenv} The \atentry{symbol} entry type falls back on the label for the \field{sort} value by default, but I've decided to fallback on the \field{name} field for sorting: \begin{codeenv} -\csopt[name]{symbol-sort-fallback} +\csopt[\field{name}]{symbol-sort-fallback} \end{codeenv} An alternative approach would simply be to alias \atentryfmt{chemical} to \atentry{entry} instead. @@ -15633,16 +17631,16 @@ needs to know the widest name, so I've use \csopt{set-widest} for convenience. The default behaviour of the tree styles is to format the name in bold. This is done through the command \ics{glstreenamefmt} which is defined as: -\begin{verbatim} -\newcommand*{\glstreenamefmt}[1]{\textbf{#1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\end{codeenv} The group headings use \ics{glstreegroupheaderfmt} which defaults to \cs{glstreenamefmt}. Since I want to keep bold headings, I need to redefine this as well: -\begin{verbatim} -\renewcommand*{\glstreenamefmt}[1]{#1} -\renewcommand*{\glstreegroupheaderfmt}[1]{\textbf{#1}} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1} +\cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}} +\end{codeenv} (For a more compact layout, you could use \glostyle{mcolalttreegroup} instead.) @@ -15674,16 +17672,16 @@ Bacteria names are often shown in the long form on first use This can easily be done with the \abbrstyle{long-only-short-only} style. Bacteria are usually typeset in italic. It's best to create a semantic command for this: -\begin{verbatim} -\newcommand{\bacteriafont}[1]{\emph{#1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\end{codeenv} There are two methods to apply this to the bacteria entries. The first is to redefine the formatting commands used by the \abbrstyle{long-only-short-only} style: -\begin{verbatim} -\renewcommand*{\glsabbrvonlyfont}[1]{\bacteriafont{#1}} -\renewcommand*{\glslongonlyfont}[1]{\bacteriafont{#1}} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsabbrvonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} +\cs{renewcommand}*\marg{\ics{glslongonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}} +\end{codeenv} This is fine if I don't intend to use this style for other types of abbreviations. However, I may decide to extend the document at a later date to include other abbreviations that need @@ -15696,15 +17694,15 @@ the \catattr{glossnamefont} attribute, the font used for the \cs{gls} in the document is governed by the \catattr{textformat} attribute (\styfmt{glossaries-extra} v1.21+). So if I set the \field{category} to \code{bacteria} then I can do: -\begin{verbatim} -\setabbreviationstyle[bacteria]{long-only-short-only} -\glssetcategoryattribute{bacteria}{textformat}{bacteriafont} -\glssetcategoryattribute{bacteria}{glossnamefont}{bacteriafont} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\end{codeenv} and (if the \field{description} field is displayed in the glossary): -\begin{verbatim} -\glssetcategoryattribute{bacteria}{glossdescfont}{bacteriafont} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\end{codeenv} (Note that the attribute value is the control sequence name without the initial backslash.) @@ -15714,12 +17712,12 @@ package.\footnote{\styfmt{glossary-bookindex} is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded automatically, but it can be loaded through the \styopt{stylemods} package option: -\begin{verbatim} -\usepackage[record,% use bib2gls - nostyles,% don't load default style packages - stylemods={bookindex},% load glossary-bookindex.sty and patch styles - style=mcolindexgroup]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\comment{use bib2gls} + \styopt{nostyles},\comment{don't load default style packages} + \styopt[bookindex]{stylemods},\comment{load glossary-bookindex.sty and patch styles} + \styopt[bookindex]{style}]\marg{glossaries-extra} +\end{codeenv} I've used the \styopt{nostyles} package option to suppress loading the default style packages, since I'm not using them. If you inspect the \ext{log} file, you may notice that \sty{glossary-tree} is still @@ -15734,9 +17732,9 @@ the \field{name} to the short form by default, only the short form will show in the glossary. I'd rather it was just the long form. This could simply be done using \csopt{replicate-fields} to copy the \field{long} field to the \field{name} field: -\begin{verbatim} -replicate-fields={long=name} -\end{verbatim} +\begin{codeenv} +\csopt[\field{long}=\field{name}]{replicate-fields} +\end{codeenv} Again, I want to consider the possibility of adding other types of abbreviations and this might not be appropriate for them (for example, I might want some abbreviations with the long form followed @@ -15744,17 +17742,17 @@ by the short form in parentheses). Another approach is to redefine \ics{glsxtrbookindexname} which is used by the \glostyle{bookindex} style to display the name. This takes the entry's label as the argument. The default definition is: -\begin{verbatim} -\newcommand*{\glsxtrbookindexname}[1]{\glossentryname{#1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\cs{glossentryname}\marg{\idx{param}1}} +\end{codeenv} This can be changed to test for the entry's category: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glsifcategory{#1}{bacteria} - {\glossentrynameother{#1}{long}}% - {\glossentryname{#1}}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \ics{glsifcategory}\marg{\idx{param}1}\marg{bacteria} + \marg{\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{long}}}\comment{} + \marg{\cs{glossentryname}\marg{\idx{param}1}}\comment{} } -\end{verbatim} +\end{codeenv} Note that I've used \ics{glossentrynameother} here rather than \ics{glsentrylong}. This ensures that it follows the same formatting as \ics{glossentryname} (so it will use \ics{glsnamefont} or the @@ -15768,9 +17766,9 @@ fallback value is the \field{short} field (not the \field{name} field). In this case it would be better to fallback on the \field{long} field instead, which can be done with the \csopt{abbreviation-sort-fallback} option: -\begin{verbatim} -abbreviation-sort-fallback=long -\end{verbatim} +\begin{codeenv} +\csopt[\field{long}]{abbreviation-sort-fallback} +\end{codeenv} If I do add other types of abbreviations, they will all be sorted according to the \field{long} form, but at least this way I can have some \meta{long} (\meta{short}) names as well. @@ -15838,7 +17836,7 @@ Similarly for the custom \atentryfmt{measurement} entry type in Remember that \atentry{symbol} uses the label as the default sort fallback, so I've changed it to use \field{name} instead: \begin{codeenv} -\csopt[name]{symbol-sort-fallback} +\csopt[\field{name}]{symbol-sort-fallback} \end{codeenv} An alternative approach would be to alias \atentryfmt{unit} and \atentryfmt{measurement} to \atentry{entry} instead. @@ -15861,9 +17859,9 @@ styles. Note that although I've used \styopt{nostyles}, the As with the previous example, the custom fields need to be aliased: \begin{codeenv} \csopt[ - unitname=name, - unitsymbol=symbol, - measurement=description + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} ]{field-aliases} \end{codeenv} @@ -15912,9 +17910,9 @@ for the first \idx{resourceset} and for the second. Similarly for the custom entry fields: \begin{codeenv} \csopt[ - unitname=name, - unitsymbol=symbol, - measurement=description + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} ]{field-aliases} \end{codeenv} @@ -15943,9 +17941,9 @@ This is another example that uses the \exfile{baseunits.bib} and \exfile{derivedunits.bib} files. As before the custom fields need to be aliased: \begin{codeenv} \csopt[ - unitname=name, - unitsymbol=symbol, - measurement=description + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} ]{field-aliases} \end{codeenv} This time I want two glossaries containing all the units (base and @@ -15960,12 +17958,11 @@ and \atentryfmt{measurement} entry types behave like measurement=dualsymbol ]{entry-type-aliases} \end{codeenv} -This causes the \field{name} and \field{symbol} fields to be swapped -in the dual list. Remember that the fallback for the \field{sort} field is the -label for the symbol entry types so I need \csopt[name]{symbol-sort-fallback} -to fallback on \field{name} field instead. (Alternative, I could -just sort by the \field{name} field instead using -\csopt[name]{sort-field}.) +This causes the \field{name} and \field{symbol} fields to be swapped in the +dual list. Remember that the fallback for the \field{sort} field is the label +for the symbol entry types so I need \csopt[\field{name}]{symbol-sort-fallback} +to fallback on \field{name} field instead. (Alternative, I could just sort by +the \field{name} field instead using \csopt[\field{name}]{sort-field}.) The primary entries can still be sorted according to the default locale collator, but the dual entries need a sort method that's @@ -15996,31 +17993,31 @@ style. Since my custom style is based on one of the long styles, I need to set the length register \ics{glsdescwidth} to adjust the width of the description column: -\begin{verbatim} -\setlength{\glsdescwidth}{.4\hsize} -\end{verbatim} +\begin{codeenv} +\cmd{setlength}\marg{\cs{glsdescwidth}}\marg{.4\cmd{hsize}} +\end{codeenv} The \glostyle{long3col-booktabs} style sets up a three column \env{longtable} so I just need to adjust the table header (to rename the column headers) and the way each row is formatted: -\begin{verbatim} -\newglossarystyle{units}% style name -{% base it on long3col-booktabs - \setglossarystyle{long3col-booktabs}% - \renewcommand*{\glossaryheader}{% - \toprule - \bfseries Name & - \bfseries Measurement & - \bfseries Symbol - \tabularnewline\midrule\endhead - \bottomrule\endfoot}% -% main entries: - \renewcommand{\glossentry}[2]{% - \glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}} & - \glossentrydesc{##1}\glspostdescription & - \glossentrysymbol{##1}\tabularnewline - }% +\begin{codeenv} +\ics{newglossarystyle}\marg{units}\comment{style name} +\marg{\comment{base it on \glostyle{long3col-booktabs}} + \ics{setglossarystyle}\marg{long3col-booktabs}\comment{} + \cs{renewcommand}*\marg{\ics{glossaryheader}}\marg{\comment{} + \ics{toprule} + \ics{bfseries} Name \idx{colsep} + \cs{bfseries} Measurement \idx{colsep} + \cs{bfseries} Symbol + \ics{tabularnewline}\ics{midrule}\ics{endhead} + \ics{bottomrule}\ics{endfoot}}\comment{} +\comment{main entries:} + \cs{renewcommand}\marg{\ics{glossentry}}[2]\marg{\comment{} + \ics{glsentryitem}\marg{\idx{param}\idx{param}1}\ics{glstarget}\marg{\idx{param}\idx{param}1}\marg{\cs{glossentryname}\marg{\idx{param}\idx{param}1}} \idx{colsep} + \cs{glossentrydesc}\marg{\idx{param}\idx{param}1}\ics{glspostdescription} \idx{colsep} + \cs{glossentrysymbol}\marg{\idx{param}\idx{param}1}\cs{tabularnewline} + }\comment{} } -\end{verbatim} +\end{codeenv} There are no sub-entries 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 @@ -16081,11 +18078,11 @@ are two simple ways to achieve this: use \csopt[same as base]{category} (which sets the \field{category} to \code{books} for entries in \exfile{books.bib} and to \code{films} for entries in \exfile{films.bib}) or alias the custom \fieldfmt{identifier} field to -\field{category}. I've chosen the later method and also provided +\field{category}. I've chosen the latter method and also provided aliases for the custom \fieldfmt{year} and \fieldfmt{cast} fields: \begin{codeenv} -\csopt[identifier=category,year=user1,cast=user2]{field-aliases}, -\csopt[category]{identical-sort-action} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{year}=\field{user1},\fieldfmt{cast}=\field{user2}]{field-aliases}, +\csopt[\field{category}]{identical-sort-action} \end{codeenv} This ensures that books always come before films with the same title. An oddity is the film \qt{Whisky Galore!}\ which is one @@ -16098,14 +18095,14 @@ still be placed after the book since the film title is longer. Since I've set the \field{category} I can provide semantic formatting commands (as for \exfile{sample-bacteria.tex}): -\begin{verbatim} -\newcommand*{\bookfont}[1]{\emph{#1}} -\newcommand*{\filmfont}[1]{\textsf{\em #1}} -\glssetcategoryattribute{book}{textformat}{bookfont} -\glssetcategoryattribute{book}{glossnamefont}{bookfont} -\glssetcategoryattribute{film}{textformat}{filmfont} -\glssetcategoryattribute{film}{glossnamefont}{filmfont} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{newcommand}*\marg{\cmd{filmfont}}[1]\marg{\ics{textsf}\marg{\ics{em} \idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} +\end{codeenv} I've given films a slightly different format to make them easier to distinguish from books of the same name. @@ -16115,42 +18112,53 @@ or release, which I've assigned to the \field{user1} field. I can define \idxpl{postnamehook} for each category to append the year in brackets after the name is displayed in the glossary: -\begin{verbatim} -\newcommand*{\glsxtrpostnamebook}{% - \ifglshasfield{user1}{\glscurrententrylabel}% - {\space(published \glscurrentfieldvalue)}% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postnamehook{book}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(published \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} } - -\newcommand*{\glsxtrpostnamefilm}{% - \ifglshasfield{user1}{\glscurrententrylabel}% - {\space(released \glscurrentfieldvalue)}% - {}% +\strut +\cs{newcommand}*\marg{\postnamehook{film}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(released \cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} +As with the post-description hook, if you have at least +\styfmt{glossaries-extra} v1.31, it's better to use: +\begin{codeenv} +\ics{glsdefpostname}\margm{category} +\end{codeenv} +instead of: +\begin{codeenv} +\cs{newcommand}\marg{\cs{glsxtrpostnamecategory}} +\end{codeenv} +as it can guard against accidental misspelling of the \code{glsxtrpostname} +part of the command name. I've assigned the \fieldfmt{cast} field to the \field{user2} field, and since this field uses \BibTeX's contributor markup I need to convert this to a form that's easier to customize: -\begin{verbatim} -bibtex-contributor-fields={user2} -\end{verbatim} +\begin{codeenv} +\csopt[\field{user2}]{bibtex-contributor-fields} +\end{codeenv} I'm not sorting by this field and it would look better in the document to list the forenames before the surname so I've also done: -\begin{verbatim} -contributor-order={forenames} -\end{verbatim} -Since I have \sty{datatool-base} v2.28+ installed, the list will be -formatted using \ics{DTLformatlist}. If I want an Oxford comma, I need -to redefine \ics{DTLlistformatoxford} in the document: -\begin{verbatim} -\renewcommand*{\DTLlistformatoxford}{,} -\end{verbatim} +\begin{codeenv} +\csopt[forenames]{contributor-order} +\end{codeenv} +Since I have at least version 2.28 of \sty{datatool-base} installed, +the list will be formatted using \ics{DTLformatlist}. If I want an +Oxford comma, I need to redefine \ics{DTLlistformatoxford} in the document: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{DTLlistformatoxford}}\marg{,} +\end{codeenv} If I want to change \qt{\&} to \qt{and} I also need to redefine \ics{DTLandname}: -\begin{verbatim} -\renewcommand*{\DTLandname}{and} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{DTLandname}}\marg{and} +\end{codeenv} If \ics{DTLformatlist} isn't defined (\sty{datatool-base} v2.27 or earlier), the cast list will look a little odd as it uses a comma separator between all elements of this list, including the final @@ -16158,16 +18166,16 @@ pair (so there's no final \& or \qt{and}). I've provided a \idx{postdescriptionhook} \ics{glsxtrpostdesccategory} to append the cast list: -\begin{verbatim} -\newcommand*{\glsxtrpostdescfilm}{% - \ifglshasfield{user2}{\glscurrententrylabel}% - {% - \glsxtrrestorepostpunc % requires glossaries-extra v1.23+ - \ featuring \glscurrentfieldvalue - }% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postdeschook{film}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} + \cs{glsxtrrestorepostpunc} \comment{requires glossaries-extra v1.23+} + \cs{cs.space}featuring \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} This uses \ics{glsxtrrestorepostpunc} to restore the post-description punctuation if it was suppressed with \ics{glsxtrnopostpunc}. This means that if I decide not to include @@ -16226,9 +18234,9 @@ so the keys either need to be defined or the fields need to be mapped to existing keys. In this case I've decided to map them to the \field{user1}, \field{user2} and \field{user3} fields using \csopt{field-aliases}: -\begin{verbatim} -field-aliases={born=user1,died=user2,othername=user3} -\end{verbatim} +\begin{codeenv} +\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} +\end{codeenv} Although the aliases haven't been referenced in the document, I've taken into account the possibility that they might later be added. To prevent them from showing in the first two lists I've filtered @@ -16236,18 +18244,18 @@ them out. This is easy to do since the aliases are all defined using \atentry{index} whereas the remaining (non-aliased) entries are defined using \atentry{entry} so \csopt{match} can be used to only select entries defined with \atentry{entry}: -\begin{verbatim} -match={entrytype=entry} -\end{verbatim} +\begin{codeenv} +\csopt[entrytype=entry]{match} +\end{codeenv} I'd like the first use of \ics{gls} to display the full name, except for the entry that has the \field{first} field set. The remaining entries only have \field{text} set to a shortened version of the name so they need to have the \field{name} field copied to the \field{first} field using \csopt{replicate-fields}: -\begin{verbatim} -replicate-fields={name={first}} -\end{verbatim} +\begin{codeenv} +\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} +\end{codeenv} I'd like the first use to show the other name in parentheses where provided. The simplest way to achieve this is by defining the @@ -16258,9 +18266,9 @@ could just define \csfmt{glsxtrpostlinkgeneral} but to allow for the possibility of extending the document to incorporate other types of entries I decided to set the \field{category} to \code{people} through the use of the \csopt{category} option: -\begin{verbatim} -category={people} -\end{verbatim} +\begin{codeenv} +\csopt[people]{category} +\end{codeenv} This means that I now need to define a command called \csfmt{glsxtrpostlinkpeople} that will be used after instances of @@ -16270,30 +18278,30 @@ entry with \ics{glsxtrifwasfirstuse} and then tests if the \field{user3} field is set. If so, it does a space followed by that field's value in parentheses. The entry's label can be obtained from \ics{glslabel}: -\begin{verbatim} -\newcommand*{\glsxtrpostlinkpeople}{% - \glsxtrifwasfirstuse - {% - \ifglshasfield{user3}{\glslabel}% - {\space(\glscurrentfieldvalue)}% - {}% - }% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{people}}\marg{\comment{} + \cs{glsxtrifwasfirstuse} + \marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} I'd also like to do something similar after the name when the entry is displayed in the glossary. This means defining the \idx{postnamehook} \ics{glsxtrpostnamecategory}, in this case \csfmt{glsxtrpostnamepeople}. The entry's label is referenced with \ics{glscurrententrylabel}: -\begin{verbatim} -\newcommand*{\glsxtrpostnamepeople}{% - \ifglshasfield{user3}{\glscurrententrylabel}% - {\space(\glscurrentfieldvalue)}% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postnamehook{people}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} (A different command is used since \cs{gls} may occur in the description, which would interfere with the current entry label if they shared the same command to reference the label.) @@ -16303,21 +18311,21 @@ death dates. Although all the entries that have been selected from \exfile{peopl \fieldfmt{died} field, I've added a check for the corresponding \field{user3} field in case new references are added for people who are still alive: -\begin{verbatim} -\newcommand*{\glsxtrpostdescpeople}{% - \ifglshasfield{user1}{\glscurrententrylabel} - {% born - \space(\glscurrentfieldvalue\,--\,% - \ifglshasfield{user2}{\glscurrententrylabel} - {% died - \glscurrentfieldvalue - }% - {}% - )% - }% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postdeschook{people}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{born} + \cs{space}(\cs{glscurrentfieldvalue}\ics{comma}-{}-\cs{comma}\comment{} + \cs{ifglshasfield}\marg{user2}\marg{\cs{glscurrententrylabel}} + \marg{\comment{died} + \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} The first list is quite straight-forward and can be created with: \begin{codeenv} @@ -16325,8 +18333,8 @@ The first list is quite straight-forward and can be created with: \csopt[people]{src}, \csopt[entrytype=entry]{match}, \csopt[people]{category}, - \csopt[name=\marg{first}]{replicate-fields}, - \csopt[born=user1,died=user2,othername=user3]{field-aliases} + \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, + \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases} } \end{codeenv} I have used the \csopt{sort} option and there's no document language, @@ -16337,7 +18345,7 @@ entries are all sorted alphabetically according to the surnames. The second list can easily be created by adding the \csopt{secondary} option: \begin{codeenv} -\csopt[date:user1:bybirth]{secondary} +\csopt[date:\field{user1}:bybirth]{secondary} \end{codeenv} This sorts according to the \field{user1} field (which was originally the \fieldfmt{birth} field). @@ -16354,14 +18362,14 @@ file isn't recognised, the required format can be set with: I've changed the date group headings by redefining \gls{bibglsdategroup} and \gls{bibglsdategrouptitle}, which means that the grouping in the \code{bybirth} glossary will be in the form \meta{year} \meta{era}: -\begin{verbatim} -\newcommand{\bibglsdategroup}[7]{#1#4#7} -\newcommand{\bibglsdategrouptitle}[7]{\number#1\ #4} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7} +\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\cs{number}\idx{param}1\ \idx{param}4} +\end{codeenv} I've also defined the \code{bybirth} glossary and supplied a title: -\begin{verbatim} -\newglossary*{bybirth}{People (Ordered by Birth)} -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{bybirth}\marg{People (Ordered by Birth)} +\end{codeenv} The first two glossaries have entries with fairly long names (especially those with the \idx{postnamehook}), so the best style is the @@ -16386,14 +18394,14 @@ package option. I've set the default style to \glostyle{altlistgroup} but this can locally be changed to \glostyle{bookindex} when I display the index. The \styopt{record} option is needed to use \bibgls, so the \styfmt{glossaries-extra} package is loaded with: -\begin{verbatim} -\usepackage[record,% using bib2gls - index,% create index glossary - postdot,% dot after descriptions -% load glossary-list.sty and glossary-bookindex.sty and patch: - stylemods={list,bookindex}, - style=altlistgroup]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}[\styopt{record},\comment{using bib2gls} + \styopt{index},\comment{create index glossary} + \styopt{postdot},\comment{dot after descriptions} +\comment{load glossary-list.sty and glossary-bookindex.sty and patch:} + \styopt[list,bookindex]{stylemods}, + \styopt[altlistgroup]{style}]\marg{glossaries-extra} +\end{codeenv} The index needs to include all the entries that have already been defined but also needs to include the aliased entries. This means @@ -16412,9 +18420,9 @@ in which to save the group information using \end{codeenv} I need to remember to redefine \ics{glsxtrgroupfield} to this value before displaying the index: -\begin{verbatim} -\renewcommand{\glsxtrgroupfield}{indexgroup} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup} +\end{codeenv} The aliased entries won't be selected by default since they haven't been used in the document, so I need to change the selection @@ -16427,53 +18435,54 @@ In the index, I'd like the surnames first. This can be done by redefining the custom commands used in the \field{name} fields. There's a slight complication here. These commands aren't defined on the first \LaTeX\ run as their definitions are written to the -\ext{glstex} file by \bibgls, so I can't use \cs{renewcommand}. -instead I've provided some custom commands: -\begin{verbatim} -\newcommand*{\swaptwo}[2]{#2, #1} -\newcommand*{\swapthree}[3]{#2 #3, #1} -\end{verbatim} +\ext{glstex} file by \bibgls, so I can't use \cs{renewcommand} (although +I could use \cs{glsrenewcommand}). +Instead I've provided some custom commands: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} +\end{codeenv} Now I just need to make an assignment using \ics{let}: -\begin{verbatim} -\let\sortname\swaptwo -\let\sortart\swaptwo -\let\sortvonname\swapthree -\end{verbatim} +\begin{codeenv} +\cs{let}\gls{sortname}\cmd{swaptwo} +\cs{let}\gls{sortart}\cmd{swaptwo} +\cs{let}\gls{sortvonname}\cmd{swapthree} +\end{codeenv} This doesn't perform any check to determine if the commands are already defined so there won't be a problem on the first run. The first two glossaries shouldn't have number lists: -\begin{verbatim} -\printunsrtglossary[title={People (Alphabetical)},nonumberlist] -\printunsrtglossary[type=bybirth,target=false,nonumberlist] -\end{verbatim} +\begin{codeenv*} +\cs{printunsrtglossary}\oarg{\printglossopt[People (Alphabetical)]{title},\printglossopt{nonumberlist}} +\cs{printunsrtglossary}\oarg{\printglossopt[bybirth]{type},\printglossopt[false]{target},\printglossopt{nonumberlist}} +\end{codeenv*} I'd like to use \sty{hyperref} but I have to switch off the hypertargets for the second glossary otherwise I'll end up with -duplicate targets. This is done with \code{target=false}. +duplicate targets. This is done with \code{\printglossopt[false]{target}}. All references using \cs{gls} etc will link to the first glossary. I could also do this for the index but the cross-references in the aliased entries will link to the first glossary rather than the relevant entry in the index. The simplest way to fix this is to redefine \ics{glolinkprefix} to provide a different target: -\begin{verbatim} -\renewcommand*{\glolinkprefix}{idx:} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:} +\end{codeenv} These redefinitions need to be done before the index. I've decided to use the starred \ics{printunsrtglossary*} to localise these changes, although that's not needed for this document since the index comes right at the end: -\begin{verbatim} -\printunsrtglossary* - [type=index,style=bookindex] - {% - \let\sortname\swaptwo - \let\sortart\swaptwo - \let\sortvonname\swapthree - \renewcommand{\glsxtrgroupfield}{indexgroup}% - \renewcommand*{\glolinkprefix}{idx:}% +\begin{codeenv*} +\cs{printunsrtglossary*} + \oarg{\printglossopt[index]{type},\printglossopt[\glostyle{bookindex}]{style}} + \marg{\comment{} + \cs{let}\gls!{sortname}\cmd{swaptwo} + \cs{let}\gls!{sortart}\cmd{swaptwo} + \cs{let}\gls!{sortvonname}\cmd{swapthree} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}\comment{} + \cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}\comment{} } -\end{verbatim} +\end{codeenv*} The complete document code is listed below. The document build is: \begin{verbatim} pdflatex sample-people @@ -16501,38 +18510,38 @@ finding a way of assigning each book entry a \field{parent} field that contains the label identifying the relevant author in \exfile{people.bib}. To recap, each author is defined in \exfile{people.bib} in the form: -\begin{verbatim} -@entry{dickens, - name={\sortname{Charles}{Dickens}}, - text={Dickens}, - description={English writer and social critic}, - born={7~February 1812 AD}, - died={9~June 1870 AD}, - identifier={person} +\begin{codeenv} +\atentry{entry}\marg{dickens, + \field{name}=\marg{\gls{sortname}\marg{Charles}\marg{Dickens}}, + \field{text}=\marg{Dickens}, + \field{description}=\marg{English writer and social critic}, + \fieldfmt{born}=\marg{7\idx{nbspchar}February 1812 AD}, + \fieldfmt{died}=\marg{9\idx{nbspchar}June 1870 AD}, + \fieldfmt{identifier}=\marg{person} } -\end{verbatim} +\end{codeenv} and each book is defined in \exfile{books.bib} in the form: -\begin{verbatim} -@entry{bleakhouse, - name={Bleak House}, - description={novel by Charles Dickens}, - identifier={book}, - author={\sortmediacreator{Charles}{Dickens}}, - year={1852} +\begin{codeenv} +\atentry{entry}\marg{bleakhouse, + \field{name}=\marg{Bleak House}, + \field{description}=\marg{novel by Charles Dickens}, + \fieldfmt{identifier}=\marg{book}, + \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Charles}\marg{Dickens}}, + \fieldfmt{year}=\marg{1852} } -\end{verbatim} +\end{codeenv} There's a field here (the custom \fieldfmt{author} field) that contains the author's name, and this can be aliased to the \field{parent} field with \csopt{field-aliases}: \begin{codeenv} -\csopt[author=parent]{field-aliases} +\csopt[\fieldfmt{author}=\field{parent}]{field-aliases} \end{codeenv} but the author's label in the \exfile{people.bib} file is just the \idx!{lowercase} surname. Remember from \sectionref{sec:texparserlib} that the interpreter will be used on the \field{parent} field if the value contains -\verb|\| or \verb|{| or \verb|}| and +\idx{escchar} or \idx{bgroupchar} or \idx{egroupchar} and \csopt[true]{interpret-label-fields}. This means that with this field alias and the interpreter on, \bibgls\ will attempt to interpret the field contents. So all that's needed is to ensure that @@ -16548,21 +18557,21 @@ As with the \exfile{sample-people.tex} example, I need to copy the \field{name} field to the \field{first} field if that field is missing using \csopt{replicate-fields}: \begin{codeenv} -\csopt[{name=\marg{first}}]{replicate-fields} +\csopt[\field{name}=\marg{\field{first}}]{replicate-fields} \end{codeenv} and I also want to provide a semantic command to format the book title, so the field aliases also need to convert the custom \fieldfmt{identifier} field to \field{category}: \begin{codeenv} -\csopt[identifier=category,author=parent]{field-aliases} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{author}=\field{parent}]{field-aliases} \end{codeenv} so that the document can set the \catattr{textformat} and \catattr{glossnamefont} attributes: -\begin{verbatim} -\newcommand*{\bookfont}[1]{\emph{#1}} -\glssetcategoryattribute{book}{textformat}{bookfont} -\glssetcategoryattribute{book}{glossnamefont}{bookfont} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\end{codeenv} As with \exfile{sample-media.tex}, the terminating question mark at the end of some of the \field{name} fields can cause an awkward situation if \cs{gls} is used at the end of a sentence. This can be @@ -16573,24 +18582,24 @@ the \csopt{check-end-punctuation} option. In this example, the all the books, so it's sufficient just to check the \field{name} field: \begin{codeenv} -\csopt[name]{check-end-punctuation} +\csopt[\field{name}]{check-end-punctuation} \end{codeenv} With \sty{glossaries-extra} v1.23+ it's easy to hook into the \idx{postlinkhook} to check if -\fielddisp{fieldendpunc}{namendpunc} exists: -\begin{verbatim} -\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% - \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% +\fielddisp{fieldendpunc}{nameendpunc} exists: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} } -\end{verbatim} -This will now cause the full stops following -\begin{verbatim} -\gls{whydidnttheyaskevans}. -\end{verbatim} +\end{codeenv} +This will now cause the full stops following: +\begin{codeenv} +\cs{gls}\marg{whydidnttheyaskevans}. +\end{codeenv} and -\begin{verbatim} -\gls{doandroidsdreamofelectricsheep}. -\end{verbatim} +\begin{codeenv} +\cs{gls}\marg{doandroidsdreamofelectricsheep}. +\end{codeenv} to be discarded. The complete document code is listed below. The document build is: @@ -16632,15 +18641,15 @@ automatic loading of the default style packages and \sty{glossary-list} packages and patch the styles. A \idx{full-stop} is automatically placed after the descriptions with \styopt{postdot}. -\begin{verbatim} -\usepackage[record,% using bib2gls -nomain,% don't define main glossary -postdot,% full stop after descriptions -nostyles,% don't load default styles -% load glossary-tree and glossary-list and patch styles: -stylemods={tree,list} -]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} +\styopt{nomain},\comment{don't define main glossary} +\styopt{postdot},\comment{full stop after descriptions} +\styopt{nostyles},\comment{don't load default styles} +\comment{load glossary-tree and glossary-list and patch styles:} +\styopt[tree,list]{stylemods} +}\marg{glossaries-extra} +\end{codeenv} Next I need to create the glossaries for the list of authors and list of titles: \begin{codeenv} @@ -16648,16 +18657,16 @@ list of titles: \cs{newglossary*}\marg{titles}\marg{Titles} \end{codeenv} The simplest way of assigning the authors to the \code{contributors} -glossary and the titles to the \code{titles} glossary is to use +glossary and the titles to the \code{titles} glossary is to use: \begin{codeenv} \csopt[contributors]{type} \end{codeenv} in the \idx{resourceset} and provide a -modified version of \ics{bibglsnewbibtexentry} that assigns +modified version of \gls{bibglsnewbibtexentry} that assigns \field{type} after the options: \begin{codeenv} -\cs{newcommand}\marg{\cs{bibglsnewbibtexentry}}[4]\marg{\idx{commentchar} - \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{name=\marg{\idx{param}3},\idx{param}2,type=\marg{titles}}\marg{\idx{param}4}\idx{commentchar} +\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{} + \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{} } \end{codeenv} The standard \BibTeX\ entry types need aliasing to @@ -16667,7 +18676,7 @@ The standard \BibTeX\ entry types need aliasing to \end{codeenv} and the \fieldfmt{title} field is aliased to \field{name}: \begin{codeenv} -\csopt[title=name]{field-aliases} +\csopt[\fieldfmt{title}=\field{name}]{field-aliases} \end{codeenv} (The other fields aren't required for the glossary lists.) The \field{category} is set to the original entry type: @@ -16685,21 +18694,21 @@ are \code{contributor}. In order to list the titles according to category, I've use this as the sort field: \begin{codeenv} -\csopt[category]{sort-field} +\csopt[\field{category}]{sort-field} \end{codeenv} and setting the sort suffix to the \field{name} field sub-sorts the \atentry{bibtexentry} types according to the title (which was aliased to the \field{name}) and the \atentry{contributor} types according to the author: \begin{codeenv} -\csopt[name]{sort-suffix} +\csopt[\field{name}]{sort-suffix} \end{codeenv} Next the groups identified by the labels \code{article} and \code{book} are assigned titles. \begin{codeenv} -\cs{glsxtrsetgrouptitle}\marg{article}\marg{Articles} -\cs{glsxtrsetgrouptitle}\marg{book}\marg{Books} +\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles} +\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books} \end{codeenv} The \field{group} field is actually set to the associated letter by the default \csopt{sort} method. The desired labels are stored in the \field{category} @@ -16707,11 +18716,11 @@ field. Since the entries are sorted by category, then they are naturally in those sub-blocks, which means that the group titles can be set by locally redefining \ics{glsxtrgroupfield} to \code{category}: \begin{codeenv} -\cs{printunsrtglossary*}[type=titles,style=indexgroup] -\marg{\idx{commentchar} - \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{category}\idx{commentchar} - \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\idx{commentchar} - \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\idx{commentchar} +\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}] +\marg{\comment{} + \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{\field{category}}\comment{} + \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{} + \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{} } \end{codeenv} There's no \field{description} field set for these entries, but the @@ -16730,7 +18739,7 @@ this case the \ext{bib} file only contains \atentryfmt{article} and The list of contributors can simply be displayed with: \begin{codeenv} -\cs{printunsrtglossary}[type=contributors,style=altlist] +\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}] \end{codeenv} This will only list the names as there's no description, but again the \idx{postdescriptionhook} can be used, in this case for the \code{contributor} @@ -16738,14 +18747,14 @@ category. The hook iterates over the internal list provided by the \field{bibtexentry} field. This allows the titles to be listed as well: \begin{codeenv} -\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\idx{commentchar} - \ics{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\idx{commentchar} - \marg{\idx{commentchar} +\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{} + \ics{glsxtrifhasfield}\marg{\field{bibtexentry}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\comment{} \cs{glsxtrfieldforlistloop} - \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\idx{commentchar} - \marg{\csfmt{contributorhandler}}\idx{commentchar} - }\idx{commentchar} - \marg{\ics{par} No titles.}\idx{commentchar} + \marg{\cs{glscurrententrylabel}}\marg{\field{bibtexentry}}\comment{} + \marg{\csfmt{contributorhandler}}\comment{} + }\comment{} + \marg{\ics{par} No titles.}\comment{} } \end{codeenv} The handler macro displays the name of the associated @@ -16785,13 +18794,13 @@ I'm using the \glostyle{mcolalttree} style for this document, which means that the \sty{glossary-mcols} package is required and the styles need patching, which can be done with the \styopt{stylemods} package option: -\begin{verbatim} -\usepackage[record,% using bib2gls - nostyles,% don't load default styles - postdot,% append a dot after descriptions - stylemods={mcols},% load glossary-mcols.sty and patch - style=mcolalttree]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls} + \styopt{nostyles},\comment{don't load default styles} + \styopt{postdot},\comment{append a dot after descriptions} + \styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch} + \styopt[mcolalttree]{style}}\marg{glossaries-extra} +\end{codeenv} I'm not using a group-based style which suggests that I don't need the \longarg{group} switch. However, although I don't want group titles, I still want a slight gap between logical groups, which means that I @@ -16813,21 +18822,21 @@ I've used \csopt{field-aliases} to convert the custom \fieldfmt{identifier} field to \field{category}, which means I can also sort by that field: \begin{codeenv} -\csopt[category]{sort-field}, -\csopt[identifier=category]{field-aliases} +\csopt[\field{category}]{sort-field}, +\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases} \end{codeenv} Since this will cause identical sort values, I need to provide a fallback. Here I've decided to fallback on the \field{description} field: \begin{codeenv} -\csopt[description]{identical-sort-action} +\csopt[\field{description}]{identical-sort-action} \end{codeenv} -This means that entries will be order by \field{category} and +This means that entries will be ordered by \field{category} and then \field{description}, which naturally creates blocks of symbol types in the glossary. Remember that I want a small vertical gap between each logical -block. These needs the \field{group} field which, with the default +block. These need the \field{group} field which, with the default locale sort, is obtained from the first letter of the sort value. In this case the sort value is obtained from the \field{category} field, and as each category happens to start with a different @@ -16837,7 +18846,7 @@ with the same letter as an existing category, it's better to provide a more future-proof method, so I've set the \field{group} field to fetch its value from the \field{category} field: \begin{codeenv} -\csopt[category=group]{replicate-fields} +\csopt[\field{category}=\field{group}]{replicate-fields} \end{codeenv} (Since the \csopt{field-aliases} option is always performed before \csopt{replicate-fields}, the \field{category} field will already @@ -16871,18 +18880,18 @@ This example uses \exfile{bigmathsymbols.bib} and \exfile{mathsobjects.bib}. It has a fairly similar preamble to \exfile{sample-msymbols.tex}, but \exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib} are now needed to provide -the \csref{sortart} command: +the \gls!{sortart} command: \begin{codeenv} -\gls!{GlsXtrLoadResources}\oarg{ +\gls{GlsXtrLoadResources}\oarg{ \csopt[no-interpret-preamble]{src}, \csopt[false]{interpret-preamble} } \end{codeenv} There's also an extra custom field to alias: \begin{codeenv} -\csopt[identifier=category,format=user1]{field-aliases} +\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{format}=\field{user1}]{field-aliases} \end{codeenv} -I've aliased \fieldfmt{format} to \field{user1} since \csref{glsxtrfmt} +I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt} defaults to that field. If I decided to use a different field I also need to remember to redefine \ics{GlsXtrFmtField} to match. @@ -16892,29 +18901,29 @@ indexed, so I've omitted the \csopt{selection} option I used in the I still don't want any number lists so I still have \csopt[false]{save-locations}. -I want \csref{glsxtrfmt} to index (which it doesn't by default) so +I want \gls!{glsxtrfmt} to index the term (which it doesn't by default) so that means I need to redefine \ics{GlsXtrFmtDefaultOptions} to prevent it from using \code{noindex}: -\begin{verbatim} -\renewcommand{\GlsXtrFmtDefaultOptions}{} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}\marg{\cs{GlsXtrFmtDefaultOptions}}\marg{} +\end{codeenv} I've provided some convenient wrapper commands that use -\csref{glsxtrfmt*} or the non-linking \csref{glsxtrentryfmt} that +\gls!{glsxtrfmt*} or the non-linking \gls!{glsxtrentryfmt} that are in the form: -\begin{verbatim} -\newcommand{\set}[2][]{\glsxtrfmt*[#1]{set}{#2}} -\newcommand{\nlset}[1]{\glsxtrentryfmt{set}{#1}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{set}}[2][]\marg{\gls{glsxtrfmt*}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}} +\cs{newcommand}\marg{\cmd{nlset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}} +\end{codeenv} The use of the starred form allows: -\begin{verbatim} -\[\set{A} = \gls{bigcup}[_{i=1}^n] \set{B}[_i] \] -\end{verbatim} +\begin{codeenv} +\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}[\idx{sbchar}\marg{i=1}\idx{spchar}n] \cmd{set}\marg{B}[\idx{sbchar}i] \cmd{]} +\end{codeenv} which produces: \[ \mathcal{A} = \bigcup_{i=1}^n \mathcal{B}_i \] Note the difference if the optional arguments aren't used: -\begin{verbatim} -\[\set{A} = \gls{bigcup}_{i=1}^n \set{B}_i \] -\end{verbatim} +\begin{codeenv} +\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}\idx{sbchar}\marg{i=1}\idx{spchar}n \cmd{set}\marg{B}\idx{sbchar}i \cmd{]} +\end{codeenv} This produces: \[ \mathcal{A} = \bigcup{}_{i=1}^n \mathcal{B}{}_i \] @@ -16956,15 +18965,19 @@ the first package is loaded and before the second. Since I want the definitions provide by \sty{ifsym} I have to first load \sty{marvosym}, then undefine the conflicting commands and then load \sty{ifsym}: -\begin{verbatim} -\usepackage{etoolbox} -\usepackage{marvosym} -\undef\Sun -\undef\Lightning -\usepackage[weather]{ifsym} -\end{verbatim} +\begin{codeenv} +\cs{usepackage}\marg{etoolbox} +\cs{usepackage}\marg{marvosym} +\cs{undef}\cmd{Sun} +\cs{undef}\cmd{Lightning} +\cs{usepackage}\oarg{\styoptfmt{weather}}\marg{ifsym} +\end{codeenv} The \sty{etoolbox} package is also loaded as it provides -\ics{undef}. +\ics{undef}. (An alternative is to modify the +\exfile{miscsymbols.bib} file so that it uses \sty{ifsym}'s more +generic \cs{textweathersymbol} command and omit the \styoptfmt{weather} +option when loading the package, but the method used here +demonstrates how to deal with such conflicts.) The custom entry type \atentryfmt{icon} must be aliased for the entries to be recognised: @@ -16980,18 +18993,18 @@ are obtained from the \field{category}, which again I obtain from the custom \fieldfmt{identifier} field using: \begin{codeenv} \csopt[ - identifier=category, - icon=name, - icondescription=description]{field-aliases}, -\csopt[category=group]{replicate-fields} + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icon}=\field{name}, + \fieldfmt{icondescription}=\field{description}]{field-aliases}, +\csopt[\field{category}=\field{group}]{replicate-fields} \end{codeenv} The \field{group} field is just a label and an appropriate title needs to be supplied for each group label: -\begin{verbatim} -\glsxtrsetgrouptitle{information}{Information} -\glsxtrsetgrouptitle{mediacontrol}{Media Controls} -\glsxtrsetgrouptitle{weather}{Weather Symbols} -\end{verbatim} +\begin{codeenv} +\cs{glsxtrsetgrouptitle}\marg{information}\marg{Information} +\cs{glsxtrsetgrouptitle}\marg{mediacontrol}\marg{Media Controls} +\cs{glsxtrsetgrouptitle}\marg{weather}\marg{Weather Symbols} +\end{codeenv} This also requires sorting first by \field{category} and then fallback on another field. The most appropriate here is the \field{description} field, but instead of using @@ -16999,8 +19012,8 @@ fallback on another field. The most appropriate here is the which works better with the default locale sort when the fallback field consists of words or phrases. \begin{codeenv} -\csopt[category]{sort-field}, -\csopt[description]{sort-suffix}, +\csopt[\field{category}]{sort-field}, +\csopt[\field{description}]{sort-suffix}, \csopt[|]{sort-suffix-marker} \end{codeenv} Since I'm using one of the \glostyle{alttree} styles, I need to set @@ -17032,27 +19045,31 @@ The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}. {fig:sample-textsymbols.pdf} \end{figure} -\filesection{sample-languages.tex} +\filesection{sample-markuplanguages.tex} This example uses \exfile{markuplanguages.bib}. Since the file includes abbreviations, any commands that must be used before abbreviations are defined need to go before -\ics{GlsXtrLoadResources}. This includes the abbreviation style, +\gls!{GlsXtrLoadResources}. This includes the abbreviation style, which I've set to \abbrstyle{long-short-desc}: -\begin{verbatim} -\setabbreviationstyle[markuplanguage]{long-short-desc} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\end{codeenv} This style sets the \field{name} field using \ics{glsxtrlongshortdescname}, which defaults to the long form -followed by the short form in parenthesis. I decided to switch this +followed by the short form in parentheses. I decided to switch this round so that the short form is shown first, which conveniently matches the default \csopt{abbreviation-sort-fallback}. -\begin{verbatim} -\renewcommand*{\glsxtrlongshortdescname}{% - \protect\glsabbrvfont{\the\glsshorttok}\space - \glsxtrparen{\glslongfont{\the\glslongtok}}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\ics{glsabbrvfont}\marg{\ics{the}\ics{glsshorttok}}\cs{space} + \ics{glsxtrparen}\marg{\ics{glslongfont}\marg{\cs{the}\ics{glslongtok}}}\comment{} } -\end{verbatim} +\end{codeenv} +(The long form is still shown before the short form on the first use +of \cs{gls} in the document. The switch in the above code only +affects how the term is displayed in the glossary.) + This redefinition must be done before the abbreviations are defined as it's expanded when the \field{name} field is set. (Note the need to protect commands that shouldn't be expanded.) If I decide not to change @@ -17064,7 +19081,7 @@ that marks up the letters in the \field{long} field used to obtain the abbreviation. As with the abbreviation style, this must be done before the abbreviations are defined: \begin{codeenv} -\cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\csfmt{abbrvtag}} +\cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\cmd{abbrvtag}} \end{codeenv} If you accidentally place it after \gls{GlsXtrLoadResources}, you'll encounter an error on the second \LaTeX\ run (but not the first). @@ -17076,15 +19093,15 @@ the \atentry{preamble} definition, which is now in the resource file. The tagging format is governed by \ics{glsxtrtagfont} which underlines its argument by default. I've redefined it to also convert the letter to \idx{uppercase}: -\begin{verbatim} -\renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{MakeTextUppercase}\marg{\idx{param}1}}} +\end{codeenv} Note that in the \code{mathml} case, the first tag consists of more than one letter: -\begin{verbatim} -long={\abbrvtag{m\NoCaseChange{ath}}ematical }#markuplang -\end{verbatim} -Here \ics{NoCaseChange} is used to prevent \ics{MakeTextUppercase} +\begin{codeenv} +\field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang +\end{codeenv} +Here \ics{NoCaseChange} prevents \ics{MakeTextUppercase} from applying the case change. The default \csopt{selection} criteria includes entries that have @@ -17093,24 +19110,24 @@ been indexed and any cross-references. Some of the up and the referenced entry is included in the dependency list. However, I don't want any indexing performed by commands occurring in the glossary. This can be dealt -with in one of two ways: either switch the format to \code{glsignore} +with in one of two ways: either switch the format to \encap{glsignore} or suppress the indexing by changing the default options with \ics{GlsXtrSetDefaultGlsOpts}. In this case I decided to turn the records into ignored records: \begin{codeenv} -\ics{GlsXtrSetDefaultNumberFormat}\marg{glsignore} +\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} -This means that some of the entries won't have location lists, so I've provided -a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the +This means that some of the entries won't have location lists, 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 comma: -\begin{verbatim} -\newcommand{\glsxtrpostdescmarkuplanguage}{% - \glsxtrifhasfield{location}{\glscurrententrylabel}% - {,}% - {.}% +\begin{codeenv} +\cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{,}\comment{} + \marg{.}\comment{} } -\end{verbatim} +\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 indexed. @@ -17120,32 +19137,42 @@ I decided to convert the first letter of the \field{name} field to abbreviations based on the style, I've decided to implement this through the \catattr{glossname} attribute rather than using \csopt{name-case-change}: -\begin{verbatim} -\glssetcategoryattribute{markuplanguage}{glossname}{firstuc} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossname}}\marg{firstuc} +\end{codeenv} If this line causes an error when the glossary is displayed that goes away if it's commented out, make sure you have at least version 2.06 of \sty{mfirstuc}. For most of the entries, this doesn't make a difference as they already start with a capital. It's only the \code{markdown} entry that's actually affected. +The description case change is dealt with by \bibgls\ instead: +\begin{codeenv} +\csopt[firstuc]{description-case-change} +\end{codeenv} +This works better than the \catattr{glossdesc} attribute as \bibgls\ can +convert commands like \ics{glstext} into \ics{Glstext} which +\ics{makefirstuc} can't do. (Although in this particular example, +there's no difference as both instances of \cs{glstext} already +produce \idx{uppercase} text.) + The complete document code is listed below. The document build is: \begin{verbatim} -pdflatex sample-languages -bib2gls --group sample-languages -pdflatex sample-languages +pdflatex sample-markuplanguages +bib2gls --group sample-markuplanguages +pdflatex sample-markuplanguages \end{verbatim} -The resulting document is shown in \figureref{fig:sample-languages.pdf}. +The resulting document is shown in \figureref{fig:sample-markuplanguages.pdf}. -\lstinputlisting[firstline=5]{../examples/sample-languages.tex} +\lstinputlisting[firstline=5]{../examples/sample-markuplanguages.tex} \begin{figure} \figcontents {% - \frame{\includegraphics[height=.9\textheight]{../examples/sample-languages.pdf}}% + \frame{\includegraphics[height=.9\textheight]{../examples/sample-markuplanguages.pdf}}% } -{\caption{\filefmt{sample-languages.pdf}}} -{fig:sample-languages.pdf} +{\caption{\filefmt{sample-markuplanguages.pdf}}} +{fig:sample-markuplanguages.pdf} \end{figure} @@ -17161,19 +19188,19 @@ If this field is present, the language is given by the first element of the custom \fieldfmt{language} field. In this case, I'm providing keys for the custom -\fieldfmt{language} and \fieldfmt{translation} fields, and for a bit +\fieldfmt{language} and \fieldfmt{translation} fields, and, for a bit of variety from the other examples, I'm ignoring the custom \fieldfmt{identifier} field. The custom keys are provided with \ics{glsaddstoragekey}: -\begin{verbatim} -\glsaddstoragekey{language}{}{\glsentrylanguage} -\glsaddstoragekey{translation}{}{\glsentrytranslation} -\end{verbatim} +\begin{codeenv} +\cs{glsaddstoragekey}\marg{language}\marg{}\marg{\cmd{glsentrylanguage}} +\cs{glsaddstoragekey}\marg{translation}\marg{}\marg{\cmd{glsentrytranslation}} +\end{codeenv} The \ext{bib} file includes abbreviations. Remember that the abbreviation style must be set before the resource file is loaded: -\begin{verbatim} -\setabbreviationstyle[tug]{long-short-user} -\end{verbatim} +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{tug}\marg{\abbrstyle{long-short-user}} +\end{codeenv} For this example, I'm explicitly setting the \field{category} field to \code{tug}: \begin{codeenv} @@ -17186,25 +19213,25 @@ subsequent use if the \field{short} field ends with a \idx{full-stop}. This means I need to check for end-of-sentence punctuation for the \field{short} field. It's also a good idea to do this for the \field{name} field for the non-abbreviations. -\begin{verbatim} -check-end-punctuation={name,short} -\end{verbatim} +\begin{codeenv} +\csopt[\field{name},\field{short}]{check-end-punctuation} +\end{codeenv} It's now possible to discard a \idx{full-stop} that follows \ics{gls}: -\begin{verbatim} -\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{% - \ifglshasshort{\glslabel}% - {% - \glsxtrifwasfirstuse{}% - {% - \GlsXtrIfFieldUndef{shortendpunc}{\glslabel}{#2}{#1}% - }% - }% - {% - \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}% - }% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{} + \ics{ifglshasshort}\marg{\cs{glslabel}}\comment{} + \marg{\comment{} + \cs{glsxtrifwasfirstuse}\marg{}\comment{} + \marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{shortendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} + }\comment{} + }\comment{} + \marg{\comment{} + \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{} + }\comment{} } -\end{verbatim} +\end{codeenv} This first tests if the entry that's just been referenced has a \field{short} field. If it has, then the next test is to check if that was the first use for that entry. If it was, nothing is done. @@ -17224,10 +19251,10 @@ If you don't have it installed, you'll need to change it. \end{verbatim} Since it's a multilingual document I also need \sty{polyglossia} with the main language set to \code{english}: -\begin{verbatim} -\usepackage{polyglossia} -\setmainlanguage[variant=uk]{english} -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}\marg{polyglossia} +\ics{setmainlanguage}\oarg{variant=uk}\marg{english} +\end{codeenv} Now comes the difficult bit. The document needs to determine what other languages need to be loaded. The \sty{tracklang} package provides a convenient interface when dealing with language tags. @@ -17236,26 +19263,26 @@ it here explicitly as a reminder: \begin{verbatim} \usepackage{tracklang} \end{verbatim} -Once the resource file has been loaded, I need to iterate over all -the defined entries and check if the \fieldfmt{translation} field -has been set. If it has, then the first language tag in the -\fieldfmt{language} field will supply the language, but this needs -to be converted from the \idx{IETF} language tag to a language name -recognised by \sty{polyglossia}. +Once the \hyperref[sec:resourcesets]{resource file} has been loaded, I need to +iterate over all the defined entries and check if the \fieldfmt{translation} +field has been set. If it has, then the first language tag in the +\fieldfmt{language} field will supply the language, but this needs to be +converted from the \idx{IETF} language tag to a language name recognised by +\sty{polyglossia}. Iterating over all entries can be done with \ics{forglsentries} but remember that no entries will be defined before \bibgls\ has been run, so this does nothing on the first \LaTeX\ run. -\begin{verbatim} -\forglsentries{\thislabel}{% - \glsxtrifhasfield{translation}{\thislabel}% - {% - % requires glossaries-extra v1.24 - \glsxtrforcsvfield{\thislabel}{language}{\addfirstlang}% - }% - {}% +\begin{codeenv} +\cs{forglsentries}\marg{\cmd{thislabel}}\marg{\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cmd{thislabel}}\comment{} + \marg{\comment{} + \comment{requires glossaries-extra v1.24} + \cs{glsxtrforcsvfield}\marg{\cmd{thislabel}}\marg{language}\marg{\cmd{addfirstlang}}\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} Within the outer (\cs{forglsentries}) loop, there's a check for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}. If it's present, then the first element of the \fieldfmt{language} @@ -17272,7 +19299,7 @@ adds the given language tag as a tracked language using can then be converted to the root language label using \ics{TrackedLanguageFromDialect}. If this language is supported by \sty{polyglossia}, then there should be a file called -\metafilefmt{gloss}{language}{.ldf}. +\metafilefmt{gloss-}{language}{.ldf}. Some of the entries use the same language, so it's necessary to check if the language has already been defined before loading it. @@ -17289,64 +19316,65 @@ already in the list before adding it. Since this part of the code is scoped, the global \ics{listxadd} is used to add the language label to the list. -Next the \field{useri} field is set to \code{text}\meta{language} +Next the \field{useri} field is set to +\encapdisp{textlanguage}{text\meta{language}} which is the name of the control sequence used with -\sty{polyglossia} to switch languages. This means that -\ics{glsxtrentryfmt}\margm{text} can be used to format \meta{text} +\sty{polyglossia} to switch language for a short block of text. This means that +\gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text} in the relevant language. Finally, \ics{glsxtrendfor} is used to break out of the loop. -\begin{verbatim} -\newcommand*{\addfirstlang}[1]{% - \TrackLocale{#1}% - \edef\thislanguage{% - \TrackedLanguageFromDialect\TrackLangLastTrackedDialect}% - \IfFileExists{gloss-\thislanguage.ldf}% - {% - \xifinlist{\thislanguage}{\langlist}{}% - {\listxadd{\langlist}{\thislanguage}}% - \xGlsXtrSetField{\thislabel}{useri}{text\thislanguage}% - \glsxtrendfor - }% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{} + \cs{TrackLocale}\marg{\idx{param}1}\comment{} + \ics{edef}\cmd{thislanguage}\marg{\comment{} + \cs{TrackedLanguageFromDialect}\cs{TrackLangLastTrackedDialect}}\comment{} + \ics{IfFileExists}\marg{gloss-\cmd{thislanguage}.ldf}\comment{} + \marg{\comment{} + \ics{xifinlist}\marg{\cmd{thislanguage}}\marg{\cmd{langlist}}\marg{}\comment{} + \marg{\ics{listxadd}\marg{\cmd{langlist}}\marg{\cmd{thislanguage}}}\comment{} + \ics{xGlsXtrSetField}\marg{\cmd{thislabel}}\marg{\field{useri}}\marg{\encapdisp{textlanguage}{text\cmd{thislanguage}}}\comment{} + \ics{glsxtrendfor} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} Once the \ics{forglsentries} loop has found the appropriate -languages, it's now necessary to iterator over the internal list +languages, it's now necessary to iterate over the internal list \csfmt{langlist} and set the language: -\begin{verbatim} -\forlistloop{\setotherlanguage}{\langlist} -\end{verbatim} +\begin{codeenv} +\ics{forlistloop}\marg{\ics{setotherlanguage}}\marg{\cmd{langlist}} +\end{codeenv} The \abbrstyle{long-short-user} style now needs to be adjusted to ensure that it picks up the appropriate language change. By default this style checks the \field{useri} field, so this needs to be changed to \fieldfmt{translation} by redefining \ics{glsxtruserfield}: -\begin{verbatim} -\renewcommand*{\glsxtruserfield}{translation} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{translation} +\end{codeenv} The command that governs the format of the parenthetical material (\ics{glsxtruserparen}) also needs adjusting. I've changed the space before the parenthesis to \ics{cs.space} because some of the long fields end with a \idx{full-stop} and this corrects the spacing. The \fieldfmt{translation} field is in English, -so this needs to be encapsulated with \csfmt{textenglish} +so this needs to be encapsulated with \icsdisp{textlanguage}{textenglish} in case the surrounding text is in a different language. -\begin{verbatim} -\renewcommand*{\glsxtruserparen}[2]{% - \ - \glsxtrparen{#1% - \ifglshasfield{\glsxtruserfield}{#2}{, - \textenglish{\glscurrentfieldvalue}}{}}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtruserparen}}[2]\marg{\comment{} + \cs{cs.space} + \cs{glsxtrparen}\marg{\idx{param}1\comment{} + \cs{ifglshasfield}\marg{\cs{glsxtruserfield}}\marg{\idx{param}2}\marg{, + \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\marg{}}\comment{} } -\end{verbatim} +\end{codeenv} Next I've defined a convenient command for use in the \catattr{textformat} attributes for the custom \code{tug} category: -\begin{verbatim} -\newcommand*{\tugtextformat}[1]{% - \glsxtrentryfmt{\glslabel}{#1}% +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{tugtextformat}}[1]\marg{\comment{} + \cs{glsxtrentryfmt}\marg{\cs{glslabel}}\marg{\idx{param}1}\comment{} } -\end{verbatim} -This uses \ics{glsxtrentryfmt} to encapsulate the given text +\end{codeenv} +This uses \gls{glsxtrentryfmt} to encapsulate the given text in the appropriate language command (if provided). When this is set as the \catattr{textformat} attribute, it will be used instead of \ics{glstextformat}, which means that the entry label can be @@ -17355,47 +19383,47 @@ referenced with \cs{glslabel}. There's a similar command for use in the \catattr{glossnamefont} attribute. This is used in the glossary, so the label is referenced with \cs{glscurrententrylabel}: -\begin{verbatim} -\newcommand*{\tugnameformat}[1]{% - \glsxtrentryfmt{\glscurrententrylabel}{#1}% +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{tugnameformat}}[1]\marg{\comment{} + \cs{glsxtrentryfmt}\marg{\cs{glscurrententrylabel}}\marg{\idx{param}1}\comment{} } -\end{verbatim} +\end{codeenv} The attributes can now be set to the relevant control sequence name: -\begin{verbatim} -\glssetcategoryattribute{tug}{textformat}{tugtextformat} -\glssetcategoryattribute{tug}{glossnamefont}{tugnameformat} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{textformat}}\marg{tugtextformat} +\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{glossnamefont}}\marg{tugnameformat} +\end{codeenv} -This document uses the \glostyle{bookindex} style. This is set in +The document uses the \glostyle{bookindex} style, which is set in the package options: -\begin{verbatim} -\usepackage[record, - nostyles, - stylemods={bookindex}, - style={bookindex} -]{glossaries-extra} -\end{verbatim} -This style ignores the \field{description} field, so I've provided -a \idx{postnamehook} to append it in parentheses (with the +\begin{codeenv} +\cmd{usepackage}\oarg{\styopt{record}, + \styopt{nostyles}, + \styopt[bookindex]{stylemods}, + \styopt[bookindex]{style} +}\marg{glossaries-extra} +\end{codeenv} +The \glostyle{bookindex} style ignores the \field{description} field, so I've +provided a \idx{postnamehook} to append it in parentheses (with the translation, if provided): -\begin{verbatim} -\newcommand{\glsxtrpostnametug}{% - \ifglshasdesc{\glscurrententrylabel}% - {\ (\glossentrydesc{\glscurrententrylabel}% - \glsxtrifhasfield{translation}{\glscurrententrylabel}% - {, \textenglish{\glscurrentfieldvalue}}% - {}% - )}% - {% - \glsxtrifhasfield{translation}{\glscurrententrylabel}% - {\ (\textenglish{\glscurrentfieldvalue})}% - {}% - }% +\begin{codeenv} +\cs{newcommand}\marg{\postnamehook{tug}}\marg{\comment{} + \ics{ifglshasdesc}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{cs.space}(\cs{glossentrydesc}\marg{\cs{glscurrententrylabel}}\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{, \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\comment{} + \marg{}\comment{} + )}\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{cs.space}(\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}})}\comment{} + \marg{}\comment{} + }\comment{} } -\end{verbatim} +\end{codeenv} Remember that this hook is included within the \field{name} font (provided by the \catattr{glossnamefont} attribute in this case) -so \csfmt{textenglish} is again used to switch the language to +so \csdisp{textlanguage}{textenglish} is again used to switch the language to English for the translation. The complete document code is listed below. The document build is: @@ -17563,7 +19591,7 @@ languages, vegetables, minerals, animals, chemical formula, base units and derived units) and also an index listing all referenced entries with number lists as well as aliased entries that haven't explicitly been used but the -cross-reference term as been indexed. This requires +cross-reference term as been indexed. This requires: \begin{codeenv} \csopt[recorded and deps and see]{selection} \end{codeenv} @@ -17581,66 +19609,66 @@ be in an unnumbered chapter, which is the default for book-like styles, but I want the other glossaries in unnumbered sections so I've used the \styopt{section} option. I just need to remember to switch this before displaying the index: -\begin{verbatim} -\usepackage[record,% use bib2gls - section,% use \section* for glossary headings - postdot,% insert dot after descriptions in glossaries - nomain,% don't create 'main' glossary - index,% create 'index' glossary - nostyles,% don't load default styles -% load and patch required style packages: - stylemods={list,mcols,tree,bookindex} -]{glossaries-extra} -\end{verbatim} +\begin{codeenv} +\cmd{usepackage}\oarg{\styopt{record},\comment{use bib2gls} + \styopt{section},\comment{use \ics{section*} for glossary headings} + \styopt{postdot},\comment{insert dot after descriptions in glossaries} + \styopt{nomain},\comment{don't create 'main' glossary} + \styopt{index},\comment{create 'index' glossary} + \styopt{nostyles},\comment{don't load default styles} +\comment{load and patch required style packages:} + \styopt[list,mcols,tree,bookindex]{stylemods} +}\marg{glossaries-extra} +\end{codeenv} The remaining glossaries need defining: -\begin{verbatim} -\newglossary*{bacteria}{Bacteria} -\newglossary*{markuplanguage}{Markup Languages} -\newglossary*{vegetable}{Vegetables} -\newglossary*{mineral}{Minerals} -\newglossary*{animal}{Animals} -\newglossary*{chemical}{Chemical Formula} -\newglossary*{baseunit}{SI Units} -\newglossary*{derivedunit}{Derived Units} -\end{verbatim} -As with \exfile{sample-bacteria.tex} and \exfile{sample-languages.tex} +\begin{codeenv} +\cs{newglossary*}\marg{bacteria}\marg{Bacteria} +\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} +\cs{newglossary*}\marg{vegetable}\marg{Vegetables} +\cs{newglossary*}\marg{mineral}\marg{Minerals} +\cs{newglossary*}\marg{animal}\marg{Animals} +\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} +\cs{newglossary*}\marg{baseunit}\marg{SI Units} +\cs{newglossary*}\marg{derivedunit}\marg{Derived Units} +\end{codeenv} +As with \exfile{sample-bacteria.tex} and \exfile{sample-markuplanguages.tex} I need to set the abbreviation styles before the abbreviations are defined: -\begin{verbatim} -\setabbreviationstyle[bacteria]{long-only-short-only} -\setabbreviationstyle[markuplanguage]{long-short-desc} -\end{verbatim} -Unlike the \exfile{sample-languages.tex} example, I'm not interested +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\end{codeenv} +Unlike the \exfile{sample-markuplanguages.tex} example, I'm not interested in tagging the initials in this case, but I still want to change the way the \field{name} field is set with the \abbrstyle{long-short-desc} abbreviation style: -\begin{verbatim} -\renewcommand*{\glsxtrlongshortdescname}{% - \protect\protect\glsabbrvfont{\the\glsshorttok}\space - \glsxtrparen{\glslongfont{\the\glslongtok}}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} + \cs{glsxtrparen}\marg{\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}}\comment{} } -\end{verbatim} +\end{codeenv} Remember that this also needs to be set before the abbreviations are defined. The \catattr{textformat} and \catattr{glossnamefont} attributes may be set after definition: -\begin{verbatim} -\newcommand{\bacteriafont}[1]{\emph{#1}} -\glssetcategoryattribute{bacteria}{textformat}{bacteriafont} -\glssetcategoryattribute{bacteria}{glossnamefont}{bacteriafont} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\end{codeenv} The description font also needs to be set since this will contain the long form: -\begin{verbatim} -\glssetcategoryattribute{bacteria}{glossdescfont}{bacteriafont} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\end{codeenv} The \code{markuplanguage} glossary contains descriptions and some long names, so it's better suited to the \glostyle{altlist} style, in which case the descriptions would look better if they started with a capital letter: -\begin{verbatim} -\glssetcategoryattribute{markuplanguage}{glossdesc}{firstuc} -\end{verbatim} +\begin{codeenv} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} +\end{codeenv} Remember that the \glostyle{altlist} style uses the \env{description} environment, which is governed by the document class (and may be modified by list-related packages). In this case, @@ -17672,21 +19700,21 @@ The primary entries for the \atentry{dualindexabbreviation} type ignore the short form. It would be useful to store it. This could be done by copying the \field{short} field with \csopt{replicate-fields}. For example, -\csopt[short=symbol]{replicate-fields}. However, this will cause the +\csopt[\field{short}=\field{symbol}]{replicate-fields}. However, this will cause the \field{symbol} field to be set for both the primary and dual entries, which will cause an unwanted duplication if the dual entries are displayed using a glossary style that shows the \field{symbol} field. Another field (such as \field{user1}) could be used instead or \gls{bibglsnewdualindexabbreviation} could be -defined before \ics{GlsXtrLoadResources}: -\begin{verbatim} -\newcommand{\bibglsnewdualindexabbreviation}[7]{% - \longnewglossaryentry*{#1}{% - name={\protect\bibglsuselongfont{#4}{\glscategory{#2}}},% - symbol={\protect\bibglsuseabbrvfont{#5}{\glscategory{#2}}},% - category={index},#3}{}% +defined before \gls{GlsXtrLoadResources}: +\begin{codeenv} +\cs{newcommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{} + \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{} + \field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{symbol}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}5}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{} + \field{category}=\marg{index},\idx{param}3}\marg{}\comment{} } -\end{verbatim} +\end{codeenv} However, this will affect all \atentry{dualindexabbreviation} entry types, but it's not necessary for the bacteria abbreviations. Instead it's simpler to just keep a record of the dual label so that @@ -17712,12 +19740,12 @@ I also need to alias the custom fields (especially for those in the \exfile{derivedunits.bib} files): \begin{codeenv} \csopt[ - identifier=category, - formula=symbol, - chemicalname=name, - unitname=name, - unitsymbol=symbol, - measurement=description + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{symbol}, + \fieldfmt{chemicalname}=\field{name}, + \fieldfmt{unitname}=\field{name}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{description} ]{field-aliases} \end{codeenv} There's a slight problem here. This ensures that the entries defined @@ -17728,20 +19756,20 @@ entries don't have a \field{description} field. Since I'd like to use the \glostyle{mcolalttreegroup} style, this will end up with the odd appearance of the formula (stored in the \field{name} field for the dual) followed by the chemical name (stored in the \field{symbol} -field for the dual) in parenthesis. This is default \meta{name} +field for the dual) in parenthesis. This is the default \meta{name} (\meta{symbol}) \meta{description} format for the style. I've fixed this by locally redefining \ics{glsxtralttreeSymbolDescLocation} for just that glossary: -\begin{verbatim} -\printunsrtglossary*[type=chemical,style=mcolalttreegroup] -{% - \renewcommand\glsxtralttreeSymbolDescLocation[2]{% - \glossentrysymbol{#1}\glspostdescription\glsxtrAltTreePar - }% - \renewcommand*{\glstreenamefmt}[1]{#1}% - \renewcommand*{\glstreegroupheaderfmt}[1]{\textbf{#1}}% +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[chemical]{type},\printglossopt[mcolalttreegroup]{style}} +\marg{\comment{} + \cs{renewcommand}\cs{glsxtralttreeSymbolDescLocation}[2]\marg{\comment{} + \ics{glossentrysymbol}\marg{\idx{param}1}\cs{glspostdescription}\ics{glsxtrAltTreePar} + }\comment{} + \cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}\comment{} + \cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{} } -\end{verbatim} +\end{codeenv} I've also redefined \cs{glstreenamefmt} to prevent the names appearing in bold, which means I also need to redefine \cs{glstreegroupheaderfmt} to keep the headers bold. @@ -17749,7 +19777,7 @@ appearing in bold, which means I also need to redefine All the \atentryfmt{dualindex\meta{type}} entry types provide a primary entry that behaves like \atentry{index}. The secondary behaves like \atentryfmt{\meta{type}}. This means that the primaries are -conveniently gather together with all the unaliased \atentry{index} +conveniently gathered together with all the unaliased \atentry{index} entries, so the primary entry type needs to be set to \code{index}: \begin{codeenv} \csopt[index]{type} @@ -17760,7 +19788,7 @@ custom \fieldfmt{identifier} field, I can both alias this custom field to the \field{category} field and also set \csopt{dual-type} so that it matches the category: \begin{codeenv} -\csopt[identifier=category]{field-aliases}, +\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, \csopt[same as category]{dual-type} \end{codeenv} The primary entries (in the \code{index} glossary) need to be sorted @@ -17815,20 +19843,20 @@ something that won't cause them to be discarded: The document loads \sty{hyperref} which means that all the \cs{gls} references will create hyperlinks. Since the primaries are in the index, the default prefixes mean that, for example, -\verb|\gls{svg}| links to the \qt{scalable vector graphics} item in +\code{\cs{gls}\marg{svg}} links to the \qt{scalable vector graphics} item in the index rather than to the abbreviation \qt{SVG} in the \code{markuplanguage} glossary. There are two alternatives: change -\verb|\gls{svg}| to \verb|\gls{dual.svg}| or change the default -prefixes, which is the more convenient approach as is the one used +\code{\cs{gls}\marg{svg}} to \code{\cs{gls}\marg{dual.svg}} or change the +default prefixes, which is the more convenient approach and is the one used here: \begin{codeenv} \csopt[idx.]{label-prefix}, \csopt[\empty]{dual-prefix} \end{codeenv} -Now \verb|\gls{svg}| refers to the dual abbreviation \qt{SVG} and -\verb|\gls{idx.svg}| refers to the primary entry \qt{scalable vector +Now \code{\cs{gls}\marg{svg}} refers to the dual abbreviation \qt{SVG} and +\code{\cs{gls}\marg{idx.svg}} refers to the primary entry \qt{scalable vector graphics}. Unfortunately this means that the records created with -\verb|\gls{svg}| now refer to the dual abbreviation and will end up +\code{\cs{gls}\marg{svg}} now refer to the dual abbreviation and will end up being displayed in the glossary instead of the index. This can be fixed with: \begin{codeenv} @@ -17838,9 +19866,9 @@ Which transfers the dual entry locations to the corresponding primary. The other problem is the cross-references in the \field{description} -fields. Since the labels don't start with \idprefix{dual} \bibgls\ -will assume the refer to the primary entries, which means that -\idprefixfmt{idx} (the value of \csopt{label-prefix}) will be +fields. Since the labels don't start with \qt{\idprefix{dual}} \bibgls\ +will assume they refer to the primary entries, which means that +\qt{\idprefixfmt{idx}} (the value of \csopt{label-prefix}) will be inserted. This means that they'll link to the index rather than the glossary entry. It also means that the cross-references where the dual is an abbreviation won't behave like an abbreviation as the @@ -17854,68 +19882,68 @@ The index is displayed using the \glostyle{bookindex} style. This doesn't show the description or symbol by default, but it would be useful to include the symbol in parentheses after the name. This can be done by redefining \ics{glsxtrbookindexname}: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}{\space(\glossentrysymbol{#1})}{}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} } -\end{verbatim} +\end{codeenv} However the chemical forumlae look a little odd in parentheses (especially those that contain parenthetical parts) but this can be fixed by adding a category check: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}% - {% - \glsifcategory{#1}{chemical}% - {, \glossentrysymbol{#1}}% - {\space(\glossentrysymbol{#1})}% - }% - {}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} Unfortunately \ics{glossentrysymbol} doesn't pick up the \catattr{glossnamefont} attribute, so if the short form of the abbreviations is saved in the \field{symbol} field, using one of the methods discussed above, then the custom \csfmt{bacteriafont} won't be applied. A simple solution is to use \ics{glossentrynameother} instead: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}% - {% - \glsifcategory{#1}{chemical}% - {, \glossentrysymbol{#1}}% - {\space(\glossentrynameother{#1}{symbol})}% - }% - {}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} However, since I decided not to store the short form in the \field{symbol} field and just saved the dual entry label instead, I need to lookup the short form from the dual entry: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}% - {% - \glsifcategory{#1}{chemical}% - {, \glossentrysymbol{#1}}% - {\space(\glossentrynameother{#1}{symbol})}% - }% - {% - \glsifcategory{#1}{markuplanguage}% - {% - \glsxtrifhasfield{short}{\glsxtrusefield{#1}{dual}}% - {\space(\glscurrentfieldvalue)}% - {}% - }% - {}% - }% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \ics{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\ics{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{markuplanguage}\comment{} + \marg{\comment{} + \cs{glsxtrifhasfield}\marg{\field{short}}\marg{\cs{glsxtrusefield}\marg{\idx{param}1}\marg{\field{dual}}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} + }\comment{} } -\end{verbatim} +\end{codeenv} Not all of the markup languages are abbreviations so this uses \ics{glsxtrifhasfield} to check if the \field{short} field is set. The dual entry's label is easily obtained because \csopt{dual-field} @@ -17926,16 +19954,17 @@ It's sometimes useful for the index to include a reference to the term's definition. This can be done by making use of \idx{glsextrapostnamehook}, which can be redefined before the glossaries to automatically record each entry: -\begin{verbatim} -\renewcommand{\glsextrapostnamehook}[1]{\glsadd[format=hyperbf]{#1}} -\end{verbatim} +\begin{codeenv} +\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}} +\end{codeenv} This needs to be redefined to ignore its argument before the index, to avoid the redundant index record: -\begin{verbatim} -\renewcommand{\glsextrapostnamehook}[1]{} -\end{verbatim} +\begin{codeenv} +\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, so the document build is: +\LaTeX\ and \bibgls\ call are required to ensure that the location list +is correct, so the document build is: \begin{verbatim} pdflatex sample-multi1 bib2gls --group sample-multi1 @@ -17976,24 +20005,24 @@ letter-number sort methods. This document uses some additional \ext{bib} files to the previous example, so it has extra glossaries, which all need to be defined: -\begin{verbatim} -\newglossary*{bacteria}{Bacteria} -\newglossary*{markuplanguage}{Markup Languages} -\newglossary*{vegetable}{Vegetables} -\newglossary*{mineral}{Minerals} -\newglossary*{animal}{Animals} -\newglossary*{chemical}{Chemical Formula} -\newglossary*{baseunit}{SI Units} -\newglossary*{measurement}{Measurements} -\newglossary*{film}{Films} -\newglossary*{book}{Books} -\newglossary*{person}{People} -\newglossary*{mediacontrol}{Media Control Symbols} -\newglossary*{information}{Information Symbols} -\newglossary*{weather}{Weather Symbols} -\end{verbatim} +\begin{codeenv} +\cs{newglossary*}\marg{bacteria}\marg{Bacteria} +\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages} +\cs{newglossary*}\marg{vegetable}\marg{Vegetables} +\cs{newglossary*}\marg{mineral}\marg{Minerals} +\cs{newglossary*}\marg{animal}\marg{Animals} +\cs{newglossary*}\marg{chemical}\marg{Chemical Formula} +\cs{newglossary*}\marg{baseunit}\marg{SI Units} +\cs{newglossary*}\marg{measurement}\marg{Measurements} +\cs{newglossary*}\marg{film}\marg{Films} +\cs{newglossary*}\marg{book}\marg{Books} +\cs{newglossary*}\marg{person}\marg{People} +\cs{newglossary*}\marg{mediacontrol}\marg{Media Control Symbols} +\cs{newglossary*}\marg{information}\marg{Information Symbols} +\cs{newglossary*}\marg{weather}\marg{Weather Symbols} +\end{codeenv} Note that this is a total of 15~glossaries (including the -\code{index}). With the basic \ics{makeglossaries} method, this would +\code{index}). With the basic \ics{cs.makeglossaries} method, this would require 16 write registers (including the write register used to create the indexing style file), and a total of $15\times3 + 1 = 46$ associated files. (This doesn't include the standard \ext{aux} file @@ -18033,15 +20062,15 @@ the date fields so that I can customise the format in the document. \gls{GlsXtrLoadResources}\oarg{ \csopt[interpret-preamble,people]{src}, \csopt[ - identifier=category, - born=user1, - died=user2, - othername=user3 + \fieldfmt{identifier}=\field{category}, + \fieldfmt{born}=\field{user1}, + \fieldfmt{died}=\field{user2}, + \fieldfmt{othername}=\field{user3} ]{field-aliases}, - \csopt[name=\marg{first}]{replicate-fields}, + \csopt[\field{name}=\marg{\field{first}}]{replicate-fields}, \csopt[person]{type}, \csopt[false]{save-locations} - \csopt[user1,user2]{date-fields}, + \csopt[\field{user1},\field{user2}]{date-fields}, \csopt[d MMM y G]{date-field-format} } \end{codeenv} @@ -18055,9 +20084,9 @@ loaded the \sty{datetime2} package:\footnote{The \usepackage[en-GB]{datetime2} \end{verbatim} so that I can use \ics{DTMdisplaydate} to adjust the formatting: -\begin{verbatim} -\newcommand*{\bibglsdate}[7]{\DTMdisplaydate{#1}{#2}{#3}{#4}} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}*\marg{\gls{bibglsdate}}[7]\marg{\cs{DTMdisplaydate}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\marg{\idx{param}4}} +\end{codeenv} This needs to go before the \idx{resourceset} is loaded. Note that the \styoptfmt{en-GB} option identifies the document locale as \code{en-GB} (since there are no language packages loaded). @@ -18068,80 +20097,80 @@ from the custom \fieldfmt{identifier} field, which in this case has the value \code{person}. This means that the category hooks from \exfile{sample-people.tex} need to be renamed to reflect the different category label: -\begin{verbatim} -\newcommand*{\glsxtrpostlinkperson}{% - \glsxtrifwasfirstuse - {% - \ifglshasfield{user3}{\glslabel}% - {\space(\glscurrentfieldvalue)}% - {}% - }% - {}% -} - -\newcommand*{\glsxtrpostnameperson}{% - \ifglshasfield{user3}{\glscurrententrylabel}% - {\space(\glscurrentfieldvalue)}% - {}% -} - -\newcommand*{\glsxtrpostdescperson}{% - \ifglshasfield{user1}{\glscurrententrylabel} - {% born - \space(\glscurrentfieldvalue\,--\,% - \ifglshasfield{user2}{\glscurrententrylabel} - {% died - \glscurrentfieldvalue - }% - {}% - )% - }% - {}% +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{person}}{\comment{} + \cs{glsxtrifwasfirstuse} + \marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} + }\comment{} + \marg{}\comment{} +} +\strut +\cs{newcommand}*\marg{\postnamehook{person}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{} + \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{} + \marg{}\comment{} +} +\strut +\cs{newcommand}*\marg{\postdeschook{person}}\marg{\comment{} + \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{born} + \cs{space}(\cs{glscurrentfieldvalue}\cs{comma}-{}-\cs{comma}\comment{} + \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}} + \marg{\comment{died} + \cs{glscurrentfieldvalue} + }\comment{} + \marg{}\comment{} + )\comment{} + }\comment{} + \marg{}\comment{} } -\end{verbatim} +\end{codeenv} The other \ext{bib} files that require locale sorting can now be loaded, but remember that the abbreviation style settings must be set first since this resource set includes abbreviations: -\begin{verbatim} -\setabbreviationstyle[bacteria]{long-only-short-only} -\setabbreviationstyle[markuplanguage]{long-short-desc} - -\renewcommand*{\glsxtrlongshortdescname}{% - \protect\protect\glsabbrvfont{\the\glsshorttok}\space +\begin{codeenv} +\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}} +\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}} +\strut +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space} \glsxtrparen{\glslongfont{\the\glslongtok}}% } -\end{verbatim} +\end{codeenv} Now the resource set can be loaded: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ \csopt[bacteria,markuplanguages,vegetables, minerals,animals,books,films]{src}, - \csopt[identifier=category]{field-aliases}, + \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}, \csopt[same as category]{type}, \csopt[false]{save-locations} } \end{codeenv} The semantic markup command and attributes are as for \exfile{sample-multi1.tex}: -\begin{verbatim} -\newcommand{\bacteriafont}[1]{\emph{#1}} -\glssetcategoryattribute{bacteria}{textformat}{bacteriafont} -\glssetcategoryattribute{bacteria}{glossnamefont}{bacteriafont} -\glssetcategoryattribute{bacteria}{glossdescfont}{bacteriafont} -\glssetcategoryattribute{markuplanguage}{glossdesc}{firstuc} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont} +\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc} +\end{codeenv} Similarly for the books: -\begin{verbatim} -\newcommand{\bookfont}[1]{\emph{#1}} -\glssetcategoryattribute{book}{textformat}{bookfont} -\glssetcategoryattribute{book}{glossnamefont}{bookfont} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont} +\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont} +\end{codeenv} (as for \exfile{sample-media.tex}) and for films: -\begin{verbatim} -\newcommand{\filmfont}[1]{\emph{#1}} -\glssetcategoryattribute{film}{textformat}{filmfont} -\glssetcategoryattribute{film}{glossnamefont}{filmfont} -\end{verbatim} +\begin{codeenv} +\cs{newcommand}\marg{\cmd{filmfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont} +\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont} +\end{codeenv} Next come the chemical formulae: \begin{codeenv} @@ -18149,14 +20178,14 @@ Next come the chemical formulae: \csopt[chemicalformula]{src}, \csopt[chemical=symbol]{entry-type-aliases}, \csopt[ - identifier=category, - formula=name, - chemicalname=description + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{name}, + \fieldfmt{chemicalname}=\field{description} ]{field-aliases}, \csopt[chemical]{type}, \csopt{set-widest}, \csopt[letternumber-case]{sort}, - \csopt[name]{symbol-sort-fallback}, + \csopt[\field{name}]{symbol-sort-fallback}, \csopt[false]{save-locations} } \end{codeenv} @@ -18165,16 +20194,16 @@ glossary: \begin{codeenv} \gls{GlsXtrLoadResources}\oarg{ \csopt[baseunits,derivedunits]{src}, - \csopt[measurement=symbol,unit=symbol]{entry-type-aliases}, + \csopt[\fieldfmt{measurement}=\field{symbol},\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}, \csopt[ - unitname=description, - unitsymbol=symbol, - measurement=name + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{name} ]{field-aliases}, \csopt[measurement]{category}, \csopt[measurement]{type}, \csopt{set-widest}, - \csopt[name]{symbol-sort-fallback}, + \csopt[\field{name}]{symbol-sort-fallback}, \csopt[false]{save-locations} } \end{codeenv} @@ -18183,17 +20212,17 @@ Here the \field{name} field is obtained from the custom default locale sort is appropriate. I've locally redefined \ics{glsxtralttreeSymbolDescLocation} to place the symbol in parentheses after the description: -\begin{verbatim} -\printunsrtglossary*[type=measurement,style=alttree,nogroupskip] -{% - \renewcommand{\glsxtralttreeSymbolDescLocation}[2]{% - \glossentrydesc{#1}% - \ifglshassymbol{#1}{\space(\glossentrysymbol{#1})}{}% - \glspostdescription\glstreeprelocation - \glsxtrAltTreePar - }% +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[measurement]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} +\marg{\comment{} + \cs{renewcommand}\marg{\cs{glsxtralttreeSymbolDescLocation}}[2]\marg{\comment{} + \cs{glossentrydesc}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{} + \cs{glspostdescription} + \cs{glsxtrAltTreePar} + }\comment{} } -\end{verbatim} +\end{codeenv} The base units are replicated in the \code{baseunit} glossary, this time with the \field{name} field obtained from the custom @@ -18205,25 +20234,25 @@ prevent duplicate labels. The simplest method is to use \csopt[baseunits]{src}, \csopt[unit=symbol]{entry-type-aliases}, \csopt[ - unitname=description, - unitsymbol=name + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{name} ]{field-aliases}, \csopt[measurement]{category}, \csopt[baseunit]{type}, \csopt[.copy]{duplicate-label-suffix}, - \csopt[name]{symbol-sort-fallback}, + \csopt[\field{name}]{symbol-sort-fallback}, \csopt[false]{save-locations} } \end{codeenv} I can't use \csopt{set-widest} here as it won't pick up the modified label and will instead use the label from the original entry. Instead I've used \cs{glsFindWidestTopLevelName} to find it: -\begin{verbatim} -\printunsrtglossary*[type=baseunit,style=alttree,nogroupskip] -{% - \glsFindWidestTopLevelName[baseunit]% +\begin{codeenv} +\cs{printunsrtglossary*}\oarg{\printglossopt[baseunit]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}} +\marg{\comment{} + \cs{glsFindWidestTopLevelName}\oarg{baseunit}\comment{} } -\end{verbatim} +\end{codeenv} The text symbols from \exfile{miscsymbols.bib} are all loaded in a single \idx{resourceset}, where the \field{type} field can be @@ -18237,13 +20266,13 @@ makes more sense in this case.) \gls{GlsXtrLoadResources}\oarg{ \csopt[miscsymbols]{src}, \csopt[ - identifier=category, - icon=name, - icondescription=description + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icon}=\field{name}, + \fieldfmt{icondescription}=\field{description} ]{field-aliases}, \csopt[icon=symbol]{entry-type-aliases}, \csopt[same as category]{type}, - \csopt[description]{sort-field}, + \csopt[\field{description}]{sort-field}, \csopt[false]{save-locations}, \csopt{set-widest} } @@ -18258,18 +20287,18 @@ with a \idx{symbolgroup} containing the icons from \exfile{miscsymbols.bib}. This needs to be dealt with separately from the rest of the index to keep them together in a single group: \begin{codeenv} -\cs{GlsXtrLoadResources}\oarg{ +\gls{GlsXtrLoadResources}\oarg{ \csopt[miscsymbols]{src}, \csopt[recorded no deps]{selection}, \csopt[.copy]{duplicate-label-suffix}, \csopt[icon=index]{entry-type-aliases}, \csopt[ - identifier=category, - icondescription=symbol, - icon=name + \fieldfmt{identifier}=\field{category}, + \fieldfmt{icondescription}=\field{symbol}, + \fieldfmt{icon}=\field{name} ]{field-aliases}, \csopt[index]{type}, - \csopt[symbol]{sort-field}, + \csopt[\field{symbol}]{sort-field}, \csopt[glssymbols]{group} } \end{codeenv} @@ -18290,23 +20319,23 @@ so that the abbreviations using the \abbrstyle{long-short-desc} style (that is, the abbreviations with the \field{category} set to \code{markuplanguage}) have the \field{name} field set to \meta{long} (\meta{short}): -\begin{verbatim} -\renewcommand*{\glsxtrlongshortdescname}{% - \protect\glslongfont{\the\glslongtok}\space - \glsxtrparen{\glsabbrvfont{\the\glsshorttok}}% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{} + \cs{protect}\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}\cs{space} + \cs{glsxtrparen}\marg{\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}}\comment{} } -\end{verbatim} +\end{codeenv} The \abbrstyle{long-only-short-only} style has a similar command, but it was only introduced to \sty{glossaries-extra} version 1.25: -\begin{verbatim} -\renewcommand*{\glsxtronlyname}{% - \protect\glsabbrvonlyfont{\the\glslongtok}% +\begin{codeenv} +\cs{renewcommand}*\marg{\ics{glsxtronlyname}}{\comment{} + \cs{protect}\cs{glsabbrvonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{} } -\end{verbatim} +\end{codeenv} The abbreviations all need to be sorted according to the long form: \begin{codeenv} -\csopt[long]{abbreviation-sort-fallback} +\csopt[\field{long}]{abbreviation-sort-fallback} \end{codeenv} The custom entry types and fields again need to be aliased \begin{codeenv} @@ -18317,14 +20346,14 @@ The custom entry types and fields again need to be aliased icon=index ]{entry-type-aliases}, \csopt[ - identifier=category, - formula=symbol, - chemicalname=name, - unitname=description, - unitsymbol=symbol, - measurement=name, - icon=symbol, - icondescription=name + \fieldfmt{identifier}=\field{category}, + \fieldfmt{formula}=\field{symbol}, + \fieldfmt{chemicalname}=\field{name}, + \fieldfmt{unitname}=\field{description}, + \fieldfmt{unitsymbol}=\field{symbol}, + \fieldfmt{measurement}=\field{name}, + \fieldfmt{icon}=\field{symbol}, + \fieldfmt{icondescription}=\field{name} ]{field-aliases} \end{codeenv} The chemical formulae and icons are now defined using @@ -18391,7 +20420,7 @@ look up other locations 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: \begin{codeenv} -\csopt[category]{identical-sort-action} +\csopt[\field{category}]{identical-sort-action} \end{codeenv} For the people who have a \field{first} field, I've decided that this would be more appropriate for the index as it's more compact @@ -18401,76 +20430,76 @@ since the \field{name} field is already provided the override setting needs to be on: \begin{codeenv} \csopt{replicate-override}, -\csopt[first=name]{replicate-fields} +\csopt[\field{first}=\field{name}]{replicate-fields} \end{codeenv} As with \exfile{sample-people.tex} I've provided some custom -commands to make it easier to locally redefined \cs{sortname} and -\cs{sortvonname}: -\begin{verbatim} -\newcommand*{\swaptwo}[2]{#2, #1} -\newcommand*{\swapthree}[3]{#2 #3, #1} -\end{verbatim} +commands to make it easier to locally redefine \gls{sortname} and +\gls{sortvonname}: +\begin{codeenv} +\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1} +\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1} +\end{codeenv} I've redefined \ics{glsxtrbookindexname} in a similar manner to \exfile{sample-multi1.tex} but it has some modifications: -\begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}% - {% - \glsifcategory{#1}{chemical}% - {, \glossentrysymbol{#1}}% - {\space(\glossentrynameother{#1}{symbol})}% - }% - {% - \glsifcategory{#1}{film}% - {\ (film)}% - {}% - }% +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{} + \cs{glossentryname}\marg{\idx{param}1}\comment{} + \cs{ifglshassymbol}\marg{\idx{param}1}\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{} + \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{} + \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{} + }\comment{} + \marg{\comment{} + \cs{glsifcategory}\marg{\idx{param}1}\marg{film}\comment{} + \marg{\cs{cs.space}(film)}\comment{} + \marg{}\comment{} + }\comment{} } -\end{verbatim} +\end{codeenv} This appends \qt{(film)} to film names. I've chosen this method rather than using the \idx{postnamehook} as I only want this in the index and not in the list of films. For some of the entries that are referenced in the document, I've appended information in parentheses: -\begin{verbatim} -\gls{Al2SO43} (\glsdesc{Al2SO43}) -\end{verbatim} +\begin{codeenv} +\cs{gls}\marg{Al2SO43} (\ics{glsdesc}\marg{Al2SO43}) +\end{codeenv} This is all right for odd instances, but if this always needs to be done on first use, then it's better to use the \idx{postlinkhook}, which is what I've done for the icons for comparison: -\begin{verbatim} -\newcommand*{\glsxtrpostlinkmediacontrol}{% - \glsxtrpostlinkAddDescOnFirstUse +\begin{codeenv} +\cs{newcommand}*\marg{\postlinkhook{mediacontrol}}\marg{\comment{} + \ics{glsxtrpostlinkAddDescOnFirstUse} } - -\newcommand*{\glsxtrpostlinkinformation}{% - \glsxtrpostlinkAddDescOnFirstUse +\strut +\cs{newcommand}*\marg{\postlinkhook{information}}\marg{\comment{} + \cs{glsxtrpostlinkAddDescOnFirstUse} } - -\newcommand*{\glsxtrpostlinkweather}{% - \glsxtrpostlinkAddDescOnFirstUse +\strut +\cs{newcommand}*\marg{\postlinkhook{weather}}\marg{\comment{} + \cs{glsxtrpostlinkAddDescOnFirstUse} } -\end{verbatim} +\end{codeenv} I've also provided some custom commands to make it easier to reference entries without worrying about the prefixes: \begin{codeenv} \cs{newcommand}\marg{\csfmt{unit}}\marg{\ics{glssymbol}} \cs{newcommand}\marg{\csfmt{measurement}}\marg{\cs{gls}} -\cs{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}} +\gls{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}} \end{codeenv} As with \exfile{sample-multi1.tex}, it would be useful to include the page where the entries are defined in their corresponding lists. Again this can be done by redefining the general purpose non-category post-name hook \ics{glsextrapostnamehook}: -\begin{verbatim} -\newcommand*{\glsextrapostnamehook}[1]{% - \glsadd[format=hyperbf]{#1}% +\begin{codeenv} +\cs{newcommand}*\marg{\cs{glsextrapostnamehook}}[1]\marg{\comment{} + \cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}\comment{} } -\end{verbatim} +\end{codeenv} This needs resetting before the index, since it's redundant to record an entry in the index. This will require an extra \bibgls+\LaTeX\ system call as this code can't be performed until @@ -18516,5 +20545,20 @@ The resulting document is shown in \figureref{fig:sample-multi2.pdf}, \bibliographystyle{plain} \bibliography{bib2gls-cite} +\renewcommand*{\glsxtrbookindexsubname}[1]{% + \glsifcategory{#1}{command}% + {% + \glsxtrifhasfield{useri}{#1}% + {\glossentrynameother{#1}{useri}}% + {\glossentryname{#1}}% + }% + {\glossentryname{#1}}% +} +\renewcommand*{\glsxtrbookindexprelocation}[1]{% + \glsxtrifhasfield{location}{#1}% + {\nobreak\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill}% + {\glsxtrprelocation}% +} +\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}} \printunsrtglossary[type=index] \end{document} 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 65d30f1005c..fec7422d20d 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 cdeb582956d..c1648c9de85 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |