texlive[47658] Master/texmf-dist: bib2gls (8may18)
commits+karl at tug.org
commits+karl at tug.org
Thu May 10 00:21:21 CEST 2018
Revision: 47658
http://tug.org/svn/texlive?view=revision&revision=47658
Author: karl
Date: 2018-05-10 00:21:20 +0200 (Thu, 10 May 2018)
Log Message:
-----------
bib2gls (8may18)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES
trunk/Master/texmf-dist/doc/support/bib2gls/README.md
trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1
trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/convertgls2bib.1
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
trunk/Master/texmf-dist/scripts/bib2gls/bib2gls.jar
trunk/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar
trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml
trunk/Master/texmf-dist/scripts/bib2gls/texparserlib.jar
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
trunk/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
trunk/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
Added Paths:
-----------
trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/citations.bib
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.tex
trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/CHANGES 2018-05-09 22:21:20 UTC (rev 47658)
@@ -1,3 +1,36 @@
+v1.5 (2018-05-09):
+
+ * added introductory guide (bib2gls-begin.pdf)
+
+ * rearranged some of the resource option sections in
+ the main user manual (bib2gls.pdf)
+
+ * new .glstex helper command:
+
+ \bibglssetlastgrouptitle
+
+ * added @indexplural and associated .glstex helper command
+ \bibglsnewindexplural
+
+ * added resource options:
+
+ - sort-replace
+ - dual-sort-replace
+ - secondary-sort-replace
+
+ * save-child-count now also creates the childlist internal field.
+
+ * bug fixes:
+
+ - corrected encoding setting (bib2gls and convertgls2bib)
+ - corrected \ (backslash space) eol causing unwanted extra eol
+ - corrected sort fallback
+ - labelify-replace now recognises \$ in the replacement part as a
+ reference to a captured group
+ - improved error handling for invalid entry IDs
+ - save-child-count was partially switching on flatten-lonely
+ - corrected name-case-change for @index
+
v1.4 (2018-04-09):
* added switches:
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/README.md 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/README.md 2018-05-09 22:21:20 UTC (rev 47658)
@@ -174,6 +174,8 @@
xelatex bib2gls
```
+Similarly for the bib2gls-begin.pdf document.
+
## JAR Files
Create the following directories:
Added: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf 2018-05-09 22:21:20 UTC (rev 47658)
Property changes on: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.1 2018-05-09 22:21:20 UTC (rev 47658)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
+.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -46,7 +46,7 @@
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
@@ -54,20 +54,16 @@
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
-.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 .nr F 0
+.if \nF>0 \{\
+. 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.
@@ -133,7 +129,7 @@
.\" ========================================================================
.\"
.IX Title "BIB2GLS 1"
-.TH BIB2GLS 1 "2018-04-07" "perl v5.18.4" "bib2gls"
+.TH BIB2GLS 1 "2018-04-07" "perl v5.26.1" "bib2gls"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/convertgls2bib.1
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/convertgls2bib.1 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/convertgls2bib.1 2018-05-09 22:21:20 UTC (rev 47658)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
+.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -46,7 +46,7 @@
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
@@ -54,20 +54,16 @@
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
-.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 .nr F 0
+.if \nF>0 \{\
+. 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.
@@ -133,7 +129,7 @@
.\" ========================================================================
.\"
.IX Title "CONVERTGLS2BIB 1"
-.TH CONVERTGLS2BIB 1 "2018-03-04" "perl v5.18.4" "convertgls2bib"
+.TH CONVERTGLS2BIB 1 "2018-03-04" "perl v5.26.1" "convertgls2bib"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
Added: trunk/Master/texmf-dist/doc/support/bib2gls/examples/citations.bib
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/examples/citations.bib (rev 0)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/examples/citations.bib 2018-05-09 22:21:20 UTC (rev 47658)
@@ -0,0 +1,65 @@
+% This file is public domain. See the "Examples" chapter
+% in the bib2gls user manual for a more detailed description
+% of this file.
+
+% Encoding: UTF-8
+
+ at preamble{"\providecommand{\titlefmt}[1]{`#1'}"}
+
+ at article{duck2018,
+ author = {Dickie Duck and Jos\'{e} Arara and Polly Parrot},
+ title = {Avian friendship},
+ journal = {Fowl Times},
+ year = 2018,
+ volume = 7,
+ number = 5,
+ pages = "1032--5"
+}
+
+ at book{duck2016,
+ author = {Dickie Duck},
+ title = {Feathered stunt doubles: \titlefmt{The Birds} and
+other films},
+ publisher = {Duck Duck Goose},
+ year = 2016
+}
+
+ at book{macaw,
+ author = {Prof Macaw},
+ title = {Annotated notes on the \titlefmt{Duck and Goose}
+chronicles},
+ publisher = {Duck Duck Goose},
+ year = 2012
+}
+
+ at book{ing,
+ author = {Bor Ing},
+ title = {\titlefmt{Duck and Goose}: an allegory for modern
+times?},
+ publisher = {Duck Duck Goose},
+ year = 2010
+}
+
+ at article{parrot,
+ author = {Polly Parrot and Dickie Duck},
+ title = {\titlefmt{Duck and Goose} Cheat Sheet for Students},
+ journal = {Fowl Times},
+ year = 2013,
+ volume = 2,
+ number = 10,
+ pages = "15--23"
+}
+
+ at book{parrot2012,
+ author = {A Parrot},
+ title = {My Friend is a Duck},
+ publisher = {Duck Duck Goose},
+ year = 2012
+}
+
+ at book{quackalot,
+ author = {Sir Quackalot},
+ title = {The Adventures of Duck and Goose},
+ publisher = {Duck Duck Goose},
+ year = 2011
+}
Property changes on: trunk/Master/texmf-dist/doc/support/bib2gls/examples/citations.bib
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
===================================================================
(Binary files differ)
Added: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf 2018-05-09 22:21:20 UTC (rev 47658)
Property changes on: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.tex 2018-05-09 22:21:20 UTC (rev 47658)
@@ -0,0 +1,70 @@
+% This file is public domain. See the "Examples" chapter
+% in the bib2gls user manual for a more detailed description
+% of this file.
+
+% bib2gls must be run with the --cite-as-record switch
+
+\documentclass[12pt,a4paper]{article}
+
+\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}
+
+\newglossary*{contributors}{Authors}
+\newglossary*{titles}{Titles}
+
+\newcommand{\bibglsnewbibtexentry}[4]{%
+ \longnewglossaryentry*{#1}{name={#3},#2,type={titles}}{#4}%
+}
+
+\GlsXtrLoadResources[
+ src={citations},% data in citations.bib
+ entry-type-aliases={\GlsXtrBibTeXEntryAliases},
+ field-aliases={
+ title=name
+ },
+ type={contributors},
+ category={same as original entry},
+ sort-field={category},
+ sort-suffix={name}
+]
+
+\glsxtrsetgrouptitle{article}{Articles}
+\glsxtrsetgrouptitle{book}{Books}
+
+\newcommand{\contributorhandler}[1]{\par\glsentryname{#1} \cite{#1}}
+
+\newcommand{\glsxtrpostdesccontributor}{%
+ \glsxtrifhasfield{bibtexentry}{\glscurrententrylabel}%
+ {%
+ \glsxtrfieldforlistloop
+ {\glscurrententrylabel}{bibtexentry}%
+ {\contributorhandler}%
+ }%
+ {\par No titles.}%
+}
+
+\newcommand{\glsxtrpostdescarticle}{\cite{\glscurrententrylabel}}
+\newcommand{\glsxtrpostdescbook}{\cite{\glscurrententrylabel}}
+
+\begin{document}
+This is a sample document with some citations~\cite{macaw,parrot}
+and some more citations~\cite{duck2018,duck2016} and don't
+forget~\cite{ing,parrot2012} and lastly~\cite{quackalot}.
+
+\printunsrtglossary[type=contributors,style=altlist]
+\printunsrtglossary*[type=titles,style=indexgroup]
+{%
+ \renewcommand{\glsxtrgroupfield}{category}%
+ \renewcommand{\glstreenamefmt}[1]{\emph{#1}}%
+ \renewcommand{\glstreegroupheaderfmt}[1]{\textbf{#1}}%
+}
+
+\bibliographystyle{unsrt}
+\bibliography{citations}
+
+\end{document}
Property changes on: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-languages.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/bib2gls.jar
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml
===================================================================
--- trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml 2018-05-09 22:21:20 UTC (rev 47658)
@@ -25,7 +25,8 @@
Synonym: {1}</entry>
<entry key="syntax.silent">{0} Only display error messages.</entry>
<entry key="syntax.locale">{0} <lang> (or {1} <lang>)
- Use language resource file for <lang>.</entry>
+ Use language resource file for <lang>.
+ Also sets default document language.</entry>
<entry key="syntax.log">{0} <file> (or {1} <file>)
Set transcript file name.</entry>
<entry key="syntax.dir">{0} <directory> (or {1} <directory>)
@@ -141,7 +142,7 @@
<entry key="syntax.custom.packages">{0} <list>
Instruct the interpreter to parse
the listed packages.</entry>
-<entry key="syntax.list.known.packages">
+<entry key="syntax.list.known.packages">{0}
List the packages known to the interpreter.</entry>
<entry key="message.reading">Reading {0}</entry>
@@ -242,6 +243,12 @@
Defaulting to: {0}.
(Use {1} if this is incorrect.)</entry>
<entry key="message.tex.charset">TeX character encoding: {0}</entry>
+<entry key="message.charset">Encoding: {0}</entry>
+<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.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>
<entry key="message.adding.supplemental.record">Adding supplemental record {0} to entry {1}''s record list.</entry>
<entry key="message.adding.counter.record">Adding record {0} to entry {1}''s {2} record list.</entry>
@@ -347,6 +354,8 @@
<entry key="warning.identical.field">Falling back on ''{0}'' field (''{1}'' <=> ''{2}'' = {3})</entry>
<entry key="warning.unknown.widest.fortype">Can''t determine widest level {0} entry for glossary type ''{1}''. Using fallback method.</entry>
<entry key="warning.unknown.widest">Can''t determine widest level {0} entry for unknown glossary type. Using fallback method.</entry>
+<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="error.title">Error: {0}</entry>
<entry key="error.alias.map.forbidden">The 'alias' field can't be mapped.</entry>
@@ -368,7 +377,7 @@
(Did you forget to use the ''src'' key?)</entry>
<entry key="error.dir.not.found">Directory not found: {0}</entry>
<entry key="error.not.dir">Not a directory: {0}</entry>
-<entry key="error.cant.open.log">Can't open log file: {0}</entry>
+<entry key="error.cant.open.log">Can''t open log file: {0}</entry>
<entry key="error.invalid.id">Invalid or missing id
{0}</entry>
<entry key="error.invalid.sort.value">Invalid sort method ''{0}'' given in option: {1}</entry>
@@ -394,6 +403,7 @@
<entry key="error.forbidden.ext">Write access forbidden for extension: {0}</entry>
<entry key="error.cant.open.process.stream">Unable to open input stream from process: {0}</entry>
<entry key="error.cyclic.hierarchy">Cyclical hierarchy for entry: {0}</entry>
+<entry key="error.child.parent">Entry can''t be its own parent: {0}</entry>
<entry key="error.duplicate.resource">Duplicate resource: {0}</entry>
<entry key="error.nested.range">Nested location range: {0}
Outer range started with: {1}</entry>
@@ -431,9 +441,9 @@
The following messages are used by convertgls2bib
-->
-<entry key="gls2bib.override.newdualentry">Overriding default definition of \\newdualentry with custom
-definition. (Change \\newcommand to \\providecommand if you want
-\\newdualentry[options]'{'label'}{'short'}{'long'}{'description'}'
+<entry key="gls2bib.override.newdualentry">Overriding default definition of \newdualentry with custom
+definition. (Change \newcommand to \providecommand if you want
+\newdualentry[options]'{'label'}{'short'}{'long'}{'description'}'
converted to @dualabbreviationentry.)</entry>
<!--
@@ -488,7 +498,17 @@
<entry key="tex.error.illegal_align">Illegal alignment {0}</entry>
<entry key="tex.error.misplaced_omit">Misplaced \omit</entry>
<entry key="tex.error.improper_alphabetic_constant">Improper alphabetic constant {0}</entry>
+<entry key="tex.error.register_expected">Register expected</entry>
+<entry key="tex.error.register_expected_but_found">Register expected (found ''{0}'')</entry>
+<entry key="tex.error.numeric register_expected">Numeric register expected</entry>
+<entry key="tex.error.register_not_numeric">Register ''{0}'' not numeric</entry>
+<entry key="tex.error.register_not_token">Register ''{0}'' not a token register</entry>
+<entry key="tex.error.generic">{0}</entry>
+<entry key="tex.error.file.not.found">File ''{0}'' not found.</entry>
+<entry key="tex.error.unexpandable">Can''t expand ''{0}''</entry>
+
+
<entry key="latex.error.no_alignment">No alignment specifiers found</entry>
<entry key="latex.error.undefined_counter">No counter ''{0}'' defined</entry>
<entry key="latex.error.multi_begin_doc">Only one \begin'{document}' permitted</entry>
@@ -500,11 +520,16 @@
<entry key="latex.error.defined">''{0}'' already defined</entry>
<entry key="latex.error.illegal_array_arg_char">Illegal character ''{0}'' in array arg</entry>
<entry key="latex.error.lonely_item">Lonely \item</entry>
+<entry key="latex.package.error">Package {0} Error: {1}</entry>
+<entry key="latex.class.error">Class {0} Error: {1}</entry>
+<entry key="latex.illegal.argtype">Illegal argument type {0}</entry>
+<entry key="latex.package.not.loaded">Package ''{0}'' has not been loaded</entry>
<entry key="bibtex.error.missing_value">Missing value</entry>
<entry key="bibtex.error.expecting">Expecting ''{0}''</entry>
<entry key="bibtex.error.expecting_or">Expecting ''{0}'' or ''{1}''</entry>
-<entry key="bibtex.error.missing_id">Missing identifier</entry>
+<entry key="bibtex.error.missing.id">Missing identifier</entry>
+<entry key="bibtex.error.invalid.id">Invalid identifier element {0}</entry>
<entry key="bibtex.error.missing_field_part">Missing field value</entry>
<entry key="bibtex.error.missing_field_name">Missing field identifier</entry>
<entry key="bibtex.error.unbalanced_braces">Unbalanced braces</entry>
@@ -542,5 +567,13 @@
<entry key="ifthen.invalid.condition">Invalid condition ''{0}''.</entry>
+<!-- inputenc messages -->
+<entry key="inputenc.unknown.encoding">Unknown encoding ''{0}''.</entry>
+
+<!-- color messages -->
+<entry key="color.unsupported">Unsupported ''{0}'' model colour {1}</entry>
+<entry key="color.invalid.specs">Invalid specification ''{0}'' for colour model {1}</entry>
+<entry key="color.unknown">Unknown named colour ''{0}''</entry>
+
</properties>
Modified: trunk/Master/texmf-dist/scripts/bib2gls/texparserlib.jar
===================================================================
(Binary files differ)
Added: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex (rev 0)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex 2018-05-09 22:21:20 UTC (rev 47658)
@@ -0,0 +1,5589 @@
+% arara: xelatex
+% arara: bib2gls: {group: on}
+% 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")
+\documentclass[titlepage=false,fontsize=12pt,captions=tableheading]{scrreprt}
+
+\usepackage[no-math]{fontspec}
+\setmainfont{Linux Libertine O}
+
+\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase]
+\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}}
+
+\usepackage[x11names]{xcolor}
+\usepackage{upquote}
+\usepackage{hologo}
+\usepackage{pifont}
+\usepackage{graphicx}
+\usepackage{datetime2}
+\usepackage{siunitx}
+\usepackage{mhchem}
+
+\usepackage{xr-hyper}
+\usepackage[hidelinks]{hyperref}
+\usepackage[record,
+ entrycounter,subentrycounter,%need to define counters for some examples
+ nostyles,stylemods={bookindex},style=index]{glossaries-extra}
+
+\setupglossaries{entrycounter=false,subentrycounter=false}
+
+\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{\dhyphen}{%
+ \texorpdfstring
+ {\discretionary{}{}{}\texttt{-}}%
+ {-}%
+}
+
+\renewrobustcmd{\-}{%
+ \discretionary
+ {{\rmfamily\char\ifnum\hyphenchar\font<0
+ \defaulthyphenchar\else\hyphenchar\font\fi
+ }}%
+ {}{}%
+}
+
+\setabbreviationstyle[common]{short-nolong}
+\setabbreviationstyle[markwordsexample]{long-hyphen-short-hyphen}
+\glssetcategoryattribute{markwordsexample}{markwords}{true}
+\GlsXtrEnableInitialTagging{taggingexample}{\itag}
+\glssetcategoryattribute{discardperiodexample}{discardperiod}{true}
+\glssetcategoryattribute{initialism}{insertdots}{true}
+\glssetcategoryattribute{initialism}{discardperiod}{true}
+\glssetcategoryattribute{initialism}{retainfirstuseperiod}{true}
+\setabbreviationstyle[initialism]{short-long}
+\setabbreviationstyle[abbrvtrans]{long-short-user}
+\setabbreviationstyle[longshortem]{long-short-em}
+\setabbreviationstyle[shortsc]{short-sc-nolong}
+
+\newcommand{\bibglspassim}{}
+\newcommand{\bibglsseealsosep}{\par\hangindent .75em\parindent .75em\relax}
+
+\newcommand*{\csfmt}[1]{%
+ \texorpdfstring
+ {\csfmtfont{\char`\\ #1}}%
+ {\string\\#1}%
+}
+
+\GlsXtrLoadResources[
+ src={bib2gls},
+ max-loc-diff=3,
+ entry-type-aliases={dualindexentry=index},
+ field-aliases={note=user2},
+ symbol-sort-fallback={name},
+ break-at={none},
+ sort-replace={{,? +}{|},{\glshex2423}{ },
+ {\string\\([a-zA-Z])}{\glscapturedgroup1},
+ {([a-zA-Z])\string\.}{\glscapturedgroup1}}
+]
+
+\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z}
+
+\IfFileExists{../java/Bib2Gls.java}
+{
+ \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java}
+}
+{
+ \DTMsavenow{moddate}
+}
+
+\newcommand{\bibgls}{\appfmt{bib2gls}}
+
+\newcommand*{\BibTeX}{\hologo{BibTeX}}
+\newcommand*{\eTeX}{\hologo{eTeX}}
+\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}}
+\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}}
+\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}}
+
+\newcommand*{\ctanfile}[2]{%
+ \href{http://mirrors.ctan.org/macros/latex/contrib/#1/#2}{\nolinkurl{#2}}%
+}
+
+\newcommand{\hex}[1]{0x#1}
+
+\newcommand{\qt}[1]{``#1''}
+
+\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}}
+
+\newcommand{\incorrect}{\marginpar{\textcolor{red}{\ding{55}}}}
+\newcommand{\correct}{\marginpar{\textcolor{green}{\ding{52}}}}
+
+\newenvironment{result}%
+{%
+ \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{hyper=false,local}}%
+ \glsresetentrycounter
+ \begin{quotation}%
+ \marginpar
+ [\raisebox{-2.5ex}{\ding{43}}]%
+ {\raisebox{-2.5ex}{\reflectbox{\ding{43}}}}%
+ \ignorespaces
+}
+{\end{quotation}\ignorespacesafterend}
+
+\newcommand{\dequals}{%
+ \texorpdfstring
+ {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}%
+ {=}%
+}
+
+\newcommand{\dcomma}{%
+ \texorpdfstring
+ {\texttt{,}\discretionary{}{}{}}%
+ {,}%
+}
+
+\newcommand{\dcolon}{%
+ \texorpdfstring
+ {\texttt{:}\discretionary{}{}{}}%
+ {:}%
+}
+
+\pdfstringdefDisableCommands{%
+ \def\dhyphen{-}%
+ \def\dcolon{:}%
+ \def\dcomma{,}%
+ \def\dequals{,}%
+ \let\-\empty
+}
+
+\newcommand*{\csfmtfont}[1]{\texttt{#1}}
+
+\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{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{\color{style}#1}}{#1}}
+\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{\color{attribute}#1}}{#1}}
+\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
+\newcommand*{\metafilefmt}[3]{%
+ \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
+}
+
+\newcommand*{\extfmt}[1]{\filefmt{.#1}}%
+
+\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}}
+
+\newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}}
+
+\newcommand*{\meta}[1]{%
+ \texorpdfstring{\ifmmode\text{\texmeta{#1}}\else\texmeta{#1}\fi}{#1}%
+}
+
+\newcommand*{\oarg}[1]{\discretionary{}{}{}[#1]}
+\newcommand*{\oargm}[1]{\oarg{\meta{#1}}}
+
+\newcommand*{\marg}[1]{\texorpdfstring
+ {\discretionary{}{}{}\char`\{#1\char`\} }%
+ {\{#1\}}%
+}
+
+\newcommand*{\margm}[1]{\marg{\meta{#1}}}
+
+\newcommand{\switcharg}{}
+\newcommand{\switchalt}{}
+
+\makeatletter
+\newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}}
+\newenvironment{codeenv}
+ {%
+ \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
+ \def\cmd{\char`\\}%
+ \def\comment##1{\textcolor{comment}{\%\ ##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}}%
+ \begin{flushleft}\textcolor{lightgray}{\hrulefill}\par\nopagebreak
+ \medskip\nopagebreak
+ \ttfamily\obeylines\frenchspacing\@vobeyspaces}
+ {\nopagebreak\textcolor{lightgray}{\hrulefill}%
+ \end{flushleft}\ignorespacesafterend}
+\makeatother
+
+\newcommand{\primary}{\emph}
+\newcommand{\primaryloc}[1]{\underline{\hyperbf{#1}}}
+
+\newcommand{\pidx}[1][]{\gls[textformat=primary,format=primaryloc,#1]}
+\newcommand{\pidxpl}[1][]{\glspl[textformat=primary,format=primaryloc,#1]}
+\newcommand{\pIdx}[1][]{\Gls[textformat=primary,format=primaryloc,#1]}
+\newcommand{\pIdxpl}[1][]{\Glspl[textformat=primary,format=primaryloc,#1]}
+
+\newcommand{\idx}{\gls}
+\newcommand{\idxpl}{\glspl}
+\newcommand{\Idx}{\Gls}
+\newcommand{\Idxpl}{\Glspl}
+
+\newcommand{\ext}{\gls}
+
+\newcommand*{\iext}[1]{%
+ \glsxtrtitleorpdforheading{\idx{#1}}{.#1}{\extfmt{#1}}%
+}
+
+\newcommand{\sty}{\gls}
+
+\newcommand*{\isty}[1]{%
+ \texorpdfstring{\idx{#1}}{#1}%
+}
+
+\newcommand*{\env}[1]{%
+ \texorpdfstring{\idx{env.#1}}{#1}%
+}
+
+\newcommand*{\abbrstyle}[2][]{%
+ \texorpdfstring{\idx[#1]{#2}}{#2}%
+}
+
+\newcommand*{\glostyle}[1]{%
+ \texorpdfstring{\idx{glostyle.#1}}{#1}%
+}
+
+\newcommand*{\catattr}[1]{%
+ \texorpdfstring{\idx{#1}}{#1}%
+}
+
+\newcommand*{\counter}[1]{%
+ \texorpdfstring{\idx{ctr.#1}}{#1}%
+}
+
+\newcommand*{\styopt}[2][]{%
+ \texorpdfstring%
+ {%
+ \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ }%
+ {#2\ifblank{#1}{}{=#1}}%
+}
+
+\newcommand*{\keyvallist}{%
+ \texorpdfstring
+ {key\dequals value list}%
+ {key=value list}%
+}
+
+\newcommand{\nosecformatdef}[1]{%
+ \begin{definition}
+ \gls[format=primaryloc]{#1}%
+ \glsentryuseri{#1}%
+ \end{definition}\ignorespaces
+}
+
+\newcommand*{\cs}{\gls}
+
+\newcommand*{\ics}{\cs}
+
+\newcommand*{\icswithargs}[2][]{\cs{#2}\glsentryuseri{#2}}
+
+\newcommand*{\postdeschook}[2][]{%
+ \glslink[#1]{idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#2}}}
+
+\newcommand*{\postlinkhook}[2][]{%
+ \glslink[#1]{idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#2}}}
+
+
+\glsxtrnewgls{file.}{\exfile}
+
+\newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}%
+\newcommand*{\glsopt}[2][]{\gencsopt{#1}{gls}{#2}}%
+\newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{glsadd}{#2}}%
+\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{printgloss}{#2}}%
+
+\newcommand*{\gencsopt}[3]{%
+ \texorpdfstring%
+ {%
+ \gls{#2.#3}%
+ \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ }%
+ {#3\ifblank{#1}{}{=#1}}%
+}
+
+\newcommand*{\field}[1]{%
+ \texorpdfstring
+ {\gls{field.#1}}%
+ {#1}%
+}
+
+\newcommand*{\atentry}[2][]{%
+ \texorpdfstring
+ {\gls[#1]{entry.#2}}%
+ {#2}%
+}
+
+\newrobustcmd{\longswitch}{\string-{}\string-}
+
+\newcommand*{\longargfmt}[1]{%
+ \texorpdfstring{\texttt{\longswitch #1}}%
+ {\string-\string-#1}%
+}
+
+\newcommand*{\shortargfmt}[1]{%
+ \texorpdfstring{\texttt{\string-#1}}%
+ {\string-#1}%
+}
+
+\newcommand*{\longarg}[1]{%
+ \texorpdfstring
+ {\gls{switch.#1}}%
+ {\string-\string-#1}%
+}
+
+\definecolor{defbackground}{rgb}{1,1,0.75}
+
+\newsavebox\borderedboxcontents
+\newlength\borderedboxwidth
+
+\newenvironment{definition}%
+{%
+ \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}%
+ \begin{lrbox}{\borderedboxcontents}%
+ \setlength\borderedboxwidth\linewidth
+ \addtolength\borderedboxwidth{-2\fboxrule}%
+ \addtolength\borderedboxwidth{-2\fboxsep}%
+ \begin{minipage}{\borderedboxwidth}
+ \flushleft\ttfamily\ignorespaces
+}%
+{%
+ \end{minipage}%
+ \end{lrbox}\par\medskip\noindent
+ \fcolorbox{black}{defbackground}{\usebox\borderedboxcontents}%
+ \medskip\par\noindent
+ \ignorespacesafterend
+}
+
+\newenvironment{important}{%
+ \setlength{\fboxrule}{4pt}%
+ \setlength\borderedboxwidth{\linewidth}%
+ \addtolength\borderedboxwidth{-2\fboxsep}%
+ \addtolength\borderedboxwidth{-2\fboxrule}%
+ \begin{lrbox}{\borderedboxcontents}%
+ \begin{minipage}{\borderedboxwidth}%
+ \raggedright
+ \setlength\parindent{1em}%
+ \noindent\ignorespaces
+}%
+{%
+ \end{minipage}%
+ \end{lrbox}%
+ \par\vskip10pt\noindent
+ \fcolorbox{red}{white}{\usebox{\borderedboxcontents}}\par\vskip10pt
+ \noindent\ignorespacesafterend
+}
+
+\newcommand*{\sectionref}[1]{section~\ref{#1}}
+\newcommand*{\Sectionref}[1]{Section~\ref{#1}}
+
+\newcommand{\doglossaryentry}[1]{%
+ \glsxtrglossentry{#1} & \glsentrydesc{#1}\glspostdescription\\%
+}
+\newcounter{localglossary}
+\newenvironment{localglossary}
+{%
+ \stepcounter{localglossary}%
+ \renewcommand{\glolinkprefix}{\thelocalglossary.}%
+ \GlsXtrStartUnsetBuffering*
+}
+{%
+ \par
+ \begin{tabular}{ll}
+ \GlsXtrForUnsetBufferedList\doglossaryentry
+ \end{tabular}
+ \GlsXtrStopUnsetBuffering
+ \par
+}
+\pagestyle{headings}
+
+\newcommand{\glossarytitle}{Index}
+\externaldocument{bib2gls}
+
+\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}}
+\title{\styfmt{glossaries-extra} and \bibgls: An Introductory Guide}
+\author{Nicola Talbot\addr{dickimaw-books.com}}
+\date{\DTMusedate{moddate}}
+
+\makeatletter
+\begingroup
+ \renewcommand{\addr}[1]{}
+ \let\texorpdfstring\@secondoftwo
+ \DTMsetstyle{pdf}
+ \protected at edef\x{\endgroup
+ \noexpand\hypersetup{%
+ pdfinfo={
+ Title={\@title},
+ Author={\@author},
+ CreationDate={\DTMuse{creation}},
+ ModDate={\DTMuse{moddate}},
+ }%
+ }%
+ }\x
+
+\makeatother
+
+\begin{document}
+\maketitle
+\pagenumbering{alph}
+\thispagestyle{empty}
+
+\begin{abstract}
+This document is an introductory guide to \bibgls\ and the
+\sty{glossaries-extra} package to help you get started. For
+further information, including more complex commands and settings,
+see the main \bibgls\ user manual (\filefmt{bib2gls.pdf},
+in the same directory as this document),
+the \isty{glossaries-extra} user manual,
+(distributed with the \sty{glossaries-extra}
+package~\cite{glossaries-extra})
+and the \isty{glossaries} user manual
+(distributed with the \sty{glossaries} package~\cite{glossaries}).
+
+The \sty{glossaries} package is the \emph{base} package. The
+\sty{glossaries-extra} package internally loads the \sty{glossaries} package
+and extends it, providing extra options or modifying the base
+commands to increase flexibility. If you want to use \bibgls, you
+must load \sty{glossaries-extra}, which provides the interface
+required by \bibgls.
+This document doesn't cover the other indexing methods described in
+the base package. If you get an undefined control sequence or
+unknown option error when trying out any of the examples here, check
+that you are using the latest versions of \sty{glossaries},
+\sty{glossaries-extra} and \bibgls.
+\end{abstract}
+
+\clearpage
+\pagenumbering{roman}
+\tableofcontents
+
+\clearpage
+\pagenumbering{arabic}
+
+\chapter{Introduction}
+\label{sec:beginintro}
+
+The \sty{glossaries} package provides a way of defining terms,
+notation or abbreviations that can then be used in the document.
+This ensures consistent naming and formatting. (With the help of the
+\sty{hyperref} package, it's also possible to create hyperlinks from
+the reference to a place in the document that provides a definition
+of the term, but more about that later.) Each entry (term,
+notation or abbreviation) is defined using:
+\nosecformatdef{newglossaryentry}
+Here's a simple example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{\comment{ information about this term:}
+ \field{name}=\marg{duck},\comment{ display name}
+ \field{description}=\marg{a waterbird with webbed feet}\comment{description}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}\comment{ label}
+\marg{\comment{information about this term:}
+ \field{name}=\marg{goose},\comment{display name}
+ \field{plural}=\marg{geese},\comment{plural form}
+ \field{description}=\marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\strut
+\cmd{begin}\marg{document}
+The pond contained a \gls{gls}\marg{duck} (\gls{glsentrydesc}\marg{duck}) and
+a \gls{gls}\marg{goose} (\gls{glsentrydesc}\marg{goose}). \gls{Glspl}\marg{duck} and
+\gls{glspl}\marg{goose} are fowl.
+\cmd{end}\marg{document}
+\end{codeenv}
+The resulting text is:
+\begin{result}
+The pond contained a \gls{ex1.duck} (\glsentrydesc{ex1.duck}) and
+a \gls{ex1.goose} (\glsentrydesc{ex1.goose}). \Glspl{ex1.duck} and
+\glspl{ex1.goose} are fowl.
+\end{result}
+For convenience, the text produced by commands such as \cs{gls} is called the
+\pidx{link-text} (even if there are no hyperlinks).
+
+The first argument of \gls{newglossaryentry} is a label that
+uniquely identifies the term (see \sectionref{sec:labels}). The
+second argument is a comma-separated list of
+\meta{setting}\dequals\meta{value} assignments. Each \meta{setting}
+is referred to as a \qt{key} in the \isty{glossaries} manual or as a
+\qt{field} in the \bibgls\ manual. A list of the available base keys
+can be found in the \isty{glossaries} user manual. The
+\isty{glossaries-extra} package provides some additional keys that
+are described in the \sty{glossaries-extra} manual. The \bibgls\
+user manual summarises all keys (fields) in \sectionref{sec:fields}.
+
+\begin{important}
+If the field value contains commas or equal signs the value must be grouped
+to hide those characters from the \meta{key}\dequals\meta{value} parser.
+\end{important}
+
+The two main keys are \field{name} and \field{description}. The
+\field{name} identifies how the term should be displayed in the
+glossary (see \sectionref{sec:displaygloss}). It also provides the
+default singular term, if not explicitly given. The default plural
+is obtained by appending \qt{s} to the singular form. If this isn't
+correct (as with \qt{geese}), then the plural form can be specified
+with the \field{plural} key.
+
+The description (set with the \field{description} key) is usually
+only displayed in the glossary, but you can display it in the text
+using:
+\nosecformatdef{glsentrydesc}
+as in the above example. This simply expands to the value of the
+\field{description} field (or does nothing if there's no entry
+associated with the given label).
+
+The main command used to reference a term is:
+\nosecformatdef{gls}
+In the above example, \gls{gls} just displays the singular form, but you
+can provide alternative text to use the first time a term is
+referenced (see \sectionref{sec:firstuse}). The plural form is obtained with
+the \pidx{variant} command:
+\nosecformatdef{glspl}
+There are other \idxpl{variant} of \gls{gls} that perform
+\glslink{case-change}{case-changing}.
+If you want to start a sentence with an entry then you can use:
+\nosecformatdef{Gls}
+for the singular form and
+\nosecformatdef{Glspl}
+for the plural form. For all capitals, use:
+\nosecformatdef{GLS}
+for the singular form and
+\nosecformatdef{GLSpl}
+for the plural form. Any mention of \gls{gls} and its
+\idxpl{variant} in this guide or in the user manuals means that the
+comments applied to \gls{gls} also apply to the plural and
+case-changing versions.
+
+The \meta{insert} optional argument is provided to insert additional material.
+For example:
+\begin{codeenv}
+The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}['s] hat.
+\end{codeenv}
+which produces (assuming the above definitions):
+\begin{result}
+The \gls{ex1.goose} liked the \gls{ex1.duck}['s] hat.
+\end{result}
+In some cases, there may not be a noticeable difference between the
+above and the following:
+\begin{codeenv}
+The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}'s hat.
+\end{codeenv}
+It depends on other settings, such as whether or not hyperlinks have
+been enabled. (The inserted material is commonly moved inside the
+hyperlink.) Take care if you need a literal open square bracket
+following \code{\cs{gls}\margm{label}} as you need to prevent it from being
+interpreted as the optional \meta{insert} argument. For example:
+\begin{codeenv}
+The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\marg{['s]} hat.
+\end{codeenv}
+which now produces:
+\begin{result}
+The \gls{ex1.goose} liked the \gls{ex1.duck}{['s]} hat.
+\end{result}
+An alternative in this case could be to define:
+\begin{codeenv}
+\cmd{newcommand}*\marg{\cmd{missing}}[1]\marg{[\gls*{param}1]}
+\end{codeenv}
+and then use:
+\begin{codeenv}
+The \gls{gls}\marg{goose} liked the \gls{gls}\marg{duck}\cmd{missing}\marg{'s} hat.
+\end{codeenv}
+This conveniently hides the open square bracket from \cs{gls}.
+
+\begin{important}
+Commands like \gls{gls} are \idx{robust}. Commands like
+\gls{glsentrydesc} are \idx{expandable}. (See \sectionref{sec:robust}.)
+If you want the entry to appear in a PDF bookmark, you need to use an
+expandable command to reference it.
+\end{important}
+
+There are some helper commands that internally use
+\gls{newglossaryentry}, such as \cs{newabbreviation} (described in
+\sectionref{sec:abbreviations}) and \cs{glsxtrnewsymbol} (described
+in \sectionref{sec:symbols}). If the description contains explicit paragraph
+breaks then:
+\nosecformatdef{longnewglossaryentry}
+is required instead.
+
+\section{Labels}
+\label{sec:labels}
+
+The label used to identify the entry can't contain any special characters, such
+as \gls{commentchar} (percent), \gls{ampchar} (ampersand), \gls{param} (hash),
+\gls{mshiftchar} (dollar), or \gls{nbspchar} (tilde). Be careful of packages
+that make other characters active (such as \isty{babel} with its shortcuts). If
+you are using \isty{inputenc}, this also includes extended Latin characters and
+characters from other scripts. If you want to include UTF-8 characters in the
+label then you must use a \TeX\ engine with native Unicode support (that is,
+\XeLaTeX\ or \LuaLaTeX).
+
+For example, with no UTF-8 support (not even \sty{inputenc}):
+\begin{codeenv}
+\gls{newglossaryentry}\marg{elite}\comment{label (no UTF-8 support)}
+\marg{
+ \field{name} = \marg{\marg{\gls{acute}e}lite},
+ \field{description} = \marg{group of people regarded as
+ the best of a particular society or organisation}
+}
+\end{codeenv}
+or with \sty{inputenc}:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{elite}\comment{label (UTF-8 not natively supported)}
+\marg{
+ \field{name} = \marg{élite},
+ \field{description} = \marg{group of people regarded as
+ the best of a particular society or organisation}
+}
+\end{codeenv}
+Whereas with \XeLaTeX\ or \LuaLaTeX\ you can do:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{élite}\comment{label (UTF-8 natively supported)}
+\marg{
+ \field{name} = \marg{élite},
+ \field{description} = \marg{group of people regarded as
+ the best of a particular society or organisation}
+}
+\end{codeenv}
+
+You may have noticed the grouping of the initial (accented) letter
+in the \gls{ASCII} example (\code{\marg{\gls{acute}e}lite}). This is
+necessary to ensure that the first-letter case-changing commands,
+such as \ics{Gls}, work. It also used to be required around the
+\qtt{é} with \sty{inputenc}, but if you have up-to-date versions of
+\sty{glossaries} and \sty{datatool} then it should no longer be
+necessary. No special treatment is needed with \XeLaTeX\ or
+\LuaLaTeX\ where \qtt{é} is a single token.
+
+If you can't use extended characters in the label (because you're
+not using \XeLaTeX\ or \LuaLaTeX), then simply stripping the accents
+to create an \gls{ASCII} alternative may be sufficient, but take
+care if this may cause a conflict. For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{resume}\comment{label}
+\marg{
+ \field{name} = \marg{resume},
+ \field{description} = \marg{continue after an interruption}
+}
+\strut
+\gls{newglossaryentry}\marg{resumee}\comment{label}
+\marg{
+ \field{name} = \marg{r\gls{acute}esum\gls{acute}e},
+ \field{description} = \marg{summary of something or curriculum vitae}
+}
+\end{codeenv}
+For languages that use a non-Latin script, if you can't or don't
+want to use \XeLaTeX\ or \LuaLaTeX, then you need to decide the most
+appropriate \gls{ASCII} naming scheme.
+For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{goose}\comment{using translation for label}
+\marg{
+ \field{name} = \marg{\textcyrillicmono{гусь}},
+ \field{plural} = \marg{\textcyrillicmono{гуси}},
+ \field{description} = \marg{\textnormal{\ldots}}
+}
+\end{codeenv}
+or
+\begin{codeenv}
+\gls{newglossaryentry}\marg{hus}\comment{using closest ASCII match for label}
+\marg{
+ \field{name} = \marg{\textcyrillicmono{гусь}},
+ \field{plural} = \marg{\textcyrillicmono{гуси}},
+ \field{description} = \marg{\textnormal{\ldots}}
+}
+\end{codeenv}
+
+In addition to labels identifying entries, there are also labels
+that identify other things, such as a glossary, category or letter
+group. The same restrictions apply to those labels.
+
+\section{First Use}
+\label{sec:firstuse}
+
+Each entry has a \pidx{firstuseflag} (boolean variable) that
+determines whether or not the entry has been referenced in the
+document. Commands like \gls{gls} and \gls{glspl} change the flag
+to indicate that the entry has been used. Commands like
+\gls{glsentrydesc} don't. Here's a modification of the earlier
+example document that provides different versions depending on
+whether or not the entry has already been referenced:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{\comment{information about this term:}
+ \field{name} = \marg{Duck (noun)},\comment{display name}
+ \field{first} = \marg{duck (quack, quack)},\comment{first use singular}
+ \field{firstplural} = \marg{ducks (quack, quack)},\comment{first use plural}
+ \field{text} = \marg{duck},\comment{subsequent use singular}
+ \field{description} = \marg{a waterbird with webbed feet}\comment{description}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}\comment{label}
+\marg{\comment{information about this term:}
+ \field{name} = \marg{Goose (noun, pl.\ geese)},\comment{display name}
+ \field{first} = \marg{goose (honk, honk)},\comment{first use singular}
+ \field{firstplural} = \marg{geese (honk, honk)},\comment{first use plural}
+ \field{text} = \marg{goose},\comment{subsequent use singular}
+ \field{plural} = \marg{geese},\comment{subsequent use plural}
+ \field{description}=\marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\strut
+\cmd{begin}\marg{document}
+The pond contained a \gls{gls}\marg{duck}\cmd{footnote}\marg{\gls{glsentryname}\marg{duck}:
+\gls{glsentrydesc}\marg{duck}} and two
+\gls{glspl}\marg{goose}\cmd{footnote}\marg{\gls{glsentryname}\marg{goose}:
+\gls{glsentrydesc}\marg{goose}}. \gls{Glspl}\marg{duck} and \gls{glspl}\marg{goose} are fowl.
+\cmd{end}\marg{document}
+\end{codeenv}
+This now produces:
+\begin{result}
+The pond contained a \gls{ex2.duck}\footnote{\glsentryname{ex2.duck}:
+\glsentrydesc{ex2.duck}} and two
+\glspl{ex2.goose}\footnote{\glsentryname{ex2.goose}:
+\glsentrydesc{ex2.goose}}. \Glspl{ex2.duck} and \glspl{ex2.goose} are fowl.
+\end{result}
+This uses:
+\nosecformatdef{glsentryname}
+which works in a similar way to \gls{glsentrydesc}. In this case,
+\gls{glsentryname} simply expands to the value of the \field{name}
+key. There's also a case-changing version:
+\nosecformatdef{Glsentryname}
+which changes the initial character to \idx{uppercase},
+but (unlike \cs{glsentryname}) this command isn't expandable. If,
+for example, I had instead set the duck's \field{name} key using:
+\begin{codeenv}
+\field{name} = \marg{duck (noun)}
+\end{codeenv}
+then I would need to use \code{\gls{Glsentryname}\marg{duck}}
+instead.
+
+So on \pidx{firstuse}, \cs{gls} uses the value of the \field{first} key
+and \cs{glspl} uses the value of the \field{firstplural} key. On
+\pidx{subsequentuse}, \cs{gls} uses the value of the \field{text} key and
+\cs{glspl} uses the value of the \field{plural} key. \pIdx{regular}
+abbreviations also follow this usage. \pIdx{non-regular}
+abbreviations follow a different behaviour for \gls{gls} (and its
+\idxpl{variant}) that's determined by the abbreviation style.
+
+If the first use for a particular group of terms always has the
+same pattern (such as following the term with a brief description or
+alternative representation), then it's simpler to use one of the
+automated methods provided, such as the abbreviation mechanism
+(\sectionref{sec:abbreviations}) or changing the formatting
+(\sectionref{sec:glsformats}).
+
+\section{Categories}
+\label{sec:categories}
+
+The \isty{glossaries-extra} extension package provides the
+\field{category} key, which isn't available with just the base
+\sty{glossaries} package. The value of this key must be a
+label as it's used to construct command names. You can choose
+whatever label you like (as long as it conforms to the valid
+labelling scheme, described in \sectionref{sec:labels}). If you
+don't specify a category, then \gls{newglossaryentry} and
+\gls{longnewglossaryentry} assume \code{general}. The helper
+commands, such as \gls{newabbreviation}, have different defaults.
+
+For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{category} = \marg{mineral}
+}
+\end{codeenv}
+The value of the \field{category} field for a given entry can be obtained
+with:
+\nosecformatdef{glscategory}
+where \meta{label} identifies the entry. This command is expandable
+and does nothing if the entry hasn't been defined. You can test the
+value of the \field{category} field using:
+\nosecformatdef{glsifcategory}
+This checks if the \field{category} field for the entry given by
+\meta{label} is set to \meta{category}, but doesn't perform any
+expansion. It generates an error if the entry doesn't exist (or
+warning with \styopt[warn]{undefaction}).
+
+The category allows you to apply certain types of formatting, such
+as the \idx{postlinkhook} (\sectionref{sec:postlinkhooks}).
+For abbreviations, the category also governs the abbreviation style (see
+\sectionref{sec:abbreviations}) and can be used for filtering.
+Categories may be assigned \pidxpl{attribute} that can also be used
+to modify formatting or styles.
+
+Unlike the \idx{postlinkhook}, which
+needs to be defined before an entry is \emph{used} (with commands like
+\gls{gls}), some \idxpl{attribute} need to be set before the entry
+is \emph{defined}, so it's best to set them up as soon as possible in the
+preamble (after loading \sty{glossaries-extra}).
+
+\section{Adding Extra Information}
+\label{sec:userkeys}
+
+In addition to the \field{name} and \field{description} keys,
+there's also a \field{symbol} key which allows you to store an
+associated symbol. The value can be obtained with:
+\nosecformatdef{glssymbol}
+(which is robust and recognises the \idx{postlinkhook}) or with:
+\nosecformatdef{glsentrysymbol}
+(which behaves like \gls{glsentrydesc} and \gls{glsentryname}).
+Neither of the above commands affect the \idx{firstuseflag}.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[hidelinks]\marg{hyperref}
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{pi}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{Archimedes' constant},
+ \field{symbol} = \marg{\gls[noindex=false]{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{ratio of a circle's circumference to its
+diameter}
+}
+\strut
+\gls{newglossaryentry}\marg{thetai}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{theta parameter},
+ \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{theta}\gls{sbchar}i}},
+ \field{description} = \marg{one of the model parameters}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{pi} (\gls{glssymbol}\marg{pi}). Compare \gls{mshiftchar}\gls{glssymbol}\marg{thetai}\gls[noindex=false]{spchar}2\gls{mshiftchar}
+with \gls{mshiftchar}\gls{glssymbol}\marg{thetai}[\gls{spchar}2]\gls{mshiftchar}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\gls{ex.pi} (\glssymbol{ex.pi}). Compare $\glssymbol{ex.thetai}^2$
+with $\glssymbol{ex.thetai}[^2]$.
+\end{result}
+Note that in this case there is now a difference between using the
+final optional \meta{insert} argument and simply appending the extra
+material. This is a result of the hyperlink that causes an
+interruption between the subscript \code{\gls{sbchar}i} and the following
+superscript \code{\gls{spchar}2}. (In this case, there's no target for the
+hyperlinks. That's covered in \sectionref{sec:displaygloss}.)
+
+If you have additional information, such as a translation,
+associated image or citation, then you can supply this with the six
+user keys:
+\field{user1}\glsaddeach{field.user2,field.user3,field.user4,field.user5},
+\ldots, \field{user6}. The value of the
+first field can be obtained with:
+\nosecformatdef{glsuseri}
+(which behaves like \gls{glssymbol}) or with:
+\nosecformatdef{glsentryuseri}
+(which behaves like \gls{glsentrysymbol}).
+\glsaddeach{glsuserii,glsuseriii,glsuseriv,glsuserv,%
+glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv}%
+The other fields are similarly obtained using \idx{lowercase} Roman
+numerals, so the sixth field can be obtained with:
+\nosecformatdef{glsuservi}
+(which behaves like \gls{glssymbol}) or with:
+\nosecformatdef{glsentryuservi}
+(which behaves like \gls{glsentrysymbol}).
+For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{polly.parrot}\comment{label}
+\marg{\comment{}
+ \field{name} = \marg{Polly Parrot},
+ \field{description} = \marg{Senior assistant at the International Society
+of Duck and Geese},
+ \field{user1} = \marg{British},\comment{nationality}
+ \field{user2} = \marg{1970-12-31},\comment{date of birth}
+ \field{user3} = \marg{female},\comment{gender}
+ \field{user4} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address}
+ \field{user5} = \marg{polly.parrot at example.com}\comment{email}
+}
+\end{codeenv}
+
+Alternatively you can define your own custom keys. If you don't need
+commands equivalent to \gls{glssymbol}, then you can use:
+\nosecformatdef{glsaddstoragekey}
+where \meta{key} is the name of the new key, \meta{default value} is
+the default value if the key isn't explicitly set and \meta{no link
+cs} is the name of the command to access the field value (equivalent
+to \gls{glsentrysymbol}). If you want commands equivalent to
+\gls{glssymbol} that have the \meta{options} and \meta{insert}
+optional arguments and obey the \idx{postlinkhook}, then use
+\nosecformatdef{glsaddkey}
+The first three arguments are as for \gls{glsaddstoragekey}.
+The next argument \meta{no link ucfirst cs} is like \meta{no link
+cs} but converts the first letter to \idx{uppercase} (analogous to
+\gls{Glsentryname}). The final three commands behave like
+\gls{glssymbol}, but \meta{link ucfirst cs} converts the first
+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 key definitions must come before the first \idx{resourceset}
+if you use \bibgls). For example:
+\begin{codeenv}
+\gls{glsaddstoragekey}\marg{\fieldfmt{nationality}}\marg{}\marg{\cmd{Nationality}}
+\gls{glsaddstoragekey}\marg{\fieldfmt{dateofbirth}}\marg{}\marg{\cmd{DateOfBirth}}
+\gls{glsaddstoragekey}\marg{\fieldfmt{gender}}\marg{}\marg{\cmd{Gender}}
+\gls{glsaddstoragekey}\marg{\fieldfmt{address}}\marg{}\marg{\cmd{Address}}
+\gls{glsaddstoragekey}\marg{\fieldfmt{email}}\marg{}\marg{\cmd{Email}}
+\gls{newglossaryentry}\marg{polly.parrot}\comment{label}
+\marg{\comment{}
+ \field{name} = \marg{Polly Parrot},
+ \field{description} = \marg{Senior assistant at the International Society
+of Duck and Geese},
+ \fieldfmt{nationality} = \marg{British},\comment{nationality}
+ \fieldfmt{dateofbirth} = \marg{1970-12-31},\comment{date of birth}
+ \fieldfmt{gender} = \marg{female},\comment{gender}
+ \fieldfmt{address} = \marg{43 The Lane, Some Town, Noshire AB1 2XY},\comment{address}
+ \fieldfmt{email} = \marg{polly.parrot at example.com}\comment{email}
+}
+\end{codeenv}
+
+In addition to the commands like \gls{glssymbol} and
+\gls{glsentrysymbol}, there are other ways of accessing the field
+value or checking if the field has been set. In the commands listed
+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.
+
+The \sty{glossaries-extra} package provides a generic way of
+accessing a field, analogous to commands like \gls{glsentryname}:
+\nosecformatdef{glsxtrusefield}
+This expands to the field value if defined or does nothing if the
+entry or field isn't defined.
+
+The base \sty{glossaries} package provides:
+\nosecformatdef{ifglshassymbol}
+which tests if the \field{symbol} field has been assigned. There are similar
+commands for other common fields. For a more general purpose test, you
+can use:
+\nosecformatdef{ifglshasfield}
+which checks if the given entry (identified by \meta{entry label},
+which must be defined) has the field identified by \meta{field label}
+set to a non-empty value. Within \meta{true}, you can access the
+field value with:
+\nosecformatdef{glscurrentfieldvalue}
+The \sty{glossaries-extra} package provides a similar command:
+\nosecformatdef{glsxtrifhasfield}
+which doesn't test if the entry exists. The unstarred form adds
+implicit grouping around \meta{true} or \meta{false} (allowing
+nested use). The starred form \gls{glsxtrifhasfield*} doesn't.
+You can compare the field value with a string using:
+\nosecformatdef{GlsXtrIfFieldEqStr}
+If you need the string to be (protected) fully expanded before
+comparison, you need:
+\nosecformatdef{GlsXtrIfFieldEqXpStr}
+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.
+
+The earlier \code{duck} and \code{goose} examples from
+\sectionref{sec:firstuse} can be rewritten to move the parenthetical
+material into separate keys:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{\comment{information about this term:}
+ \field{name} = \marg{duck},
+ \field{user1} = \marg{noun},
+ \field{user2} = \marg{quack, quack},
+ description = {a waterbird with webbed feet}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}\comment{label}
+\marg{\comment{information about this term:}
+ \field{name} = \marg{goose},
+ \field{plural} = \marg{geese},
+ \field{user1} = \marg{noun},
+ \field{user2} = \marg{honk, honk},
+ \field{description}=\marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\end{codeenv}
+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]{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{}
+ \cmd{space}
+ (\gls{glsentryuseri}\marg{\gls[noindex=false]{glscurrententrylabel}}\comment{}
+ \gls{GlsXtrIfXpFieldEqXpStr}\marg{plural}\marg{\gls{glscurrententrylabel}}\comment{}
+ \marg{\gls[noindex=false]{glsentrytext}\marg{\gls{glscurrententrylabel}}s}\marg{}\comment{}
+ \marg{, pl.\gls{cs.space}\gls[noindex=false]{glsentryplural}{\gls{glscurrententrylabel}}}\comment{}
+ )\comment{}
+}
+\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.
+
+\section{Accessibility Support}
+\label{sec:accsupp}
+
+The base \sty{glossaries} package is distributed with the
+supplementary \sty{glossaries-accsupp} package, which uses the
+\sty{accsupp} package~\cite{accsupp} to provide accessibility support. With the
+\sty{glossaries-extra} extension package, the
+\sty{glossaries-accsupp} package needs to be loaded after \sty{glossaries}
+but before \sty{glossaries-extra} sets up the accessibility
+integration support. The simplest way to do this is with
+\sty{glossaries-extra}'s \styopt{accsupp} package option.
+
+The accessibility support is provided through the PDF
+\code{ActualText} specification (via the \sty{accsupp} package).
+If you need \code{E} or \code{Alt} instead of \code{ActualText} then redefine:
+\nosecformatdef{glsaccsupp}
+as appropriate. For example:
+\begin{codeenv}
+\cmd{renewcommand}*\marg{\gls{glsaccsupp}}[2]\marg{\comment{}
+ \cmd{BeginAccSupp}\marg{Alt=\marg{\gls{param}1}}\gls{param}2\cmd{EndAccSupp}\marg{}\comment{}
+}
+\end{codeenv}
+
+The \sty{glossaries-accsupp} package provides additional keys (see
+Table~\ref{tab:accsuppfields} in the \bibgls\ user manual or
+Chapter~18 of the \sty{glossaries} user manual~\cite{glossaries}).
+The main keys are \field{access}, which provides an alternative to
+the \field{name} field, \field{symbolaccess}, which provides an
+alternative to the \field{symbol} field and \field{shortaccess},
+which provides an alternative to the \field{short} field,
+\field{firstaccess}, which provides an alternative to the
+\field{first} field, and \field{textaccess}, which provides an
+alternative to the \field{text} field. If any of the accessibility
+fields are unset, no accessibility support is provided for that
+field.
+For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{R}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{\cmd{ensuremath}\marg{\cmd{Re}}},
+ \field{access} = \marg{set of real numbers symbol},\comment{name access}
+ \field{textaccess} = \marg{set of real numbers},\comment{text access}
+ \field{firstaccess} = \marg{set of real numbers},\comment{first access}
+ \field{description} = \marg{set of real numbers}
+}
+\end{codeenv}
+This means that when the \field{name} field is displayed in the
+glossary, the corresponding accessibility text is \qt{set of real
+numbers symbol}, but the \idx{link-text} for \gls{gls} is just
+\qt{set of real numbers} (for both \idx{firstuse} and subsequent
+use).
+
+There are some category attributes that govern the default settings
+of some fields when using \gls{newabbreviation} (see
+\sectionref{sec:abbreviations}). If accessibility support is
+provided, there are some additional attributes (introduced to
+\sty{glossaries-extra} version 1.31):
+\begin{description}
+\item[\catattr{accessinsertdots}] This is a boolean attribute that behaves like
+\catattr{insertdots} but only applies to the \field{shortaccess}
+field, if it hasn't explicitly been set. This is useful for
+initialisms that should be read out as letters but the screen reader
+might interpret as a word. For example:
+\begin{codeenv}
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true}
+\gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator}
+\end{codeenv}
+This means that the short form appears as just \qt{PI} in the
+document text, but the accessibility text is \qt{P.I.} which prompts
+the screen reader to read it as an abbreviation instead of the word
+\qt{pi}. Since the \field{shortaccess} field is an aid to the screen
+reader and doesn't modify the visible text, there's no check
+for the \catattr{retainfirstuseperiod} or \catattr{discardperiod}
+attributes for that field. This setting doesn't affect the
+accessibility support for the \field{name}, \field{first} or
+\field{text} fields.
+
+\item[\catattr{nameshortaccess}] This is a boolean attribute, where
+the value \code{true} indicates the attribute is set. If the
+\field{shortaccess} field is assigned (either explicitly with the key or
+implicitly through the use of the \catattr{accessinsertdots}
+attribute) and the \field{access} field isn't specified, then if the
+\catattr{nameshortaccess} attribute is set this will copy the
+\field{shortaccess} field to the \field{access} field. For example:
+\begin{codeenv}
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{accessinsertdots}}\marg{true}
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{nameshortaccess}}\marg{true}
+\gls{newabbreviation}\oarg{\field{category}=initialism}\marg{pi}\marg{PI}\marg{Private Investigator}
+\end{codeenv}
+Abbreviations that behave like regular terms (such as
+\abbrstyle{short-nolong}) may also need \catattr{textshortaccess}
+and \catattr{firstshortaccess} set.
+
+\item[\catattr{textshortaccess}] Like \catattr{nameshortaccess}, but
+applies to the \field{textaccess} field.
+
+\item[\catattr{firstshortaccess}] Like \catattr{firstshortaccess}, but
+applies to the \field{firstaccess} field.
+
+\item[\catattr{accessaposplural}] If the \field{shortaccess} field
+is set (either explicitly with the key or implicitly through the use
+of the \catattr{accessinsertdots} attribute) and the
+\field{shortpluralaccess} field isn't set, the
+\catattr{accessaposplural} boolean attribute behaves like
+\catattr{aposplural} but only applies to the
+\field{shortpluralaccess} field. If the \catattr{accessaposplural}
+attribute isn't set but the \catattr{aposplural} attribute is set,
+then that's used instead. If you want \catattr{aposplural} on but
+not apply it to \field{shortpluralaccess} then you need to set the
+\catattr{accessaposplural} attribute to \code{false}.
+
+\item[\catattr{accessnoshortplural}] A boolean attribute like
+\catattr{accessaposplural} but analogous to \catattr{noshortplural}
+instead.
+\end{description}
+These attributes have no effect for entries that aren't defined
+using \gls{newabbreviation}. (These attributes apply to
+\gls{newacronym} provided it internally uses \gls{newabbreviation},
+which is does by default with \sty{glossaries-extra}.)
+
+\section{Prefixes}
+\label{sec:prefixes}
+
+The \sty{glossaries} package is distributed with the supplementary
+\sty{glossaries-prefix} package. This automatically loads
+\sty{glossaries}, but if you are using \sty{glossaries-extra}, it's
+best loaded after. This supplementary package supplies extra keys
+and some commands analogous to \gls{gls}. The main purpose is to
+provide a different prefix to \gls{gls}, depending on whether it's
+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
+\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.
+
+To include the prefix, use:
+\nosecformatdef{pgls}
+instead of \gls{gls}. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\cmd{usepackage}\marg{glossaries-prefix}
+\strut
+\gls{newabbreviation}
+ \oarg{\field{prefixfirst}=\marg{a\gls[noindex=false]{nbspchar}},\field{prefix}=\marg{an\cmd{space}}}
+ \marg{svm}\marg{SVM}\marg{support vector machine}
+\strut
+\cmd{begin}\marg{document}
+With a prefix: \gls{pgls}\marg{svm} or \gls{pgls}\marg{svm}.
+Without a prefix: the \gls{gls}\marg{svm}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+With a prefix: a support vector machine (SVM) or an SVM. Without a
+prefix: the SVM.
+\end{result}
+
+\section{Spaces}
+\label{sec:spaces}
+
+With \LaTeX\ in general, spaces are sometimes significant and
+sometimes ignored. When defining entries, any spaces around the
+equal sign or comma are ignored. For example, if an entry is defined
+as
+\begin{codeenv}
+\gls{newglossaryentry}\marg{sample}
+\marg{
+ \field{name} = \marg{sample} , \field{description} = \marg{an example}
+}
+\end{codeenv}
+then
+\begin{codeenv}
+/\gls{gls}\marg{sample}/
+\end{codeenv}
+will produce
+\begin{result}
+/sample/
+\end{result}
+(no spaces). Similarly with:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{sample}
+\marg{
+ \field{name} = sample , \field{description} = \marg{an example}
+}
+\end{codeenv}
+However, spaces at the start or end of the value if it's been
+enclosed in braces aren't ignored. For example, if the entry is now
+defined as:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{sample}
+\marg{
+ \field{name} = \marg{ sample } , \field{description} = {an example}\incorrect
+}
+\end{codeenv}
+then:
+\begin{codeenv}
+/\gls{gls}\marg{sample}/
+\end{codeenv}
+produces:
+\begin{result}
+/ sample /
+\end{result}
+The spaces in this case have been retained. The unstarred version of
+\gls{longnewglossaryentry} appends extra code to the end of the
+description, which removes any trailing spaces (and also the
+\gls{postdescriptionhook}). The starred version
+\gls{longnewglossaryentry*} (only available with \sty{glossaries-extra})
+doesn't. In both cases any leading spaces are retained. For example,
+if the entry is defined as:
+\begin{codeenv}
+\gls{longnewglossaryentry}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect
+\end{codeenv}
+then:
+\begin{codeenv}
+/\gls{glsentrydesc}\marg{sample}/
+\end{codeenv}
+produces:
+\begin{result}
+/ an example/
+\end{result}
+(trailing space removed), whereas if the entry is defined as:
+\begin{codeenv}
+\gls{longnewglossaryentry*}\marg{sample}\marg{name=\marg{sample}}\marg{ an example }\incorrect
+\end{codeenv}
+then:
+\begin{codeenv}
+/\gls{glsentrydesc}\marg{sample}/
+\end{codeenv}
+produces:
+\begin{result}
+/ an example /
+\end{result}
+(leading and trailing spaces retained).
+
+Spaces in labels are significant. For example, in \verb|\gls{ duck }|
+the spaces are considered part of the label. If the entry was
+actually defined without spaces in the label then the entry
+referenced in \verb|\gls{ duck }| won't be found.
+
+\section{Undefined References}
+\label{sec:undefaction}
+
+If an entry that hasn't been defined is referenced with \gls{gls},
+by default an error is triggered. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces the error:
+\begin{verbatim}
+Glossary entry `duck' has not been defined.
+\end{verbatim}
+If you instruct \LaTeX\ to ignore the error and continue, the result
+is
+\begin{result}
+A .
+\end{result}
+The \sty{glossaries-extra} package provides the option
+\styopt[warn]{undefaction}, which will convert the error to a
+warning. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This now produces the warning:
+\begin{verbatim}
+Glossary entry `duck' has not been defined on input line 6
+\end{verbatim}
+(There are also other warnings about an empty \code{main} glossary.)
+The result is now:
+\begin{result}
+A ??.
+\end{result}
+This replaces the undefined reference with two question marks, just like
+undefined cross-references.
+Notice the difference between using \gls{ifglshasfield}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}
+(\gls{ifglshasfield}\marg{\gls[noindex=false]{field.useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
+\cmd{end}\marg{document}
+\end{codeenv}
+which produces:
+\begin{result}
+A ?? (??).
+\end{result}
+(and has two undefined warnings) and using \gls{glsxtrifhasfield}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{undefaction}=warn]\marg{glossaries-extra}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}
+(\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
+\cmd{end}\marg{document}
+\end{codeenv}
+which only has one undefined warning and produces:
+\begin{result}
+A ?? (not set).
+\end{result}
+
+When you incorporate \bibgls\ into the build process (see
+\sectionref{sec:bib2gls}), the first \LaTeX\ run doesn't have any
+entries defined. One of the actions that the \styopt{record} option
+automatically performs is to switch on \styopt[warn]{undefaction}, which avoids
+undefined errors on the first \LaTeX\ run. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}
+(\gls{glsxtrifhasfield}\marg{\field{useri}}\marg{duck}\marg{\gls{glscurrentfieldvalue}}\marg{not set}).
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces the same result as the previous example, but there's
+only the one warning (about an undefined reference) and no warning
+about the empty \code{main} glossary.
+
+\section{Robust, Fragile and Expandable Commands}
+\label{sec:robust}
+
+Commands like \gls{gls} are \pidx{robust}. This protects them from
+premature expansion in situations that would otherwise break the
+command. If content containing a \idx{robust} command is written to
+an external file, the \idx{robust} command itself is written instead of its
+definition. For example, consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{newcommand}\marg{\csfmt{test}}\marg{some sample text}
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls[noindex=false]{section}\marg{\csfmt{test}}
+\cmd{end}\marg{document}
+\end{codeenv}
+In this case, \csfmt{test} is expandable. Its definition doesn't
+contain anything complicated. The \ext{toc} file (which is input by
+\csfmt{tableofcontents}) contains the line:
+\begin{codeenv}
+\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some sample text}\marg{1}
+\end{codeenv}
+So \csfmt{test} has been expanded to its definition when it was
+written to the \ext{toc} file. If \csfmt{test} is defined in terms
+of another command, that will also be expanded. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{newcommand}\marg{\csfmt{sample}}\marg{\gls{emph}\marg{sample}}
+\cmd{newcommand}\marg{\csfmt{test}}\marg{some \csfmt{sample}\gls{cs.space}text}
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{section}\marg{\csfmt{test}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The \ext{toc} file now contains:
+\begin{codeenv}
+\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}some \gls{emph} \marg{sample}\gls{cs.space}text}\marg{1}
+\end{codeenv}
+So \csfmt{sample} has also been expanded but neither
+\gls{emph} nor \idx{cs.space} (backslash space) have
+been expanded. \Idx{robust} commands don't expand. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The \ext{toc} file now contains:
+\begin{codeenv}
+\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a waterbird with
+webbed feet}\marg{1}
+\end{codeenv}
+So \gls{Gls} doesn't expand, and the command itself is written to the
+\ext{toc} file, but \gls{glsentrydesc} does expand.
+
+A \pidx{fragile} command is one that breaks (causes an error) when
+it's expanded in this type of context. One such command is \gls{footnote}.
+For example, the following won't work:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{section}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\incorrect
+\cmd{end}\marg{document}
+\end{codeenv}
+This causes the error:
+\begin{verbatim}
+! Argument of \@sect has an extra }.
+\end{verbatim}
+Inserting \gls{protect} before the command prevents the attempted
+expansion, which makes the command behave as though it was robust:
+\begin{codeenv}
+\gls{section}\marg{\gls{Gls}\marg{duck}\gls{protect}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}
+\end{codeenv}
+In this case, it's unlikely that you'd want the footnote to appear
+in the table of contents, so it would be better to use the optional
+argument:
+\begin{codeenv}
+\gls{section}\oarg{Duck}\marg{\gls{Gls}\marg{duck}\gls{footnote}\marg{\gls{glsentrydesc}\marg{duck}}}\correct
+\end{codeenv}
+Now the \ext{toc} file is just:
+\begin{codeenv}
+\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}Duck}\marg{1}
+\end{codeenv}
+If the \field{description} field contains a \idx{fragile} command
+then \gls{glsentrydesc} will break in expandable contexts. For
+example, the following doesn't work:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird\gls{footnote}\marg{a bird that lives on or
+ near water} with webbed feet}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}\incorrect
+\cmd{end}\marg{document}
+\end{codeenv}
+This is a contrived example. In this case, it would be better to
+also define the term \qt{waterbird}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{waterbird}
+\marg{
+ \field{name}=\marg{waterbird},
+ \field{description}=\marg{a bird that lives on or near water}
+}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a \gls{gls}\marg{waterbird} with webbed feet}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{section}\marg{\gls{Gls}\marg{duck}: \gls{glsentrydesc}\marg{duck}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The \ext{toc} file now contains:
+\begin{codeenv}
+\cmd{contentsline} \marg{section}\marg{\cmd{numberline} \marg{1}\gls{Gls} \marg{duck}: a \gls{gls} \marg{waterbird}
+with webbed feet}\marg{1}
+\end{codeenv}
+
+\begin{important}
+The examples in this section are used to illustrate the differences
+between \idx{robust}, \idx{fragile} and \idx{expandable} commands.
+In general, it's better not to use commands like \gls{gls} in
+headings or captions (see \sectionref{sec:headings}) and using
+commands like \gls{gls} in field values can be problematic (see
+\sectionref{sec:nested}).
+\end{important}
+
+By default, most of the field values are expanded when the entry is
+defined. This allows for defining entries programmatically, but it
+can cause a problem if the value contains any \idx{fragile} commands.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}},\incorrect
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This causes the confusing error:
+\begin{verbatim}
+! Undefined control sequence.
+\in@ #1#2->\begingroup \def \in@@
+\end{verbatim}
+In order for this example to work, the \idx{fragile} command must either be
+protected:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{first} = \marg{duck\gls{protect}\gls{footnote}\marg{quack, quack}},\correct
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\end{codeenv}
+or the expansion must first be switched off:
+\begin{codeenv}
+\gls{glsnoexpandfields} \correct
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{first} = \marg{duck\gls{footnote}\marg{quack, quack}},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\end{codeenv}
+Since it's not possible to programmatically define entries with
+\bibgls, the expansion is automatically switched off as \bibgls\
+writes \gls{glsnoexpandfields} to the \ext{glstex} file (although
+you can switch this feature off with \longarg{expand-fields}).
+
+The reason why \gls{footnote} didn't cause a problem in the
+\field{description} field \emph{when the entry was defined} is that, by
+default, expansion isn't performed on the \field{name},
+\field{description} and \field{symbol} fields, regardless of whether
+or not \gls{glsnoexpandfields} has been used. This only applies to
+the point when the entries are being defined. Unprotected
+\idx{fragile} commands can still cause a problem if the value is
+later used in a problematic context (such as the earlier example
+where \gls{glsentrydesc} was used in a section heading).
+
+\chapter{Abbreviations}
+\label{sec:abbreviations}
+
+The abbreviation handling provided by the base \isty{glossaries}
+package is quite restrictive and only one abbreviation style can be
+used for all abbreviations. The \isty{glossaries-extra} package
+internally loads the \sty{glossaries} package and extends it,
+providing new options and a better abbreviation mechanism that
+allows different styles per category.
+
+The base \sty{glossaries} package provides:
+\nosecformatdef{newacronym}
+The extension package \sty{glossaries-extra} provides:
+\nosecformatdef{newabbreviation}
+which internally uses \gls{newglossaryentry} with the
+\field{category} set to \code{abbreviation} (which can be
+overridden in the optional \meta{\keyvallist}).
+The \gls{glossaries-extra} package also redefines \gls{newacronym} in
+terms of \gls{newabbreviation} so that it effectively behaves like:
+\begin{codeenv}
+\gls{newabbreviation}\oarg{\gls[noindex=false]{field.type}=\gls{acronymtype},\field{category}=acronym,\meta{\keyvallist}}
+\margm{label}\margm{short}\margm{long}
+\end{codeenv}
+This makes it easier to transfer over from the base \sty{glossaries}
+package, but if you use \gls{newacronym} remember that the
+\field{category} is set to \code{acronym} instead of \code{abbreviation}.
+
+In both cases, \meta{label} is the entry's label used to identify
+the abbreviation in commands like \gls{gls}, \meta{short} is the
+short form and \meta{long} is the long form. Any additional
+settings, such as the \field{category} or \field{description}
+can be set in the optional argument.
+
+The style must be set \emph{before the abbreviations are defined}
+using:
+\nosecformatdef{setabbreviationstyle}
+where \meta{category} is the category label and \meta{style-name} is
+the name of the style. If the optional argument is omitted,
+\code{abbreviation} is assumed. The \sty{glossaries-extra} package
+automatically sets the default styles:
+\begin{codeenv}
+\gls{setabbreviationstyle}\marg{\abbrstyle{long-short}}
+\gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle{short-nolong}}
+\end{codeenv}
+This means that if you don't explicitly set the style then any
+abbreviation defined with \gls{newacronym} will use the
+\abbrstyle{short-nolong} style (unless you change the category in
+the optional argument) and other abbreviations will use the
+\abbrstyle{long-short} style.
+
+If these styles aren't suitable, then you need to change them. Any
+abbreviation that's defined with a category that hasn't been
+assigned a style will fallback on the style for the default
+\code{abbreviation} category. There are many predefined styles to
+choose from and they come with commands to help adjust the
+formatting. See the \sty{glossaries-extra} user
+manual~\cite{glossaries-extra} for the
+complete list. The \sty{glossaries-extra} package also comes with a
+sample document
+\ctanfile{glossaries-extra/samples}{sample-abbr-styles.pdf}
+demonstrating all the predefined styles.
+
+The style determines whether the abbreviation is treated as a
+\idx{regular} term. There are also some \idxpl{categoryattribute} that govern
+abbreviations (see below and \sectionref{sec:accsupp}). These
+should also be set before the abbreviation is defined.
+
+Some of the styles set the \field{description} field (typically to
+the \meta{long} form). The styles that end with \code{-desc} don't,
+and so that key must be set explicitly in the \meta{\keyvallist} optional part.
+
+Here's a simple example that uses both \gls{newabbreviation} and
+\gls{newacronym} to illustrate the difference:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
+\gls{newabbreviation}\marg{cldr}\marg{CLDR}\marg{Unicode Common Locale Data
+Repository}
+\strut
+\gls{newacronym}\marg{SIunit}\marg{SI unit}\marg{International System of Units}
+\gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for
+Information Interchange}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}.
+Next use: \gls{gls}\marg{tug}, \gls{gls}\marg{cldr}, \gls{gls}\marg{SIunit}, \gls{gls}\marg{ascii}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+First use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}.
+Next use: \gls{TUG}, \gls{CLDR}, \gls{SIunit}, \gls{ASCII}.
+\end{result}
+Note that the \idx{firstuse} of \code{SIunit} and \code{ascii} only
+show the short form. This is because the default style for the
+\code{acronym} category is the \abbrstyle{short-nolong} style, which
+doesn't show the long form with \gls{gls} (and its \idxpl{variant}).
+
+If you only want \gls{gls} to show the short form but not the long
+form, use one of the \code{-nolong} styles (such as
+\abbrstyle{short-nolong}). If you only want the
+long form and not the short form, use one of the \code{-noshort}
+styles (such as \abbrstyle{long-noshort}). If you want only the long
+form on \idx{firstuse} and only the short form subsequently
+then use one of the \code{-only} styles, such as
+\abbrstyle{long-only-short-only}.
+
+If you want a specific instance to show only the short form, without
+modifying the \idx{firstuseflag}, then use
+\nosecformatdef{glsxtrshort}
+If you want a specific instance to show only the long form, without
+modifying the \idx{firstuseflag}, then use
+\nosecformatdef{glsxtrlong}
+If you want a specific instance to show both the long and short form, without
+modifying the \idx{firstuseflag}, then use
+\nosecformatdef{glsxtrfull}
+Depending on the style, this may not exactly match the format
+produced by the \idx{firstuse} of \code{\gls{gls}\margm{label}}.
+
+If you find these commands quite long-winded, there are some
+shortcuts available with the \styopt{shortcuts} option, but as these
+may interfere with other packages, you might want to consider
+investigating your text editor settings as the more sophisticated
+ones provide ways of inserting commonly-used commands to save typing.
+
+The final optional \meta{insert} argument of commands like \gls{gls}
+is typically moved inside, depending on the style. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
+\strut
+\cmd{begin}\marg{document}
+The \gls{gls}\marg{svm}\oarg{'s} parameters are\cmd{ldots}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+The \gls{ex.svm}['s] parameters are\ldots
+\end{result}
+Compare this with:
+\begin{codeenv}
+The \gls{gls}\marg{svm}'s parameters are\cmd{ldots}\incorrect
+\end{codeenv}
+which produces:
+\begin{result}
+The \gls{ex.svm}'s parameters are\ldots
+\end{result}
+
+\section{Plural Abbreviations}
+If the abbreviation represents something countable then the plural
+form can again be obtained with \gls{glspl}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+First use: \glspl{ex.svm}. Next use: \glspl{ex.svm}.
+\end{result}
+The default plural short and long forms are obtained by
+appending the letter \qt{s} after the singular form. These can be
+changed on an individual basis with the \field{shortplural} and
+\field{longplural} keys. For example:
+\begin{codeenv}
+\gls{newabbreviation}
+ [\field{longplural}=\marg{lower triangular matrices}]
+ \marg{ltm}\marg{LTM}\marg{lower triangular matrix}
+\end{codeenv}
+
+It may be that you prefer to keep the short plural form the same as
+the short singular value for all abbreviations within a particular
+category. You can implement this with the
+\catattr{noshortplural} attribute, which must be set to \code{true}
+before the abbreviations for that category are defined. For example:
+\begin{codeenv}
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{noshortplural}}\marg{true}
+\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
+\end{codeenv}
+Now:
+\begin{codeenv}
+First use: \gls{glspl}\marg{svm}. Next use: \gls{glspl}\marg{svm}.
+\end{codeenv}
+produces:
+\begin{result}
+First use: support vector machines (SVM). Next use: SVM.
+\end{result}
+A related attribute is \catattr{aposplural} which inserts \qtt{'s}
+(apostrophe followed by \qt{s}) to form the default short plural to
+help avoid ambiguity with \idx{lowercase} abbreviations where it might
+not be obvious that the \qt{s} indicates a plural (rather than
+another letter in the abbreviation). Again, this needs to be set
+before the abbreviations for the given category (or categories) are
+defined (but check with your supervisor, publisher or editor as this
+usage is controversial).
+
+\section{Abbreviation Markup}
+
+The \catattr{markwords} attribute can be set to \code{true} to
+indicate that \gls{newabbreviation} should parse the long form and
+markup the words using:
+\nosecformatdef{glsxtrword}
+The words are separated with
+\nosecformatdef{glsxtrwordsep}
+For example:
+\begin{codeenv}
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true}
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
+\end{codeenv}
+This is essentially the same as
+\begin{codeenv}
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{\gls{glsxtrword}\marg{Secure}\gls{glsxtrwordsep}
+\gls{glsxtrword}\marg{Sockets}\gls{glsxtrwordsep}\gls{glsxtrword}\marg{Layer}}
+\end{codeenv}
+This is typically used with the \code{-hyphen} abbreviation styles.
+If the final optional \meta{insert} argument of commands like
+\gls{gls} starts with a hyphen, \gls{glsxtrwordsep} is locally
+changed to a hyphen.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{setabbreviationstyle}\marg{\gls[noindex=false]{long-hyphen-short-hyphen}}
+\strut
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{markwords}}\marg{true}
+\strut
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{gls}\marg{ssl}\oarg{-enabled}. Next use: \gls{gls}\marg{ssl}\oarg{-enabled}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+First use: \gls{ex.ssl}[-enabled]. Next use: \gls{ex.ssl}[-enabled].
+\end{result}
+Compare this with:
+\begin{codeenv}
+First use: \gls{gls}\marg{ssl}-enabled. Next use: \gls{gls}\marg{ssl}-enabled.\incorrect
+\end{codeenv}
+which instead produces:
+\begin{result}
+First use: \gls{ex.ssl}-enabled. Next use: \gls{ex.ssl}-enabled.
+\end{result}
+Whereas:
+\begin{codeenv}
+First use: \gls{gls}\marg{ssl}\oarg{ enabled}. Next use: \gls{gls}\marg{ssl}\oarg{ enabled}.
+\end{codeenv}
+produces:
+\begin{result}
+First use: \gls{ex.ssl}[ enabled]. Next use: \gls{ex.ssl}[ enabled].
+\end{result}
+Note that this is different to the result obtained with the
+\abbrstyle{long-short} style which doesn't include the inserted
+material in the parentheses (and doesn't check if the inserted
+text starts with a hyphen).
+
+There's a related attribute \catattr{markshortwords} which applies
+to the short form instead. This is only useful if the short form contains
+spaces.
+
+Another markup-related attribute is \catattr{tagging}. In general,
+you don't need to explicitly set this attribute. Instead, you need
+to define a tagging command using:
+\nosecformatdef{GlsXtrEnableInitialTagging}
+This (robustly) defines \meta{cs} (a control sequence) to accept a
+single argument, which you need to use in the \meta{long} part of the
+abbreviation definition (it's not inserted automatically).
+
+The \gls{GlsXtrEnableInitialTagging} command also sets the
+\catattr{tagging} attribute to \code{true} for each of the listed
+categories, which ensures that \meta{cs} uses
+\nosecformatdef{glsxtrtagfont}
+within the glossary (see \sectionref{sec:displaygloss}). Within the
+main text the command simply does its argument.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrEnableInitialTagging}\marg{abbreviation}\marg{\cmd{itag}}
+\strut
+\gls{newabbreviation}\marg{xml}\marg{XML}\marg{e\cmd{itag}\marg{x}tensible \cmd{itag}\marg{m}arkup
+\cmd{itag}\marg{l}anguage}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{gls}\marg{xml}. Next use: \gls{gls}\marg{xml}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+First use: \gls{ex.xml}. Next use: \gls{ex.xml}.
+\end{result}
+This doesn't show the markup as the tagging command (\csfmt{itag} in
+this example) simply expands to its argument in the main document
+text. The difference is only evident in the glossary.
+
+If all your abbreviations are defined in a separate file, it's
+useful to provide a definition of the tagging command with
+\gls{providecommand} to ensure it's defined if you decide not to use
+\gls{GlsXtrEnableInitialTagging}. With \bibgls, you can include it
+in the \atentry{preamble}. For example:
+\begin{codeenv}
+\atentry{preamble}\marg{"\gls{providecommand}\marg{\cmd{itag}}\oarg{1}\marg{\gls{param}1}"}
+\end{codeenv}
+
+\section{Dotted Abbreviations}
+
+If an abbreviation ends with a \idx{full-stop}, it can be awkward
+when it appears at the end of a sentence, as you can end up with two
+dots by mistake. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{dante}\marg{DANTE e.V.}
+\marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.}
+\strut
+\gls{newabbreviation}\marg{gp}\marg{G.P.}\marg{General Practitioner}
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group.
+The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}.
+\strut
+A \gls{gls}\marg{gp} is a medical doctor.
+I went to my surgery to see the \gls{gls}\marg{gp}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This results in:
+\begin{result}
+\gls{ex.dante} is a local \TeX\ user group.
+The German-speaking local \TeX\ user group is \gls{ex.dante}\relax.\incorrect
+
+A \gls{ex.gp} is a medical doctor.
+I went to my surgery to see the \gls{ex.gp}\relax.\incorrect
+\end{result}
+The awkward double-dot is caused by the final dot in the
+short form followed by the sentence terminating \idx{full-stop}.
+
+If the \catattr{discardperiod} attribute is set to \code{true}, the
+\idx{postlinkhook} will look ahead for a \idx{full-stop}. If it
+finds one, it will be discarded. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{glssetcategoryattribute}\marg{abbreviationdot}\marg{\catattr{discardperiod}}\marg{true}
+\strut
+\gls{newabbreviation}\oarg{\field{category}=abbreviationdot}
+ \marg{dante}\marg{DANTE e.V.}\marg{Deutschsprachige Anwendervereinigung \cmd{TeX}\gls{cs.space}e.V.}
+\strut
+\gls{newabbreviation}\oarg{\field{category}=abbreviationdot}
+ \marg{gp}\marg{G.P.}\marg{General Practitioner}
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{dante} is a local \cmd{TeX}\gls{cs.space}user group.
+The German-speaking local \cmd{TeX}\gls{cs.space}user group is \gls{gls}\marg{dante}.
+\strut
+A \gls{gls}\marg{gp} is a medical doctor.
+I went to my surgery to see the \gls{gls}\marg{gp}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This now results in:
+\begin{result}
+\gls{ex.dante} is a local \TeX\ user group.
+The German-speaking local \TeX\ user group is \gls{ex.dante}.
+
+A \gls{ex.gp} is a medical doctor.
+I went to my surgery to see the \gls{ex.gp}.
+\end{result}
+This attribute only affects the \emph{non-plural} commands, such as
+\gls{gls} and \gls{glsxtrshort}. If the last paragraph in the above
+example is changed to:
+\begin{codeenv}
+A \gls{gls}\marg{gp} is a medical doctor.
+I went to my surgery to see the \gls{glspl}\marg{gp}.
+\end{codeenv}
+then the result is:
+\begin{result}
+A \gls{ex.gp} is a medical doctor.
+I went to my surgery to see the \glspl{ex.gp}.
+\end{result}
+In this case there's no need to discard the terminating
+\idx{full-stop} as the plural form doesn't end with one. If the
+plural form also ends with a \idx{full-stop} (for example, if the
+\catattr{noshortplural} attribute is also set) then you additionally
+need to set the \catattr{pluraldiscardperiod} attribute.
+
+The \idx{postlinkhook} is also applied to other commands, such as
+\gls{glsxtrfull}, \gls{glsxtrlong}, \gls{glsxtrshort} and \gls{glssymbol}.
+For example:
+\begin{codeenv}
+I went to my surgery to see the \gls{glsxtrshort}\marg{gp}.
+\end{codeenv}
+results in:
+\begin{result}
+I went to my surgery to see the \glsxtrshort{ex.gp}.
+\end{result}
+In some cases, this may be inappropriate, for example:
+\begin{codeenv}
+I went to my surgery to see the \gls{glsxtrlong}\marg{gp}.
+\end{codeenv}
+results in:
+\begin{result}
+I went to my surgery to see the \glsxtrlong{ex.gp}.
+\end{result}
+In this case the terminating \idx{full-stop} shouldn't be discarded.
+There are several ways to prevent it. For example, moving the
+\idx{full-stop} into the \meta{insert} argument:
+\begin{codeenv}
+I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\oarg{.}
+\end{codeenv}
+This results in:
+\begin{result}
+I went to my surgery to see the \glsxtrlong{ex.gp}[.]
+\end{result}
+Alternatively, insert \csfmt{relax} before the \idx{full-stop}:
+\begin{codeenv}
+I went to my surgery to see the \gls{glsxtrlong}\marg{gp}\cmd{relax}.
+\end{codeenv}
+
+Depending on the abbreviation style, it may be inappropriate for the
+\idx{firstuse} to discard the \idx{full-stop}. In this case, it's a
+bit of a nuisance to keep track of whether the term is being
+referenced for the first time. Instead, set the
+\catattr{retainfirstuseperiod} attribute to \code{true}.
+
+If you have many abbreviations defined without dots and then you
+later decide to insert them, you may prefer an automated approach.
+This can be done by setting the \catattr{insertdots} attribute to \code{true}.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{insertdots}}\marg{true}
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{discardperiod}}\marg{true}
+\gls{glssetcategoryattribute}\marg{initialism}\marg{\catattr{retainfirstuseperiod}}\marg{true}
+\strut
+\gls{setabbreviationstyle}\oarg{initialism}\marg{\gls[noindex=false]{short-long}}
+\strut
+\gls{newabbreviation}\oarg{\field{category}=initialism}
+ \marg{gp}\marg{GP}\marg{General Practitioner}
+\strut
+\cmd{begin}\marg{document}
+Today I went to my surgery to see the \gls{gls}\marg{gp}.
+Tomorrow I'm going to my surgery to see the \gls{gls}\marg{gp}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+Today I went to my surgery to see the \gls{ex2.gp}.
+Tomorrow I'm going to my surgery to see the \gls{ex2.gp}.
+\end{result}
+
+\section{Translations}
+\label{sec:abbrvtrans}
+
+If an abbreviation needs to be accompanied by a translation, then
+you can use a custom field or one of the supplied user fields
+described in \sectionref{sec:userkeys} to store the translation. The
+\code{-user} abbreviation styles can be used to include the extra
+information if the field is set. The \field{user1} field
+is the default, but you can change this by redefining
+\nosecformatdef{glsxtruserfield}
+to the \emph{internal} field name. (For example, \field{userii} for
+\field{user2}.) In the sample document below, the translation is
+supplied in the default \field{user1} field:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-user}}
+\strut
+\gls{newabbreviation}\oarg{\field{user1}=\marg{ribonucleic acid}}
+ \marg{rna}\marg{RNA}\marg{ribonukleins\gls[noindex=false]{umlaut}aure}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{gls}\marg{rna}. Next use: \gls{gls}\marg{rna}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+First use: \gls{ex.rna}. Next use: \gls{ex.rna}.
+\end{result}
+If the field is empty, \abbrstyle{long-short-user} behaves like
+\abbrstyle{long-short}.
+
+\chapter{Symbols}
+\label{sec:symbols}
+
+\Sectionref{sec:userkeys} described the \field{symbol} key, which can
+be used to additionally provide a symbol. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{\gls[noindex=false]{siunitx}}\comment{provides \gls{si}}
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{length}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{length},
+ \field{symbol} = \marg{\gls{si}\marg{\cmd{metre}}},
+ \field{description} = \marg{measurement between two points}
+}
+\strut
+\gls{newglossaryentry}\marg{area}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{area},
+ \field{symbol} = \marg{\gls[noindex=false]{si}\marg{\cmd{metre}\cmd{squared}}},
+ \field{description} = \marg{measurement of a surface}
+}
+\strut
+\cmd{begin}\marg{document}
+Measurements: \gls{gls}\marg{length} (\gls{glssymbol}\marg{length}) and
+\gls{gls}\marg{area} (\gls{glssymbol}\marg{area}).
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+Measurements: \gls{ex.length} (\glssymbol{ex.length}) and
+\gls{ex.area} (\glssymbol{ex.area}).
+\end{result}
+
+It may be that you prefer to have the symbol in the \field{name}
+field instead. The example document below is a modification of the
+above and uses the \idx{postlinkhook} to append the description on
+\idx{firstuse} (see \sectionref{sec:postlinkhooks}).
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{siunitx}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls[noindex=false]{glsnoexpandfields} \comment{name field contains \gls{si}}
+\strut
+\gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}}
+\strut
+\gls{newglossaryentry}\marg{length}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{\gls{si}\marg{\cmd{metre}}},
+ \field{description} = \marg{length},
+ \field{category} = \marg{symbol}
+}
+\strut
+\gls{newglossaryentry}\marg{area}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}},
+ \field{description} = \marg{area},
+ \field{category} = \marg{symbol}
+}
+\strut
+\cmd{begin}\marg{document}
+First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
+Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
+\cmd{end}\marg{document}
+\end{codeenv}
+Note the need for \gls{glsnoexpandfields} (described in
+\sectionref{sec:robust}). This wasn't required in the previous
+example because the \sty{siunitx} commands were in the
+\field{symbol} field, which isn't expanded by default. The
+\field{name} field also isn't expanded by default, but its value is
+copied to the \field{text} and \field{first} fields, which are
+expanded by default. If \gls{glsnoexpandfields} is omitted from the
+above document, the following error would occur:
+\begin{verbatim}
+! Undefined control sequence.
+\@glo at name ->\si {\metre
+ }
+\end{verbatim}
+Although \gls{si} is robust, commands like \csfmt{metre} and
+\csfmt{squared} are only available within the argument of \gls{si}
+(and other similar commands provided by \sty{siunitx}) and so break
+in expandable contexts.
+With \gls{glsnoexpandfields}, the document compiles correctly and
+produces:
+\begin{result}
+\glsdefpostlink{symbol}{\glsxtrpostlinkAddDescOnFirstUse}%
+First use: \gls{ex2.length} and \gls{ex2.area}.
+Next use: \gls{ex2.length} and \gls{ex2.area}.
+\end{result}
+
+The \sty{glossaries-extra}['s] \styopt{symbols} package option
+provides the command
+\nosecformatdef{glsxtrnewsymbol}
+which is a shortcut for
+\begin{codeenv}
+\gls{newglossaryentry}\margm{label}\marg{\field{name}=\margm{symbol},\field{category}=\marg{symbol},\gls[noindex=false]{field.sort}=\margm{label},
+\gls[noindex=false]{field.type}=\marg{symbols},\meta{\keyvallist}}
+\end{codeenv}
+So the above document can be changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{siunitx}
+\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{glsnoexpandfields}
+\strut
+\gls{glsdefpostlink}\marg{symbol}\marg{\gls{glsxtrpostlinkAddDescOnFirstUse}}
+\strut
+\gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{length}}\marg{length}\marg{\gls{si}\marg{\cmd{metre}}}
+\strut
+\gls{glsxtrnewsymbol}\oarg{\field{description} = \marg{area}}\marg{area}\marg{\gls{si}\marg{\cmd{metre}\cmd{squared}}}
+\strut
+\cmd{begin}{document}
+First use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
+Next use: \gls{gls}\marg{length} and \gls{gls}\marg{area}.
+\cmd{end}\marg{document}
+\end{codeenv}
+The result is the same.
+
+\section{Functions}
+\label{sec:functions}
+
+Some symbols may represent functions. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{glsnoexpandfields}
+\strut
+\gls{glsxtrnewsymbol}
+ \oarg{\field{description} = \marg{derivative}}
+ \marg{deriv}\comment{label}
+ \marg{\gls{ensuremath}\marg{f'(x)}}\comment{symbol}
+\strut
+\cmd{begin}\marg{document}
+The derivative is denoted \gls{gls}\marg{deriv}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+The derivative is denoted \gls{ex.deriv}.
+\end{result}
+What if I need to change the variable for a specific instance, for
+example, if I want $f'(x_i)$ instead of $f'(x)$? I can just use:
+\begin{codeenv}
+The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}.
+\end{codeenv}
+So far, none of the example documents have a glossary or list of
+terms. The ultimate aim when using the \styfmt{glossaries} package
+is to ensure consistent formatting and notation, and, where
+applicable, include a list of all terms referenced in the document.
+The use of commands like \gls{gls} helps to achieve this. If the
+notation needs to be changed, only the entry definition (and
+associated formatting commands) should need to be redefined without
+having to go through the whole document changing the code. Using
+commands like \gls{gls} also identifies which entries need to be
+included in the list of terms and, if \sty{hyperref} is loaded, can
+be hyperlinked to the relevant place in that list (see
+\sectionref{sec:displaygloss}).
+
+So explicitly using \verb|f'(x_i)| won't index the \code{deriv} entry
+or mark it has having been used or create a hyperlink. One
+possibility is to use one of the following commands:
+\nosecformatdef{glslink}
+\nosecformatdef{glsdisp}
+They both work in much the same way, indexing the entry and
+displaying \meta{text} as the \idx{link-text}. The only difference is
+that \gls{glsdisp} also unsets the \idx{firstuseflag}, which marks the entry
+as having been used. For example:
+\begin{codeenv}
+The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}f'(x\gls{sbchar}i)\gls{mshiftchar}}.
+\end{codeenv}
+This solves the problem of ensuring that the \code{deriv} entry is
+indexed and, if \sty{hyperref} is loaded, ensures that the
+\idx{link-text} has a hyperlink to the relevant place in the list of
+notation, but it doesn't solve the problem of consistent formatting.
+
+One way of ensuring consistent formatting is to define a semantic
+command. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{glsnoexpandfields}
+\strut
+\cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)}
+\strut
+\gls{glsxtrnewsymbol}
+ \oarg{\field{description} = \marg{derivative}}
+ \marg{deriv}\comment{label}
+ \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
+\strut
+\cmd{begin}\marg{document}
+The derivative is denoted \gls{gls}\marg{deriv}.
+The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{glslink}\marg{deriv}\marg{\gls{mshiftchar}\cmd{derivfn}\marg{x\gls{sbchar}i}\gls{mshiftchar}}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\providecommand{\derivfn}[1]{f'(#1)}
+The derivative is denoted \gls{ex.deriv}.
+The gradient at $x_i$ is \glslink{ex.deriv}{$\derivfn{x_i}$}.
+\end{result}
+Now only \csfmt{derivfn} needs modifying if the notation must change.
+This requires remembering both the entry label (\code{deriv} in this
+case) and the associated formatting command (\csfmt{derivfn} in this
+case). The \sty{glossaries-extra} package provides a way of storing
+the associated formatting command in one of the additional keys (see
+\sectionref{sec:userkeys}). The field is identified by:
+\nosecformatdef{GlsXtrFmtField}
+which defaults to \field{useri} (the internal representation of the
+\field{user1} key). The value must be the name (without the leading
+backslash) of a control sequence that takes a \emph{single}
+mandatory argument. The above custom command \code{derivfn}
+satisfies this requirement, so the entry can be defined as:
+\begin{codeenv}
+\gls{glsxtrnewsymbol}
+ \oarg{\comment{settings:}
+ \field{description} = \marg{derivative},
+ \field{user1} = \marg{derivfn}
+ }
+ \marg{deriv}\comment{label}
+ \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
+\end{codeenv}
+The formatting command can now be applied using one of the
+following:
+\nosecformatdef{glsxtrfmt}
+\nosecformatdef{glsxtrfmt*}
+which internally use \gls{glslink} or:
+\nosecformatdef{glsxtrentryfmt}
+which doesn't (as so is more like using \gls{glsentryname}).
+
+So an alternative approach is:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{glsnoexpandfields}
+\strut
+\cmd{newcommand}\marg{\cmd{derivfn}}[1]\marg{f'(\gls{param}1)}
+\strut
+\gls{glsxtrnewsymbol}
+ \oarg{\comment{settings:}
+ \field{description} = \marg{derivative},
+ \field{user1} = \marg{derivfn}
+ }
+ \marg{deriv}\comment{label}
+ \marg{\gls{ensuremath}\marg{\cmd{derivfn}\marg{x}}}\comment{symbol}
+\strut
+\cmd{begin}\marg{document}
+The derivative is denoted \gls{gls}\marg{deriv}.
+The gradient at \gls{mshiftchar}x\gls{sbchar}i\gls{mshiftchar} is \gls{mshiftchar}\gls{glsxtrfmt}\marg{deriv}\marg{x\gls{sbchar}i}\gls{mshiftchar}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This again produces:
+\begin{result}
+The derivative is denoted \gls{ex.deriv}.
+The gradient at $x_i$ is $\glsxtrfmt{ex.deriv}{x_i}$.
+\end{result}
+
+Both the starred \gls{glsxtrfmt*} and unstarred \gls{glsxtrfmt}
+format the \meta{text} argument using:
+\nosecformatdef{glsxtrfmtdisplay}
+where \meta{cs-name} is the control sequence name stored in the
+field identified by \gls{GlsXtrFmtField} and the \meta{insert} part
+is the final optional argument for the starred \gls{glsxtrfmt*} (if
+provided) otherwise it's empty. If the command identified by
+\meta{cs-name} doesn't exist (or if the field providing it isn't
+set) then just \meta{text}\meta{insert} is done.
+
+\begin{important}
+Nested \idx{link-text} causes problems so don't use \gls{glsxtrfmt}
+in the optional part of commands like \gls{gls} or \gls{glssymbol}
+or in field values that are used by those types of command. Also
+don't use \gls{glsxtrfmt} within the \meta{text} or \meta{insert}
+part of another instance of \gls{glsxtrfmt} or in \gls{glslink} or
+\gls{glsdisp}. Use \gls{glsxtrentryfmt} instead.
+\end{important}
+
+If more than one argument is required, then a helper macro is
+needed. For example:
+\begin{verbatim}
+\newcommand{\iderivfn}[2][f]{#1'(#2)}
+\newcommand{\derivfn}[1]{\iderivfn#1}
+\end{verbatim}
+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}
+
+\section{Dealing with Automated Case-Changing}
+\label{sec:symfirstuc}
+
+Commands like \gls{Gls} don't usually make much sense for symbols as
+a change in case can cause a change in meaning. For example,
+$\boldsymbol{x}$ might denote a vector and $\boldsymbol{X}$ might
+denote a matrix. However, you may have a mixed list of terms
+containing both symbols and words, and if you set the
+\catattr{glossname} attribute to \code{firstuc}, which automatically
+converts the first letter of each \field{name} to \idx{uppercase} in the
+glossary, then this can cause a problem for entries where the
+\field{name} starts with a symbol. The simplest solution is to
+insert an empty group at the start of the \field{name} field for
+such entries. For example:
+\begin{codeenv}
+\gls{glsxtrnewsymbol}
+ \oarg{\field{description} = \marg{length}}\comment{settings}
+ \marg{length}\comment{label}
+ \marg{\marg{}\gls{si}\marg{\cmd{metre}}}\comment{name}
+\end{codeenv}
+This is done automatically by \bibgls, but if it causes any
+interference you can switch off the behaviour with
+\longarg{no-mfirstuc-math-protection}.
+
+\chapter{Displaying the Definition}
+\label{sec:displaygloss}
+
+The examples so far only use the defined entries in the documents
+with commands like \gls{gls} or \gls{glssymbol} or
+\gls{glsentrydesc}. These are useful for ensuring consistent
+formatting, but it's also helpful to have a place in the document
+where the term is formally defined. This can be partially solved
+by including the description in parentheses on \idx{firstuse},
+either by explicitly including the description in the \field{first}
+field or with the use of the \idx{postlinkhook}, but the
+\idx{firstuse} might not be the most appropriate place for the
+description.
+
+\section{Listing the Terms (Glossary)}
+\label{sec:printgloss}
+
+If you want a complete list of all defined terms, you can use:
+\nosecformatdef{printunsrtglossary}
+This lists all the terms for the given glossary (identified by the
+\printglossopt{type} key in \meta{options}, see
+\sectionref{sec:multigloss}) according to the order of the
+glossary's internal list of labels, which is typically in the order of
+definition. (As each entry is defined, its label is appended to the
+internal list of the associated glossary.)
+
+You can change the default title with the \printglossopt{title} option. For
+example:
+\begin{codeenv}
+\gls{printunsrtglossary}\oarg{\printglossopt[Nomenclature]{title}}
+\end{codeenv}
+The title used in the table of contents is assumed to be the same,
+but you can change it with \printglossopt{toctitle}. For example:
+\begin{codeenv}
+\gls{printunsrtglossary}\oarg{
+ \printglossopt[List of Terms and Notation]{title},
+ \printglossopt[Notation]{toctitle}
+}
+\end{codeenv}
+
+The glossary style can be set with the \printglossopt{style} key
+in \meta{options}. Alternatively, you can set a default style with the
+\styopt{style} package option. There are many predefined styles to
+choose from (see the
+\href{https://www.dickimaw-books.com/gallery/glossaries-styles/}{\styfmt{glossaries}
+gallery}~\cite{glossarystylesgallery}). The styles are provided in supplementary packages, some
+of which are automatically loaded. Since each package adds to the
+document overhead, and some require additional packages to be
+loaded, when using \sty{glossaries-extra}, it's a good idea to
+disable the automatic loading of all styles with \styopt{nostyles}
+and then use \styopt{stylemods} to load the specific packages (along
+with the \sty{glossaries-extra-stylemods} package, which patches
+some of the predefined styles). For example, the
+\glostyle{index} style is provided by the \styfmt{glossary-tree}
+package, so \styopt[tree]{stylemods} will automatically load
+\styfmt{glossary-tree} and provide all the tree-like styles,
+including \glostyle{index}. The \styopt{stylemods} value may be a
+comma-separated list, so to load both \styfmt{glossary-tree} and
+\styfmt{glossary-long}, use \styopt[tree,long]{stylemods}.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\cmd{usepackage}\marg{\gls[noindex=false]{mhchem}}\comment{provides \gls{ce}}
+\cmd{usepackage}[\styopt[dot]{postpunc},\comment{full stop after description}
+ \styopt{nostyles},\comment{don't load default style packages}
+\comment{load glossaries-extra-stylemods.sty and glossary-tree.sty:}
+ \styopt[tree]{stylemods}
+]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area}
+}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls[noindex=false]{ce}\marg{SiO2}}
+}
+\strut
+\gls{newglossaryentry}\marg{circumference}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{C}},
+ \field{description} = \marg{circumference}
+}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name} = \marg{goose},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+webbed feet and a short broad bill}
+}
+\strut
+\gls{newglossaryentry}\marg{radius}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{r}},
+ \field{description} = \marg{radius}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{\printglossopt[index]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\glsaddeach{ex3.goose,ex3.duck,ex2.amethyst,standalone.pi,%
+standalone.circumference,standalone.area,standalone.radius}%
+\setupglossaries{toc=false,section}%
+\glossariesextrasetup{postpunc=dot}%
+\renewcommand{\glsxtrgroupfield}{useriii}%
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
+}%
+\printunsrtglossary[style=index,title=Glossary,nonumberlist,target=false]
+\end{result}
+The \glostyle{index} glossary style checks if the \field{symbol}
+field has been set. If it has, then the symbol is added in
+parentheses (as in the amethyst example). Only some of the styles
+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 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
+determined by the first character of the \field{sort} field. Since the
+default behaviour of both \sty{glossaries} and
+\sty{glossaries-extra} is to use \idx{makeindex}, the \field{sort}
+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
+heading is displayed by some styles, such as the
+\glostyle{indexgroup} style. For example, with:
+\begin{codeenv}
+\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\end{codeenv}
+The glossary is now:
+\begin{result}
+\setupglossaries{toc=false,section}%
+\glossariesextrasetup{postpunc=dot}%
+\renewcommand{\glsxtrgroupfield}{useriii}%
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
+}%
+\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
+\end{result}
+This explains why there's a gap between $A$ (area) and amethyst as
+they don't belong to the same letter group. The \field{sort} field
+for the \code{area} entry is \verb|\ensuremath{A}| which has been
+sanitized, so it starts with a literal backslash (\idx{backslashchar}).
+This means that \code{area} is assigned to the symbols letter group. The
+symbols group occurs three times, because the list is following the
+order of definition.
+
+\subsection{Groups and Locations}
+\label{sec:group}
+
+The \field{group} key isn't defined by default, but if it is defined
+then \gls{printunsrtglossary} will use the \field{group} field
+instead of trying to determine the group from the first character of
+the \field{sort} field (as in the example above). The value of the
+\field{group} field must be a label (see \sectionref{sec:labels}).
+A title may be assigned to a group with:
+\nosecformatdef{glsxtrsetgrouptitle}
+If a title hasn't been assigned, the label is used as the title.
+The above command is the preferred form, but the base
+\sty{glossaries} package checks for a control sequence in the form
+\csfmt{\meta{label}groupname} where \meta{label} is the group label.
+The \sty{glossaries-extra} package also recognises this form to
+ensure backward-compatibility. If the \field{group} field is empty
+the sub-group won't have a title.
+
+For example, the following defines the \field{group} field with a
+custom command \csfmt{grouplabel} (that's not needed, but it's
+required by the \gls{glsaddstoragekey} syntax):
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\cmd{usepackage}\marg{mhchem}
+\cmd{usepackage}[\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}
+]\marg{glossaries-extra}
+\strut
+\gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}}
+\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area},
+ \field{group} = \marg{A}
+}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
+ \field{group} = \marg{A}
+}
+\strut
+\gls{newglossaryentry}\marg{circumference}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{C}},
+ \field{description} = \marg{circumference},
+ \field{group} = \marg{C}
+}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet},
+ \field{group} = \marg{D}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name} = \marg{goose},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ \field{group} = \marg{G}
+}
+\strut
+\gls{newglossaryentry}\marg{radius}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{r}},
+ \field{description} = \marg{radius},
+ \field{group} = \marg{R}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant},
+ \field{group} = \marg{greek}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\setupglossaries{toc=false,section}%
+\glossariesextrasetup{postpunc=dot}%
+\renewcommand{\glsxtrgroupfield}{useriv}%
+\glsxtrsetgrouptitle{greek}{Greek Symbols}%
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{standalone}{}{\printunsrtglossaryskipentry}%
+}%
+\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
+\end{result}
+Note that with this method \emph{every} entry must be assigned a
+group or it will be assigned to the empty group.
+
+Similarly, if the \field{location} field is defined, you can use it
+to provide a \idx{locationlist}. The \styopt{record} package option
+conveniently defines both \field{group} and \field{location}, so the
+following can be used instead:
+\begin{codeenv}
+\cmd{usepackage}[
+ \styopt{record},\comment{provides group and location fields (and other stuff)}
+ postpunc=dot,nostyles,stylemods={tree}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area},
+ \field{group} = \marg{A},
+ \field{location} = \marg{page 1}
+}
+\end{codeenv}
+This very quickly becomes tedious and prone to errors as the entries
+have to be ordered manually, and every entry must be assigned the
+group and location (if required). Every time the location changes
+through edits to the document, the locations must be updated.
+However, this is exactly the method that \bibgls\ uses, but it does
+it automatically for you by selecting the required data from one or
+more \ext{bib} files and then creating a file containing all the
+glossary entry definitions with the fields set appropriately. The \ext{aux}
+file provides \bibgls\ with the indexing information so that it
+knows which entries to select and what the locations are, and how to
+order the definitions. See \sectionref{sec:bib2gls} for further
+information.
+
+\subsection{Homographs and Hierarchical Terms}
+\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
+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
+the parent's \field{name}.
+For example:
+\begin{codeenv}
+\comment{parent:}
+\gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}}
+\comment{children:}
+\gls{newglossaryentry}\marg{glossarycol}
+\marg{\comment{settings:}
+ \field{parent} = \marg{glossary},\comment{parent label}
+ \field{description} = \marg{collection of glosses}
+}
+\gls{newglossaryentry}\marg{glossarylist}
+\marg{\comment{settings:}
+ \field{parent} = \marg{glossary},\comment{parent label}
+ \field{description} = \marg{list of technical words}
+}
+\end{codeenv}
+In this case the entry with the label \code{glossary} is the
+\pidx{parent-entry}, and the entries with
+the labels \code{glossarycol} and \code{glossarylist} are
+\pidxpl{child-entry} (or sub-items). An entry that doesn't have a
+parent is a main or top-level or level~0 item. In this case, the
+\idxpl{child-entry} don't have the \field{name} key, so the name is
+obtained from the parent's name. This is an example of a
+\pidx{homograph}, where two words with different meanings
+have the same spelling. The parent entry has an empty description.
+
+Here's another example:
+\begin{codeenv}
+\comment{parent:}
+\gls{newglossaryentry}\marg{mineral}\comment{label}
+\marg{\comment{settings:}
+ \field{name} = \marg{mineral},
+ \field{description} = \marg{natural inorganic substance}
+}
+\comment{sub-entries:}
+\gls{newglossaryentry}\marg{quartz}\comment{label}
+\marg{
+ \field{parent} = \marg{mineral},\comment{parent label}
+ \field{name} = \marg{quartz},
+ \field{description} = \marg{hard mineral consisting of silica}
+}
+\gls{newglossaryentry}\marg{amethyst}\comment{label}
+\marg{
+ \field{parent} = \marg{quartz},\comment{parent label}
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz}
+}
+\end{codeenv}
+In this case, the \idxpl{child-entry} have the \field{name} key
+set. This is an example of a set of \pidxpl{hierarchical-entry},
+where each \idx{child-entry} is a sub-category of the parent.
+Some glossary styles are appropriate for \idxpl{homograph} and some
+are appropriate for \idxpl{hierarchical-entry} and some are only
+appropriate for flat glossaries (no child entries).
+For example, the \glostyle{index}, \glostyle{indexgroup},
+\glostyle{tree} and \glostyle{treegroup} styles are appropriate
+for \idxpl{hierarchical-entry}:
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\strut
+\cmd{usepackage}[\styopt{nostyles},\styopt[dot]{postpunc},\styopt[tree]{stylemods}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{animal}
+\marg{
+ \field{name} = \marg{animal},
+ \field{description} = \marg{living organism with a nervous system and sense organs
+ that can move independently}
+}
+\strut
+\gls{newglossaryentry}\marg{bird}
+\marg{
+ \field{parent} = \marg{animal},
+ \field{name} = \marg{bird},
+ \field{description} = \marg{warm-blooded egg-laying animal with feathers, wings
+ and a beak}
+}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{parent} = \marg{bird},
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{parent} = \marg{bird},
+ \field{name} = \marg{goose},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\strut
+\gls{newglossaryentry}\marg{mineral}
+\marg{
+ \field{name} = \marg{mineral},
+ \field{description} = \marg{natural inorganic substance}
+}
+\strut
+\gls{newglossaryentry}\marg{calcite}\comment{label}
+\marg{
+ \field{parent} = \marg{mineral},\comment{parent label}
+ \field{name} = \marg{calcite},
+ \field{description} = \marg{a carbonate mineral}
+}
+\strut
+\gls{newglossaryentry}\marg{quartz}
+\marg{
+ \field{parent} = \marg{mineral},
+ \field{name} = \marg{quartz},
+ \field{description} = \marg{hard mineral consisting of silica}
+}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{parent} = \marg{quartz},
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+}
+\strut
+\gls{newglossaryentry}\marg{citrine}
+\marg{
+ \field{parent} = \marg{quartz},
+ \field{name} = \marg{citrine},
+ \field{description} = \marg{a form of quartz with a colour ranging
+ from pale yellow to brown due to ferric impurities}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{style=indexgroup}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\glsaddeach{hier.animal,hier.bird,hier.duck,hier.goose,hier.mineral,%
+hier.calcite,hier.quartz,hier.amethyst,hier.citrine}%
+\setupglossaries{toc=false,section}%
+\glossariesextrasetup{postpunc=dot}%
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{hierarchical}{}{\printunsrtglossaryskipentry}%
+}%
+\printunsrtglossary[style=indexgroup,title=Glossary,nonumberlist,target=false]
+\end{result}
+
+The \glostyle{treenoname} and \glostyle{treenonamegroup} styles are
+appropriate for \idxpl{homograph}. These are usually best with the
+\styopt{subentrycounter} package option, which defines the
+\counter{glossarysubentry} counter that's incremented and
+displayed for every level~1 entry (that is, an entry with a parent
+but not a grandparent). If the \styopt{entrycounter} option is also
+used, \counter{glossaryentry} is set as the master counter for
+\counter{glossarysubentry} (although it's not included in the
+display form of that counter), but \styopt{subentrycounter} may be used
+without \styopt{entrycounter}, in which case
+\counter{glossarysubentry} has no master counter. If
+\styopt{subentrycounter} is used as a package option and
+\styopt{entrycounter} is later switched on outside of the package
+option list (through \gls{setupglossaries} or in the optional argument of
+\gls{printunsrtglossary}) then it won't be made the master counter.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\strut
+\cmd{usepackage}[\styopt{subentrycounter},\comment{create glossarysubentry counter}
+ \styopt[dot]{postpunc},\comment{append full stop after description}
+ \styopt{nostyles},\styopt[tree]{stylemods}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{bow1}
+\marg{
+ \field{name}=\marg{bow},
+ \field{description}=\marg{(rhymes with toe)}
+}
+\strut
+\gls{newglossaryentry}\marg{bowknot}
+\marg{
+ \field{parent} = \marg{bow1},
+ \field{description} = \marg{a knot tied with two loops and loose ends}
+}
+\strut
+\gls{newglossaryentry}\marg{bowweapon}
+\marg{
+ \field{parent} = \marg{bow1},
+ \field{description} = \marg{a weapon for shooting arrows, made of curved wood
+ joined at both ends with taut string}
+}
+\strut
+\gls{newglossaryentry}\marg{bow2}
+\marg{
+ \field{name}=\marg{bow},
+ \field{description}=\marg{(rhymes with cow)}
+}
+\strut
+\gls{newglossaryentry}\marg{bowbend}
+\marg{
+ \field{parent} = \marg{bow2},
+ \field{description} = \marg{bend head or upper body}
+}
+\strut
+\gls{newglossaryentry}\marg{bowpressure}
+\marg{
+ \field{parent} = \marg{bow2},
+ \field{description} = \marg{give in to pressure}
+}
+\strut
+\gls{newglossaryentry}\marg{bow3}
+\marg{
+ \field{name}=\marg{bow},
+ \field{description}=\marg{(also bows) the front end of a ship}
+}
+\strut
+\gls{newglossaryentry}\marg{glossary}\marg{\field{name}=\marg{glossary},\field{description}=\marg{}}
+\strut
+\gls{newglossaryentry}\marg{glossarycol}
+\marg{
+ \field{parent} = \marg{glossary},
+ \field{description} = \marg{collection of glosses}
+}
+\strut
+\gls{newglossaryentry}\marg{glossarylist}
+\marg{
+ \field{parent} = \marg{glossary},
+ \field{description} = \marg{list of technical words}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{style=treenoname}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces
+\begin{result}
+\glsaddeach{hom.bow1,hom.bowknot,hom.bowweapon,%
+hom.bow2,hom.bowbend,hom.bowpressure,hom.bow3,%
+hom.glossary,hom.glossarycol,hom.glossarylist}%
+\setupglossaries{toc=false,section,subentrycounter}%
+\glossariesextrasetup{postpunc=dot}%
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{homograph}{}{\printunsrtglossaryskipentry}%
+}%
+\printunsrtglossary[style=treenoname,title=Glossary,nonumberlist,target=false]
+\end{result}
+The empty description for the top-level \code{glossary} entry has
+caused an odd effect with a space occurring between the name and the
+post-description punctuation. This can be removed by redefining:
+\nosecformatdef{glstreenonamedesc}
+so that it checks if the \field{description} field has been set with:
+\nosecformatdef{ifglshasdesc}
+For example:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\gls{glstreenonamedesc}}[1]\marg{\comment{}
+ \gls{ifglshasdesc}\marg{\gls{param}1}
+ \marg{\gls[noindex=false]{glstreepredesc}\gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}}
+ \marg{}\comment{do nothing, description field is empty}
+}
+\end{codeenv}
+Another variation is to check if the entry has children add use a
+colon instead of a \idx{full-stop}. The base \sty{glossaries}
+package provides:
+\nosecformatdef{ifglshaschildren}
+However this method is very inefficient as it has to iterate over
+all defined entries and check if any have the \field{parent} field
+set to \meta{entry label}. A more efficient method can be obtained
+with \bibgls\ and the \csopt{save-child-count} resource option,
+which will save the number of child entries that have been indexed
+in an internal field labelled \field{childcount} and a list of child
+entry labels is stored in the internal field labelled
+\field{childlist}. In this case, a more efficient method is to use:
+\nosecformatdef{GlsXtrIfHasNonZeroChildCount}
+which checks the \field{childcount} field for a non-zero value.
+If you don't use \bibgls, this command will always do \meta{false}
+(unless you explicitly set the internal fields to the correct
+values, which is tedious and has to be updated whenever
+definitions are added, deleted or have the \field{parent} field
+changed).
+
+Another variation could use custom fields (see
+\sectionref{sec:userkeys}) to store the pronunciation guide (\qt{rhymes
+with \ldots}) and the alternative version (\qt{also \ldots}) as well
+as other information, such as whether the word is a noun or verb.
+
+\subsection{Multiple Glossaries}
+\label{sec:multigloss}
+
+The default glossary has the label \code{main}, but it can also be referenced
+with:
+\nosecformatdef{glsdefaulttype}
+The \styopt{nomain} package option suppresses the creation of the
+\code{main} glossary, in which case \gls{glsdefaulttype} will be set to
+the first glossary to be defined. (There must be at least one
+glossary defined, so if you use \styopt{nomain} you must provide
+another default.) If you use the \styopt{entrycounter} package
+option, the associated counter isn't reset at the start of the
+glossary. If you have multiple glossaries and you need it to be reset, add:
+\nosecformatdef{glsresetentrycounter}
+before the start of the appropriate glossary.
+
+Abbreviations defined with \gls{newabbreviation}
+(see \sectionref{sec:abbreviations}) are, by default, assigned to the glossary
+given by:
+\nosecformatdef{glsxtrabbrvtype}
+This initially expands to \gls{glsdefaulttype}, but the
+\styopt{abbreviations} option redefines this to \code{abbreviations}
+and creates a glossary with that label.
+
+Abbreviations defined with \gls{newacronym} are, by default,
+assigned to the glossary given by:
+\nosecformatdef{acronymtype}
+This initially expands to \gls{glsdefaulttype}, but the
+\styopt{abbreviations} option redefines this to
+\gls{glsxtrabbrvtype}. However, the \styopt{acronyms} option
+redefines \gls{acronymtype} to \code{acronym} and creates a glossary
+with that label. So if you use both the \styopt{abbreviations} and
+\styopt{acronyms} package options, you will have two extra
+glossaries created, one as the default for \gls{newabbreviation} and
+the other as the default for \gls{newacronym}.
+
+The \styopt{symbols} package option creates a glossary with the
+label \code{symbols} and defines \gls{glsxtrnewsymbol} (see
+\sectionref{sec:symbols}) which sets the \field{type} to
+\code{symbols}. There are also similar package options
+\styopt{numbers} and \styopt{index}, which create the \code{numbers}
+glossary (and \gls{glsxtrnewnumber}) and the \code{index} glossary
+(and \gls{newterm}).
+
+In each case, the default type can be overridden when defining an
+entry by using the \field{type} key in the assignment list. The
+value must be the label identifying a defined glossary.
+
+You can provide your own custom glossary using:
+\nosecformatdef{newglossary*}
+where \meta{type} is the label used to identify the glossary and
+\meta{title} is the default title used by \gls{printunsrtglossary}.
+(The unstarred version has a different syntax and is only applicable
+with \gls{makeindex} or \gls{xindy}.) For example:
+\begin{codeenv}
+\gls{newglossary*}\marg{measurements}\marg{SI Units}
+\gls{newglossaryentry}\marg{length}
+\marg{\comment{settings:}
+ \field{name} = \marg{\gls{si}\marg{\cmd{metre}}},
+ \field{description} = \marg{length},
+ \field{type} = \marg{measurements}\comment{glossary label}
+}
+\end{codeenv}
+In this case, the label identifying the new glossary is
+\code{measurements} and the title is \qt{SI Units}.
+
+You can specify the glossary using the \printglossopt{type} setting
+in the optional argument of \gls{printunsrtglossary}. For example,
+the above \code{measurements} glossary can be displayed with:
+\begin{codeenv}
+\gls{printunsrtglossary}\oarg{\printglossopt[measurements]{type}}
+\end{codeenv}
+For convenience, there's a command that iterates over all defined
+glossaries (in the order of definition) and does
+\gls{printunsrtglossary}\oarg{\printglossopt[\meta{label}]{type}}
+for each glossary:
+\nosecformatdef{printunsrtglossaries}
+There's no optional argument for this command. When creating
+glossaries with package options, such as \styopt{abbreviations}, you
+may find an unexpected order as the options aren't always processed
+in the order in which they were specified. (Some
+\sty{glossaries-extra} options are passed to the base
+\sty{glossaries} package and are processed when that package is
+internally loaded not when the extension options are processed.) In
+which case you need to use \gls{printunsrtglossary} for each
+glossary in the required order. You will also need to do this if the
+glossary settings are different. (For example, if one glossary needs
+to use the \glostyle{tree} style and another needs to use the
+\glostyle{treenoname} style.)
+
+You can also define an \pidx{ignoredglossary}, which is ignored by
+\gls{printunsrtglossaries}. This is a useful way of creating a
+glossary for common terms that shouldn't appear in a list or for
+stand-alone entries (see \sectionref{sec:standalone}). The unstarred
+form:
+\nosecformatdef{newignoredglossary}
+is useful for common terms where the list won't be displayed as it
+automatically suppresses hyperlinks for entries assigned to that
+glossary. The starred form:
+\nosecformatdef{newignoredglossary*}
+is useful for stand-alone entries as it doesn't automatically
+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.
+
+\subsection{Redisplaying or Filtering a Glossary}
+\label{sec:printglossagain}
+
+It's possible to use \gls{printunsrtglossary} multiple times for the
+same glossary, but if you have hyperlinks you will need to either
+suppress the targets with \printglossopt[false]{target} or change
+the target name (see \sectionref{sec:targetnames}).
+
+The starred form of \gls{printunsrtglossary} has an extra
+argument:
+\nosecformatdef{printunsrtglossary*}
+This may be used to make local assignments. It's equivalent to:
+\begin{codeenv}
+\cmd{begingroup} \meta{code}\gls{printunsrtglossary}\oargm{options}\cmd{endgroup}
+\end{codeenv}
+For example, if the \field{group} key has been defined (see
+\sectionref{sec:group}) you can locally switch to a different field
+for the group label by redefining:
+\nosecformatdef{glsxtrgroupfield}
+within \meta{code}.
+For example, if the \field{secondarygroup} field has been defined:
+\begin{codeenv}
+\gls{printunsrtglossary*}\marg{\comment{}
+ \cmd{renewcommand}\marg{\gls{glsxtrgroupfield}}\marg{secondarygroup}\comment{}
+}
+\end{codeenv}
+Note that this just changes the group labels. The order is still
+according to the glossary's internal list of labels.
+
+Unlike \gls{printglossary} (used with \gls{makeindex} and
+\gls{xindy}) which inputs a file containing the code to typeset the glossary,
+\gls{printunsrtglossary} iterates over the labels defined in the
+given glossary and adds the appropriate code to an internal command.
+Once the construction of the internal command is completed, it's
+then performed. (The construction of this internal command is done
+to avoid complications when iterating within \env{tabular}-like
+environments, as some of the styles use \env{longtable} or
+\env{supertabular}.) There's a hook just before the internal command is
+expanded:
+\nosecformatdef{printunsrtglossarypredoglossary}
+The glossary header and preamble are displayed before
+the loop starts, so this hook won't change them (but you can make
+local changes in \meta{code} outside of the hook).
+The style is also set before the loop, but the start
+and end of the \env{theglossary} environment (which is defined by
+the glossary styles) is included in the internal command, so minor
+adjustments to the style can be made in this hook.
+
+There's another hook that's performed at each iteration:
+\nosecformatdef{printunsrtglossaryentryprocesshook}
+where \meta{label} is the current entry label. For example, the
+\glostyle{alttree} style needs to know the widest entry name in
+order to set up the correct indentation. The widest name is set
+using:
+\nosecformatdef{glssetwidest}
+but this requires knowing which entry has the widest name. There are
+some commands provided by the \sty{glossary-tree} and
+\sty{glossaries-extra-stylemods} packages that iterate over all
+entries, measuring each name, in order to find the widest, but since
+\gls{printunsrtglossary} already has to iterate over the list before
+typesetting it, this hook can be used to update the widest name at
+the same time. You can update the value with:
+\nosecformatdef{glsupdatewidest}
+which computes the width of \meta{text} and, if it's wider than the
+current widest name for the given level, sets the widest value to
+\meta{text} (without expanding it). If \meta{text} needs expanding
+you need to use:
+\nosecformatdef{eglsupdatewidest}
+The \meta{level} refers to the entry's hierarchical level with a
+value of~0 indicating top-level (that is, an entry without a parent).
+The level is stored in the internal \field{level} field and can only
+be accessed with \gls{glsxtrusefield} or similar commands
+(see \sectionref{sec:userkeys}).
+
+You can also redefine this hook to filter the glossary list.
+If an entry shouldn't appear in the list, use:
+\nosecformatdef{printunsrtglossaryskipentry}
+For example, to only include entries that have the \field{category}
+set to \code{formula}:
+\begin{codeenv}
+\gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}}
+\marg{\comment{local code:}
+ \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{}
+ \gls{glsifcategory}\marg{\gls{param}1}\marg{formula}
+ \marg{}\comment{category = formula}
+ \marg{\gls{printunsrtglossaryskipentry}}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+This uses \gls{glsifcategory} to check the value of the entry's
+\field{category} field (see \sectionref{sec:categories}). Another
+conditional you might find useful is:
+\nosecformatdef{glsxtriflabelinlist}
+which tests if the given \meta{label} is in the comma-separated
+\meta{list} of labels. Both \meta{label} and \meta{list} are fully
+expanded before testing. This command is only intended for labels,
+which must be fully expandable.
+For example, the following excludes any entries that have the
+\field{category} set to \code{abbreviation} or \code{acronym}:
+\begin{codeenv}
+\gls{printunsrtglossary*}\oarg{\printglossopt{target}=false,\printglossopt{title}=\marg{Formula}}
+\marg{\comment{local code:}
+ \cmd{renewcommand}\marg{\gls{printunsrtglossaryentryprocesshook}}[1]\marg{\comment{}
+ \gls{glsxtriflabelinlist}
+ \marg{\gls{glscategory}\marg{\gls{param}1}}\comment{category label for this entry}
+ \marg{abbreviation,acronym}\comment{exclusion list}
+ \marg{\gls{printunsrtglossaryskipentry}}\comment{skip (exclude)}
+ \marg{}\comment{don't skip (include)}
+ }\comment{}
+}
+\end{codeenv}
+
+\subsection{Hyperlink Targets}
+\label{sec:targetnames}
+
+The naming system used for the hyperlinks from commands like
+\gls{gls} and \gls{glssymbol} to the corresponding definition in the
+glossary is given by \meta{prefix}\meta{label} where \meta{label} is
+the entry's label and \meta{prefix} is given by:
+\nosecformatdef{glolinkprefix}
+This can locally be changed within commands like \gls{gls} and
+\gls{glssymbol} with the \glsopt{prefix} option. There is a matching
+\printglossopt{prefix} option for \gls{printunsrtglossary}.
+You can set an additional prefix in the glossary with
+\printglossopt[\meta{extra}]{targetnameprefix}, which means that the
+target name in the glossary is now
+\code{\meta{extra}\gls{glolinkprefix}\meta{label}} (so
+\printglossopt{targetnameprefix} doesn't modify \gls{glolinkprefix}
+but prepends an extra prefix).
+
+If you change the prefix either by using the above options or by
+redefining \gls{glolinkprefix}, you need to make sure that the
+target names match for the links to work correctly.
+The \styopt[showtargets]{debug} package option can be used to show
+the target names in the document. The target is displayed in the
+document using:
+\nosecformatdef{glsshowtarget}
+which may be redefined as appropriate. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{hyperref}
+\cmd{usepackage}[\styopt{debug}=showtargets]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}}
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\oarg{\glsopt{prefix}=\marg{TARGET.}}\marg{sample}.
+\strut
+\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.}}
+\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{TARGET.},\printglossopt{targetnameprefix}=\marg{EXTRA.}}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+\section{Stand-alone Definitions}
+\label{sec:standalone}
+
+The \sty{glossaries-extra} package provides:
+\nosecformatdef{glsxtrglossentry}
+which may be used to create a target for a particular entry (identified by
+\meta{label}). This displays the value of the \field{name} field,
+but it also obeys the \idx{postnamehook} (see
+\sectionref{sec:postfieldhooks}), the \catattr{glossname}
+and \catattr{glossnamefont} attributes (see
+\sectionref{sec:glossname}), and provides accessibility support if
+the \field{access} field is set (see \sectionref{sec:accsupp}).
+This command may be used for both top-level and child entries, and
+will obey the \styopt{entrycounter} (see below) and \styopt{subentrycounter}
+(see \sectionref{sec:parent}) package options according to the
+entry's hierarchical level.
+
+This command doesn't display any of the other field values.
+If any are required, you need to add them afterwards.
+For the description, you can use \gls{glsentrydesc}, but it's better
+to use:
+\nosecformatdef{glossentrydesc}
+Unlike \gls{glsentrydesc}, which just displays the value of the
+\field{description} field, \gls{glossentrydesc} obeys the
+\catattr{glossdesc} and \catattr{glossdescfont} attributes
+(\sectionref{sec:glossname}). Alternatively, you can use:
+\nosecformatdef{Glossentrydesc}
+which converts the first letter of the description to
+\idx{uppercase}.
+To pick up the \styopt{postpunc} setting and the
+\glslink{postdescriptionhook}{post-description category hook},
+append \gls{glspostdescription}
+after the description (see \sectionref{sec:postfieldhooks}).
+
+There's a similar command for symbols:
+\nosecformatdef{glossentrysymbol}
+There are currently no category attributes governing this
+command, but it does check for the \field{symbolaccess} field if
+accessibility support has been added (see \sectionref{sec:accsupp}).
+For other fields, you can use the commands described in
+\sectionref{sec:userkeys}.
+
+If you need to substitute the \field{name} for another field in the
+target, you can use:
+\nosecformatdef{glsxtrglossentryother}
+instead of \code{\gls{glsxtrglossentry}\margm{label}},
+where \meta{label} identifies the entry and \meta{field} is the
+internal field label to use instead of the \field{name}. The
+\meta{header} argument is the code to use in the header (which
+should be left empty for the default value\footnote{The
+\meta{header} argument doesn't use standard \LaTeX\ optional syntax
+\code{\oargm{option}} because \gls{glsxtrglossentryother} has to be
+expandable in order for it to work correctly in section arguments.})\ if
+\gls{glsxtrglossentryother} is used in a sectioning command. This
+command obeys the \catattr{glossname} and \catattr{glossnamefont}
+attributes and the \idx{postnamehook}, even though it's not actually
+displaying the name. For example,
+\begin{codeenv}
+\cmd{section}\marg{\gls{glsxtrglossentryother}\marg{}\marg{duck}\marg{\field{plural}}}
+\end{codeenv}
+
+Here's a complete example that uses \gls{glsxtrglossentry} after an
+equation to describe the notation:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{\gls[noindex=false]{xcolor}}\comment{provides colour}
+\cmd{usepackage}[colorlinks,linkcolor=purple]\marg{\gls[noindex=false]{hyperref}}
+\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\gls{newglossaryentry}\marg{radius}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{r}},
+ \field{description} = \marg{radius}
+}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area}
+}
+\strut
+\cmd{begin}\marg{document}
+\cmd{begin}\marg{equation}
+\gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2]
+\cmd{end}\marg{equation}
+\cmd{begin}\marg{tabular}\marg{ll}
+\gls{glsxtrglossentry}\marg{area} \gls[noindex=false]{colsep} \gls{glossentrydesc}\marg{area}\gls{glspostdescription}\gls[noindex=false]{cs.backslash}
+\gls{glsxtrglossentry}\marg{pi} \gls{colsep} \gls{glossentrydesc}\marg{pi}\gls{glspostdescription}\gls{cs.backslash}
+\gls{glsxtrglossentry}\marg{radius} \gls{colsep} \gls{glossentrydesc}\marg{radius}\gls{glspostdescription}
+\cmd{end}\marg{tabular}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\setcounter{equation}{0}%
+\renewcommand{\theequation}{\arabic{equation}}%
+\renewcommand{\theHequation}{\thechapter.standalone1.\arabic{equation}}%
+\renewcommand{\glolinkprefix}{standalone1}%
+\renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}%
+\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}%
+\glossariesextrasetup{postdot}%
+\begin{equation}
+\gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2]
+\end{equation}
+\begin{tabular}{ll}
+\glsxtrglossentry{standalone.area} & \glossentrydesc{standalone.area}\glspostdescription\\
+\glsxtrglossentry{standalone.pi} & \glossentrydesc{standalone.pi}\glspostdescription\\
+\glsxtrglossentry{standalone.radius} & \glossentrydesc{standalone.radius}\glspostdescription
+\end{tabular}
+\end{result}
+The purple text shows the hyperlinks to the relevant definition. As
+with \gls{printunsrtglossary}, the hypertargets are prefixed with
+\gls{glolinkprefix} (see \sectionref{sec:printglossagain}). This
+can be locally changed to avoid clashes if the definition needs to
+be reproduced later.
+
+A more convenient approach to the above is to define an environment that can
+list all the referenced entries automatically. The
+\sty{glossaries-extra} package provides a way of buffering the
+boolean switch performed by \gls{gls} that ensures that the
+\idx{firstuseflag} is unset (see \sectionref{sec:buffering}).
+This is intended for use where the switch causes a problem, but it
+can also be used in this case to store a list of used entries (since
+there's no difference between \idx{firstuse} and subsequent use in
+this case, it won't affect the \idx{link-text}).
+
+Here's a modified version of the above document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{xcolor}
+\cmd{usepackage}[colorlinks,linkcolor=purple]\marg{hyperref}
+\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\gls{newglossaryentry}\marg{radius}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{r}},
+ \field{description} = \marg{radius}
+}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area}
+}
+\strut
+\gls{newglossaryentry}\marg{circumference}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{C}},
+ \field{description} = \marg{circumference}
+}
+\strut
+\cmd{newcommand}\marg{\cmd{doglossaryentry}}[1]\marg{\comment{handler macro}
+ \gls{glsxtrglossentry}\marg{\gls{param}1} \gls{colsep} \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\gls{cs.backslash}\comment{}
+}
+\strut
+\cmd{newcounter}\marg{localglossary}
+\strut
+\cmd{newenvironment}\marg{localglossary}
+\marg{\comment{}
+ \cmd{stepcounter}\marg{localglossary}\comment{}
+ \cmd{renewcommand}\marg{\gls{glolinkprefix}}\marg{\cmd{thelocalglossary}.}\comment{}
+ \gls{GlsXtrStartUnsetBuffering}*
+}
+\marg{\comment{}
+ \cmd{par}
+ \cmd{begin}\marg{tabular}\marg{ll}
+ \gls{GlsXtrForUnsetBufferedList}\cmd{doglossaryentry}
+ \cmd{end}\marg{tabular}
+ \gls{GlsXtrStopUnsetBuffering}
+ \cmd{par}
+}
+\strut
+\cmd{begin}\marg{document}
+The area of a circle is given by:
+\cmd{begin}\marg{localglossary}
+\cmd{begin}\marg{equation}
+\gls{gls}\marg{area} = \gls{gls}\marg{pi}\gls{gls}\marg{radius}[\gls{spchar}2]
+\cmd{end}\marg{equation}
+\cmd{end}\marg{localglossary}
+The circumference of a circle is given by:
+\cmd{begin}\marg{localglossary}
+\cmd{begin}\marg{equation}
+\gls{gls}\marg{circumference} = 2\gls{gls}\marg{pi}\gls{gls}\marg{radius}
+\cmd{end}\marg{equation}
+\cmd{end}\marg{localglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\setcounter{equation}{0}%
+\renewcommand{\theequation}{\arabic{equation}}%
+\renewcommand{\theHequation}{\thechapter.standalone2.\arabic{equation}}%
+\renewcommand{\glolinkprefix}{standalone2}%
+\renewcommand{\glstextformat}[1]{\textcolor{purple}{#1}}%
+\renewcommand{\glslinkpresetkeys}{}%
+\glossariesextrasetup{postdot}%
+The area of a circle is given by:
+\begin{localglossary}
+\begin{equation}
+\gls{standalone.area} = \gls{standalone.pi}\gls{standalone.radius}[^2]
+\end{equation}
+\end{localglossary}
+The circumference of a circle is given by:
+\begin{localglossary}
+\begin{equation}
+\gls{standalone.circumference} = 2\gls{standalone.pi}\gls{standalone.radius}
+\end{equation}
+\end{localglossary}
+\end{result}
+The custom \counterfmt{localglossary} counter is defined and incremented to
+ensure that the target prefix \gls{glolinkprefix} is unique for each
+environment. This definition of the custom \envfmt{localglossary}
+environment is intentionally kept trivial since the main point here is
+the demonstration of \gls{glsxtrglossentry} and the buffering rather
+than the actual formatting of the entries. Additional vertical
+spacing, appropriate alignment and a paragraph column specifier are
+left as an exercise for the reader.
+
+\subsection{Numbering Top-Level Entries}
+\label{sec:entrycounter}
+
+The \styopt{entrycounter} package option creates a new counter
+called \counter{glossaryentry}, which will automatically be
+incremented and displayed at the start of \gls{glsxtrglossentry}
+for top-level entries. (The \counter{glossarysubentry} counter created with the
+\styopt{subentrycounter} option, described in \sectionref{sec:parent},
+may be used independently of the \styopt{entrycounter} package option.) In
+the above example, this counter will need to depend on the custom
+\counterfmt{localglossary} counter to ensure that it's reset at the
+start of each \envfmt{localglossary} environment. This can easily be
+done by using the name of the master counter as the value of
+\styopt{counterwithin} (which automatically implements
+\styopt{entrycounter}), but the master counter must be defined
+first:
+\begin{codeenv}
+\cmd{newcounter}\marg{localglossary}
+\cmd{usepackage}[\styopt[localglossary]{counterwithin}]\marg{glossaries-extra}
+\end{codeenv}
+The default definition of \gls{theHglossaryentry} is:
+\begin{codeenv}
+\gls{currentglossary}.\gls[noindex=false]{theglossaryentry}
+\end{codeenv}
+The prefix \gls{currentglossary} is set by both
+\gls{printunsrtglossary} and \gls{glsxtrglossentry} to the current
+glossary label (given by the \printglossopt{type} option in
+\gls{printunsrtglossary} and by the entry's \field{type} field for
+\gls{glsxtrglossentry}). In the case of \gls{glsxtrglossentry}
+(and \gls{glsxtrglossentryother}), the value of
+\gls{currentglossary} is obtained from:
+\nosecformatdef{GlsXtrStandaloneGlossaryType}
+which defaults to the value of the \field{type} field for the
+current entry.
+
+Since this example is using multiple stand-alone definitions that
+may repeat the same entry, this definition isn't appropriate and will
+cause duplicate destination warnings. The simplest solution is to redefine
+\gls{GlsXtrStandaloneGlossaryType} in terms of the custom
+\counterfmt{localglossary} counter value:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\cmd{GlsXtrStandaloneGlossaryType}}\marg{\comment{}
+ standalone.\cmd{thelocalglossary}.\cmd{arabic}\marg{\counter{glossaryentry}}\comment{}
+}
+\end{codeenv}
+
+Unlike commands such as \gls{gls}, which can be problematic in moving
+arguments, \gls{glsxtrglossentry} is designed to work in section
+headings. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{mhchem}
+\cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref}
+\cmd{usepackage}[\styopt[dot]{postpunc}]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
+ \field{category} = \marg{mineral}
+}
+\strut
+\gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc}
+\strut
+\cmd{newcommand}\marg{\cmd{displayterm}}[1]\marg{\comment{}
+ \cmd{subsection}\marg{\gls{glsxtrglossentry}\marg{\gls{param}1}}\comment{}
+ Chemical formula: \gls{glossentrysymbol}\marg{\gls{param}1}.
+ \gls{Glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par}
+}
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\cmd{section}\marg{Types of Quartz}
+A reference to \gls{gls}\marg{amethyst}.
+\strut
+\cmd{displayterm}\marg{amethyst}
+\cmd{end}\marg{document}
+\end{codeenv}
+(Again, improvements to the actual formatting of the custom
+\csfmt{displayterm} is left as an exercise to the reader. Additional
+fields could contain, for example, the name of an image file to
+illustrated the entry. See the
+\href{https://www.dickimaw-books.com/gallery/}{\styfmt{glossaries}
+gallery}~\cite{gallery} for further ideas.)
+
+The above example uses the \catattr{glossname} attribute to convert the first
+letter of the \field{name} to \idx{uppercase}. Unfortunately this can't be
+applied to the PDF bookmark or table of contents. A solution to this
+would be to explicitly set the \field{name} with the first letter as
+an \idx{uppercase} character and the \field{text} field in
+\idx{lowercase}. For example:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{Amethyst},
+ \field{text} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
+ \field{category} = \marg{mineral}
+}
+\end{codeenv}
+The \catattr{glossname} attribute can then be omitted. This is a bit
+inconvenient, but if you use \bibgls\ (see \sectionref{sec:bib2gls})
+this can be performed automatically with the
+\csopt{name-case-change} resource option.
+
+\subsection{Stand-alone Hierarchical Entries}
+\label{sec:standalonehierarchy}
+
+Sub-entries can also be displayed with \gls{glsxtrglossentry} or
+\gls{glsxtrglossentryother}. These check if the entry has a parent
+(with \gls{ifglshasparent}). If it doesn't, then it will display
+the \counter{glossaryentry} counter label if the
+\styopt{entrycounter} package option has been used. If the entry
+does have a parent, it uses:
+\nosecformatdef{GlsXtrStandaloneSubEntryItem}
+which checks the internal \field{level} field to
+determine the hierarchical level. If the \field{level} is~1 (that
+is, the entry has a parent but not a grandparent) then it will
+display the \counter{glossarysubentry} label if that counter has
+been defined, otherwise it does nothing.
+
+Here's an example document with a top-level entry (\code{mineral}),
+a level~1 entry (\code{quartz}) and a level~2 entry (\code{amethyst}).
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{xcolor}\comment{provides colour}
+\cmd{usepackage}[colorlinks,linkcolor=magenta]\marg{hyperref}
+\cmd{usepackage}[
+ \styopt{entrycounter},\comment{enable top-level counter}
+ \styopt{subentrycounter},\comment{enable level 1 counter}
+ \styopt{postpunc}=\marg{dot},\comment{put full-stop after description}
+ \styopt{nostyles},\comment{suppress automatic loading of default styles}
+ \styopt[tree]{stylemods}\comment{load glossary-tree.sty}
+]\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{mineral}
+\marg{
+ \field{name} = \marg{mineral},
+ \field{description} = \marg{natural inorganic substance},
+ \field{category} = \marg{mineral}
+}
+\strut
+\gls{newglossaryentry}\marg{calcite}
+\marg{
+ \field{parent} = \marg{mineral},
+ \field{name} = \marg{calcite},
+ \field{description} = \marg{a carbonate mineral},
+ \field{category} = \marg{mineral}
+}
+\strut
+\gls{newglossaryentry}\marg{quartz}
+\marg{
+ \field{parent} = \marg{mineral},
+ \field{name} = \marg{quartz},
+ \field{description} = \marg{hard mineral consisting of silica},
+ \field{category} = \marg{mineral}
+}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{parent} = \marg{quartz},
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{category} = \marg{mineral}
+}
+\strut
+\gls{glssetcategoryattribute}\marg{mineral}\marg{glossname}\marg{firstuc}
+\strut
+\cmd{renewcommand}\marg{\gls[noindex=false]{GlsXtrStandaloneGlossaryType}}\marg{standalone}
+\strut
+\cmd{newcommand}\marg{\cmd{displayterm}}\oarg{1}\marg{\comment{}
+ \cmd{par}
+ Definition \gls{glsxtrglossentry}\marg{\gls{param}1}:
+ \gls{glossentrydesc}\marg{\gls{param}1}\gls{glspostdescription}\cmd{par}
+}
+\strut
+\cmd{begin}\marg{document}
+\cmd{displayterm}\marg{mineral}
+\cmd{displayterm}\marg{calcite}
+\cmd{displayterm}\marg{quartz}
+\cmd{displayterm}\marg{amethyst}
+\strut
+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-}
+\gls{glsresetentrycounter}
+\gls{printunsrtglossary}\oarg{\printglossopt{prefix}=\marg{main.},\printglossopt{style}=tree}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{local}}%
+\def\glolinkprefix{standalone.hier.}%
+\renewcommand{\glstextformat}[1]{\textcolor{magenta}{#1}}%
+\setupglossaries{entrycounter,subentrycounter,section,toc=false}%
+\glossariesextrasetup{postdot}%
+\glssetcategoryattribute{hierarchical}{glossname}{firstuc}%
+\renewcommand{\GlsXtrStandaloneGlossaryType}{standalone}%
+\newcommand{\displayterm}[1]{%
+ \par
+ \begingroup
+ Definition \glsxtrglossentry{#1}:
+ \glossentrydesc{#1}\glspostdescription\par
+ \endgroup
+}%
+\displayterm{hier.mineral}
+\displayterm{hier.calcite}
+\displayterm{hier.quartz}
+\displayterm{hier.amethyst}
+
+A reference to \gls{hier.mineral}.
+A reference to \gls[prefix={hierarchical.main.}]{hier.amethyst}.
+
+\printunsrtglossary*[prefix={hierarchical.main.},style=tree,nonumberlist]
+{%
+ \glsresetentrycounter
+ \renewcommand{\GlsEntryCounterLabelPrefix}{hierarchical.main.glsentry-}%
+ \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsxtriflabelinlist{#1}{hier.mineral,hier.calcite,hier.quartz,hier.amethyst}%
+ {}{\printunsrtglossaryskipentry}%
+ }%
+}
+\end{result}
+Note the need to reset the \counter{glossaryentry} counter with
+\gls{glsresetentrycounter} before the main glossary. The top-level
+entry (\code{mineral}) has the label formatted as
+\qt{1.\textvisiblespace} and the level~1 entries (\code{calcite}
+and \code{quartz}) have their labels formatted as
+\qt{1)\textvisiblespace} and \qt{2)\textvisiblespace} but the
+level~2 entry (\code{amethyst}) doesn't have an associated number.
+If you want to number levels deeper than 1, you will have to provide
+your own custom counters. (If the stand-alone level~2 entry shows a
+number when you try this, then you've encountered a bug that's been
+fixed in \sty{glossaries-extra} version~1.31.)
+
+The hyperlinks are shown in magenta. The first (\code{mineral}) links to the
+stand-alone target, and the second (\code{amethyst}) links to the entry in
+the main glossary.
+
+\chapter{Changing the Formatting}
+\label{sec:glsformats}
+
+All commands like \gls{gls} and \gls{glssymbol} by default
+encapsulate the \idx{link-text} within the argument of:
+\nosecformatdef{glstextformat}
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{xcolor}\comment{provides colour}
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls[noindex=false]{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
+\strut
+\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
+\gls{glsentrydesc}\marg{fleuron}) and \gls{gls}\marg{tug}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}%
+\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
+A \gls{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
+\glsentrydesc{ex.fleuron}) and \gls{TUG}.
+\end{result}
+Note that this has affected \gls{gls} and \gls{glssymbol} but not
+\gls{glsentrydesc}.
+
+A distinction can be made between abbreviations (\idx{non-regular}
+terms) and \idx{regular} terms (non-abbreviations or abbreviations
+that are considered \idx{regular} entries).
+A \idx{regular} term is encapsulated with
+\nosecformatdef{glsxtrregularfont}
+and an abbreviation is encapsulated with
+\nosecformatdef{glsxtrabbreviationfont}
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{xcolor}\comment{provides colour}
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
+\gls{newacronym}\marg{ascii}\marg{ASCII}\marg{American Standard Code for
+Information Interchange}
+\strut
+\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
+\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}}
+\cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{emph}\marg{\gls{param}1}}
+\strut
+\cmd{begin}\marg{document}
+Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
+\gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This now produces:
+\begin{result}%
+\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
+\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
+\renewcommand{\glsxtrabbreviationfont}[1]{\emph{#1}}%
+Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
+\glsentrydesc{ex.fleuron}), \gls{TUG} and \gls{ASCII}.
+\end{result}
+Note the difference between the abbreviation defined with
+\gls{newabbreviation} and the one defined with \gls{newacronym}.
+The above example document is using the default styles, which is
+\abbrstyle{long-short} for the \code{abbreviation} category
+and \abbrstyle{short-nolong} for the \code{acronym} category.
+The \abbrstyle{short-nolong} style makes the abbreviation behave
+like a \idx{regular} entry and so it's governed by \gls{glsxtrregularfont}
+not by \gls{glsxtrabbreviationfont}.
+
+The \gls{glstextformat} command is overridden by the
+\catattr{textformat} attribute. The value of this attribute must be
+the name (without the leading backslash) of a command that takes a
+single argument, which will be used instead of \gls{glstextformat}
+for any entry that has this attribute set for its category.
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{xcolor}\comment{provides colour}
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\cmd{newcommand}\marg{\cmd{ornamentfmt}}[1]\marg{\cmd{textcolor}\marg{cyan}\marg{\gls{param}1}}
+\strut
+\gls{glssetcategoryattribute}\marg{ornament}\marg{\catattr{textformat}}\marg{ornamentfmt}
+\strut
+\gls{setabbreviationstyle}\marg{\abbrstyle[noindex=false]{long-short-em}}
+\gls{setabbreviationstyle}\oarg{acronym}\marg{\abbrstyle[noindex=false]{short-sc-nolong}}
+\strut
+\gls{newglossaryentry}\marg{duck}\comment{label}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet}
+}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newabbreviation}\marg{tug}\marg{TUG}\marg{\cmd{TeX}\gls{cs.space}Users Group}
+\gls{newacronym}\marg{ascii}\comment{label}
+\marg{ascii}\comment{short form needs to be in lower case with sc styles}
+\marg{American Standard Code for Information Interchange}
+\strut
+\cmd{renewcommand}\marg{\gls{glstextformat}}[1]\marg{\cmd{textcolor}\marg{violet}\marg{\gls{param}1}}
+\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{underline}\marg{\gls{param}1}}
+\cmd{renewcommand}\marg{\gls{glsxtrabbreviationfont}}[1]\marg{\gls{textbf}\marg{\gls{param}1}}
+\strut
+\cmd{begin}\marg{document}
+Two \gls{glspl}\marg{duck}, a \gls{gls}\marg{fleuron} (\gls{glssymbol}\marg{fleuron},
+\gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug} and \gls{gls}\marg{ascii}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
+\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
+\renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}%
+\newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}%
+\glssetcategoryattribute{ornament}{textformat}{ornamentfmt}%
+Two \glspl{ex1.duck}, a \gls{ex.fleuron} (\glssymbol{ex.fleuron},
+\glsentrydesc{ex.fleuron}), \gls{ex.tug} and \gls{ex.ascii}.
+\end{result}
+So \code{\gls{gls}\marg{fleuron}} and \code{\gls{glssymbol}\marg{fleuron}} are now
+formatted according to the custom command \csfmt{ornamentfmt} (cyan)
+not by \gls{glstextformat} (violet), but they are still affected by
+\gls{glsxtrregularfont} (underline).
+
+The \code{tug} abbreviation has been assigned the
+\abbrstyle{long-short-em} style which encapsulates the short form
+with \gls{emph}, but it also obeys \gls{glsxtrabbreviationfont}
+(bold) and it's encapsulated by \gls{glstextformat} (violet), so the
+full form on \idx{firstuse} is all violet and bold with the short
+form in italics.
+
+The \code{ascii} entry (which has the \field{category} set to
+\code{acronym}) has been assigned the \abbrstyle{short-sc-nolong}
+style, which encapsulates the short form with \gls{textsc} (so the
+short form must be converted to \idx{lowercase}) and identifies the
+entry as a \idx{regular} term, so it obeys \gls{glsxtrregularfont}
+(underline). Again, the \idx{link-text} is encapsulated with
+\gls{glstextformat} (violet) so the abbreviation is violet,
+underlined and in small-caps.
+
+You can override a specific instance with the \glsopt{textformat}
+setting in the first optional argument of commands like \gls{gls}.
+For example, if the above is modified to:
+\begin{codeenv}
+Two \gls{glspl}\marg{duck}, a \gls{gls}\oarg{\glsopt{textformat}=textbf}\marg{fleuron}
+(\gls{glssymbol}\marg{fleuron}, \gls{glsentrydesc}\marg{fleuron}), \gls{gls}\marg{tug}
+and \gls{gls}\marg{ascii}.
+\end{codeenv}
+then the result is now:
+\begin{result}
+\renewcommand{\glstextformat}[1]{\textcolor{violet}{#1}}%
+\renewcommand{\glsxtrregularfont}[1]{\underline{#1}}%
+\renewcommand{\glsxtrabbreviationfont}[1]{\textbf{#1}}%
+\newcommand{\ornamentfmt}[1]{\textcolor{cyan}{#1}}%
+\glssetcategoryattribute{ornament}{textformat}{ornamentfmt}%
+Two \glspl{ex1.duck}, a \gls[textformat=textbf]{ex.fleuron}
+(\glssymbol{ex.fleuron}, \glsentrydesc{ex.fleuron}),
+\gls{ex.tug} and \gls{ex.ascii}.
+\end{result}
+In this case, only that specific instance is changed.
+
+Take care if the formatting command needs to parse its argument as
+the argument won't be the actual text but consists of intermediary commands
+that determine the required text and any inner formatting, such as
+the formatting applied by abbreviation styles. See
+\sectionref{sec:expandedfmt} for further details.
+
+\section{Post-Link Category Hooks}
+\label{sec:postlinkhooks}
+
+Extra information can be appended after commands such as \gls{gls}
+by defining a \pidx{postlinkhook} for the given category. You can
+obtain the label of the entry that's just been referenced with:
+\nosecformatdef{glslabel}
+The \idx{postlinkhook} is a command in the form
+\nosecformatdef{glsxtrpostlinkcategory}
+where \meta{category} is the category label. This hook is
+implemented after any instances of commands such as \gls{gls} or
+\gls{glssymbol} (but not after commands like \gls{glsentryname},
+\gls{glsentrydesc} or \gls{glsentryname}, which may be used in the
+hook).
+
+Consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{ding}\marg{167}},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}\comment{label}
+\marg{
+ \field{name} = \marg{Archimedes' constant},
+ \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{category} = \marg{constant},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\comment{post-link hook for 'constant' category:}
+\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
+ \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}%
+A \gls{ex.fleuron} and \gls{ex.pi}.
+\end{result}
+The \code{fleuron} entry doesn't have the \field{category} key
+explicitly set, so it defaults to \code{general}, but the \code{pi}
+entry has the \field{category} set to \code{constant}, so it's
+affected by the \idx{postlinkhook} for that category, which in this
+case is given by \csfmt{glsxtrpostlinkconstant}. This hook is
+defined to use \gls{glsentrysymbol} where the entry label is obtained
+from \gls{glslabel}, which is set by \gls{gls} and similar commands.
+
+\begin{important}
+If \code{\gls{glssymbol}\marg{\gls{glslabel}}} had been used instead of
+\code{\gls{glsentrysymbol}\marg{\gls{glslabel}}} it would've caused infinite
+recursion! Don't use commands like \gls{glssymbol}, \gls{glsdesc} or
+\gls{gls} in \idxpl{postlinkhook}.
+\end{important}
+
+This means that \code{\gls{gls}\marg{pi}} is automatically followed by the
+symbol in parentheses, but \code{\gls{gls}\marg{fleuron}} isn't because it's
+governed by the \code{general} \idx{postlinkhook} instead. Note that
+the above is a simple example to demonstrate one of the uses of the
+\field{category} field.
+
+Here's a minor modification that sets the category for the
+\code{fleuron} entry to \code{ornament} and creates another hook for
+that.
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}\comment{label}
+\marg{
+ \field{name} = \marg{pi},
+ \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{category} = \marg{constant},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\comment{post-link hook for 'ornament' category:}
+\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkornament}}\marg{\comment{}
+ \cmd{space} (\gls{glsentrydesc}\marg{\gls{glslabel}})}
+\strut
+\comment{post-link hook for 'constant' category:}
+\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}{\comment{}
+ \cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}
+\strut
+\cmd{begin}\marg{document}
+A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and
+\gls{gls}\marg{pi}. Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+\newcommand{\glsxtrpostlinkornament}{\space (\glsentrydesc{\glslabel})}%
+\newcommand{\glsxtrpostlinkconstant}{\space (\glsentrysymbol{\glslabel})}%
+A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and
+\gls{ex.pi}. Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}.\incorrect
+\end{result}
+The \idx{postlinkhook} is repeated after every instance of \gls{gls}
+or \gls{glssymbol} etc. In the case of the \code{ornament} category,
+the description is appended in parentheses and in the case of the
+\code{constant} category the symbol is appended. This results in
+redundant repetition, especially with \verb|\glssymbol{pi}| which
+displays the symbol followed by the symbol in parentheses.
+
+It's more likely that the information only needs to be appended
+after the \idx{firstuse}. You can determine if the
+\idx{postlinkhook} follows the \idx{firstuse} of the entry using:
+\nosecformatdef{glsxtrifwasfirstuse}
+For example:
+\begin{codeenv}
+\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
+ \gls{glsxtrifwasfirstuse}\marg{\cmd{space} (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\marg{}\comment{}
+}
+\end{codeenv}
+Commands that don't check or modify the \idx{firstuseflag}, such as
+\gls{glssymbol}, always set \gls{glsxtrifwasfirstuse} so that it
+expands to \meta{false}. This means that even if
+\code{\gls{glssymbol}\marg{pi}}
+is placed before the first instance of \code{\gls{gls}\marg{pi}} it still
+won't be treated as the first use of that entry.
+
+For convenience, there's a shortcut command:
+\nosecformatdef{glsxtrpostlinkAddSymbolOnFirstUse}
+So an alternative definition is:
+\begin{codeenv}
+\cmd{newcommand}\marg{\csfmt{glsxtrpostlinkconstant}}\marg{\comment{}
+ \gls{glsxtrpostlinkAddSymbolOnFirstUse}
+}
+\end{codeenv}
+This does nothing if the \field{symbol} field hasn't been set.
+
+Similarly, there's a shortcut command for the description:
+\nosecformatdef{glsxtrpostlinkAddDescOnFirstUse}
+Version 1.31+ provides a combination:
+\nosecformatdef{glsxtrpostlinkAddSymbolDescOnFirstUse}
+If the \field{symbol} field is set, this displays the symbol
+followed by a comma and space. The description is always displayed
+at the end of the parenthetical material.
+
+Also from \sty{glossaries-extra} v1.31, there's a shortcut
+command that you can use to define the \idx{postlinkhook}:
+\nosecformatdef{glsdefpostlink}
+This is just a shortcut for:
+\begin{codeenv}
+\csfmt{csdef}\marg{glsxtrpostlink\meta{category}}\margm{definition}
+\end{codeenv}
+So the above document can be changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{pifont}\comment{provides \gls{ding}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}\comment{label}
+\marg{
+ \field{name} = \marg{pi},
+ \field{symbol} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{category} = \marg{constant},
+ \field{description} = \marg{Archimedes' constant}
+}
+\strut
+\comment{post-link hook for 'ornament' category:}
+\gls{glsdefpostlink}\marg{ornament}\marg{\comment{}
+ \gls{glsxtrpostlinkAddSymbolDescOnFirstUse}
+}
+\strut
+\comment{post-link hook for 'constant' category:}
+\gls{glsdefpostlink}\marg{constant}\marg{\comment{}
+ \gls{glsxtrpostlinkAddSymbolOnFirstUse}
+}
+\strut
+\cmd{begin}\marg{document}
+Symbols: \gls{glssymbol}\marg{fleuron} and \gls{glssymbol}\marg{pi}.
+A \gls{gls}\marg{fleuron} and \gls{gls}\marg{pi}. Another \gls{gls}\marg{fleuron} and
+\gls{gls}\marg{pi}.
+\cmd{end}\marg{document}
+\end{codeenv}
+The result is now:
+\begin{result}%
+\glsdefpostlink{ornament}{\glsxtrpostlinkAddSymbolDescOnFirstUse}%
+\glsdefpostlink{constant}{\glsxtrpostlinkAddSymbolOnFirstUse}%
+Symbols: \glssymbol{ex.fleuron} and \glssymbol{ex.pi}.
+A \gls{ex.fleuron} and \gls{ex.pi}. Another \gls{ex.fleuron} and
+\gls{ex.pi}.
+\end{result}
+
+\section{Glossary Name and Description Formatting}
+\label{sec:glossname}
+
+When an entry's definition is displayed within
+\gls{printunsrtglossary} or \gls{glsxtrglossentry} (see
+\sectionref{sec:displaygloss}), the value of the \field{name} field
+is encapsulated by
+\nosecformatdef{glsnamefont}
+This may be overridden with the \catattr{glossnamefont} attribute
+whose value must be the name (without the leading backslash) of a
+control sequence that takes a single argument. If set, this control
+sequence is used instead of \gls{glsnamefont}.
+
+By default \gls{glsnamefont} simply does its argument, but the
+glossary style may apply additional formatting. For example, the
+\glostyle{list} styles place the name in the optional argument of
+\csfmt{item} within the \envfmt{description} environment. With the
+standard document classes, this renders the name in bold, but other
+classes may apply different formatting.
+
+The \glostyle{tree} styles defined by the \sty{glossary-tree} style
+encapsulate the name within:
+\nosecformatdef{glstreenamefmt}
+which does \code{\gls{textbf}\margm{text}} by default. So, for
+example, if \gls{glsnamefont} is redefined to use \gls{textit} and
+the \glostyle{tree} style is used, then the name will appear in
+italic bold. The letter group headings are encapsulated within:
+\nosecformatdef{glstreegroupheaderfmt}
+which defaults to \code{\gls{glstreenamefmt}\margm{text}}, so if you
+need to redefine \gls{glstreenamefmt} you may also need to redefine
+\gls{glstreegroupheaderfmt} if the headers should have different formatting.
+The \sty{glossaries-extra-stylemods} package (as from v1.31) now
+redefine both \gls{glstreenamefmt} and \gls{glstreegroupheaderfmt}
+to use:
+\nosecformatdef{glstreedefaultnamefmt}
+which does \code{\gls{textbf}\margm{text}} by default. This means
+that if you want to change both the header and name to a different
+font, you can just redefine \gls{glstreedefaultnamefmt}, and if you
+want to change only the font used for the name, then now you only
+need to redefine \gls{glstreenamefmt}, without also having to
+redefine \gls{glstreegroupheaderfmt}.
+
+Case-changing can be automatically applied to the name with the
+\catattr{glossname} attribute, which may take one of the values:
+\code{firstuc} (convert the first letter to \idx{uppercase}), \code{title}
+(convert to title case) or \code{uc} (convert to all capitals).
+Alternatively, if you're using \bibgls, you can use the
+\csopt{name-case-change} resource option.
+
+The description is similarly governed by the
+\catattr{glossdescfont}, which again should have the name (without
+the leading backslash) of a control sequence that takes a single
+argument. There's no equivalent of \gls{glsnamefont} for the
+description but the glossary or abbreviation style may apply
+particular formatting, which will be in addition to the formatting
+command given by \catattr{glossdescfont} (if set).
+
+Case-changing is also available for descriptions with the
+\catattr{glossdesc} attribute, but this only has two allowed values:
+\code{firstuc} (convert the first letter to \idx{uppercase}) and
+\code{title} (convert to title case).
+Alternatively, if you're using \bibgls, you can use the
+\csopt{description-case-change} resource option.
+
+\section{Post-Name and Post-Description Hooks}
+\label{sec:postfieldhooks}
+
+Information can be appended to the \field{name} in the glossary for
+a particular category using the \pidx{postnamehook}, which is given
+by the command:
+\nosecformatdef{glsxtrpostnamecategory}
+The current entry's label can be referenced with:
+\nosecformatdef{glscurrententrylabel}
+For example, if the preferred glossary style doesn't include the
+\field{symbol} field, but you want the symbol displayed after the
+name for entries with the \field{category} field set to \code{symbol}:
+\begin{codeenv}
+\cmd{newcommand}\marg{\cmd{glsxtrpostnamesymbol}}\marg{\cmd{space}
+ (\gls{glsentrysymbol}\marg{\gls{glscurrententrylabel}})}
+\end{codeenv}
+There's a convenient shortcut:
+\nosecformatdef{glsdefpostname}
+which defines \gls{glsxtrpostnamecategory} to \meta{definition}
+(using \gls{csdef}). There's also a more general purpose \idx{postnamehook}
+used regardless of the category:
+\nosecformatdef{glsextrapostnamehook}
+
+The \idx{postnamehook} is placed inside the formatting command used
+for the \field{name} field in the glossary. It's only present in the
+glossary (see \sectionref{sec:printgloss}) or stand-alone entries
+(see \sectionref{sec:standalone}).
+
+There is a similar \pidx{postdescriptionhook}. For a particular category,
+the hook is given by:
+\nosecformatdef{glsxtrpostdesccategory}
+There are some categories that have empty hooks already defined,
+such as
+\nosecformatdef{glsxtrpostdescgeneral}
+These will need \csfmt{renewcommand} rather than \csfmt{newcommand}.
+Again there's a shortcut command provided:
+\nosecformatdef{glsdefpostdesc}
+which just uses \gls{csdef}, so there's no check if the command is
+already defined.
+As with the \idx{postnamehook}, the entry's label can be accessed
+with \gls{glscurrententrylabel}.
+
+Punctuation (such as a \idx{full-stop} or comma) can automatically be
+appended to the description in the
+glossary with the \styopt{postpunc} option. (Note that the
+unstarred form of \gls{longnewglossaryentry} interferes with this
+option. Use the starred form \gls{longnewglossaryentry*} instead.)
+The post-description punctuation (if set) is placed after the
+\glslink{postdescriptionhook}{post-description category hook} (if
+provided). Both the post-description category hook and the
+post-description punctuation are implemented by
+\nosecformatdef{glspostdescription}
+The \sty{glossaries-extra-stylemods}
+package (which can be loaded with the \styopt{stylemods} option)
+patches the predefined styles provided with the base
+\sty{glossaries} package to ensure that the standard styles all use
+\gls{glspostdescription}.
+
+
+\chapter{Problematic Areas}
+\label{sec:problems}
+
+There are some places where the use of commands like \gls{gls} can
+cause problems. Common issues are listed below, with workarounds provided.
+
+\section{Headings and Captions}
+\label{sec:headings}
+
+The arguments of sectioning commands (such as \gls{chapter} or
+\gls{section}) and of captions (\gls{caption}) are
+\pidxpl{moving-argument}. The text is not only displayed at the
+point in the document where the command occurs, but may also be
+copied to the table of contents or list of figures etc.
+Additionally, depending on the page style, the section argument may
+also be reproduced in the page header. This repeated use of the same
+material can cause complications, in particular it can prematurely
+triggering the \idx{firstuseflag} switch and cause unwanted
+indexing. If the content appears in the page header and the page
+styles converts headers to upper case, this can also cause a
+problem.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}}
+\cmd{usepackage}\marg{glossaries}
+\strut
+\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}}
+\strut
+\cmd{begin}{document}
+\gls{chapter}\marg{A \gls{gls}\marg{sample} chapter}
+\cmd{lipsum} \comment{dummy text}
+\cmd{end}\marg{document}
+\end{codeenv}
+I've used \csfmt{lipsum} here to create some dummy text that ensures
+a multi-paged document because the problem doesn't occur until the second
+page. The error message is:
+\begin{verbatim}
+Glossary entry `SAMPLE' has not been defined.
+\end{verbatim}
+The problem here is that the chapter title is copied to the header
+(which doesn't appear on the chapter's first page) but the header
+uses \gls{MakeUppercase}, which can't expand \gls{gls} but it does
+change the label, so \code{\gls{gls}\marg{sample}} is converted to
+\code{\gls{gls}\marg{SAMPLE}}, but there's no entry with that label.
+(Labels are case-sensitive.)
+
+Here's an example that doesn't cause an error (because there's not
+enough text to trigger a page break) but does cause unexpected output:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
+\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{chapter}\marg{A chapter about \gls{gls}\marg{html}}
+Reference \gls{gls}\marg{html}.
+\cmd{end}\marg{document}
+\end{codeenv}
+On the first \LaTeX\ run, the table of contents is empty as the
+associated \ext{toc} file didn't exist at the start. The chapter title
+appears as \qt{A chapter about hypertext markup language
+(\textsc{html})}, which shows the \idx{firstuse} of
+\code{\gls{gls}\marg{html}}. The \ext{toc} file (which was created
+but not read by \gls{tableofcontents}) now contains:
+\begin{codeenv}
+\cmd{contentsline} \marg{chapter}\marg{\cmd{numberline} \marg{1}A chapter about \gls{gls} \marg{html}}\marg{3}
+\end{codeenv}
+This means that on the next \LaTeX\ run, the table of contents now
+includes \code{\gls{gls}\marg{html}}. Since the table of contents
+occurs at the start of the document, this is now the \idx{firstuse}
+of \code{html}, so the full form is shown in the table of contents,
+but the chapter title is now \qt{A chapter about \textsc{html}}, which shows
+the subsequent use.
+
+The \sty{glossaries-extra} package provides some commands that are
+designed for use in section or caption titles. These include:
+\nosecformatdef{glsfmtshort}
+which shows the short form of an abbreviation,
+\nosecformatdef{glsfmtlong}
+which shows the long form of an abbreviation,
+\nosecformatdef{glsfmtfull}
+which shows the full form of an abbreviation,
+\nosecformatdef{glsfmtname}
+which shows the entry's name,
+\nosecformatdef{glsfmtfirst}
+which shows the entry's \field{first} field, and
+\nosecformatdef{glsfmttext}
+which shows the entry's \field{text} field.
+
+Here's a modified version of the above:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
+\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{chapter}\marg{A chapter about \gls{glsfmtlong}\marg{html}}
+Reference \gls{gls}\marg{html}.
+\cmd{lipsum} \comment{dummy text}
+\cmd{end}\marg{document}
+\end{codeenv}
+This now shows the long form in the table of contents and the
+chapter title. Since \gls{glsfmtlong} doesn't affect the
+\idx{firstuseflag}, the reference after the chapter title now shows
+the \idx{firstuse} full form. There's no longer an error with the
+page header on the second page, but it's not quite right as the
+case-change hasn't been applied, so the page heading appears as:
+\begin{result}
+4\hfill \emph{CHAPTER 1. A CHAPTER ABOUT hypertext markup language}
+\end{result}
+This can be corrected by setting the \catattr{headuc} attribute to
+\code{true}:
+\begin{codeenv}
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{headuc}\marg{true}
+\end{codeenv}
+This now makes the page header too long, but remember that you can
+use the optional argument of sectioning commands to provide a
+shorter form for both the page heading and table of contents:
+\begin{codeenv}
+\gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter about
+\gls{glsfmtlong}\marg{html}}
+\end{codeenv}
+One final problem remains and it's due to the
+\abbrstyle{long-short-sc} abbreviation style which uses \gls{textsc}
+to display the short form in small capitals. The combination of
+italic and small capitals isn't supported with the default fonts and
+results in a font substitution. There's a similar problem in the
+table of contents which displays the chapter title in bold. There's
+a warning at the end of the transcript:
+\begin{verbatim}
+Some font shapes were not available, defaults substituted.
+\end{verbatim}
+The conflict between bold and small capitals can be solved by
+switching to the T1 font encoding:
+\begin{codeenv}
+\cmd{usepackage}[T1]\marg{\sty[noindex=false]{fontenc}}
+\end{codeenv}
+The conflict between italic and small capitals can be solved with
+the \sty{slantsc} package. Another possibility is to redefine:
+\nosecformatdef{glsabbrvscfont}
+which is used by the \qt{sc} abbreviation styles:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{}
+ \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}\marg{\gls{param}1}}\comment{}
+}
+\end{codeenv}
+This uses:
+\nosecformatdef{glsxtrifinmark}
+which expands to \meta{true} in headings and the table of contents,
+otherwise it expands to \meta{false}. This use of
+\gls{MakeTextUppercase} replaces the need for the \catattr{headuc}
+attribute. Both \catattr{headuc} and the above redefinition of
+\gls{glsabbrvscfont} will cause the abbreviation to appear in
+\idx{uppercase} in the table of contents. If you don't want this,
+you can defer making these modifications until after the table of
+contents. Alternatively, use:
+\nosecformatdef{glsxtrRevertTocMarks}
+which makes \gls{glsxtrifinmark} expand to \meta{false} in the table
+of contents. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}[T1]\marg{fontenc}
+\cmd{usepackage}\marg{lipsum}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{}
+ \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}{\gls{param}1}}\comment{}
+}
+\strut
+\gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}}
+\gls{newabbreviation}\marg{html}\marg{html}\marg{hypertext markup language}
+\strut
+\cmd{begin}\marg{document}
+\gls{tableofcontents}
+\gls{chapter}\oarg{A chapter about \gls{glsfmtshort}\marg{html}}\marg{A chapter
+about \gls{glsfmtlong}\marg{html}}
+Reference \gls{gls}\marg{html}.
+\cmd{lipsum} \comment{dummy text}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+
+\section{Nesting}
+\label{sec:nested}
+
+Nesting refers to commands like \gls{gls} and \gls{glssymbol} being
+used in the \idx{link-text} of similar commands. This occurs if
+these commands are used in fields that form part of the
+\idx{link-text} or if they occur in the final \meta{insert}
+optional argument (which is included in the \idx{link-text}) or in the
+\idx{postlinkhook} (which isn't included in the \idx{link-text} but
+is still problematic).
+
+The most serious problem is when the \idx{postlinkhook} includes one
+of these commands that references an entry with the same category
+(and therefore the same \idx{postlinkhook} code) as
+you can end up with an infinite loop. For example:
+\begin{codeenv}
+\gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glssymbol}\marg{\gls{glslabel}})}\comment{infinite loop!}\incorrect
+\end{codeenv}
+Instead, use \gls{glsentrysymbol}:
+\begin{codeenv}
+\gls{glsdefpostlink}\marg{symbol}\marg{ (\gls{glsentrysymbol}\marg{\gls{glslabel}})}\correct
+\end{codeenv}
+Better still, use commands like
+\gls{glsxtrpostlinkAddSymbolOnFirstUse} (see \sectionref{sec:postlinkhooks}).
+
+The next most problematic nesting is the use of \gls{gls} in
+abbreviations. It's far more of a problem if you only use the base
+\sty{glossaries} package. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\gls{usepackage}\marg{glossaries}
+\strut
+\gls{newacronym}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\gls{newacronym}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{shtml}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This results in:
+\begin{result}
+server-side includes (SSI) enabled hypertext markup language (HTML) (SHTML).
+\end{result}
+The \sty{glossaries-extra} package temporarily changes \gls{gls}
+within the \idx{link-text} to avoid this type of problem.
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{shtml}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This now produces:
+\begin{result}
+SSI enabled HTML (SHTML).
+\end{result}
+This doesn't seem so bad, but now let's see what happens if the
+\catattr{glossdesc} is set to \code{firstuc}:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{glossdesc}}\marg{firstuc}
+\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect
+\strut
+\cmd{begin}\marg{document}
+\gls{gls}\marg{shtml}.
+\gls{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+This now causes an error:
+\begin{verbatim}
+! Missing \endcsname inserted.
+<to be read again>
+ \protect
+\end{verbatim}
+The problem here is that the first-letter upper-casing command is
+being applied to \code{\gls{gls}\marg{ssi}}. This results in
+\code{\gls{gls}\marg{\gls{MakeTextUppercase} ssi}} which has an
+invalid label. A workaround is to insert an empty group before
+the initial \gls{gls}:
+\begin{codeenv}
+\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\marg{}\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}
+\end{codeenv}
+However, \gls{gls} functions normally within the glossary, so the
+result is:
+\begin{result}
+\textbf{SSI} Server-side includes
+
+\textbf{HTML} Hypertext markup language
+
+\textbf{SHTML} server-side includes (SSI) enabled hypertext markup language (HTML)
+\end{result}
+Since neither \code{ssi} nor \code{html} have been referenced in the
+document, the reference in the \code{shtml} description in the
+glossary is the \idx{firstuse} for both of them, so they show the
+full form, but the upper-casing can't be applied. This means that
+the description for the \code{shtml} entry doesn't start with an
+\idx{uppercase} letter. The best solution is to avoid using
+\gls{gls} in the \field{long} field:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\strut
+\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
+\strut
+\gls{glssetcategoryattribute}\marg{abbreviation}\marg{glossdesc}\marg{firstuc}
+\strut
+\gls[noindex]{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
+ \gls{glsxtrifhasfield}\marg{\field{seealso}}\marg{\gls{glscurrententrylabel}}\comment{}
+ \marg{ (\gls{emph}\marg{see also} \gls[noindex=false]{glsxtrseelist}\marg{\gls{glscurrentfieldvalue}})}\comment{}
+ \marg{}\comment{}
+}
+\strut
+\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\gls{newabbreviation}\oarg{\field{seealso}=\marg{ssi,html}}\marg{shtml}\marg{SHTML}
+\marg{server-side includes enabled hypertext markup language}
+\strut
+\cmd{begin}\marg{document}
+\gls{Gls}\marg{shtml}.
+\gls{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+I've used the \field{seealso} key here. (The value should be a
+comma-separated list of labels.) It doesn't show
+in the glossary by default as it needs an indexing application to add it
+automatically to the \idx{locationlist}, so I've used the
+\idx{postdescriptionhook} to append the cross-reference. The
+\styopt{record} option is needed, otherwise the default
+\gls{makeindex} setting will be assumed and an error will occur as
+the associated \gls{makeindex} file hasn't been opened. If \bibgls\
+support is added then the hook won't be needed.
+
+\section{Shortcut Commands or Active Characters}
+\label{sec:activeshortcuts}
+
+Some packages, such as \sty{babel}, provide shortcut commands or
+active characters that can be enabled through a particular setting.
+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})
+active and it becomes a shortcut for \gls{umlaut} (the umlaut accent
+command):
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[ngerman]\marg{babel}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\gls{newabbreviation}\marg{rna}\marg{RNA}\marg{ribonukleins"aure}\incorrect
+\strut
+\cmd{begin}\marg{document}
+Explicit use: ribonukleins"aure.
+Reference: \gls{gls}\marg{rna}.
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces:
+\begin{result}
+Explicit use: ribonukleins\"aure. Reference: ribonukleins"aure (RNA).
+\end{result}
+This is because the double quote character still had its normal
+meaning when the \code{rna} entry was defined, so the
+\idx{doublequotechar} in the long form is an actual double quote
+character not a shortcut for \gls{umlaut}.
+
+Another problem occurs when you have a large file containing entry
+definitions that will be shared by multiple documents. If shortcut
+commands are used in the entry definitions then every document that
+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}.
+
+For large files that are written once (with minor subsequent edits),
+but reused many times for multiple documents, it's better to use the
+actual command (that simply requires the appropriate package to be
+loaded, if applicable, without specific options to enable it).
+
+
+\section{Formatting Commands that Need Direct Access to the Text}
+\label{sec:expandedfmt}
+
+If you want to redefine any of the formatting commands
+\gls{glstextformat}, \gls{glsxtrregularfont} or
+\gls{glsxtrabbreviationfont}, remember that their argument isn't the
+actual text but consists of intermediary commands
+that determine the required text and any inner formatting, such as
+the formatting applied by abbreviation styles.
+
+With the \glsopt{hyperoutside} setting on, the outermost level
+will be the command to apply the hyperlink with \gls{glstextformat}
+(or the equivalent provided by \catattr{textformat})
+inside the hyperlink text. (If hyperlinks aren't enabled the outer
+command simply does the hyperlink text.)
+
+With \glsopt[false]{hyperoutside}, the outermost level will be
+\gls{glstextformat} (or equivalent) with the command that applies
+the hyperlink inside the formatting argument.
+
+The next level down sets up the abbreviation styles for the given
+category (if appropriate). If the entry isn't an abbreviation or is
+an abbreviation classified as regular then
+\gls{glsxtrregularfont} is applied to the command that governs how
+regular entries are formatted. Otherwise \gls{glsxtrabbreviationfont}
+is applied to the command that governs how abbreviations are
+formatted.
+
+Finally, there are tests applied to determine if this is the
+\idx{firstuse}, if the plural is required, if any case-changing is
+required, if the final optional argument has been given, or if a
+command such as \gls{glssymbol} has been used. These tests
+determine which field to obtain the \idx{link-text} from. With
+abbreviations, any formatting required by the abbreviation style is
+finally performed.
+
+This makes it very difficult to apply a formatting command that
+needs direct access to the actual text that needs to be displayed.
+One possible method is to use:
+\nosecformatdef{GlsXtrExpandedFmt}
+which first (protected) fully expands \meta{text} and then performs
+\meta{cs}\margm{expanded text} where \meta{cs} is a control
+sequence. For example, the \isty{soul} package provides the command
+\gls{ul} to underline text, but it needs to be able to parse its
+argument to work. If I simply try to change the standard
+\gls{underline} to \gls{ul} in the earlier example from
+\sectionref{sec:glsformats}:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\cmd{ul}\marg{\gls{param}1}}
+\end{codeenv}
+then this causes the error:
+\begin{verbatim}
+! Package soul Error: Reconstruction failed.
+\end{verbatim}
+Instead I need:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\gls{glsxtrregularfont}}[1]\marg{\gls{GlsXtrExpandedFmt}\cmd{ul}\marg{\gls{param}1}}
+\end{codeenv}
+\emph{and also} \gls{ding} now needs protection:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{fleuron}\comment{label}
+\marg{
+ \field{name} = \marg{fleuron},
+ \field{symbol} = \marg{\gls{protect}\gls{ding}\marg{167}},
+ \field{category} = \marg{ornament},
+ \field{description} = \marg{typographic ornament}
+}
+\end{codeenv}
+
+\section{Buffering Changes to the First Use Flag}
+\label{sec:buffering}
+
+The \sty{soul} commands, described above, also have problems if the
+\idx{firstuseflag} is switched off within the argument. This can be
+demonstrated with the following:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\marg{soul}
+\cmd{usepackage}\marg{glossaries-extra}
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
+\cmd{begin}\marg{document}
+\cmd{ul}\marg{Some text about \gls{gls}\marg{ssl}.}
+\cmd{end}\marg{document}
+\end{codeenv}
+This produces the somewhat confusing error message:
+\begin{verbatim}
+Glossary entry `{ssl}' has not been defined.
+\end{verbatim}
+Enclosing \code{\gls{gls}\marg{ssl}} inside the argument of \csfmt{mbox}
+changes the error message to:
+\begin{verbatim}
+! Package soul Error: Reconstruction failed.
+\end{verbatim}
+The only way to avoid an error is to switch on the \gls{glsunset}
+buffering, which modifies the internal command that normally changes
+the \idx{firstuseflag}. Instead, the entry label is simply stored in
+an internal list. The buffering is switched on with:
+\nosecformatdef{GlsXtrStartUnsetBuffering}
+The unstarred form of this command may result in multiple
+occurrences of an entry in the buffer's internal list. The starred form,
+which only adds an entry's label to the list if not already present,
+is better if the list needs to contain unique items.
+
+The current buffer can be iterated over using;
+\nosecformatdef{GlsXtrForUnsetBufferedList}
+where \meta{cs} is a command that takes a single argument (the
+entry's label). Finally, entries in the buffer can be unset and the
+buffer cleared with:
+\nosecformatdef{GlsXtrStopUnsetBuffering}
+
+The above example will work if it's changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\marg{soul}
+\cmd{usepackage}\marg{glossaries-extra}
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
+\cmd{begin}\marg{document}
+\gls{GlsXtrStartUnsetBuffering}
+\cmd{ul}\marg{Some text about \cmd{mbox}\marg{\gls{gls}\marg{ssl}}.}
+\gls{GlsXtrStopUnsetBuffering}
+\cmd{end}\marg{document}
+\end{codeenv}
+Note the need for \csfmt{mbox}, which can cause a problem with
+line-breaking. Another problem is that if the entry is referenced
+multiple times within the same buffer, each use of \gls{gls} (or its
+\idxpl{variant}) will be treated as the \idx{firstuse}.
+
+Another workaround is to use \glsopt{textformat} with a command that
+uses \gls{GlsXtrExpandedFmt} (see \sectionref{sec:expandedfmt}). For
+example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\marg{soul}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\cmd{newrobustcmd}\marg{\cmd{gul}}[1]\marg{\comment{}
+ \marg{\comment{}
+ \cmd{def}\gls{glsxtrabbreviationfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{}
+ \cmd{def}\gls{glsxtrregularfont}\gls{param}\gls{param}1\marg{\gls{GlsXtrExpandedFmt}\marg{\cmd{ul}}\marg{\gls{param}\gls{param}1}}\comment{}
+ \gls{param}1\comment{}
+ }%
+}
+\strut
+\gls{newabbreviation}\marg{ssl}\marg{SSL}\marg{Secure Sockets Layer}
+\cmd{begin}\marg{document}
+\cmd{ul}\marg{Some text about }\gls{gls}\oarg{\glsopt{textformat}=gul}\marg{ssl}.
+\cmd{end}\marg{document}
+\end{codeenv}
+
+\chapter{Incorporating \bibgls}
+\label{sec:bib2gls}
+
+So far, the examples haven't actually used \bibgls, so what does it
+actually do? Recall the example document in \sectionref{sec:group},
+reproduced below:
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\cmd{usepackage}\marg{mhchem}
+\cmd{usepackage}[\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}
+]\marg{glossaries-extra}
+\strut
+\gls{glsaddstoragekey}\marg{group}\marg{}\marg{\cmd{grouplabel}}
+\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
+\strut
+\gls{newglossaryentry}\marg{area}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{A}},
+ \field{description} = \marg{area},
+ \field{group} = \marg{A}
+}
+\strut
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}},
+ \field{group} = \marg{A}
+}
+\strut
+\gls{newglossaryentry}\marg{circumference}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{C}},
+ \field{description} = \marg{circumference},
+ \field{group} = \marg{C}
+}
+\strut
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name} = \marg{duck},
+ \field{description} = \marg{a waterbird with webbed feet},
+ \field{group} = \marg{D}
+}
+\strut
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name} = \marg{goose},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ \field{group} = \marg{G}
+}
+\strut
+\gls{newglossaryentry}\marg{radius}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{r}},
+ \field{description} = \marg{radius},
+ \field{group} = \marg{R}
+}
+\strut
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant},
+ \field{group} = \marg{greek}
+}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The document preamble is quite cluttered. It could be tidied up by
+moving all the \gls{newglossaryentry} code into a separate file
+called, say, \filefmt{entries.tex}. The main document code can now
+be simplified to:
+\begin{codeenv}
+\cmd{documentclass}\marg{scrartcl}
+\cmd{usepackage}\marg{mhchem}
+\cmd{usepackage}[
+ \styopt{record},\comment{create \field{group} field}
+ \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}
+]\marg{glossaries-extra}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Symbols}
+\strut
+\gls[noindex=false]{input}\marg{entries}\comment{input entries.tex}
+\strut
+\cmd{begin}\marg{document}
+\gls{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+This is much neater, but maintaining the \filefmt{entries.tex} file is
+quite troublesome. Each entry must be defined in the correct order
+(that matches the desired listing in \gls{printunsrtglossary}) and
+only those entries that should appear in \gls{printunsrtglossary}
+should be defined (unless you want the laborious task of filtering
+them out, as in \sectionref{sec:printglossagain}). The \field{group}
+field needs setting for every entry, and if the \field{location}
+field also needs setting then the \filefmt{entries.tex} file will
+need to be modified every time the document changes cause a shift in
+the page numbers.
+
+With \bibgls, you write all the entry definitions (without the
+\field{group} or \field{location} fields set) in one or more
+\ext{bib} files. It's then \bibgls\ that creates the equivalent of
+the above \filefmt{entries.tex} file with all the entry definitions
+in the correct order and with the \field{group} or \field{location}
+fields set, if appropriate. To avoid accidentally overwriting an
+important document file, \bibgls\ uses the extension \ext{glstex}
+rather than \ext{tex} (but it's still a file containing \LaTeX\ code
+that defines the entries using \gls{newabbreviation} or
+\gls{newglossaryentry}\footnote{Actually it uses
+\gls{longnewglossaryentry*} to allow for multi-paragraph descriptions,
+and \gls{longnewglossaryentry*} and \gls{newabbreviation} are used
+indirectly through helper commands.}).
+
+Instead of using \gls{input} in the document preamble, you now need
+to use:
+\nosecformatdef{GlsXtrLoadResources}
+The \ext{glstex} file doesn't exist on the first \LaTeX\ run as
+\bibgls\ can only create the file once the \ext{aux} file has been
+created (since the \ext{aux} file contains all the information about
+which entries to select, the name of the \ext{bib} files where their
+definitions are stored and how to order them).
+So \gls{GlsXtrLoadResources} tests if the \ext{glstex} file exists
+before trying to input it. The \styopt{record} option is necessary
+because it:
+\begin{itemize}
+\item enables the \styopt[warn]{undefaction} option (the entries
+aren't defined on the first \LaTeX\ run);
+\item creates the \field{group} and \field{location} fields;
+\item disables the \gls{makeindex}\slash\gls{xindy} indexing and
+instead writes the indexing information as a record in the \ext{aux}
+file;
+\item loads \sty{glossaries-extra-bib2gls} (which provides
+extra commands specific to \bibgls).
+\end{itemize}
+Each time you use a command like \gls{gls} or \gls{glssymbol} (but
+not like \gls{glsentrysymbol}) in the document, a record is added to
+the \ext{aux} file containing the entry's label, the location (by
+default the page number) where the entry was used, and extra
+information including how to format the location. The default
+behaviour of \bibgls\ is to only select those entries that have
+records in the \ext{aux} file and any dependent entries.
+
+The example above doesn't include any references (commands like
+\gls{gls}), so \bibgls\ won't select any entries and the
+\ext{glstex} file won't contain any definitions. This means that the
+glossary will be empty. If you want all entries from the specified
+\ext{bib} files selected then you need to change the \csopt{selection}
+setting:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection}}
+\end{codeenv}
+This doesn't explicitly name any \ext{bib} file. The default is
+\code{\gls{jobname}\ext{bib}} but you can change this with the
+\csopt{src} option. For example, if the entries are defined in
+\filefmt{entries.bib} (regular terms), \filefmt{symbols.bib}
+(symbols) and \filefmt{abbrvs.bib} (abbreviations) then you need
+to use:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries,symbols,abbrvs]{src},\comment{bib files}
+ \csopt[all]{selection}\comment{select all entries}
+}
+\end{codeenv}
+
+You can have multiple instances of \gls{GlsXtrLoadResources}, but
+remember that each instance inputs a file containing definitions, and
+the glossary produced with \gls{printunsrtglossary} follows the same
+order. This means that you can have blocks within the same glossary
+that use different sorting methods. For example:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[symbols]{src},\comment{bib file}
+ \csopt[letter-case]{sort},\comment{sort according to character code}
+ \csopt[symbol]{category},\comment{set this as the \field{category} field}
+ \csopt[glssymbols]{group}\comment{set this as the \field{group} field}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries,abbrvs]{src},\comment{bib files}
+ \csopt[en-GB]{sort}
+}
+\end{codeenv}
+The first instance fetches the data from \filefmt{symbols.bib},
+sorts the entries according to the character code, sets the
+\field{category} field to \code{symbol}, and sets the
+\field{group} field to \code{glssymbols} for each definition
+written to the \ext{glstex} file. The \code{glssymbols} group label is recognised by
+the \sty{glossaries} package, and the title is obtained from the
+language-sensitive \gls{glssymbolsgroupname} command (\qt{Symbols}
+in English). So the glossary will start with a symbols group
+that contains all the entries selected from \filefmt{symbols.bib}.
+The rest of the glossary is obtained from the data selected from the
+\filefmt{entries.bib} and \filefmt{abbrvs.bib} file sorted according
+to the en-GB locale. These entries will have the \field{group} field
+set by the locale's sort rule.
+
+The document build now needs to include a call to \bibgls. For
+example, if the main document file is called \filefmt{myDoc.tex}
+then the build process is:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls --group myDoc
+pdflatex myDoc
+\end{verbatim}
+Omit the \longarg{group} switch if you want the \field{group} field
+left empty, and replace \code{pdflatex} with \code{xelatex} etc, as
+appropriate.
+
+\section{The \extfmt{bib} Format}
+\label{sec:bibentries}
+
+The \ext{bib} files define entry data in the form:
+\begin{codeenv}
+\gls[noindex=false]{atchar}\meta{entry type}\marg{\meta{id},
+ \meta{field$_1$} = \margm{value},
+ \ldots
+ \meta{field$_n$} = \margm{value}
+}
+\end{codeenv}
+where \meta{id} is the entry's label. The most basic entry type is
+\atentry{entry}. For example:
+\begin{codeenv}
+\atentry{entry}\marg{goose,
+ \field{name} = \marg{goose},
+ \field{plural} = \marg{geese},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\end{codeenv}
+This is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name} = \marg{goose},
+ \field{plural} = \marg{geese},
+ \field{description} = \marg{a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill}
+}
+\end{codeenv}
+You can use any of the defined keys, such as \field{symbol}:
+\begin{codeenv}
+\atentry{entry}\marg{amethyst,
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
+}
+\end{codeenv}
+but avoid using internal fields. If you define custom keys in your
+document, make sure you define them all before the first instance of
+\gls{GlsXtrLoadResources} as all the recognised keys are written to
+the \ext{aux} file for \bibgls\ to detect. Any unrecognised fields
+in the \ext{bib} file are ignored.
+
+\begin{important}
+The \atentry{entry} type is intended mainly for words or phrases,
+optionally with an associated \field{symbol}. If
+the \field{name} field contains symbols or other non-alphabetic
+content (such as punctuation that shouldn't be ignored by the sort
+comparator) see \sectionref{sec:@symbol}.
+\end{important}
+
+\subsection{Defining Terms with Optional Descriptions}
+\label{sec:@index}
+
+The \atentry{entry} type requires the \field{description} field and
+either the \field{name} or \field{parent} field. There's a similar
+command that doesn't have any required fields: \atentry{index}. If
+the \field{name} isn't supplied, it's assumed to be the same as the
+\meta{id}. If the \field{description} isn't supplied it's assumed to
+be empty. This type behaves like \atentry{entry}, but it sets the
+default \field{category} to \code{index}. So:
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{duck},
+ \field{description}=\marg{},
+ \field{category}=\marg{index}
+}
+\end{codeenv}
+and
+\begin{codeenv}
+\atentry{index}\marg{goose,
+ \field{plural} = \marg{geese}
+}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name}=\marg{goose},
+ \field{plural}=\marg{geese},
+ \field{description}=\marg{},
+ \field{category}=\marg{index}
+}
+\end{codeenv}
+If the name contains content that can't be used in a label (see
+\sectionref{sec:labels}), then
+you need the \field{name} field. For example:
+\begin{codeenv}
+\atentry{index}\marg{chateau,
+ \field{name} = \marg{ch\gls[noindex=false]{cs.circum}ateau},
+ \field{plural} = \marg{ch\gls{cs.circum}ateaux}
+}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{chateau}
+\marg{
+ \field{name}=\marg{ch\gls{cs.circum}ateau},
+ \field{plural}=\marg{ch\gls{cs.circum}ateaux},
+ \field{description}=\marg{},
+ \field{category}=\marg{index}
+}
+\end{codeenv}
+There's a similar entry type \atentry{indexplural} that sets the
+\field{name} field (if not provided) to the plural form, which is
+obtained from the \field{plural} field, if set. Otherwise it's
+obtained by appending the plural suffix (\qt{s}) to the \field{text}
+field. If the \field{text} field isn't set it's obtained from the label.
+The other difference is that it sets the default \field{category} field to
+\code{indexplural}. For example,
+\begin{codeenv}
+\atentry{indexplural}\marg{duck}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{ducks},
+ \field{text}=\marg{duck},
+ \field{description}=\marg{},
+ \field{category}=\marg{indexplural}
+}
+\end{codeenv}
+and
+\begin{codeenv}
+\atentry{indexplural}\marg{goose,
+ \field{plural} = \marg{geese}
+}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name}=\marg{geese},
+ \field{text}=\marg{goose},
+ \field{plural}=\marg{geese},
+ \field{description}=\marg{},
+ \field{category}=\marg{indexplural}
+}
+\end{codeenv}
+
+The \csopt[firstuc]{name-case-change} resource option converts the
+first letter of the \field{name} field to \idx{uppercase}, so with
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[firstuc]{name-case-change}}
+\end{codeenv}
+then
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\end{codeenv}
+is now analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{duck}
+\marg{
+ \field{name}=\marg{Duck},
+ \field{text}=\marg{duck},
+ \field{description}=\marg{},
+ \field{category}=\marg{index}
+}
+\end{codeenv}
+and
+\begin{codeenv}
+\atentry{indexplural}\marg{goose,
+ \field{plural} = \marg{geese}
+}
+\end{codeenv}
+is now analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{goose}
+\marg{
+ \field{name}=\marg{Geese},
+ \field{text}=\marg{goose},
+ \field{plural}=\marg{geese},
+ \field{description}=\marg{},
+ \field{category}=\marg{indexplural}
+}
+\end{codeenv}
+and
+\begin{codeenv}
+\atentry{entry}\marg{amethyst,
+ \field{name} = \marg{amethyst},
+ \field{description} = \marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
+}
+\end{codeenv}
+is now analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{amethyst}
+\marg{
+ \field{name}=\marg{Amethyst},
+ \field{text}=\marg{amethyst},
+ \field{description}=\marg{a purple type of quartz},
+ \field{symbol} = \marg{\gls{ce}\marg{SiO2}}
+}
+\end{codeenv}
+
+\subsection{Defining Abbreviations}
+\label{sec:@abbreviation}
+
+Abbreviations can be defined with \atentry{abbreviation}. For
+example:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+which is analogous to:
+\begin{codeenv}
+\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\end{codeenv}
+(which sets the \field{category} to \code{abbreviation}).
+Alternatively, you can use \atentry{acronym}. For example:
+\begin{codeenv}
+\atentry{acronym}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+which is analogous to:
+\begin{codeenv}
+\gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language}
+\end{codeenv}
+(which sets the \field{category} to \code{acronym}).
+If you decide to use one of the abbreviation styles that formats the
+\field{short} field with \gls{textsc} (for example,
+\abbrstyle{long-short-sc}) then the \field{short} value needs to be
+in \idx{lowercase}. (Remember that \gls{textsc} only changes
+\idx{lowercase} characters to small capitals. For example,
+\code{\gls{textsc}\marg{html}} is displayed as \textsc{html} but
+\code{\gls{textsc}\marg{HTML}} is displayed as \textsc{HTML}.)
+This can easily be accomplished with the
+\csopt{short-case-change} resource option. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[lc]{short-case-change}}
+\end{codeenv}
+Recall from \sectionref{sec:abbreviations} that the abbreviation
+style must be set \emph{before} the abbreviations are defined. This
+means that if you want to use \gls{setabbreviationstyle} it must
+come before \gls{GlsXtrLoadResources}.
+
+The default sort value used by \bibgls\ is usually taken from the
+\field{name} field. This typically isn't supplied with abbreviations.
+The actual value depends on the abbreviation style, which \bibgls\
+doesn't know about, so \bibgls\ uses the \field{short}
+field instead for abbreviations. If you want to change this, for
+example, if you are using the \abbrstyle{long-noshort-desc} style,
+then use the \csopt{abbreviation-sort-fallback} option. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[long]{abbreviation-sort-fallback}}
+\end{codeenv}
+
+\subsection{Defining Symbols}
+\label{sec:@symbol}
+
+If the \field{name} field contains the symbol (rather than having a
+textual \field{name} and the symbol in \field{symbol}) then the
+notation can be defined with \atentry{symbol}. For example:
+\begin{codeenv}
+\atentry{symbol}\marg{pi,
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant}
+}
+\end{codeenv}
+This behaves much like \atentry{entry} but there are two significant
+differences: the \field{category} defaults to \code{symbol} and the
+default value used when sorting is the label not the value of the \field{name}
+field. So in this case, the sort value defaults to \code{pi}.
+Therefore the above is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{pi}
+\marg{
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant},
+ \field{category} = \marg{symbol},
+ \field{sort} = \marg{pi}
+}
+\end{codeenv}
+This is essentially like \gls{glsxtrnewsymbol} but it doesn't set
+the \field{type} field.
+
+You can change the default value used for sorting symbols with the
+\csopt{symbol-sort-fallback} option. For example, to sort symbols according
+to the \field{name} field:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[name]{symbol-sort-fallback},
+ \csopt[none]{break-at}
+}
+\end{codeenv}
+This means that the sort value for the above example entry is now
+\code{\gls{ensuremath}\marg{\csfmt{pi}}}, which \bibgls's \TeX\
+interpreter converts to the Unicode symbol \hex{1D70B} (mathematical
+italic small pi, $\pi$). The interpreter used by \bibgls\ recognises
+all the standard mathematical Greek commands, and also the missing
+Greek commands \gls{omicron}, \gls{Alpha} etc (which are provided by
+\sty{glossaries-extra-bib2gls}). Using these commands rather than
+the Latin equivalent ensures correct sorting (\gls{omicron} comes
+between \csfmt{xi} and \csfmt{pi}, but \code{o} comes between \code{n}
+and \code{p}). See \sectionref{sec:texparserlib} (\TeX\ Parser
+Library) in the \bibgls\ user manual for further details.
+
+\begin{important}
+The default sort method is designed for words and phrases, so
+non-letters, such as punctuation characters, are discarded.
+If your sort values include symbols that need to be taken into
+account by the comparator, use \csopt[none]{break-at} to prevent
+them from being discarded.
+\end{important}
+
+Alternatively, you may prefer to sort symbols according to the
+description:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\gls{GlsXtrLoadResources}\oarg{\csopt[description]{symbol-sort-fallback}}
+\end{codeenv}
+
+There's a similar entry type \atentry{number}, which behaves much
+like \atentry{symbol} except that it sets the default
+\field{category} to \code{number}. It also follows the
+\csopt{symbol-sort-fallback} setting. For example, the \code{pi}
+entry could be defined as:
+\begin{codeenv}
+\atentry{symbol}\marg{pi,
+ \field{name} = \marg{\gls{ensuremath}\marg{\cmd{pi}}},
+ \field{description} = \marg{Archimedes' constant},
+ \fieldfmt{value} = \marg{3.141592654}
+}
+\end{codeenv}
+I've used a custom field here (\fieldfmt{value}) that \bibgls\ will
+ignore by default. I can instruct \bibgls\ to convert this to a
+known field with \csopt{field-aliases}. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[value=user1]{field-aliases}}
+\end{codeenv}
+This makes \bibgls\ treat;
+\begin{codeenv}
+ \fieldfmt{value} = \marg{3.141592654}
+\end{codeenv}
+as though it had been:
+\begin{codeenv}
+ \fieldfmt{user1} = \marg{3.141592654}
+\end{codeenv}
+This can now be used in one of the hooks (described in
+\sectionref{sec:glsformats}). For example, the
+\idx{postdescriptionhook}:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\gls{glsdefpostdesc}\marg{number}\marg{\comment{check if \field{user1} field given:}
+ \gls{glsxtrifhasfield}\marg{\field{useri}}\marg{\gls{glscurrententrylabel}}
+ \marg{ (\gls{glscurrentfieldvalue})}
+ \marg{}\comment{not provided}
+}
+\end{codeenv}
+It can also be used if you want to order the entries numerically.
+For example:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[value=user1]{field-aliases},
+ \csopt[double]{sort},\comment{use double-precision numeric comparisons}
+ \csopt[user1]{sort-field}
+}
+\end{codeenv}
+This uses \csopt{sort-field} to set the field used for sorting. This
+affects all entry types.
+
+There are more examples in \sectionref{sec:examples} of the main
+\bibgls\ user manual.
+
+\section{Indexing}
+
+By default, \bibgls\ selects entries from the specified \ext{bib}
+files that have been directly indexed in the document or that are
+dependencies of selected entries. Indexing is performed through
+commands like \gls{gls} and \gls{glssymbol} (but not by commands
+like \gls{glsentrysymbol}). The \styopt{record} package option
+ensures that the indexing is done that matches the requirements of
+\bibgls\ (rather than the default \gls{makeindex} syntax).
+
+Each instance of \gls{gls}, \gls{glssymbol} etc writes a
+\pidx{record} to the \ext{aux} file, that includes the entry's
+label, the location in the document where the record was triggered
+and the associated format to encapsulate the location. For example,
+if \code{\gls{gls}\marg{duck}} appears on page~3, the record label
+is \code{duck}, the location is~3 and the format is the default
+\gls{glsnumberformat}.
+
+The format can be changed with the \glsopt{format} key. For example:
+\begin{codeenv}
+\gls{gls}\oarg{\glsopt{format}=hyperbf}\marg{duck}
+\end{codeenv}
+This sets the format to \code{hyperbf}, which makes a bold
+hyperlink, if \sty{hyperref} has been loaded, otherwise it just uses
+\gls{textbf}. The value of the \glsopt{format} option should be the
+name (without a leading backslash) of a text-block command that
+takes a single argument (the location to be formatted). The
+\sty{glossaries} package provides some commands like \gls{hyperbf}
+that may be used to ensure a hyperlink (if supported). The basic
+command is:
+\nosecformatdef{glshypernumber}
+which provides the hyperlink (if enabled) otherwise it just does its
+argument. So, if you want, for example, an underlined hyperlink:
+\begin{codeenv}
+\cmd{newcommand}\marg{\cmd{hyperul}}[1]\marg{\gls[noindex=false]{underline}\marg{\gls{glshypernumber}\marg{\gls{param}1}}}
+\end{codeenv}
+Now you can use \glsopt[hyperul]{format}.
+
+There's a special command \gls{glsignore} that ignores its argument.
+With \gls{makeindex} and \gls{xindy}, this can lead to spurious
+commas in the \idx{locationlist}, because the location is still
+included in the list, even though the location itself isn't
+displayed (since it's discarded by \gls{glsignore}). However, \bibgls\
+recognises \glsopt[glsignore]{format} as a special \idx{ignoredrecord}. This
+indicates that \bibgls\ should select that particular entry but not
+include that record in the \idx{locationlist}.
+
+If a selected entry depends on another entry that hasn't been
+indexed, for example, a parent entry, then the dependent entry will
+automatically be selected as well, by default. The dependent entry
+won't have a \idx{locationlist} if it hasn't been indexed anywhere.
+If you don't want the \idxpl{locationlist} to appear in a particular
+glossary, use \printglossopt{nonumberlist} in the optional argument
+of \gls{printunsrtglossary}.
+
+If you want to index an entry without actually displaying any text,
+you can use:
+\nosecformatdef{glsadd}
+where \meta{label} is the entry's label. The \glsaddopt{format} key
+is again available in \meta{options}. For example:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment
+ \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{param}1}\comment{}
+}
+\end{codeenv}
+This automatically indexes the given entry in the
+\idx{postnamehook}. This is redundant if you only have a single
+glossary, but may be useful if the entry is repeated in a later
+list. Alternatively, if you are using a dual entry type (see
+\sectionref{sec:dualentry} in the main \bibgls\ user manual), the
+hook could check for the existence of the dual label (identified by
+the \csopt{dual-field} resource option) and use that instead. For
+example:
+\begin{codeenv}\renewcommand{\glslinkpresetkeys}{}%
+\cmd{renewcommand}\marg{\gls{glsextrapostnamehook}}[1]\marg{\comment
+ \gls{glsxtrifhasfield}\marg{\gls{GlsXtrDualField}}\marg{\gls{param}1}
+ \marg{\comment{}
+ \gls{glsadd}\oarg{\glsaddopt{format}=hyperbf}\marg{\gls{glscurrentfieldvalue}}\comment{}
+ }\comment{}
+ \marg{}\comment{no dual}
+}
+\end{codeenv}
+
+If you want to index multiple entries at the same time with the same
+set of options, you can use:
+\nosecformatdef{glsaddeach}
+This just iterates through the comma-separated list of labels and
+performs \gls{glsadd}\oargm{options}\margm{label} for each label in
+\meta{label list}. For example, to ensure that \bibgls\ selects the
+entries with the labels \code{duck}, \code{goose} and \code{parrot},
+even if they aren't referenced in the document:
+\begin{codeenv}
+\gls{glsaddeach}\oarg{\glsaddopt[glsignore]{format}}\marg{duck,goose,parrot}
+\end{codeenv}
+To select all entries, regardless of whether or not they have been
+indexed, use the \csopt[all]{selection} resource option. There are
+other selection criteria. See the main \bibgls\ user manual for
+further details.
+
+\bibliographystyle{plain}
+\bibliography{bib2gls-cite}
+
+\printunsrtglossary*
+ [style=treegroup,title={Command Summary},nonumberlist]
+{%
+ \renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsifcategory{#1}{command}{}{\printunsrtglossaryskipentry}%
+ }%
+ \glssetcategoryattribute{command}{glossdesc}{firstuc}%
+ \renewcommand*{\csfmtfont}[1]{\texttt{\color{cs}#1}}%
+ \renewcommand{\glstreenamefmt}{\texttt}%
+ \renewcommand{\glstreegroupheaderfmt}{\textbf}%
+ \renewcommand{\glstreesubitem}{\glspar\parindent=2em\hangindent2em}%
+ \renewcommand{\glstreepredesc}{\glsadd{\glscurrententrylabel}%
+ \nopagebreak\glstreesubitem}%
+ \glsdefpostname{command}{\glsentryuseri{\glscurrententrylabel}}%
+ \glsdefpostdesc{command}{.\nopagebreak\glstreesubitem
+ \Glsentryuserii{\glscurrententrylabel}.%
+ \glspar\medskip}%
+}
+
+\renewcommand*{\glstarget}[2]{%
+ \glsifcategory{#1}{command}{#2}%
+ {%
+ \glsifcategory{#1}{standalone}{#2}%
+ {\glsdohypertarget{\glolinkprefix#1}{#2}}%
+ }%
+}
+\renewcommand{\glstreeitem}{\par\parindent0pt}
+\renewcommand*{\glsxtrbookindexprelocation}[1]{%
+ \glsxtrifhasfield{location}{#1}%
+ {\enspace
+ \textcolor{lightgray}{\nolinebreak\cleaders\hbox to .5em{\hss.\hss}\hfill}%
+ \enspace}%
+ {}%
+}
+\renewcommand*{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsxtriflabelinlist{\glscategory{#1}}{standalone,hierarchical,homograph}%
+ {\printunsrtglossaryskipentry}{}%
+}%
+\printunsrtglossary[style=bookindex,title=Index]
+\end{document}
Property changes on: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-begin.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-cite.bib 2018-05-09 22:21:20 UTC (rev 47658)
@@ -4,7 +4,7 @@
author = "Nicola Talbot",
title = "The \sty{glossaries} package",
note = {\url{https://ctan.org/pkg/glossaries}},
- year = 2017
+ year = 2018
}
@misc{glossaries-extra,
@@ -11,9 +11,16 @@
author = "Nicola Talbot",
title = "The \sty{glossaries-extra} package",
note = {\url{https://ctan.org/pkg/glossaries-extra}},
- year = 2017
+ year = 2018
}
+ at misc{accsupp,
+ author = "Heiko Oberdiek",
+ title = "The \sty{accsupp} package",
+ note = {\url{https://ctan.org/pkg/accsupp}},
+ year = 2018
+}
+
@misc{tex.sx,
title={Is there a program for managing glossary tags?},
note={\url{https://tex.stackexchange.com/questions/342544}},
@@ -78,6 +85,20 @@
year = 2018
}
+ at misc{gallery,
+ author = {Nicola Talbot},
+ title = {{Dickimaw Books} Gallery},
+ note = {\url{https://www.dickimaw-books.com/gallery/}},
+ year = 2018
+}
+
+ at misc{glossarystylesgallery,
+ author = {Nicola Talbot},
+ title = {Gallery (All Styles Provided by \sty{glossaries})},
+ note = {\url{https://www.dickimaw-books.com/gallery/glossaries-styles/}},
+ year = 2018
+}
+
@inbook{iterationtips,
author = "Nicola L. C. Talbot",
title = "{\LaTeX} for Administrative Work",
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib 2018-05-09 22:21:20 UTC (rev 47658)
@@ -1,6 +1,8 @@
% Encoding: UTF-8
- at preamble{"\providecommand{\dhyphen}{-}"}
+ at preamble{"\providecommand{\dhyphen}{-}
+\providecommand{\csfmt}[1]{\texttt{\glsbackslash #1}}%
+\providecommand{\derivfn}[1]{f'(#1)}"}
@abbreviation{IETF,
short = {IETF},
@@ -34,6 +36,12 @@
category={common}
}
+ at abbreviation{ASCII,
+ short = {ASCII},
+ long = {American Standard Code for Information Interchange},
+ category={common}
+}
+
@dualindexentry{bibglsnewentry,
name={\csfmt{bib\-gls\-new\-entry}},
user1={\margm{label}\margm{options}\margm{name}\margm{description}},
@@ -62,6 +70,13 @@
category={command}
}
+ at 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}},
+ category={command}
+}
+
@dualindexentry{bibglsnewabbreviation,
name={\csfmt{bib\-gls\-new\-abbreviation}},
user1={\margm{label}\margm{options}\margm{short}\margm{long}},
@@ -276,7 +291,7 @@
@dualindexentry{bibglsseesep,
name={\csfmt{bib\-gls\-see\-sep}},
user1={},
- description={separator between \gls[noindex]{dual.field.see}
+ description={separator between \field{see}
cross-references and location list},
category={command}
}
@@ -284,7 +299,7 @@
@dualindexentry{bibglsaliassep,
name={\csfmt{bib\-gls\-alias\-sep}},
user1={},
- description={separator between \gls[noindex]{dual.field.alias}
+ description={separator between \field{alias}
cross-reference and location list},
category={command}
}
@@ -291,7 +306,7 @@
@dualindexentry{bibglsseealsosep,
name={\csfmt{bib\-gls\-see\-also\-sep}},
user1={},
- description={separator between \gls[noindex]{dual.field.seealso}
+ description={separator between \field{seealso}
cross-references and location list},
category={command}
}
@@ -440,6 +455,13 @@
category={command}
}
+ at dualindexentry{bibglssetlastgrouptitle,
+ name={\csfmt{bib\-gls\-set\-last\-group\-title}},
+ user1={\margm{cs}\margm{group specs}},
+ description={sets the last group title},
+ category={command}
+}
+
@dualindexentry{bibglssetlettergrouptitle,
name={\csfmt{bib\-gls\-set\-letter\-group\-title}},
user1={\marg{\margm{title}\margm{letter}\margm{id}\margm{type}}},
@@ -807,11 +829,22 @@
@dualindexentry{longnewglossaryentry,
name={\csfmt{long\-new\-glossary\-entry}},
user1={\margm{label}\margm{\keyvallist}\margm{description}},
- description={defines a new glossary entry},
+ description={defines a new glossary entry and appends
+ \csfmt{leavemode}\csfmt{unskip}\gls{nopostdesc} at the end of
+\meta{description}},
note={provided by \styfmt{glossaries}},
category={command}
}
+ at index{longnewglossaryentry*,
+ name={\csfmt{long\-new\-glossary\-entry*}},
+ 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+},
+ category={command}
+}
+
@dualindexentry{provideglossaryentry,
name={\csfmt{provide\-glossary\-entry}},
user1={\margm{label}\margm{\keyvallist}},
@@ -834,8 +867,9 @@
name={\csfmt{new\-term}},
user1={\oargm{\keyvallist}\margm{label}},
description={defines a new glossary entry where the
- \gls[noindex]{dual.field.description} field defaults to empty},
- note={provided by \styfmt{glossaries}},
+ \field{description} field defaults to empty},
+ note={provided by the \styfmt{glossaries}'s \styopt{index} package
+option},
category={command}
}
@@ -851,7 +885,7 @@
name={\csfmt{new\-acronym}},
user1={\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}},
description={defines a new abbreviation with the
- \gls[noindex]{dual.field.category} set to \code{acronym}},
+ \field{category} set to \code{acronym}},
note={provided by \styfmt{glossaries}},
category={command}
}
@@ -860,7 +894,8 @@
name={\csfmt{gls\-xtr\-new\-symbol}},
user1={\oargm{\keyvallist}\margm{label}\margm{symbol}},
description={defines a new symbol},
- note={provided by \styfmt{glossaries-extra}},
+ note={provided by \styfmt{glossaries-extra}'s \styopt{symbols}
+package option},
category={command}
}
@@ -868,7 +903,8 @@
name={\csfmt{gls\-xtr\-new\-number}},
user1={\oargm{\keyvallist}\margm{label}},
description={defines a new number},
- note={provided by \styfmt{glossaries-extra}},
+ note={provided by \styfmt{glossaries-extra}'s \styopt{numbers}
+package option},
category={command}
}
@@ -918,6 +954,27 @@
category={command}
}
+ at dualindexentry{GlsXtrDualBackLink,
+ 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+},
+ category={command}
+}
+
+ at dualindexentry{GlsXtrDualField,
+ 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
+ value is given by \csopt{dual-field}},
+ note={internal command provided by
+ \styfmt{glossaries-extra-bib2gls} v1.30+},
+ category={command}
+}
+
@dualindexentry{glsxtrfmt,
name={\csfmt{gls\-xtr\-fmt}},
user1={\oargm{options}\margm{label}\margm{text}},
@@ -946,6 +1003,18 @@
category={command}
}
+ at 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
+\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}},
+ category={command}
+}
+
@dualindexentry{glsxtrresourcefile,
name={\csfmt{gls\-xtr\-resource\-file}},
user1={\oargm{options}\margm{filename}},
@@ -1087,6 +1156,27 @@
parent={resourceoptions}
}
+ at dualindexentry{opt.sort-replace,
+ name={\csoptfmt{sort\dhyphen replace}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+ at dualindexentry{opt.dual-sort-replace,
+ name={\csoptfmt{dual\dhyphen sort\dhyphen replace}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
+ at dualindexentry{opt.secondary-sort-replace,
+ name={\csoptfmt{secondary\dhyphen sort\dhyphen replace}},
+ user1={\meta{list}},
+ category={resourceoption},
+ parent={resourceoptions}
+}
+
@dualindexentry{opt.action,
name={\csoptfmt{action}},
user1={\meta{value}},
@@ -1440,7 +1530,7 @@
@dualindexentry{opt.save-child-count,
name={\csoptfmt{save\dhyphen child\dhyphen count}},
- user1={\meta{value}},
+ user1={\meta{boolean}},
category={resourceoption},
parent={resourceoptions}
}
@@ -2287,7 +2377,7 @@
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 \gls[noindex]{dual.field.loclist} field},
+ the \field{loclist} field},
note={provided by \styfmt{glossaries}},
category={command}
}
@@ -2307,9 +2397,30 @@
description={adds the given item to the given field that contains
an \styfmt{etoolbox} internal list},
note={provided by \styfmt{glossaries-extra} v1.12+},
+ seealso={glsxtrfieldifinlist,glsxtrfieldforlistloop,glsxtrfielddolistloop},
category={command}
}
+ at index{glsxtrfieldifinlist,
+ name={\csfmt{gls\-xtr\-field\-if\-in\-list}},
+ 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+},
+ seealso={glsxtrfieldxifinlist,glsxtrfieldlistadd,glsxtrfieldforlistloop,glsxtrfielddolistloop},
+ category={command}
+}
+
+ at index{glsxtrfieldxifinlist,
+ name={\csfmt{gls\-xtr\-field\-x\-if\-in\-list}},
+ 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+},
+ seealso={glsxtrfieldifinlist},
+ category={command}
+}
+
@index{alpha,
name={\csfmt{alpha}},
user1={},
@@ -2326,6 +2437,14 @@
category={command}
}
+ at index{Alpha,
+ name={\csfmt{Alpha}},
+ user1={},
+ description={Greek letter alpha $\Alpha$},
+ note={provided by \styfmt{glossaries-extra-bib2gls}},
+ category={command}
+}
+
@index{bigoperatornamefmt,
name={\csfmt{bigoperatornamefmt}},
user1={\margm{text}},
@@ -2511,6 +2630,12 @@
parent={fileformats}
}
+ at index{toc,
+ name={\extfmt{toc}},
+ category={fileformat},
+ parent={fileformats}
+}
+
@index{glstex,
name={\extfmt{glstex}},
category={fileformat},
@@ -2517,6 +2642,12 @@
parent={fileformats}
}
+ at index{bbl,
+ name={\extfmt{bbl}},
+ category={fileformat},
+ parent={fileformats}
+}
+
@index{applications,
name={applications},
text={applications}
@@ -2821,6 +2952,12 @@
parent={packages}
}
+ at index{slantsc,
+ name={\styfmt{slantsc}},
+ category={package},
+ parent={packages}
+}
+
@index{babel,
name={\styfmt{babel}},
category={package},
@@ -2875,6 +3012,18 @@
parent={packages}
}
+ at index{soul,
+ name={\styfmt{soul}},
+ category={package},
+ parent={packages}
+}
+
+ at index{xcolor,
+ name={\styfmt{xcolor}},
+ category={package},
+ parent={packages}
+}
+
@index{tracklang,
name={\styfmt{tracklang}},
category={package},
@@ -2881,11 +3030,22 @@
parent={packages}
}
+ at index{accsupp,
+ name={\styfmt{accsupp}},
+ category={package},
+ parent={packages}
+}
+
@index{stringconcat,
name={\code{\#} (string concatenation)},
text={\code{\#}}
}
+ at index{atchar,
+ name={\code{@} (bib entry identifier)},
+ text={\code{@}}
+}
+
@index{param,
name={\code{\#} (parameter)},
text={\code{\#}}
@@ -2981,7 +3141,11 @@
}
@index{cs.circum,
- name={\csfmt{\char`\^}}
+ name={\csfmt{\char`\^}},
+ user1={\margm{character}},
+ description={puts a circumflex accent over \meta{character}},
+ note={kernel command},
+ category={command}
}
@index{mshiftchar,
@@ -3022,6 +3186,10 @@
text={\code{\glstildechar}}
}
+ at index{doublequotechar,
+ name = {\code{"}}
+}
+
@index{cs.tilde,
name={\csfmt{\glstildechar}}
}
@@ -3056,9 +3224,28 @@
category={command}
}
+ at index{csdef,
+ name={\csfmt{csdef}},
+ user1={\margm{cs-name}\meta{syntax}\margm{definition}},
+ 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}},
+ category={command}
+}
+
@index{xifinlist,
name={\csfmt{xifinlist}},
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}},
+ category={command}
+}
+
+ at index{ifinlist,
+ name={\csfmt{ifinlist}},
+ 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}},
@@ -3074,6 +3261,15 @@
category={command}
}
+ at index{listgadd,
+ name={\csfmt{listgadd}},
+ 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}},
+ category={command}
+}
+
@index{marvosym,
name={\styfmt{marvosym}},
category={package},
@@ -3113,67 +3309,119 @@
category={environment}
}
+ at index{env.tabular,
+ name={\envfmt{tabular}},
+ category={environment}
+}
+
+ at index{supertabular,
+ name={\styfmt{supertabular}},
+ category={package},
+ parent={packages}
+}
+
+ at index{env.supertabular,
+ name={\envfmt{supertabular}},
+ category={environment}
+}
+
+ at index{env.theglossary,
+ name={\envfmt{theglossary}},
+ category={environment}
+}
+
@index{abbreviationstyles,
name={abbreviation styles},
text={abbreviation style}
}
+ at index{long-noshort,
+ name={\abbrstylefmt{long\dhyphen noshort}},
+ category={abbreviationstyle},
+ parent={abbreviationstyles}
+}
+
@index{long-noshort-desc,
- name={\abbrstylefmt{long-noshort-desc}},
+ name={\abbrstylefmt{long\dhyphen noshort\dhyphen desc}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{long-short-sc,
- name={\abbrstylefmt{long-short-sc}},
+ name={\abbrstylefmt{long\dhyphen short\dhyphen sc}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{long-short-sm,
- name={\abbrstylefmt{long-short-sm}},
+ name={\abbrstylefmt{long\dhyphen short\dhyphen sm}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
+ at index{long-short-em,
+ name={\abbrstylefmt{long\dhyphen short\dhyphen em}},
+ category={abbreviationstyle},
+ parent={abbreviationstyles}
+}
+
@index{long-short,
- name={\abbrstylefmt{long-short}},
+ name={\abbrstylefmt{long\dhyphen short}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{long-short-user,
- name={\abbrstylefmt{long-short-user}},
+ name={\abbrstylefmt{long\dhyphen short\dhyphen user}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{long-short-desc,
- name={\abbrstylefmt{long-short-desc}},
+ name={\abbrstylefmt{long\dhyphen short\dhyphen desc}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{long-short-user-desc,
- name={\abbrstylefmt{long-short-user-desc}},
+ name={\abbrstylefmt{long\dhyphen short\dhyphen user\dhyphen desc}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
+ at index{long-hyphen-short-hyphen,
+ name={\abbrstylefmt{long\dhyphen hyphen\dhyphen short\dhyphen
+hyphen}},
+ category={abbreviationstyle},
+ parent={abbreviationstyles}
+}
+
@index{long-postshort-user-desc,
- name={\abbrstylefmt{long-postshort-user-desc}},
+ name={\abbrstylefmt{long\dhyphen postshort\dhyphen user\dhyphen desc}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@index{short-long,
- name={\abbrstylefmt{short-long}},
+ name={\abbrstylefmt{short\dhyphen long}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
+ at index{short-nolong,
+ name={\abbrstylefmt{short\dhyphen nolong}},
+ category={abbreviationstyle},
+ parent={abbreviationstyles}
+}
+
+ at index{short-sc-nolong,
+ name={\abbrstylefmt{short\dhyphen sc\dhyphen nolong}},
+ category={abbreviationstyle},
+ parent={abbreviationstyles}
+}
+
@index{long-only-short-only,
- name={\abbrstylefmt{long-only-short-only}},
+ name={\abbrstylefmt{long\dhyphen only\dhyphen short\dhyphen only}},
category={abbreviationstyle},
parent={abbreviationstyles}
}
@@ -3201,6 +3449,30 @@
parent={glossarystyle}
}
+ at index{glostyle.tree,
+ name={\glostylefmt{tree}},
+ category={glossarystyle},
+ parent={glossarystyle}
+}
+
+ at index{glostyle.treegroup,
+ name={\glostylefmt{treegroup}},
+ category={glossarystyle},
+ parent={glossarystyle}
+}
+
+ at index{glostyle.treenoname,
+ name={\glostylefmt{treenoname}},
+ category={glossarystyle},
+ parent={glossarystyle}
+}
+
+ at index{glostyle.treenonamegroup,
+ name={\glostylefmt{treenonamegroup}},
+ category={glossarystyle},
+ parent={glossarystyle}
+}
+
@index{glostyle.alttree,
name={\glostylefmt{alttree}},
category={glossarystyle},
@@ -3272,72 +3544,168 @@
text={category attribute}
}
+ at index{attribute,
+ name = {attributes},
+ text = {attribute},
+ alias = {categoryattribute}
+}
+
@index{recordcount,
- name={\catattrfmt{recordcount}},
+ name={\catattrfmt{record\-count}},
category={categoryattribute},
parent={categoryattribute}
}
@index{glossname,
- name={\catattrfmt{glossname}},
+ name={\catattrfmt{gloss\-name}},
category={categoryattribute},
parent={categoryattribute}
}
@index{glossnamefont,
- name={\catattrfmt{glossnamefont}},
+ name={\catattrfmt{gloss\-name\-font}},
category={categoryattribute},
parent={categoryattribute}
}
+ at index{glossdesc,
+ name={\catattrfmt{gloss\-desc}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
@index{glossdescfont,
- name={\catattrfmt{glossdescfont}},
+ name={\catattrfmt{gloss\-desc\-font}},
category={categoryattribute},
parent={categoryattribute}
}
@index{textformat,
- name={\catattrfmt{textformat}},
+ name={\catattrfmt{text\-format}},
category={categoryattribute},
parent={categoryattribute}
}
+ at index{headuc,
+ name={\catattrfmt{headuc}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
@index{aposplural,
- name={\catattrfmt{aposplural}},
+ name={\catattrfmt{apos\-plural}},
category={categoryattribute},
parent={categoryattribute}
}
+ at index{accessaposplural,
+ name={\catattrfmt{access\-apos\-plural}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
@index{noshortplural,
- name={\catattrfmt{noshortplural}},
+ name={\catattrfmt{no\-short\-plural}},
category={categoryattribute},
parent={categoryattribute}
}
+ at index{accessnoshortplural,
+ name={\catattrfmt{access\-no\-short\-plural}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{nameshortaccess,
+ name={\catattrfmt{name\-short\-access}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{firstshortaccess,
+ name={\catattrfmt{first\-short\-access}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{textshortaccess,
+ name={\catattrfmt{text\-short\-access}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{markwords,
+ name={\catattrfmt{mark\-words}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{markshortwords,
+ name={\catattrfmt{mark\-short\-words}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
@index{targeturl,
- name={\catattrfmt{targeturl}},
+ name={\catattrfmt{target\-url}},
category={categoryattribute},
parent={categoryattribute}
}
@index{targetname,
- name={\catattrfmt{targetname}},
+ name={\catattrfmt{target\-name}},
category={categoryattribute},
parent={categoryattribute}
}
@index{externallocation,
- name={\catattrfmt{externallocation}},
+ name={\catattrfmt{external\-location}},
category={categoryattribute},
parent={categoryattribute}
}
@index{discardperiod,
- name={\catattrfmt{discardperiod}},
+ name={\catattrfmt{discard\-period}},
category={categoryattribute},
parent={categoryattribute}
}
+ at index{pluraldiscardperiod,
+ name={\catattrfmt{plural\-discard\-period}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{retainfirstuseperiod,
+ name={\catattrfmt{retain\-first\-use\-period}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{insertdots,
+ name={\catattrfmt{insert\-dots}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{accessinsertdots,
+ name={\catattrfmt{access\-insert\-dots}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{tagging,
+ name={\catattrfmt{tagging}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
+ at index{nohyperfirst,
+ name={\catattrfmt{no\-hyper\-first}},
+ category={categoryattribute},
+ parent={categoryattribute}
+}
+
@index{ctr.equation,
name={\counterfmt{equation}},
category={counter}
@@ -3358,6 +3726,16 @@
category={counter}
}
+ at index{ctr.glossaryentry,
+ name={\counterfmt{glossaryentry}},
+ category={counter}
+}
+
+ at index{ctr.glossarysubentry,
+ name={\counterfmt{glossarysubentry}},
+ category={counter}
+}
+
@index{labelprefixes,
name={label prefixes},
text={label prefix},
@@ -3387,138 +3765,684 @@
text={package option}
}
- at index{styopt.record,
+ at dualindexentry{styopt.record,
name={\styoptfmt{record}},
+ 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
+ the entry definitions but \idx{makeindex} or \idx{xindy} is used
+ for the indexing)},
+ package={glossaries-extra},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.automake,
- name={\styoptfmt{automake}},
+ at dualindexentry{styopt.accsupp,
+ name={\styoptfmt{accsupp}},
+ description={load the \sty{glossaries-accsupp} package to provide
+ accessibility support},
+ package={glossaries,glossaries-extra},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.shortcuts,
- name={\styoptfmt{shortcuts}},
+ at dualindexentry{styopt.abbreviations,
+ name={\styoptfmt{abbreviations}},
+ description={creates the \code{abbreviations} glossary},
+ package={glossaries-extra},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.accsupp,
- name={\styoptfmt{accsupp}},
+ at dualindexentry{styopt.symbols,
+ name={\styoptfmt{symbols}},
+ package={glossaries,glossaries-extra},
+ description={defines the \code{symbols} glossary; with
+ \styfmt{glossaries-extra} additionally defines
+ \gls{glsxtrnewsymbol}},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.abbreviations,
- name={\styoptfmt{abbreviations}},
+ at dualindexentry{styopt.numbers,
+ name={\styoptfmt{numbers}},
+ package={glossaries,glossaries-extra},
+ description={defines the \code{numbers} glossary; with
+ \styfmt{glossaries-extra} additionally defines
+ \gls{glsxtrnewnumber}},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.symbols,
- name={\styoptfmt{symbols}},
+ at dualindexentry{styopt.undefaction,
+ name={\styoptfmt{undefaction}},
+ user1={\meta{value}},
+ description={indicates what to do if an undefined entry is
+ referenced: \styoptfmt{warn} (generate a warning and show ?? in
+ the text, default with \styopt{record}), \styoptfmt{error}
+ (generate an error)},
+ package={glossaries-extra},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.numbers,
- name={\styoptfmt{numbers}},
+ at dualindexentry{styopt.indexcrossrefs,
+ name={\styoptfmt{indexcrossrefs}},
+ user1={\meta{boolean}},
+ package={glossaries-extra},
category={packageoption},
+ parent={packageoptions},
+ description={if true, at the end of
+ the document automatically index cross-referenced entries that
+ haven't been marked as used},
+ note={not relevant with \bibgls}
+}
+
+ at dualindexentry{styopt.autoseeindex,
+ name={\styoptfmt{autoseeindex}},
+ user1={\meta{boolean}},
+ package={glossaries-extra},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={if true, the \field{see} and \field{seealso} keys
+ automatically indexes the cross-referenced term}
+}
+
+ at dualindexentry{styopt.nopostdot,
+ name={\styoptfmt{nopostdot}},
+ user1={\meta{boolean}},
+ package={glossaries,glossaries-extra},
+ description={if true, suppresses the automatic post-description
+ punctuation. With \styfmt{glossaries-extra} you can also use
+ \styopt[none]{postpunc} instead of \styopt[true]{nopostdot} and
+ \styopt{postdot} or \styopt[dot]{postpunc} instead of
+ \styopt[false]{nopostdot}},
+ category={packageoption},
parent={packageoptions}
}
- at index{styopt.sort,
- name={\styoptfmt{sort}},
+ at dualindexentry{styopt.postdot,
+ name={\styoptfmt{postdot}},
+ package={glossaries-extra},
+ description={equivalent to \styopt[dot]{postpunc}},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.undefaction,
- name={\styoptfmt{undefaction}},
+ at dualindexentry{styopt.postpunc,
+ name={\styoptfmt{postpunc}},
+ user1={\meta{value}},
+ package={glossaries-extra},
category={packageoption},
+ parent={packageoptions},
+ description={controls the automatic post-description punctuation;
+ the value may be one of: \styoptfmt{none} (not required,
+ the \field{description} or glossary style already supplies the
+ terminating punctuation), \styoptfmt{comma} (use a comma),
+ \styoptfmt{dot} (use a \idx{full-stop} with the space factor
+ adjusted), \meta{punctuation} (use \meta{punctuation})}
+}
+
+ at dualindexentry{styopt.indexcounter,
+ name={\styoptfmt{index\-counter}},
+ description={creates the \gls{ctr.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},
+ category={packageoption},
parent={packageoptions}
}
- at index{styopt.nomain,
+ at dualindexentry{styopt.docdef,
+ name={\styoptfmt{docdef}},
+ user1={\meta{value}},
+ package={glossaries-extra},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={determines whether
+ entries can be defined in the \envfmt{document} environment; the
+ \meta{value} may be one of: \styoptfmt{false} (entries must be
+ defined in the preamble), \styoptfmt{true} (entries may be defined
+ in the \envfmt{document} environment), \styoptfmt{restricted}
+ (entries may only be defined in the \envfmt{document} environment
+ if the definition comes before all glossaries and before any
+ reference to the entry)}
+}
+
+ at dualindexentry{styopt.nomissingglstext,
+ name={\styoptfmt{nomissingglstext}},
+ user1={\meta{boolean}},
+ package={glossaries-extra},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={if true, suppress the
+ warning text that appears in the document with \cs{printglossary}
+ if the associated external file doesn't exist}
+}
+
+ at dualindexentry{styopt.stylemods,
+ name={\styoptfmt{stylemods}},
+ user1={\meta{value}},
+ description={load the \gls{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}
+ (equivalent to omitting \meta{value}) and \styoptfmt{all}, which
+ loads all predefined styles},
+ package={glossaries-extra},
+ category={packageoption},
+ parent={packageoptions}
+}
+
+ at dualindexentry{styopt.nowarn,
+ name={\styoptfmt{nowarn}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={suppresses all \styfmt{glossaries}-related warnings}
+}
+
+ at dualindexentry{styopt.nolangwarn,
+ name={\styoptfmt{nolangwarn}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={suppresses warnings generated by missing language modules}
+}
+
+ at dualindexentry{styopt.noredefwarn,
+ name={\styoptfmt{noredefwarn}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={suppresses warnings if overriding glossary commands
+ provided by another class or package}
+}
+
+ at dualindexentry{styopt.debug,
+ name={\styoptfmt{debug}},
+ user1={\meta{value}},
+ package={glossaries,glossaries-extra},
+ category={packageoption},
+ parent={packageoptions},
+ description={add debugging information; allowed values:
+ \styoptfmt{false} (default), \styoptfmt{true} (info added to
+ transcript), \styoptfmt{showtargets} (info added to transcript
+ and show target name in the document for glossary-related
+ hyperlinks), \styoptfmt{showwrgloss}\extstyopt\ show mark in
+ document where indexing occurs and \styoptfmt{all}\extstyopt\
+ (implement both \styoptfmt{showtargets} and
+ \styoptfmt{showwrgloss})}
+}
+
+ at dualindexentry{styopt.seenoindex,
+ name={\styoptfmt{seenoindex}},
+ user1={\meta{value}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={determines whether the
+ \field{see} key automatically indexes the entry using \cs{glsadd};
+ allowed values: \styoptfmt{error} (attempts indexing but triggers
+ an error if used before \cs{cs.makeglossaries}); \styoptfmt{warn}
+ (attempts indexing but triggers a warning if used before
+ \cs{cs.makeglossaries}); \styoptfmt{ignore} (attempts indexing but
+ does nothing if used before \cs{cs.makeglossaries})}
+}
+
+ at dualindexentry{styopt.nomain,
name={\styoptfmt{nomain}},
+ package={glossaries},
category={packageoption},
+ parent={packageoptions},
+ description={suppresses the creation of the default \code{main}
+ glossary. If used an alternative glossary must be created}
+}
+
+ at dualindexentry{styopt.sanitizesort,
+ name={\styoptfmt{sanitizesort}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={determines whether or not
+ to sanitize the \field{sort} key}
+}
+
+ at dualindexentry{styopt.savewrites,
+ name={\styoptfmt{savewrites}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={if true, indexing
+ information is stored in token registers that are only written at
+ the end of the document to save creating a write register per
+ glossary indexing file}
+}
+
+ at dualindexentry{styopt.translate,
+ name={\styoptfmt{translate}},
+ user1={\meta{value}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={determines the multilingual support provided by
+ \styfmt{glossaries}; allowed values: \styoptfmt{true} (default
+ with just base \styfmt{glossaries}; if
+ \styfmt{babel} has been loaded and \styfmt{translator} is
+ installed, use \styfmt{translator} interface), \styoptfmt{false}
+ (don't provide translations), \styoptfmt{babel} (default with
+ \styfmt{glossaries-extra}; don't load the
+ \styfmt{translator} package, just load \styfmt{glossaries-babel})}
+}
+
+ at dualindexentry{styopt.notranslate,
+ name={\styoptfmt{notranslate}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={equivalent to \styopt[false]{translate}}
+}
+
+ at dualindexentry{styopt.nohypertypes,
+ name={\styoptfmt{nohypertypes}},
+ user1={\meta{list}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={suppress hyperlinks for the listed glossary types}
+}
+
+ at dualindexentry{styopt.hyperfirst,
+ name={\styoptfmt{hyperfirst}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if false, terms on first use don't have hyperlinks
+ unless explicitly set (with \styfmt{glossaries-extra}, the
+ \catattr{nohyperfirst} category attribute can selectively apply this)}
+}
+
+ at dualindexentry{styopt.indexonlyfirst,
+ name={\styoptfmt{indexonlyfirst}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, only performs indexing on first use}
+}
+
+ at dualindexentry{styopt.savenumberlist,
+ name={\styoptfmt{savenumberlist}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, stores the number list for each entry (with
+ \bibgls\ use the \csopt{save-locations} resource option instead)}
+}
+
+ at dualindexentry{styopt.toc,
+ name={\styoptfmt{toc}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true (default for \styfmt{glossaries-extra}),
+ automatically add each glossary to the table of contents}
+}
+
+ at dualindexentry{styopt.numberline,
+ name={\styoptfmt{numberline}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={when used with \styopt[true]{toc}, this will add
+ \code{\csfmt{numberline}\marg{}} to the start of the TOC entry}
+}
+
+ at dualindexentry{styopt.section,
+ name={\styoptfmt{section}},
+ user1={\meta{value}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={indicates the sectional unit to use for the glossary
+ heading (the value should be the name of the section command without
+ the leading backslash, for example \styopt[subsection]{section}).
+ 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}}
+}
+
+ at dualindexentry{styopt.ucmark,
+ name={\styoptfmt{ucmark}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, converts the glossary mark (used in page
+ headings) to upper case with \cs{MakeTextUppercase}}
+}
+
+ at dualindexentry{styopt.numberedsection,
+ name={\styoptfmt{numberedsection}},
+ user1={\meta{value}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={determines whether to use numbered or unnumbered
+ section units, and whether or not to automatically add
+ \cs{label}; the value may be one of: \styoptfmt{false} (default, no
+ numbering and no label), \styoptfmt{nolabel} (numbered but no
+ label), \styoptfmt{autolabel} (numbered with automatic label),
+ \styoptfmt{nameref} (unnumbered but labelled). If no value is
+ given \styoptfmt{nolabel} is assumed}
+}
+
+ at dualindexentry{styopt.entrycounter,
+ name={\styoptfmt{entrycounter}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, creates the \counter{glossaryentry} counter
+ and each main (level 0) glossary entry will be
+ numbered (which can be referenced with \cs{glsrefentry} or
+ \cs{glsxtrpageref})}
+}
+
+ at dualindexentry{styopt.counterwithin,
+ name={\styoptfmt{counterwithin}},
+ user1={\meta{counter name}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={automatically sets \styopt[true]{entrycounter} and
+ indicates the master counter for \counter{glossaryentry}}
+}
+
+ at dualindexentry{styopt.subentrycounter,
+ name={\styoptfmt{subentrycounter}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, creates the \counter{glossarysubentry} counter
+ and each level~1 glossary entry will be
+ numbered (which can be referenced with \cs{glsrefentry} or
+ \cs{glsxtrpageref}); this option and associated counter are
+ independent of \styopt{entrycounter} and \counter{glossaryentry}}
+}
+
+ at dualindexentry{styopt.style,
+ name={\styoptfmt{style}},
+ user1={\meta{name}},
+ package={glossaries},
+ description={sets the default glossary style to \meta{name}},
+ category={packageoption},
parent={packageoptions}
}
- at index{styopt.nonumberlist,
- name={\styoptfmt{nonumberlist}},
+ at dualindexentry{styopt.nolong,
+ name={\styoptfmt{nolong}},
+ package={glossaries},
+ description={prevents the \sty{glossary-long} package (which
+ provides the \glostyle{long} styles) from being
+ automatically loaded},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.nogroupskip,
- name={\styoptfmt{nogroupskip}},
+ at dualindexentry{styopt.nosuper,
+ name={\styoptfmt{nosuper}},
+ package={glossaries},
+ description={prevents the \sty{glossary-super} package (which
+ provides the \glostyle{super} styles) from being
+ automatically loaded},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.xindy,
- name={\styoptfmt{xindy}},
+ at dualindexentry{styopt.nolist,
+ name={\styoptfmt{nolist}},
+ package={glossaries},
+ description={prevents the \sty{glossary-list} package (which
+ provides the \glostyle{list} styles) from being
+ automatically loaded},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.nopostdot,
- name={\styoptfmt{nopostdot}},
+ at dualindexentry{styopt.notree,
+ name={\styoptfmt{notree}},
+ package={glossaries},
category={packageoption},
+ parent={packageoptions},
+ description={prevents the \sty{glossary-tree} package (which
+ provides the \glostyle{tree} styles) from being
+ automatically loaded}
+}
+
+ at dualindexentry{styopt.nostyles,
+ name={\styoptfmt{nostyles}},
+ package={glossaries},
+ 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})},
+ category={packageoption},
parent={packageoptions}
}
- at index{styopt.postdot,
- name={\styoptfmt{postdot}},
+ at dualindexentry{styopt.esclocations,
+ name={\styoptfmt{esclocations}},
+ user1={\meta{boolean}},
+ package={glossaries},
category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={if true,
+ \styfmt{glossaries} tries to escape special characters from the
+ locations}
+}
+
+ at dualindexentry{styopt.nonumberlist,
+ name={\styoptfmt{nonumberlist}},
+ package={glossaries},
+ 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
+ \csopt[false]{save-locations} instead},
+ category={packageoption},
parent={packageoptions}
}
- at index{styopt.counter,
+ at dualindexentry{styopt.seeautonumberlist,
+ name={\styoptfmt{seeautonumberlist}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={if \styopt{nonumberlist}
+ is used, this allows the \field{see} key to override the setting
+ for the associated entry}
+}
+
+ at dualindexentry{styopt.counter,
name={\styoptfmt{counter}},
+ user1={\meta{value}},
+ description={sets the default location counter to \meta{value}
+ (which must be the name of a counter). May be overridden on
+ an individual basis using the
+ \glsopt{counter} option in commands like \cs{gls} and \cs{glsadd}},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.indexcounter,
- name={\styoptfmt{index\-counter}},
+ at dualindexentry{styopt.nogroupskip,
+ name={\styoptfmt{nogroupskip}},
+ user1={\meta{boolean}},
+ description={if true, suppresses the visual separation between
+ letter groups},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.index,
- name={\styoptfmt{index}},
+ at dualindexentry{styopt.sort,
+ name={\styoptfmt{sort}},
+ user1={\meta{value}},
+ note={not relevant with \bibgls, use the \csopt{sort}
+ resource option instead},
+ description={indicates how to assign the \field{sort} key if not
+ explicitly set, the value may be one of: \styoptfmt{none} (don't
+ automatically assign the \field{sort} field), \styoptfmt{standard}
+ (obtain the \field{sort} value from the \field{name} field),
+ \styoptfmt{def} (assign the \field{sort} field to a numerical value
+ that represents the order of definition), \styoptfmt{user}
+ (assign the \field{sort} field to a numerical value that
+ represents the order of first use)},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.nostyles,
- name={\styoptfmt{nostyles}},
+ at dualindexentry{styopt.order,
+ name={\styoptfmt{order}},
+ user1={\meta{value}},
+ note={not relevant with \bibgls, use the \csopt{break-at}
+ resource option instead},
+ description={sets whether to use word or letter ordering},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.stylemods,
- name={\styoptfmt{stylemods}},
+ at dualindexentry{styopt.makeindex,
+ name={\styoptfmt{makeindex}},
+ note={not relevant with \bibgls},
+ description={write the indexing
+ information using \idx{makeindex}'s format},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.style,
- name={\styoptfmt{style}},
+ at dualindexentry{styopt.xindy,
+ name={\styoptfmt{xindy}},
+ user1={\meta{settings}},
+ note={not relevant with \bibgls},
+ description={write the indexing
+ information using \idx{xindy}'s format where the optional
+ \meta{settings} may supply the language and code page and whether
+ or not to define the default number group},
+ package={glossaries},
category={packageoption},
parent={packageoptions}
}
- at index{styopt.section,
- name={\styoptfmt{section}},
+ at dualindexentry{styopt.xindygloss,
+ name={\styoptfmt{xindygloss}},
+ package={glossaries},
category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={equivalent to \styopt[\empty]{xindy}}
+}
+
+ at dualindexentry{styopt.xindynoglsnumbers,
+ name={\styoptfmt{xindynoglsnumbers}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ note={not relevant with \bibgls},
+ description={equivalent to \styopt[glsnumbers=false]{xindy}}
+}
+
+ at dualindexentry{styopt.automake,
+ name={\styoptfmt{automake}},
+ user1={\meta{boolean}},
+ description={if true, tries to use \TeX's shell escape to
+ automatically run the required indexing application (may not
+ be permitted by \TeX's security settings)},
+ package={glossaries},
+ category={packageoption},
parent={packageoptions}
}
+ at dualindexentry{styopt.acronym,
+ name={\styoptfmt{acronym}},
+ user1={\meta{boolean}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={if true, creates a new glossary with the label \code{acronym}}
+}
+
+ at dualindexentry{styopt.acronyms,
+ name={\styoptfmt{acronyms}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={equivalent to \styopt[true]{acronym}}
+}
+
+ at dualindexentry{styopt.acronymlists,
+ name={\styoptfmt{acronymlists}},
+ user1={\meta{list}},
+ package={glossaries},
+ category={packageoption},
+ parent={packageoptions},
+ description={identifies the glossaries that are lists of acronyms
+ (don't use with \sty{glossaries-extra})}
+}
+
+ at dualindexentry{styopt.shortcuts,
+ name={\styoptfmt{shortcuts}},
+ package={glossaries,glossaries-extra},
+ user1={\meta{value}},
+ description={sets up short cut commands; the value may be one of
+ \styoptfmt{false} (default), \styoptfmt{true} (assumed if no value
+ supplied, implements
+ \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}
+ shortcuts that use \styfmt{glossaries-extra}'s new abbreviation
+ commands), \styoptfmt{abbreviations}\extstyopt\ (provides \gls{ab}
+ shortcuts), \styoptfmt{other}\extstyopt\ (provides other shortcut
+ commands), \styoptfmt{all}\extstyopt\ (synonym for
+ \styopt[true]{shortcuts}) and \styoptfmt{none}\extstyopt\ (synonym
+ for \styopt[false]{shortcuts})},
+ category={packageoption},
+ parent={packageoptions}
+}
+
+ at dualindexentry{styopt.index,
+ name={\styoptfmt{index}},
+ package={glossaries},
+ description={defines the \code{index} glossary and \gls{newterm}},
+ category={packageoption},
+ parent={packageoptions}
+}
+
@index{fields,
name={fields},
text={field}
@@ -3726,7 +4650,7 @@
@dualindexentry{field.duallong,
name={\fieldfmt{duallong}},
description={The long form of a dual
- abbreviation mapped by \gls{dual.entry.dualabbreviation}.},
+ abbreviation mapped by \atentry{dualabbreviation}.},
note={provided by \appfmt{bib2gls}},
category={bib2glsfield},
parent={fields}
@@ -3735,7 +4659,7 @@
@dualindexentry{field.duallongplural,
name={\fieldfmt{duallongplural}},
description={The plural long form of a dual
- abbreviation mapped by \gls{dual.entry.dualabbreviation}.},
+ abbreviation mapped by \atentry{dualabbreviation}.},
note={provided by \appfmt{bib2gls}},
category={bib2glsfield},
parent={fields}
@@ -3744,7 +4668,7 @@
@dualindexentry{field.dualshort,
name={\fieldfmt{dualshort}},
description={The short form of a dual
- abbreviation mapped by \gls{dual.entry.dualabbreviation}.},
+ abbreviation mapped by \atentry{dualabbreviation}.},
note={provided by \appfmt{bib2gls}},
category={bib2glsfield},
parent={fields}
@@ -3753,7 +4677,7 @@
@dualindexentry{field.dualshortplural,
name={\fieldfmt{dualshortplural}},
description={The plural short form of a dual abbreviation
- mapped by \gls{dual.entry.dualabbreviation}.},
+ mapped by \atentry{dualabbreviation}.},
note={provided by \appfmt{bib2gls}},
category={bib2glsfield},
parent={fields}
@@ -3761,7 +4685,7 @@
@dualindexentry{field.prefix,
name={\fieldfmt{prefix}},
- description={The prefix associated with the \gls[noindex]{dual.field.text}
+ description={The prefix associated with the \field{text}
field.},
note={provided by \styfmt{glossaries-prefix}},
category={prefixfield},
@@ -3770,7 +4694,7 @@
@dualindexentry{field.prefixfirst,
name={\fieldfmt{prefixfirst}},
- description={The prefix associated with the \gls[noindex]{dual.field.first}
+ description={The prefix associated with the \field{first}
field.},
note={provided by \styfmt{glossaries-prefix}},
category={prefixfield},
@@ -3780,7 +4704,7 @@
@dualindexentry{field.prefixfirstplural,
name={\fieldfmt{prefixfirstplural}},
description={The prefix associated with the
- \gls[noindex]{dual.field.firstplural} field.},
+ \field{firstplural} field.},
note={provided by \styfmt{glossaries-prefix}},
category={prefixfield},
parent={fields}
@@ -3789,7 +4713,7 @@
@dualindexentry{field.prefixplural,
name={\fieldfmt{prefixplural}},
description={The prefix associated with the
- \gls[noindex]{dual.field.plural} field.},
+ \field{plural} field.},
note={provided by \styfmt{glossaries-prefix}},
category={prefixfield},
parent={fields}
@@ -3797,7 +4721,7 @@
@dualindexentry{field.access,
name={\fieldfmt{access}},
- description={The replacement text for the \gls[noindex]{dual.field.name} field.},
+ description={The replacement text for the \field{name} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3806,7 +4730,7 @@
@dualindexentry{field.descriptionaccess,
name={\fieldfmt{descriptionaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.description} field.},
+ \field{description} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3815,7 +4739,7 @@
@dualindexentry{field.descriptionpluralaccess,
name={\fieldfmt{descriptionpluralaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.descriptionplural} field.},
+ \field{descriptionplural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3823,7 +4747,7 @@
@dualindexentry{field.firstaccess,
name={\fieldfmt{firstaccess}},
- description={The replacement text for the \gls[noindex]{dual.field.first} field.},
+ description={The replacement text for the \field{first} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3832,7 +4756,7 @@
@dualindexentry{field.firstpluralaccess,
name={\fieldfmt{firstpluralaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.firstplural} field.},
+ \field{firstplural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3840,7 +4764,7 @@
@dualindexentry{field.longaccess,
name={\fieldfmt{longaccess}},
- description={The replacement text for the \gls[noindex]{dual.field.long} field.},
+ description={The replacement text for the \field{long} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3849,7 +4773,7 @@
@dualindexentry{field.longpluralaccess,
name={\fieldfmt{longpluralaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.longplural} field.},
+ \field{longplural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3857,7 +4781,7 @@
@dualindexentry{field.pluralaccess,
name={\fieldfmt{pluralaccess}},
- description={The replacement text for the \gls[noindex]{dual.field.plural} field.},
+ description={The replacement text for the \field{plural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3865,7 +4789,7 @@
@dualindexentry{field.shortaccess,
name={\fieldfmt{shortaccess}},
- description={The replacement text for the \gls[noindex]{dual.field.short} field.},
+ description={The replacement text for the \field{short} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3874,7 +4798,7 @@
@dualindexentry{field.shortpluralaccess,
name={\fieldfmt{shortpluralaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.shortplural} field.},
+ \field{shortplural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3882,7 +4806,7 @@
@dualindexentry{field.symbolaccess,
name={\fieldfmt{symbolaccess}},
- description={The replacement text for the \gls[noindex]{dual.field.symbol} field.},
+ description={The replacement text for the \field{symbol} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3891,7 +4815,7 @@
@dualindexentry{field.symbolpluralaccess,
name={\fieldfmt{symbolpluralaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.symbolplural} field.},
+ \field{symbolplural} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3900,7 +4824,7 @@
@dualindexentry{field.textaccess,
name={\fieldfmt{textaccess}},
description={The replacement text for the
- \gls[noindex]{dual.field.text} field.},
+ \field{text} field.},
note={provided by \styfmt{glossaries-accsupp}},
category={accessfield},
parent={fields}
@@ -3920,6 +4844,15 @@
parent={internalfields}
}
+ at dualindexentry{field.childlist,
+ name={\fieldfmt{childlist}},
+ description={A list of labels (in \sty{etoolbox}'s internal list
+ format) of the children this entry has had selected.},
+ 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
@@ -4008,6 +4941,15 @@
parent={internalfields}
}
+ at dualindexentry{field.dual,
+ name={\fieldfmt{dual}},
+ description={Created by \csopt{dual-field} if set with no value,
+ this field is used to store the dual label.},
+ note={internal field set by \appfmt{bib2gls}},
+ category={internalfield},
+ parent={internalfields}
+}
+
@dualindexentry{field.sort,
name={\fieldfmt{sort}},
description={The sort value obtained by the comparator.},
@@ -4088,7 +5030,7 @@
@dualindexentry{field.desc,
name={\fieldfmt{desc}},
- description={Corresponds to \gls[noindex]{dual.field.description} key.},
+ description={Corresponds to \field{description} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4096,7 +5038,7 @@
@dualindexentry{field.descplural,
name={\fieldfmt{descplural}},
- description={Corresponds to \gls[noindex]{dual.field.descriptionplural} key.},
+ description={Corresponds to \field{descriptionplural} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4104,7 +5046,7 @@
@dualindexentry{field.firstpl,
name={\fieldfmt{firstpl}},
- description={Corresponds to \gls[noindex]{dual.field.firstplural} key.},
+ description={Corresponds to \field{firstplural} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4137,7 +5079,7 @@
@dualindexentry{field.longpl,
name={\fieldfmt{longpl}},
- description={Corresponds to \gls[noindex]{dual.field.longplural} key.},
+ description={Corresponds to \field{longplural} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4189,7 +5131,7 @@
@dualindexentry{field.shortpl,
name={\fieldfmt{shortpl}},
- description={Corresponds to \gls[noindex]{dual.field.shortplural} key.},
+ description={Corresponds to \field{shortplural} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4197,7 +5139,7 @@
@dualindexentry{field.sortvalue,
name={\fieldfmt{sortvalue}},
- description={Original \gls[noindex]{dual.field.sort} value
+ description={Original \field{sort} value
(before sanitizing and escaping special characters).},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
@@ -4215,7 +5157,7 @@
@dualindexentry{field.useri,
name={\fieldfmt{useri}},
- description={Corresponds to \gls[noindex]{dual.field.user1} key.},
+ description={Corresponds to \field{user1} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4223,7 +5165,7 @@
@dualindexentry{field.userii,
name={\fieldfmt{userii}},
- description={Corresponds to \gls[noindex]{dual.field.user2} key.},
+ description={Corresponds to \field{user2} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4231,7 +5173,7 @@
@dualindexentry{field.useriii,
name={\fieldfmt{useriii}},
- description={Corresponds to \gls[noindex]{dual.field.user3} key.},
+ description={Corresponds to \field{user3} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4239,7 +5181,7 @@
@dualindexentry{field.useriv,
name={\fieldfmt{useriv}},
- description={Corresponds to \gls[noindex]{dual.field.user4} key.},
+ description={Corresponds to \field{user4} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4247,7 +5189,7 @@
@dualindexentry{field.userv,
name={\fieldfmt{userv}},
- description={Corresponds to \gls[noindex]{dual.field.user5} key.},
+ description={Corresponds to \field{user5} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4255,7 +5197,7 @@
@dualindexentry{field.uservi,
name={\fieldfmt{uservi}},
- description={Corresponds to \gls[noindex]{dual.field.user6} key.},
+ description={Corresponds to \field{user6} key.},
note={internal field set by \styfmt{glossaries}},
category={baseinternalfield},
parent={internalfields}
@@ -4318,6 +5260,12 @@
parent={entrytypes}
}
+ at dualindexentry{entry.indexplural,
+ name={\atentryfmt{indexplural}},
+ category={entrytype},
+ parent={entrytypes}
+}
+
@dualindexentry{entry.abbreviation,
name={\atentryfmt{abbreviation}},
category={entrytype},
@@ -4806,6 +5754,14 @@
name={ignored record}
}
+ at index{record,
+ seealso={ignoredrecord}
+}
+
+ at index{locationlist,
+ name = {location list}
+}
+
@index{postlinkhook,
name={post-link hook}
}
@@ -4852,6 +5808,62 @@
name={cross-resource reference}
}
+ at index{firstuse,
+ name={first use}
+}
+
+ at index{subsequentuse,
+ name={subsequent use}
+}
+
+ at index{firstuseflag,
+ name={first use flag}
+}
+
+ at index{link-text,
+ name={link text}
+}
+
+ at index{parent-entry,
+ name={parent entry},
+ plural={parent entries}
+}
+
+ at index{child-entry,
+ name={child entry},
+ plural={child entries}
+}
+
+ at index{hierarchical-entry,
+ name={hierarchical entry},
+ plural={hierarchical entries}
+}
+
+ at index{robust}
+ at index{fragile}
+ at index{expandable}
+ at index{regular}
+ at index{non-regular}
+ at index{variant}
+ at index{homograph}
+
+ at index{moving-argument,
+ name={moving argument}
+}
+
+ at index{uppercase,
+ name={upper case}
+}
+
+ at index{lowercase,
+ name={lower case}
+}
+
+ at index{case-change,
+ name = {case change},
+ seealso = {uppercase,lowercase}
+}
+
@index{unicodecategories,
name={Unicode categories},
text={Unicode category},
@@ -4976,6 +5988,14 @@
name={\filefmt{sample\dhyphen authors.tex}}
}
+ at dualindexentry{file.sample-citations.tex,
+ name={\filefmt{sample\dhyphen citations.tex}}
+}
+
+ at dualindexentry{file.citations.bib,
+ name={\filefmt{citations.bib}}
+}
+
@dualindexentry{file.bacteria.bib,
name={\filefmt{bacteria.bib}}
}
@@ -5127,6 +6147,7 @@
description={iterates over the items the given field, which contains
an \styfmt{etoolbox} internal list},
note={provided by \styfmt{glossaries-extra}},
+ seealso={glsxtrfieldforlistloop,glsxtrfieldifinlist,glsxtrfieldlistadd},
category={command}
}
@@ -5137,6 +6158,7 @@
an \styfmt{etoolbox} internal list, using the given handler},
note={provided by \styfmt{glossaries-extra}, use at least v1.29 to
avoid a bug},
+ seealso={glsxtrfielddolistloop,glsxtrfieldifinlist,glsxtrfieldlistadd},
category={command}
}
@@ -5198,20 +6220,153 @@
name={\csfmt{gls\-entry\-text}},
user1={\margm{label}},
description={expands to the value of the
- \gls[noindex]{dual.field.text} field},
+ \field{text} field},
note={provided by \styfmt{glossaries}},
category={command}
}
+ at index{glsentryplural,
+ name={\csfmt{gls\-entry\-plural}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{plural} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
@index{glsentryname,
name={\csfmt{gls\-entry\-name}},
user1={\margm{label}},
description={expands to the value of the
- \gls[noindex]{dual.field.name} field},
+ \field{name} field},
note={provided by \styfmt{glossaries}},
category={command}
}
+ at index{Glsentryname,
+ name={\csfmt{Gls\-entry\-name}},
+ user1={\margm{label}},
+ description={displays the value of the
+ \field{name} field with the first character
+ converted to upper case},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentrydesc,
+ name={\csfmt{gls\-entry\-desc}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{description} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentrysymbol,
+ name={\csfmt{gls\-entry\-symbol}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{symbol} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuseri,
+ name={\csfmt{gls\-entry\-useri}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user1} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuserii,
+ name={\csfmt{gls\-entry\-userii}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user2} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuseriii,
+ name={\csfmt{gls\-entry\-useriii}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user3} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuseriv,
+ name={\csfmt{gls\-entry\-useriv}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user4} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuserv,
+ name={\csfmt{gls\-entry\-userv}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user5} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsentryuservi,
+ name={\csfmt{gls\-entry\-uservi}},
+ user1={\margm{label}},
+ description={expands to the value of the
+ \field{user6} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glssetcategoryattribute,
+ name={\csfmt{gls\-set\-cat\-e\-gory\-at\-tribute}},
+ user1={\margm{category}\margm{attribute}\margm{value}},
+ description={sets the value of the attribute for the given
+category},
+ note={provided by \styfmt{glossaries-extra}},
+ category={command}
+}
+
+ at index{glsxtrpostlinkAddDescOnFirstUse,
+ name={\csfmt{gls\-xtr\-post\-link\-Add\-Desc\-On\-First\-Use}},
+ description={only for use in the post-link hooks,
+ this appends a space and the value of the
+ \field{description} field in parentheses
+ if the entry that was just referenced was used for the
+ first time},
+ note={provided by \styfmt{glossaries-extra}},
+ category={command}
+}
+
+ at index{glsxtrpostlinkAddSymbolOnFirstUse,
+ name={\csfmt{gls\-xtr\-post\-link\-Add\-Symbol\-On\-First\-Use}},
+ description={only for use in the post-link hooks,
+ this appends a space and the value of the
+ \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}},
+ category={command}
+}
+
+ at index{glsxtrpostlinkAddSymbolDescOnFirstUse,
+ name={\csfmt{gls\-xtr\-post\-link\-Add\-Symbol\-Desc\-On\-First\-Use}},
+ description={only for use in the post-link hooks, if the
+ entry that was just referenced was used for the first time,
+ 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+},
+ category={command}
+}
+
@index{glspluralsuffix,
name={\csfmt{gls\-plural\-suffix}},
user1={},
@@ -5248,6 +6403,30 @@
category={command}
}
+ at 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+},
+ category={command}
+}
+
+ at 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+},
+ category={command}
+}
+
+ at 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+},
+ category={command}
+}
+
@index{glsxtrifwasfirstuse,
name={\csfmt{glsxtr\-if\-was\-first\-use}},
user1={\margm{true}\margm{false}},
@@ -5260,7 +6439,7 @@
@index{glslabel,
name={\csfmt{glslabel}},
user1={},
- description={only for use in the post-link hooks this
+ 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}},
category={command}
@@ -5276,12 +6455,22 @@
category={command}
}
+ at index{glscurrentfieldvalue,
+ name={\csfmt{gls\-current\-field\-value}},
+ user1={},
+ 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}},
+ category={command}
+}
+
@index{glsxtrusefield,
name={\csfmt{gls\-xtr\-use\-field}},
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}},
+ note={provided by \styfmt{glossaries-extra} v1.12+},
category={command}
}
@@ -5291,7 +6480,7 @@
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}},
+ note={provided by \styfmt{glossaries-extra} v1.12+},
category={command}
}
@@ -5328,6 +6517,33 @@
category={command}
}
+ at index{GlsXtrIfFieldEqStr,
+ name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Str}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrIfFieldEqXpStr,
+ name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Xp\-Str}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrIfXpFieldEqXpStr,
+ name={\csfmt{Gls\-Xtr\-If\-Xp\-Field\-Eq\-Xp\-Str}},
+ 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+},
+ category={command}
+}
+
@index{ifglshasfield,
name={\csfmt{if\-gls\-has\-field}},
user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}},
@@ -5338,6 +6554,99 @@
category={command}
}
+ at index{ifglshassymbol,
+ name={\csfmt{if\-gls\-has\-symbol}},
+ user1={\margm{entry label}\margm{true}\margm{false}},
+ 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}},
+ seealso={ifglshasdesc,glsxtrifhasfield,GlsXtrIfFieldUndef},
+ category={command}
+}
+
+ at index{ifglshasdesc,
+ name={\csfmt{if\-gls\-has\-desc}},
+ 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}},
+ seealso={ifglshassymbol,ifglshasdescsuppressed},
+ category={command}
+}
+
+ at index{ifglshasdescsuppressed,
+ name={\csfmt{if\-gls\-has\-suppressedesc}},
+ 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}},
+ seealso={ifglshasdesc},
+ category={command}
+}
+
+ at index{ifglshasparent,
+ name={\csfmt{if\-gls\-has\-parent}},
+ 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}},
+ category={command}
+}
+
+ at index{ifglshaschildren,
+ name={\csfmt{if\-gls\-has\-children}},
+ user1={\margm{entry label}\margm{true}\margm{false}},
+ description={tests if the given entry, which must be defined, has
+ child entries. This method is inefficient as it has to
+ iterate over all defined entries to determine which ones
+ have \meta{entry label} as the value of the \field{parent}
+ field. With \bibgls, a more efficient approach is to
+ use \csopt{save-child-count} and test the value of
+ the \field{childcount} field},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{GlsXtrIfFieldNonZero,
+ name={\csfmt{Gls\-Xtr\-If\-Field\-Non\-Zero}},
+ user1={\margm{field}\margm{entry label}\margm{true}\margm{false}},
+ description={tests if the given field value expands to a non-zero
+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+},
+ seealso={GlsXtrIfFieldEqNum},
+ category={command}
+}
+
+ at index{GlsXtrIfFieldEqNum,
+ name={\csfmt{Gls\-Xtr\-If\-Field\-Eq\-Num}},
+ user1={\margm{field}\margm{entry label}\margm{number}\margm{true}\margm{false}},
+ description={tests if the given field value expands to the given
+integer \meta{number}. 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+},
+ seealso={GlsXtrIfFieldNonZero},
+ category={command}
+}
+
+ at dualindexentry{GlsXtrIfHasNonZeroChildCount,
+ name={\csfmt{Gls\-Xtr\-If\-Has\-Non\-Zero\-Child\-Count}},
+ user1={\margm{entry label}\margm{true}\margm{false}},
+ description={for use with the \csopt{save-child-count} resource
+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+},
+ seealso={GlsXtrIfFieldNonZero},
+ category={command}
+}
+
@dualindexentry{glsxtrifcustomdiscardperiod,
name={\csfmt{gls\-xtr\-if\-custom\-discard\-period}},
user1={\margm{true}\margm{false}},
@@ -5453,9 +6762,9 @@
@index{newsym,
name={\csfmt{newsym}},
user1={\margm{label}\margm{\keyvallist}\margm{symbol}},
- description={equivalent to \cs{glsxtrnewsymbol}},
+ description={equivalent to \gls{glsxtrnewsymbol}},
note={provided by \styfmt{glossaries-extra}'s
- \gls{styopt.shortcuts} package option},
+ \styopt{shortcuts} package option},
category={command}
}
@@ -5462,9 +6771,9 @@
@index{newnum,
name={\csfmt{newnum}},
user1={\margm{label}\margm{\keyvallist}},
- description={equivalent to \cs{glsxtrnewnumber}},
+ description={equivalent to \gls{glsxtrnewnumber}},
note={provided by \styfmt{glossaries-extra}'s
-\gls{styopt.shortcuts} package option},
+ \styopt{shortcuts} package option},
category={command}
}
@@ -5471,7 +6780,7 @@
@index{acronymtype,
name={\csfmt{acronym\-type}},
user1={},
- description={expands to the default glossary type when using
+ description={expands to the default acronym glossary type when using
\cs{newacronym}},
note={provided by \styfmt{glossaries}},
category={command}
@@ -5661,6 +6970,15 @@
category={command}
}
+ at index{glsaddeach,
+ name={\csfmt{gls\-add\-each}},
+ 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+},
+ category={command}
+}
+
@index{glsadd.thevalue,
name={\csoptfmt{thevalue}},
category={commandoption},
@@ -5679,6 +6997,46 @@
parent={glsadd}
}
+ at index{glsadd.counter,
+ name={\csoptfmt{counter}},
+ category={commandoption},
+ parent={glsadd}
+}
+
+ at index{theglossaryentry,
+ name={\csfmt{theglossaryentry}},
+ description={textual representation of the \counter{glossaryentry}
+counter, which is defined with the \styopt{entrycounter} option},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{theHglossaryentry,
+ name={\csfmt{theHglossaryentry}},
+ description={hypertarget associated with the \counter{glossaryentry}
+counter, which is defined with the \styopt{entrycounter} option},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsstepentry,
+ name={\csfmt{gls\-step\-entry}},
+ user1 = {\margm{label}},
+ 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}},
+ category={command}
+}
+
+ at index{currentglossary,
+ 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}},
+ category={command}
+}
+
@index{frontmatter,
name={\csfmt{front\-matter}},
user1={},
@@ -5774,6 +7132,31 @@
category={command}
}
+ at index{textbf,
+ name={\csfmt{textbf}},
+ user1={\margm{text}},
+ description={displays the given text in bold},
+ note={kernel command},
+ category={command}
+}
+
+ at index{textit,
+ name={\csfmt{textit}},
+ user1={\margm{text}},
+ description={displays the given text in italic},
+ note={kernel command},
+ seealso={emph},
+ category={command}
+}
+
+ at index{footnote,
+ name={\csfmt{footnote}},
+ user1={\oargm{number}\margm{text}},
+ description={displays the given text as a footnote},
+ note={kernel command},
+ category={command}
+}
+
@index{index,
name={\csfmt{index}},
user1={\margm{text}},
@@ -5785,7 +7168,7 @@
}
@index{glsignore,
- name={\csfmt{glsignore}},
+ name={\csfmt{gls\-ignore}},
user1={\margm{text}},
description={does nothing but when used as a location format
\bibgls\ recognises it as an \idx{ignoredrecord}},
@@ -5833,7 +7216,10 @@
@index{ensuremath,
name={\csfmt{ensuremath}},
user1={\margm{maths}},
- description={ensures the argument is in math mode},
+ description={ensures the argument is in math mode. As a general
+rule this should only be used if you know for certain that
+the argument just contains mathematical markup and doesn't cause a
+change in mode},
note={kernel command},
category={command}
}
@@ -5996,6 +7382,14 @@
category={command}
}
+ at index{caption,
+ name={\csfmt{caption}},
+ user1={\oargm{list title}\margm{title}},
+ description={caption title},
+ note={kernel command},
+ category={command}
+}
+
@index{boldsymbol,
name={\csfmt{boldsymbol}},
user1={\margm{symbol}},
@@ -6066,6 +7460,109 @@
category={command}
}
+ at index{printunsrtglossaryentryprocesshook,
+ 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+},
+ category={command}
+}
+
+ at index{printunsrtglossaryskipentry,
+ name={\csfmt{print\-unsrt\-glos\-sary\-skip\-entry}},
+ description={only allowed within
+ \gls{printunsrtglossaryentryprocesshook} this command
+ indicates that the current entry should be skipped},
+ note={provided by \styfmt{glossaries-extra} v1.21+},
+ category={command}
+}
+
+ at 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+},
+ category={command}
+}
+
+ at index{glscategory,
+ name={\csfmt{gls\-cat\-e\-gory}},
+ user1={\margm{label}},
+ 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}},
+ category={command}
+}
+
+ at index{glsifcategory,
+ name={\csfmt{gls\-if\-cat\-e\-gory}},
+ 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}},
+ category={command}
+}
+
+ at index{glsxtriflabelinlist,
+ name={\csfmt{gls\-xtr\-if\-label\-in\-list}},
+ user1={\margm{label}\margm{list}\margm{true}\margm{false}},
+ description={tests if the \meta{label} is contained
+ 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+},
+ category={command}
+}
+
+ at index{printgloss.type,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{type}},
+ category={commandoption},
+}
+
+ at index{printgloss.style,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{style}},
+ category={commandoption},
+}
+
+ at index{printgloss.title,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{title}},
+ category={commandoption},
+}
+
+ at index{printgloss.toctitle,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{toctitle}},
+ category={commandoption},
+}
+
+ at index{printgloss.target,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{target}},
+ category={commandoption},
+}
+
+ at index{printgloss.targetnameprefix,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{target\-name\-prefix}},
+ category={commandoption},
+}
+
+ at index{printgloss.prefix,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{prefix}},
+ category={commandoption},
+}
+
+ at index{printgloss.nonumberlist,
+ parent = {printunsrtglossary},
+ name = {\csoptfmt{no\-number\-list}},
+ category={commandoption},
+}
+
@index{cs.makeglossaries,
name={\csfmt{make\-glos\-saries}},
user1={},
@@ -6092,6 +7589,23 @@
category={command}
}
+ at index{printnoidxglossary,
+ name={\csfmt{print\-noidx\-glos\-sary}},
+ user1={\oargm{options}},
+ description={uses \TeX\ to sort, collate and list the glossary},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{printnoidxglossaries,
+ name={\csfmt{print\-noidx\-glos\-saries}},
+ user1={},
+ description={iterates over all non-ignored defined glossaries
+ and performs \cs{printnoidxglossary} for each one},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
@index{makefirstuc,
name={\csfmt{make\-first\-uc}},
user1={\margm{text}},
@@ -6104,16 +7618,25 @@
name={\csfmt{ac}},
user1={\oargm{options}\margm{label}\oargm{insert}},
description={equivalent to \cs{gls}},
- note={provided by \styfmt{glossaries-extra} \gls{styopt.shortcuts} package
+ note={provided by \styfmt{glossaries-extra} \styopt{shortcuts} package
option},
category={command}
}
+ at index{ab,
+ 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},
+ category={command}
+}
+
@index{glsxtrp,
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}},
+ note={provided by \styfmt{glossaries-extra} v1.07+},
category={command}
}
@@ -6122,7 +7645,7 @@
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}},
+ note={provided by \styfmt{glossaries-extra} v1.12},
category={command}
}
@@ -6130,8 +7653,8 @@
name={\csfmt{gls\-xtr\-use\-see}},
user1={\margm{label}},
description={applies \cs{glsseeformat} to the entry's
- \gls[noindex]{dual.field.see} field if not empty},
- note={provided by \styfmt{glossaries-extra}},
+ \field{see} field if not empty},
+ note={provided by \styfmt{glossaries-extra} v1.06+},
category={command}
}
@@ -6139,8 +7662,8 @@
name={\csfmt{gls\-xtr\-use\-seealso}},
user1={\margm{label}},
description={applies \cs{glsseeformat} to the entry's
- \gls[noindex]{dual.field.seealso} field if not empty},
- note={provided by \styfmt{glossaries-extra}},
+ \field{seealso} field if not empty},
+ note={provided by \styfmt{glossaries-extra} v1.16+},
category={command}
}
@@ -6148,7 +7671,7 @@
name={\csfmt{gls\-xtr\-set\-alias\-noindex}},
user1={},
description={hooks into the alias \gls{gls.noindex} setting},
- note={provided by \styfmt{glossaries-extra}},
+ note={provided by \styfmt{glossaries-extra} v1.12+},
category={command}
}
@@ -6156,8 +7679,9 @@
name={\csfmt{gls\-xtr\-use\-seealso\-format}},
user1={\margm{xr list}},
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}},
+ given in \meta{xr list} as a list of \qt{see also}
+cross-references},
+ note={provided by \styfmt{glossaries-extra} v1.16+},
category={command}
}
@@ -6165,7 +7689,7 @@
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}},
+ note={provided by \styfmt{glossaries-extra} v1.16+},
category={command}
}
@@ -6177,6 +7701,15 @@
category={command}
}
+ at index{glsxtrseelist,
+ name={\csfmt{gls\-xtr\-see\-list}},
+ 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+},
+ category={command}
+}
+
@index{setabbreviationstyle,
name={\csfmt{setabbreviationstyle}},
user1={\oargm{category}\margm{style-name}},
@@ -6196,6 +7729,14 @@
category={command}
}
+ at index{glscapturedgroup,
+ name={\csfmt{glscapturedgroup}},
+ user1={},
+ description={expands to \cs{cs.string}\gls{dollarchar}},
+ note={provided by \styfmt{glossaries-extra-bib2gls} v1.31+},
+ category={command}
+}
+
@index{GlsXtrBibTeXEntryAliases,
name={\csfmt{Gls\-Xtr\-Bib\-TeX\-Entry\-Aliases}},
user1={},
@@ -6327,7 +7868,7 @@
user1={},
description={hook used after the description is displayed in the
glossary for entries that have the
- \gls[noindex]{dual.field.category} set to \code{abbreviation}},
+ \field{category} set to \code{abbreviation}},
note={provided by \styfmt{glossaries-extra}},
category={command}
}
@@ -6337,7 +7878,7 @@
user1={},
description={hook used after the description is displayed in the
glossary for entries that have the
- \gls[noindex]{dual.field.category} set to \code{symbol}},
+ \field{category} set to \code{symbol}},
note={provided by \styfmt{glossaries-extra}},
category={command}
}
@@ -6347,7 +7888,7 @@
user1={},
description={hook used after the description is displayed in the
glossary for entries that have the
- \gls[noindex]{dual.field.category} set to \code{general}},
+ \field{category} set to \code{general}},
note={provided by \styfmt{glossaries-extra}},
category={command}
}
@@ -6357,7 +7898,7 @@
user1={},
description={hook used after the description is displayed in the
glossary for entries that have the
- \gls[noindex]{dual.field.category} set to \meta{category}},
+ \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},
@@ -6369,7 +7910,7 @@
user1={},
description={hook used after the name is displayed in the
glossary for entries that have the
- \gls[noindex]{dual.field.category} set to \meta{category}},
+ \field{category} set to \meta{category}},
note={user needs to define hook for use with
\styfmt{glossaries-extra}},
category={command}
@@ -6380,7 +7921,7 @@
user1={},
description={hook used after commands like \cs{gls}
for entries that have the
- \gls[noindex]{dual.field.category} set to \meta{category}},
+ \field{category} set to \meta{category}},
note={user needs to define hook for use with
\styfmt{glossaries-extra}},
category={command}
@@ -6400,9 +7941,20 @@
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}},
+ seealso={glsdisp},
category={command}
}
+ at index{glsdisp,
+ name={\csfmt{glsdisp}},
+ user1={\oargm{options}\margm{label}\oargm{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}},
+ seealso={glslink},
+ category={command}
+}
+
@index{glsxtrshort,
name={\csfmt{glsxtrshort}},
user1={\oargm{options}\margm{label}},
@@ -6425,9 +7977,38 @@
category={command}
}
+ at index{glsxtrfull,
+ name={\csfmt{glsxtrfull}},
+ user1={\oargm{options}\margm{label}},
+ description={links to the entry's location in the glossary with
+ the link text obtained from the \field{long} and \field{short}
+fields (using the
+ appropriate abbreviation style)
+ without altering the first use flag},
+ note={provided by \styfmt{glossaries-extra}},
+ category={command}
+}
+
+ at index{glsxtrword,
+ name={\csfmt{glsxtrword}},
+ 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+},
+ category={command}
+}
+
+ at index{glsxtrwordsep,
+ 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+},
+ category={command}
+}
+
@index{glstext,
name={\csfmt{glstext}},
- user1={\oargm{options}\margm{label}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
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},
@@ -6437,7 +8018,7 @@
@index{glsname,
name={\csfmt{glsname}},
- user1={\oargm{options}\margm{label}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
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},
@@ -6447,7 +8028,7 @@
@index{glsfirst,
name={\csfmt{glsfirst}},
- user1={\oargm{options}\margm{label}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
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},
@@ -6457,7 +8038,7 @@
@index{glssymbol,
name={\csfmt{glssymbol}},
- user1={\oargm{options}\margm{label}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
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},
@@ -6465,6 +8046,76 @@
category={command}
}
+ at index{glsdesc,
+ name={\csfmt{glsdesc}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuseri,
+ name={\csfmt{glsuseri}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuserii,
+ name={\csfmt{glsuserii}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuseriii,
+ name={\csfmt{glsuseriii}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuseriv,
+ name={\csfmt{glsuseriv}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuserv,
+ name={\csfmt{glsuserv}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
+ at index{glsuservi,
+ name={\csfmt{glsuservi}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ 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}},
+ category={command}
+}
+
@dualindexentry{rgls,
name={\csfmt{rgls}},
user1={\oargm{options}\margm{label}\oargm{insert}},
@@ -6505,10 +8156,10 @@
name={\csfmt{gls}},
user1={\oargm{options}\margm{label}\oargm{insert}},
description={on first use displays the first use text
- (the value of the \gls[noindex]{dual.field.first} field
+ (the value of the \field{first} field
for general entries) and on subsequent use displays
the subsequent use text (the value of the
- \gls[noindex]{dual.field.text} field
+ \field{text} field
for general entries) where the text is optionally hyperlinked
to the relevant place in the glossary},
note={provided by \styfmt{glossaries}},
@@ -6533,6 +8184,24 @@
parent={gls}
}
+ at index{gls.textformat,
+ name={\csoptfmt{text\-format}},
+ category={commandoption},
+ parent={gls}
+}
+
+ at index{gls.prefix,
+ name={\csoptfmt{prefix}},
+ category={commandoption},
+ parent={gls}
+}
+
+ at index{gls.hyperoutside,
+ name={\csoptfmt{hyperoutside}},
+ category={commandoption},
+ parent={gls}
+}
+
@index{glspl,
name={\csfmt{glspl}},
user1={\oargm{options}\margm{label}\oargm{insert}},
@@ -6558,12 +8227,38 @@
category={command}
}
+ at index{GLS,
+ 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}},
+ category={command}
+}
+
+ at index{GLSpl,
+ name={\csfmt{GLSpl}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ description={as \cs{GLS} but shows the plural form},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{pgls,
+ name={\csfmt{pgls}},
+ user1={\oargm{options}\margm{label}\oargm{insert}},
+ description={does \meta{prefix}\gls{gls}\oargm{options}\margm{label}\oargm{insert},
+ where the \meta{prefix} is obtained from the appropriate prefix
+ field},
+ note={provided by \styfmt{glossaries-prefix}},
+ category={command}
+}
+
@index{glssetwidest,
name={\csfmt{gls\-set\-widest}},
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{glossaries}},
+ note={provided by \styfmt{glossary-tree}},
category={command}
}
@@ -6574,10 +8269,20 @@
wider than the current value},
note={provided by \styfmt{glossaries-extra-stylemods} version
1.23+},
- seealso={glssetwidest},
+ seealso={glssetwidest,eglsupdatewidest},
category={command}
}
+ at index{eglsupdatewidest,
+ 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+},
+ seealso={glssetwidest,glsupdatewidest},
+ category={command}
+}
+
@index{glsFindWidestTopLevelName,
name={\csfmt{gls\-Find\-Widest\-Top\-Level\-Name}},
user1={\oargm{glossary list}},
@@ -6615,11 +8320,41 @@
category={command}
}
+ at index{glsabbrvscfont,
+ 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+},
+ category={command}
+}
+
+ at index{glsxtrifinmark,
+ name={\csfmt{gls\-xtr\-if\-in\-mark}},
+ user1={\margm{true}\margm{true}},
+ description={used by commands like \gls{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+},
+ category={command}
+}
+
+ at 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
+of contents},
+ note={provided by \styfmt{glossaries-extra} v1.07+},
+ category={command}
+}
+
@index{glstreenamefmt,
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}},
+ note={provided by \styfmt{glossary-tree} v4.08+ and redefined by
+\styfmt{glossaries-extra-stylemods} v1.31+},
+ seealso={glstreegroupheaderfmt,glstreenavigationfmt,glstreedefaultnamefmt},
category={command}
}
@@ -6628,10 +8363,30 @@
user1={\margm{text}},
description={used with the tree styles to format the group
headings},
- note={provided by \styfmt{glossary-tree}},
+ note={provided by \styfmt{glossary-tree} v4.22+ and redefined
+ by \styfmt{glossaries-extra-stylemods} v1.31+},
category={command}
}
+ at index{glstreenavigationfmt,
+ name={\csfmt{gls\-tree\-navigation\-fmt}},
+ 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+},
+ category={command}
+}
+
+ at index{glstreedefaultnamefmt,
+ name={\csfmt{gls\-tree\-default\-name\-fmt}},
+ 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+},
+ category={command}
+}
+
@index{glsdescwidth,
name={\csfmt{gls\-desc\-width}},
user1={},
@@ -6695,6 +8450,15 @@
category={command}
}
+ at 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}},
@@ -6703,6 +8467,27 @@
category={command}
}
+ at 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}},
+ category={command}
+}
+
+ at index{glsaccsupp,
+ name={\csfmt{gls\-acc\-supp}},
+ 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}},
+ category={command}
+}
+
@index{forglsentries,
name={\csfmt{for\-gls\-entries}},
user1={\oargm{glossary-list}\margm{cs}\margm{body}},
@@ -6747,11 +8532,91 @@
@index{glstextformat,
name={\csfmt{glstextformat}},
user1={\margm{text}},
- description={used by commands like \cs{gls} to format the link-text},
+ description={used by commands like \cs{gls} to format the
+ \idx{link-text}},
note={provided by \styfmt{glossaries}},
category={command}
}
+ at index{glsxtrregularfont,
+ name={\csfmt{gls\-xtr\-reg\-u\-lar\-font}},
+ 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+},
+ category={command}
+}
+
+ at index{glsxtrabbreviationfont,
+ name={\csfmt{gls\-xtr\-abbre\-vi\-a\-tion\-font}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrExpandedFmt,
+ name={\csfmt{Gls\-Xtr\-Expanded\-Fmt}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrStartUnsetBuffering,
+ name={\csfmt{Gls\-Xtr\-Start\-Unset\-Buffer\-ing}},
+ 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
+ (added to v1.31) avoids duplicate labels in the buffer's
+ internal list},
+ note={provided by \styfmt{glossaries-extra} v1.30+},
+ category={command}
+}
+
+ at index{GlsXtrStopUnsetBuffering,
+ name={\csfmt{Gls\-Xtr\-Stop\-Unset\-Buffer\-ing}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrForUnsetBufferedList,
+ name={\csfmt{Gls\-Xtr\-For\-Unset\-Buffered\-List}},
+ user1 = {\margm{cs}},
+ description={iterates over
+ all the entry whose labels are stored in the
+ buffer that was started with
+ \gls{GlsXtrStartUnsetBuffering} and implements
+ \meta{cs}\margm{label} at each iteration},
+ note={provided by \styfmt{glossaries-extra} v1.31+},
+ category={command}
+}
+
+ at index{glsunset,
+ name={\csfmt{gls\-unset}},
+ user1 = {\margm{label}},
+ description={unsets the \idx{firstuseflag} so that the entry is
+marked as having been used},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{glsreset,
+ name={\csfmt{gls\-reset}},
+ user1 = {\margm{label}},
+ description={resets the \idx{firstuseflag} so that the entry is
+marked as not used},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
@index{TrackLangLastTrackedDialect,
name={\csfmt{Track\-Lang\-Last\-Tracked\-Dialect}},
user1={},
@@ -6907,6 +8772,22 @@
category={command}
}
+ at index{acute,
+ name={\csfmt{'}},
+ user1={\margm{character}},
+ description={puts an acute accent over \meta{character}},
+ note={kernel command},
+ category={command}
+}
+
+ at index{umlaut,
+ name={\csfmt{"}},
+ user1={\margm{character}},
+ description={puts an umlaut accent over \meta{character}},
+ note={kernel command},
+ category={command}
+}
+
@index{textsuperscript,
name={\csfmt{textsuperscript}},
user1={\margm{text}},
@@ -7044,6 +8925,7 @@
user1={\margm{id}},
description={creates a label that can be referenced with \ics{ref}
or \ics{pageref}},
+ seealso={ref,pageref},
note={kernel command},
category={command}
}
@@ -7062,10 +8944,18 @@
user1={\margm{id}},
description={cross-reference the location where \cs{label}\margm{id}
occurred},
+ seealso={label},
note={kernel command},
category={command}
}
+ at index{par,
+ name={\csfmt{par}},
+ description={paragraph break},
+ note={kernel command},
+ category={command}
+}
+
@index{hyperlink,
name={\csfmt{hyperlink}},
user1={\margm{target name}\margm{text}},
@@ -7084,3 +8974,557 @@
category={command}
}
+ at index{glsrefentry,
+ name={\csfmt{gls\-ref\-entry}},
+ user1={\margm{label}},
+ description={when used with \styopt{entrycounter} or
+ \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+},
+ category={command}
+}
+
+ at index{glsxtrpageref,
+ name={\csfmt{gls\-xtr\-page\-ref}},
+ user1={\margm{label}},
+ description={when used with \styopt{entrycounter} or
+ \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},
+ category={command}
+}
+
+ at index{glsxtrglossentry,
+ name={\csfmt{gls\-xtr\-gloss\-entry}},
+ 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},
+ category={command}
+}
+
+ at index{glsxtrglossentryother,
+ name={\csfmt{gls\-xtr\-gloss\-entry\-other}},
+ user1={\margm{header}\margm{label}\margm{field}},
+ description={like \gls{glsxtrglossentry} but uses the value given
+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+},
+ category={command}
+}
+
+ at index{glsshowtarget,
+ name={\csfmt{gls\-show\-target}},
+ 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+},
+ category={command}
+}
+
+ at index{GlsEntryCounterLabelPrefix,
+ name={\csfmt{Gls\-Entry\-Counter\-Label\-Prefix}},
+ description={used as a prefix in the \gls{label} command
+ automatically implemented by the \styopt{entrycounter}
+ and \styopt{subentrycounter} options},
+ note={provided by \styfmt{glossaries} v4.38+},
+ category={command}
+}
+
+ at index{GlsXtrStandaloneGlossaryType,
+ 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+},
+ category={command}
+}
+
+ at index{GlsXtrStandaloneSubEntryItem,
+ name={\csfmt{Gls\-Xtr\-Stand\-alone\-Sub\-Entry\-Item}},
+ user1 = {\margm{label}},
+ description={used within \gls{glsxtrglossentry} and
+\gls{glsxtrglossentryother} to display sub-item labels},
+ note={provided by \styfmt{glossaries-extra} v1.31+},
+ category={command}
+}
+
+ at index{glsresetentrycounter,
+ name={\csfmt{gls\-reset\-entry\-counter}},
+ description={resets the \counter{glossaryentry} counter if the
+\styopt{entrycounter} setting is on},
+ note={provided by \styfmt{glossaries}},
+ category={command}
+}
+
+ at index{setupglossaries,
+ name={\csfmt{set\-up\-glossaries}},
+ 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}},
+ category={command}
+}
+
+ at index{glossariesextrasetup,
+ name={\csfmt{glossaries\-extra\-setup}},
+ 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}},
+ category={command}
+}
+
+ at index{glstreepredesc,
+ name={\csfmt{gls\-tree\-pre\-desc}},
+ user1={\margm{label}},
+ description={separator used before the description for the
+ \glostyle{tree} styles},
+ note={provided by \styfmt{glossary-tree} v4.26+},
+ category={command}
+}
+
+ at index{glstreenonamedesc,
+ name={\csfmt{gls\-tree\-no\-name\-desc}},
+ user1={\margm{label}},
+ 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+},
+ category={command}
+}
+
+ at index{glsfmtshort,
+ name={\csfmt{gls\-fmt\-short}},
+ 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}},
+ category={command}
+}
+
+ at index{glsfmtlong,
+ name={\csfmt{gls\-fmt\-long}},
+ 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}},
+ category={command}
+}
+
+ at index{glsfmtfull,
+ name={\csfmt{gls\-fmt\-full}},
+ 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}},
+ category={command}
+}
+
+ at index{glsfmtname,
+ name={\csfmt{gls\-fmt\-name}},
+ 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}},
+ category={command}
+}
+
+ at index{glsfmtfirst,
+ name={\csfmt{gls\-fmt\-first}},
+ 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}},
+ category={command}
+}
+
+ at index{glsfmttext,
+ name={\csfmt{gls\-fmt\-text}},
+ 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}},
+ category={command}
+}
+
+ at index{tableofcontents,
+ name={\csfmt{table\-of\-contents}},
+ description={displays the table of contents (by reading in the
+\ext{toc} file) and then opens \ext{toc} file to allow the
+sectioning commands to write to it},
+ note={kernel command},
+ category={command}
+}
+
+ at index{underline,
+ name={\csfmt{under\-line}},
+ user1={\margm{text}},
+ description={underlines the given text},
+ note={kernel command},
+ category={command}
+}
+
+ at index{ul,
+ name={\csfmt{ul}},
+ user1={\margm{text}},
+ description={underlines the given text},
+ note={provided by \styfmt{soul}},
+ category={command}
+}
+
+ at index{ding,
+ name={\csfmt{ding}},
+ user1={\margm{number}},
+ description={displays the symbol associated with the given number},
+ note={provided by \styfmt{pifont}},
+ category={command}
+}
+
+ at index{exampleterms,
+ name = {example terms}
+}
+
+ at entry{ex1.duck,
+ parent={exampleterms},
+ name={duck},
+ description={a waterbird with webbed feet},
+ identifier={animal}
+}
+
+ at entry{ex1.goose,
+ parent={exampleterms},
+ name={goose},
+ plural={geese},
+ description={a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ identifier={animal}
+}
+
+ at entry{ex2.duck,
+ parent={exampleterms},
+ name={Duck (noun)},
+ first={duck (quack, quack)},
+ firstplural={ducks (quack, quack)},
+ text={duck},
+ description={a waterbird with webbed feet},
+ identifier={animal}
+}
+
+ at entry{ex2.goose,
+ parent={exampleterms},
+ name={Goose (noun, pl.\ geese)},
+ first={goose (honk, honk)},
+ firstplural={geese (honk, honk)},
+ text={goose},
+ plural={geese},
+ description={a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ identifier={animal}
+}
+
+ at entry{ex.fleuron,
+ parent={exampleterms},
+ name = {fleuron},
+ symbol = {\ding{167}},
+ category = {ornament},
+ description = {typographic ornament}
+}
+
+ at entry{ex.pi,
+ parent={exampleterms},
+ name = {Archimedes' constant},
+ symbol = {\ensuremath{\pi}},
+ category = {constant},
+ description = {ratio of a circle's circumference to its diameter}
+}
+
+ at entry{ex.thetai,
+ parent = {exampleterms},
+ name = {theta parameter},
+ symbol = {\ensuremath{\theta_i}},
+ description = {one of the model parameters}
+}
+
+ at abbreviation{ex.tug,
+ parent={exampleterms},
+ category = {longshortem},
+ short = {TUG},
+ long = {\TeX\ Users Group}
+}
+
+ at abbreviation{ex.ascii,
+ short = {ascii},
+ long = {American Standard Code for Information Interchange},
+ category={shortsc}
+}
+
+ at abbreviation{ex.svm,
+ parent={exampleterms},
+ short = {SVM},
+ long = {support vector machine}
+}
+
+ at abbreviation{ex.ssl,
+ parent={exampleterms},
+ category = {markwordsexample},
+ short = {SSL},
+ long = {Secure Sockets Layer}
+}
+
+ at abbreviation{ex.xml,
+ parent={exampleterms},
+ category = {taggingexample},
+ short = {XML},
+ long = {e\itag{x}tensible \itag{m}arkup \itag{l}anguage}
+}
+
+ at abbreviation{ex.dante,
+ parent={exampleterms},
+ category = {discardperiodexample},
+ short = {DANTE e.V.},
+ long = {Deutschsprachige Anwendervereinigung \TeX\ e.V.}
+}
+
+ at abbreviation{ex.gp,
+ parent={exampleterms},
+ category = {discardperiodexample},
+ short = {G.P.},
+ long = {General Practitioner}
+}
+
+ at abbreviation{ex2.gp,
+ parent={exampleterms},
+ category = {initialism},
+ short = {GP},
+ long = {General Practitioner}
+}
+
+ at abbreviation{ex.rna,
+ parent={exampleterms},
+ short = {RNA},
+ long = {ribonukleins\"aure},
+ user1 = {ribonucleic acid},
+ category = {abbrvtrans}
+}
+
+ at entry{ex.length,
+ parent={exampleterms},
+ name = {length},
+ symbol = {\si{\metre}},
+ description = {measurement between two points}
+}
+
+ at entry{ex.area,
+ parent={exampleterms},
+ name = {area},
+ symbol = {\si{\metre\squared}},
+ description = {measurement of a surface}
+}
+
+ at symbol{ex2.length,
+ parent={exampleterms},
+ description = {length},
+ name = {\si{\metre}}
+}
+
+ at symbol{ex2.area,
+ parent={exampleterms},
+ description = {area},
+ name = {\si{\metre\squared}}
+}
+
+ at symbol{ex.deriv,
+ parent={exampleterms},
+ description = {derivative},
+ name = {\ensuremath{\derivfn{x}}},
+ user1 = {derivfn}
+}
+
+ at index{hom.bow1,
+ name={bow},
+ description={(rhymes with toe)},
+ category = {homograph}
+}
+
+ at entry{hom.bowknot,
+ parent={hom.bow1},
+ description = {a knot tied with two loops and loose ends},
+ category = {homograph}
+}
+
+ at entry{hom.bowweapon,
+ parent={hom.bow1},
+ description = {a weapon for shooting arrows, made of curved wood
+ joined at both ends with taut string},
+ category = {homograph}
+}
+
+ at index{hom.bow2,
+ name={bow},
+ description={(rhymes with cow)},
+ category = {homograph}
+}
+
+ at index{hom.bowbend,
+ parent={hom.bow2},
+ description={bend head or upper body},
+ category = {homograph}
+}
+
+ at index{hom.bowpressure,
+ parent={hom.bow2},
+ description={give in to pressure},
+ category = {homograph}
+}
+
+ at index{hom.bow3,
+ name={bow},
+ description={(also bows) the front end of a ship},
+ category = {homograph}
+}
+
+ at index{hom.glossary,
+ name={glossary},
+ category = {homograph}
+}
+
+ at entry{hom.glossarycol,
+ parent = {hom.glossary},
+ description = {collection of glosses},
+ category = {homograph}
+}
+
+ at entry{hom.glossarylist,
+ parent = {hom.glossary},
+ description = {list of technical words},
+ category = {homograph}
+}
+
+ at entry{hier.animal,
+ name = {animal},
+ description = {living organism with a nervous system and sense organs
+ that can move independently},
+ category = {hierarchical}
+}
+
+ at entry{hier.bird,
+ parent = {hier.animal},
+ name = {bird},
+ description = {warm-blooded egg-laying animal with feathers, wings
+ and a beak},
+ category = {hierarchical}
+}
+
+ at entry{hier.duck,
+ parent = {hier.bird},
+ name = {duck},
+ description={a waterbird with webbed feet},
+ category = {hierarchical}
+}
+
+ at entry{hier.goose,
+ parent = {hier.bird},
+ name = {goose},
+ description = {a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ category = {hierarchical}
+}
+
+ at entry{hier.mineral,
+ name = {mineral},
+ description = {natural inorganic substance},
+ category = {hierarchical}
+}
+
+ at entry{hier.calcite,
+ parent = {hier.mineral},
+ name = {calcite},
+ description = {a carbonate mineral},
+ category = {hierarchical}
+}
+
+ at entry{hier.quartz,
+ parent = {hier.mineral},
+ name = {quartz},
+ description = {hard mineral consisting of silica},
+ category = {hierarchical}
+}
+
+ at entry{hier.amethyst,
+ parent = {hier.quartz},
+ name = {amethyst},
+ description = {a purple type of quartz},
+ category = {hierarchical}
+}
+
+ at entry{hier.citrine,
+ parent = {hier.quartz},
+ name = {citrine},
+ description = {a form of quartz with a colour ranging
+from pale yellow to brown due to ferric impurities},
+ category = {hierarchical}
+}
+
+ at entry{ex2.amethyst,
+ name = {amethyst},
+ description = {a purple type of quartz},
+ symbol = {\ce{SiO2}},
+ user3={A},
+ user4={A},
+ category = {standalone}
+}
+
+ at entry{ex3.goose,
+ name={goose},
+ user3={G},
+ user4={G},
+ plural={geese},
+ description={a large waterbird with a long neck, short legs,
+ webbed feet and a short broad bill},
+ category={standalone}
+}
+
+ at entry{ex3.duck,
+ name={duck},
+ user3={D},
+ user4={D},
+ description={a waterbird with webbed feet},
+ category={standalone}
+}
+
+ at entry{standalone.pi,
+ name = {\ensuremath{\pi}},
+ description = {Archimedes' constant},
+ user3={glssymbols},
+ user4={greek},
+ category = {standalone}
+}
+
+ at entry{standalone.area,
+ name = {\ensuremath{A}},
+ description = {area},
+ user3={glssymbols},
+ user4={A},
+ category = {standalone}
+}
+
+ at entry{standalone.radius,
+ name = {\ensuremath{r}},
+ description = {radius},
+ user3={glssymbols},
+ user4={R},
+ category = {standalone}
+}
+
+ at entry{standalone.circumference,
+ name = {\ensuremath{C}},
+ user3={glssymbols},
+ user4={C},
+ description = {circumference},
+ category = {standalone}
+}
+
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex
===================================================================
--- trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex 2018-05-09 22:20:11 UTC (rev 47657)
+++ trunk/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex 2018-05-09 22:21:20 UTC (rev 47658)
@@ -9,6 +9,8 @@
\documentclass[titlepage=false,index=totoc,bibliography=totoc,
fontsize=12pt,captions=tableheading]{scrreprt}
+\usepackage{pifont}
+
% Need support for extended characters
% and need a mono font that supports hyphenation
\usepackage[no-math]{fontspec}
@@ -27,7 +29,6 @@
\usepackage{etoolbox}
\usepackage{hologo}
-\usepackage{xcolor}
\usepackage{amsmath}
\usepackage{accents}
\usepackage{tikz}
@@ -41,12 +42,15 @@
entrycounter,% enable entry counting
subentrycounter,% enable entry counting
%debug=showtargets,% debugging information
- stylemods=bookindex,% adjust predefined styles and load glossary-bookindex.sty
+ stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty
style=bookindex
]
{glossaries-extra}
+\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}}
+
\glsxtrprovidestoragekey{note}{}{}
+\glsxtrprovidestoragekey{package}{}{}
\providecommand{\omicron}{o}
@@ -85,6 +89,12 @@
\newcommand{\glsxtrpostnameenvironment}{\space environment}
\newcommand{\glsxtrpostnamecounter}{\space counter}
+\newcommand*{\csfmt}[1]{%
+ \texorpdfstring
+ {\texttt{\char`\\ #1}}%
+ {\string\\#1}%
+}
+
\setabbreviationstyle[common]{short-nolong}
\GlsXtrLoadResources[
@@ -91,6 +101,7 @@
label-prefix={idx.},
save-loclist=false,
sort={letternumber-nocase},
+ sort-replace={{\glshex2423}{ },{\string\\([a-zA-Z])}{\glscapturedgroup1}},
type={index},
dual-field={dualid},
match-action={add},
@@ -177,15 +188,10 @@
\let\-\empty
}
-\newcommand*{\csfmt}[1]{%
- \texorpdfstring
- {\texttt{\char`\\ #1}}%
- {\string\\#1}%
-}
-
% Provide commands that work like \gls[#1]{idx.#2}[#3]
\glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
+\newcommand{\idxlink}[3][]{\glslink[#1]{idx.#2}{#3}}
\newcommand{\stringu}{\idx{cs.string}\idx{u}}
@@ -206,6 +212,7 @@
{\string\\jobname-#1.glstex}%
}
+\newcommand{\extstyopt}{\textsuperscript{\textdagger}}
\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
@@ -297,7 +304,7 @@
\newcommand*{\styopt}[2][]{%
\texorpdfstring%
{%
- \idx{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
}%
{#2\ifblank{#1}{}{=#1}}%
}
@@ -513,6 +520,69 @@
}%
}
+\newglossarystyle{styoptsummary}%
+{%
+ \setglossarystyle{mcolindex}%
+ \renewcommand{\glossarypreamble}{%
+ Most options are in the form \meta{option}=\meta{value} and
+ may have a default if \meta{value} is omitted,
+ but some options don't have values and should not have
+ one assigned. For boolean options,
+ if the value is omitted \styoptfmt{true} is assumed.
+ \extstyopt Indicates a value that's only provided by
+ \styfmt{glossaries-extra} and not by the base
+ \styfmt{glossaries} package. \par
+ }%
+ \renewcommand*{\glossaryheader}{}%
+ \renewcommand*{\glsgroupheading}[1]{%
+ \glsxtrgetgrouptitle{##1}{\thisgrptitle}%
+ \glsxtrbookindexbookmark{\thisgrptitle}{styopt.##1}%
+ \glsxtrbookindexformatheader{\thisgrptitle}%
+ \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}%
+ }%
+ \renewcommand*{\glossentry}[2]{%
+ \item \glstarget{##1}{\strut}%
+ \glsxtrifhasfield{dualid}{##1}%
+ {%
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
+ {%
+ \gls[hyper=false]{##1}%
+ }%
+ \glsxtrifhasfield{useri}{##1}{=\glscurrentfieldvalue}{}%
+ \nopagebreak\par\hspace{10pt}%
+ \Glossentrydesc{##1}.%
+ \glsxtrifhasfield{package}{##1}%
+ {\nopagebreak\par \ding{43}Provided by
+ \ifdefstring{\glscurrentfieldvalue}{glossaries,glossaries-extra}
+ {\styfmt{glossaries} and modified by \styfmt{glossaries-extra}}%
+ {\styfmt{\glscurrentfieldvalue}}.}%
+ {}%
+ \glsxtrifhasfield{note}{##1}%
+ {\space \xmakefirstuc{\glscurrentfieldvalue}.}%
+ {}%
+ \par\medskip
+ }%
+}
+
+\newcommand*{\styoptsummaryhook}[1]{%
+ \edef\currentcategory{\glscategory{#1}}%
+ \ifdefstring{\currentcategory}{packageoption}%
+ {}%
+ {\printunsrtglossaryskipentry}%
+}
+
+\newcommand*{\printstyoptsummary}{%
+ \printunsrtglossary*[type=main,
+ style=styoptsummary,
+ title={Package Option Summary}
+ ]%
+ {%
+ \let\printunsrtglossaryentryprocesshook\styoptsummaryhook
+ \glsxtrlocalsetgrouptitle{glssymbols}{@}%
+ }%
+}
+
\newcommand{\entrysection}[2][\subsection]{%
#1[\texorpdfstring{\glsxtrheadname{entry.#2}}{\glsentryname{entry.#2}}]
{\glsadd{entry.#2}\glsxtrglossentry{entry.#2}}%
@@ -672,15 +742,13 @@
\DTMsetstyle{pdf}
\protected at edef\x{\endgroup
\noexpand\hypersetup{%
- pdfinfo={
- Title={\@title},
- Author={\@author},
- CreationDate={\DTMuse{creation}},
- ModDate={\DTMuse{moddate}},
+ pdfinfo={
+ Title={\@title},
+ Author={\@author},
+ CreationDate={\DTMuse{creation}},
+ ModDate={\DTMuse{moddate}},
+ }%
}%
- %\noexpand\pdfinfo{/CreationDate (\DTMuse{creation})
- %/ModDate (\DTMuse{moddate})}
- }%
}\x
\makeatother
@@ -726,6 +794,11 @@
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
+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.
\end{abstract}
\frontmatter
@@ -757,8 +830,13 @@
hierarchical sorting and can collate location lists, it doubles as
an indexing application, which means that the \idx{makeglossaries}
step can be skipped.
+Note that \bibgls\ doesn't warn you if an entry that's referenced
+in the document doesn't exist in any of the supplied \ext{bib}
+files, but instead relies on the \styfmt{glossaries-extra} package
+to generate the warning. So at the end of the document build check
+the \ext{log} file for warnings.
-You can't use \ics{glsaddall} with this method as that command works
+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
entries defined, so \ics{glsaddall} does nothing. If you want to
@@ -1557,7 +1635,7 @@
protects against the possibility that the \catattr{glossname}
category attribute might be set to \optfmt{firstuc}, which
automatically converts the first letter of the name to
-upper case when displaying the glossary. See also
+\idx{uppercase} when displaying the glossary. See also
\longarg{mfirstuc-protection} and
\longarg{mfirstuc-math-protection}.)
@@ -1611,7 +1689,7 @@
So the \field{sort} value for this entry is set to \qtt{M}. The font
change (caused by math-mode and \ics{boldsymbol}) has been
ignored. The sort value therefore consists of a single Unicode
-character \hex{4D} (Latin upper case letter \qtt{M}, decimal value 77).
+character \hex{4D} (Latin \idx!{uppercase} letter \qtt{M}, decimal value 77).
For the \code{v} entry, the code is:
\begin{verbatim}
@@ -1623,7 +1701,7 @@
\end{alltt}
So the \field{sort} value for this entry is set to \qtt{\usebox\varrow},
which consists of two Unicode characters \hex{76}
-(Latin lower case letter \qtt{v}, decimal value 118) and
+(Latin \idx!{lowercase} letter \qtt{v}, decimal value 118) and
\hex{20D7} (combining right arrow above, decimal value 8407).
For the \code{set} entry, the code is:
@@ -1636,7 +1714,7 @@
\end{verbatim}
So the \field{sort} value for this entry is set to \qtt{S} (again
ignoring the font change). This consists of a single Unicode
-character \hex{53} (Latin upper case letter \qtt{S}, decimal value~83).
+character \hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value~83).
For the \code{card} entry, the code is:
\begin{verbatim}
@@ -1652,7 +1730,7 @@
font change has been discarded). In this case the sort value
consists of three Unicode characters \hex{7C} (vertical line, decimal
value 124),
-\hex{53} (Latin upper case letter \qtt{S}, decimal value 83) and
+\hex{53} (Latin \idx!{uppercase} letter \qtt{S}, decimal value 83) and
\hex{7C} again.
If \csopt[false]{interpret-preamble} had been used, \csfmt{card}
wouldn't be recognised and would be discarded leaving just \qtt{S}
@@ -1701,7 +1779,7 @@
If \csopt[letter-nocase]{sort} is used instead then, after conversion
by the interpreter, the sort values will all be changed to
-lower case. The order is now: \code{i} ($\imaginary$),
+\idx{lowercase}. The order is now: \code{i} ($\imaginary$),
\code{M} ($\mtx{M}$), \code{S} ($\set{S}$),
\code{v} ($\vec{v}$) and \code{card} ($\card{S}$).
The transcript (with \longarg{verbose}) now shows
@@ -1721,7 +1799,7 @@
S -> 's' (S) [115]
v -> '\usebox\varrow' (V) [118 8407]
\end{alltt}
-Note that the letter groups are upper case not lower case.
+Note that the letter groups are \idx{uppercase} not \idx{lowercase}.
Again the \code{card} entry doesn't have an associated
letter group.
@@ -1846,7 +1924,15 @@
Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag.
This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml}
resource file otherwise \bibgls\ will fallback on English.
+This also sets the default document locale when \csopt[doc]{sort} is
+used and the document doesn't have any language support.
+Note that \csopt[locale]{sort} uses the \idx{JVM}['s] default
+locale and is not governed by this switch.
+If a document doesn't have any locale support or has support
+for more than one language then it's best to explicitly set
+the required locale in the appropriate \idx{resourceset}.
+
\argsection{log-file}
Sets the name of the transcript file. By default, the name is the
@@ -1916,7 +2002,12 @@
\argsection{no-interpret}
Switch off the interpreter mode. See \sectionref{sec:texparserlib}
-for more details.
+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.
\argsection{no-break-space}
@@ -2138,7 +2229,7 @@
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 upper case, then this will
+convert the first letter of the name to \idx{uppercase}, then this will
cause a problem.
With \longarg{mfirstuc-math-protection} set, \bibgls\ will
@@ -2349,7 +2440,7 @@
\end{description}
The \idx{lettergroup} titles will typically have the first character
-converted to upper case for the alphabet sort methods
+converted to \idx{uppercase} for the alphabet sort methods
(\tableref{tab:sortoptionsrule}). A \qt{letter} may not necessarily
be a single character (depending on the sort rule), but may be
composed of multiple characters, such as a \idx{digraph} (two
@@ -2364,8 +2455,8 @@
<entry key="grouptitle.case.ij">IJ</entry>
\end{verbatim}
If there isn't a \code{grouptitle.case.\meta{lc}} key (where
-\meta{lc} is the lower case version), then only the first character
-will be converted to upper case otherwise the value supplied by the
+\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
the alphabetical comparisons listed in
\tableref{tab:sortoptionsrule}. If the initial part of the sort
@@ -2380,7 +2471,7 @@
\code{Character.isAlphabetic(int)} method} then it will be a
\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive
ordering (such as \csopt[letter-nocase]{sort}) will convert the
-letter group character to upper case. The case-sensitive ordering
+letter group character to \idx{uppercase}. The case-sensitive ordering
(such as \csopt[letter-case]{sort}) won't change the case.
Glossary styles with navigational links to groups (such as
@@ -2808,6 +2899,12 @@
\caption[Fields Set by \bibgls]{Fields Sometimes Set by \bibgls\ in
the \iext{glstex} File}
\label{tab:internalfields}
+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
+\bigskip
\centering
\printfields{internalfield}%
\end{table}
@@ -2815,8 +2912,12 @@
\begin{table}[hbtp]
\caption[Internal Fields Set by \styfmt{glossaries} or
\styfmt{glossaries-extra} or \bibgls]{Internal Fields Set by
-\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls\
-(don't use in \ext{bib} files)}\label{tab:baseinternalfields}
+\styfmt{glossaries} or \styfmt{glossaries-extra} or \bibgls}%
+\label{tab:baseinternalfields}
+\medskip
+Don't define any of these and don't use any of them in the \ext{bib}
+file.\par
+\bigskip
\centering
\printfields{baseinternalfield}%
\end{table}
@@ -3255,6 +3356,52 @@
Terms that are defined using \atentry{index} will be written to the output
file using the command \csref{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
+\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}
+ at indexplural{goose,
+ plural = {geese}
+}
+
+ at indexplural{duck}
+
+ at indexplural{chateau,
+ text = {ch\^ateau},
+ plural = {ch\^ateaux}
+}
+\end{verbatim}
+This is equivalent to:
+\begin{verbatim}
+ at indexplural{goose,
+ name = {geese},
+ text = {goose},
+ plural = {geese}
+}
+
+ at indexplural{duck,
+ name = {ducks},
+ text = {duck},
+ plural = {ducks}
+}
+
+ at indexplural{chateau,
+ name = {ch\^ateaux},
+ text = {ch\^ateau},
+ plural = {ch\^ateaux}
+}
+\end{verbatim}
+
+Terms that are defined using \atentry{indexplural} will be written to the output
+file using the command \csref{bibglsnewindexplural}.
+
\entrysection{abbreviation}
The \atentry{abbreviation} entry type is designed for abbreviations.
@@ -3304,7 +3451,7 @@
\setabbreviationstyle{long-short-sc}
\GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}]
\end{verbatim}
-or to convert the short value to upper case and use the
+or to convert the short value to \idx{uppercase} and use the
\abbrstyle{long-short-sm} style instead:
\begin{verbatim}
\setabbreviationstyle{long-short-sm}
@@ -4661,7 +4808,7 @@
second line provides the internal list field
\field{bibtexentry at entrytype}, where \meta{entry-type} is the
original entry type (before it was aliased to
-\atentry{bibtexentry} and converted to lower case).
+\atentry{bibtexentry} and converted to \idx!{lowercase}).
For example \code{article} or \code{book}.
You can iterate over these internal list fields using
@@ -5564,6 +5711,101 @@
the \ext{glstex} file, so this will increase the total number of
entries.
+\section{Hierarchical Options}
+\label{sec:hierarchicalopts}
+
+\optsection{save-child-count}
+
+This is a boolean option. The default setting is
+\csopt[false]{save-child-count}.
+If \csopt[true]{save-child-count},
+each entry will be assigned a field called \field{childcount} with
+the value equal to the number of child entries that have been
+selected. As from version 1.5, this option also creates
+the \field{childlist} field for entries that have children
+selected. This field is in \sty{etoolbox}'s internal list
+format and can be iterated over using \ics{glsxtrfieldforlistloop}.
+
+The assignment is done using \ics{GlsXtrSetField} so there's
+no associated key. You can test if the field is set and non-zero
+using:
+\nosecformatdef{GlsXtrIfHasNonZeroChildCount}
+which is provided with \sty{glossaries-extra-bib2gls} v1.31+.
+Within \meta{true}, you can access the actual value with
+\ics{glscurrentfieldvalue}. If \csopt[false]{save-child-count},
+this command will do \meta{false} as the \field{childcount} field
+won't be set.
+
+For example, suppose \filefmt{entries.bib} contains:
+\begin{verbatim}
+ at index{birds}
+ at index{duck,parent={birds}}
+ at index{goose,plural={geese},parent={birds}}
+ at index{swan,parent={birds}}
+
+ at index{minerals}
+ at index{quartz,parent={minerals}}
+ at index{corundum,parent={minerals}}
+ at index{amethyst,parent={minerals}}
+ at index{gypsum,parent={minerals}}
+ at index{gold,parent={minerals}}
+\end{verbatim}
+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}
+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}
+Note that although \code{birds} has three children defined in the
+\ext{bib} file, only two have been selected, so the child count is
+set to 2. Similarly the \code{minerals} entry has five children
+defined in the \ext{bib} file, but only three have been selected, so
+the child count is 3.
+
+The 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.)}%
+ {}%
+}
+\end{verbatim}
+\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
+It's slightly more efficient that \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
+grouping. With \sty{glossaries-extra} v1.31+ you can perform a
+numerical test with \ics{GlsXtrIfFieldNonZero} or
+\ics{GlsXtrIfFieldEqNum}.
+
\optsection{flatten}
This is a boolean option. The default value is \csopt[false]{flatten}.
@@ -5924,6 +6166,124 @@
cross-references obtained from the \field{see} or \field{seealso}
fields. See \csopt{flatten-lonely} for further details.
+\optsection{strip-missing-parents}
+
+The \sty{glossaries} package requires that all child entries must be
+defined after the parent entry. An error occurs otherwise, so
+\bibgls\ will omit the \field{parent} field if it can't be found in
+the given \idx{resourceset}. However, when the default
+\csopt[false]{strip-missing-parents} is on, this omission only occurs
+while writing the definitions in the \ext{glstex} file (after
+selection and sorting).
+
+Sorting is performed hierarchically and the \field{group} field is set
+accordingly for the top-level entries (but not for child entries),
+which means that an entry with a \field{parent} field will be
+treated by the sort method as a child entry. This can lead to a
+strange result, which \bibgls\ warns about:
+\begin{alltt}
+Parent '\meta{parent id}' not found for entry \meta{child-id}
+\end{alltt}
+
+This is the default behaviour as it may simply be a result of a
+typing mistake in the \field{parent} field. If you actually want
+missing parents to be stripped before sorting (but after the
+selection process) then use \csopt[true]{strip-missing-parents}. If
+you want all parents stripped then use \csopt{flatten} or
+\csopt[parent]{ignore-fields} instead. As from version 1.4, if you
+want \bibgls\ to create the missing parents, then you can use
+\csopt[create]{missing-parents}.
+
+\optsection{missing-parents}
+
+As an alternative to \csopt{strip-missing-parents}, as from version
+1.4 you can now use \csopt[\meta{value}]{missing-parents} where
+\meta{value} may be one of:
+\begin{itemize}
+\item \optfmt{strip}: this is equivalent to
+\csopt[true]{strip-missing-parents};
+
+\item \optfmt{warn}: this is equivalent to the default
+\csopt[false]{strip-missing-parents};
+
+\item \optfmt{create}: this will create a new \atentry{index}
+entry with the missing parent's label (after it's been processed by
+options such as \csopt{labelify}) with the \field{name} obtained
+from the \emph{original} value of the \field{parent} field (before being
+processed by options like \csopt{labelify}).
+If the child entry has the \field{type} field set, then the new
+parent entry will be given the same value. The \field{category} for
+the new parent entry can be assigned with
+\csopt{missing-parent-category}.
+\end{itemize}
+
+For example, consider the \exfile{books.bib} file which contains
+entries like
+\begin{verbatim}
+ at entry{ubik,
+ name={Ubik},
+ description={novel by Philip K. Dick},
+ identifier={book},
+ author={\sortmediacreator{Philip K.}{Dick}},
+ year={1969}
+}
+\end{verbatim}
+then the field alias
+\begin{codeenv}
+\csopt[author=parent]{field-aliases}
+\end{codeenv}
+will treat
+\begin{verbatim}
+ author={\sortmediacreator{Philip K.}{Dick}},
+\end{verbatim}
+as though it had been defined as
+\begin{verbatim}
+ parent={\sortmediacreator{Philip K.}{Dick}},
+\end{verbatim}
+This can be converted into a label with the options:
+\begin{codeenv}
+ \csopt[parent]{labelify},
+ \csopt[
+ \marg{[ \cs{cs.string}\csfmt{.}]}\marg{}
+ ]{labelify-replace}
+\end{codeenv}
+If the interpreter has been provided with the definition:
+\begin{verbatim}
+\providecommand*{\sortmediacreator}[2]{#2 #1}
+\end{verbatim}
+then the \field{parent} field for the \code{ubik} entry
+will become \code{DickPhilipK} but the original value is stored
+internally when \csopt[create]{missing-parents} is set so that it
+can be used as the \field{name} if the parent needs to be created.
+Once all the entries have been processed, if \code{ubik} has been
+selected but no entry can be found with the label \code{DickPhilipK}
+then a new entry will be added as though it had been defined with:
+\begin{verbatim}
+ at index{DickPhilipK,
+ name={\sortmediacreator{Philip K.}{Dick}}
+}
+\end{verbatim}
+This is an alternative approach to the \exfile{sample-authors.tex}
+document from the \hyperref[sec:examples]{examples chapter}.
+
+\optsection{missing-parent-category}
+
+If a missing parent entry is created through the use of
+\csopt[create]{missing-parents} then the \field{category} field can
+be assigned to the new parent entry with this option. The
+\meta{value} may be one of:
+\begin{itemize}
+ \item \code{same as child}: the parent entry's \field{category}
+ field is set to the same value as the child's (if set);
+ \item \code{same as base}: the parent entry's \field{category} is
+ set to the base name of the \ext{bib} file that provided the
+ child entry's definition;
+ \item \code{no value}: don't set the \field{category} field;
+ \item \meta{label}: the parent entry's \field{category} field is set to
+ \meta{label} (which shouldn't contain any special characters).
+\end{itemize}
+The default setting is \csopt[no value]{missing-parent-category}.
+
\section{Master Documents}
\label{sec:master}
@@ -6161,7 +6521,7 @@
\end{verbatim}
\section{Field and Label Options}
-\label{sec:labelopts}
+\label{sec:fieldlabelopts}
The options in this section may be used to set or adjust field
values or labels. Some field values are expected to be labels (such
@@ -6169,198 +6529,11 @@
characters or commands, but it's possible to convert a field value
into a valid label using options such as \csopt{labelify}.
-\optsection{group}
+\subsection{Label Options}
+\label{sec:labelopts}
-The \csopt{group} option may only be used with the \longarg{group} switch.
-This will set the \field{group} field to \meta{label} unless
-\meta{label} is \optfmt{auto}, in which case the value is
-set automatically during the sorting (see also
-\csopt{group-formation}).
-The corresponding title can be set
-with \gls{glsxtrsetgrouptitle} if the title is different from the
-label. The default behaviour is \csopt[auto]{group}.
+\optsection[\subsubsection]{interpret-label-fields}
-For example:
-\begin{verbatim}
-\GlsXtrLoadResources[sort=integer,group={Constants},
- src={entries-constants}% data in entries-constants.bib
-]
-\GlsXtrLoadResources[sort=letter-case,group={Variables},
- src={entries-variables}% data in entries-variables.bib
-]
-\end{verbatim}
-In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
-these entries will be added to the same glossary, but will
-be grouped according to each instance of \gls{GlsXtrLoadResources},
-with the provided group label.
-
-
-\optsection{category}
-
-The selected entries may all have their \field{category} field
-changed before writing their definitions to the \ext{glstex} file.
-The \meta{value} may be:
-\begin{itemize}
-\item \optfmt{same as entry}: set the
-\field{category} to the \ext{bib} entry type used to define it
-(lower case and without the initial \code{@}) after any aliasing,
-if applicable;
-
-\item \optfmt{same as original entry}: (new to v1.4) set the \field{category}
-to the original entry type (lower case and without
-the initial \code{@}) before it was aliased (behaves like
-\optfmt{same as entry} if the entry type wasn't aliased);
-
-\item \optfmt{same as base}: (new to v1.1) set the \field{category}
-to the base name of the \ext{bib} file (without the extension)
-that provided the entry definition;
-
-\item \optfmt{same as type}: set the \field{category} to the same
-value as the \field{type} field (if that field has been provided
-either in the \ext{bib} file or through the \csopt{type} option);
-
-\item \meta{label}: the \field{category} is set to
-\meta{label} (which mustn't contain any special characters).
-\end{itemize}
-This will override any
-\field{category} fields supplied in the \ext{bib} file.
-
-When used with \csopt{entry-type-aliases}, the option \csopt[same as
-entry]{category} refers to the \emph{target} entry type whereas
-\csopt[same as original entry]{category} refers to the
-\emph{original} entry type given in the \ext{bib} file. In both
-cases, the value is converted to lower case to ensure consistency.
-
-For example, if the \ext{bib} file contains:
-\begin{verbatim}
- at entry{bird,
- name={bird},
- description = {feathered animal}
-}
-
- at index{duck}
-
- at index{goose,plural="geese"}
-
- at dualentry{dog,
- name={dog},
- description={chien}
-}
-\end{verbatim}
-then if the document contains
-\begin{verbatim}
-\GlsXtrLoadResources[category={same as entry},src={entries}]
-\end{verbatim}
-this will set the \field{category} of the \code{bird} term to
-\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and
-\code{goose} terms to \optfmt{index} (since they were defined
-with \atentry{index}), and the \field{category} of the \code{dog}
-term to \optfmt{dualentry} (since it was
-defined with \atentry{dualentry}). Note that the dual entry
-\code{dual.dog} doesn't have the category set, since that's
-governed by \csopt{dual-category} instead.
-
-If, instead, the document contains
-\begin{verbatim}
-\GlsXtrLoadResources[category={animals},src={entries}]
-\end{verbatim}
-then the \field{category} of all the primary selected entries will
-be set to \optfmt{animals}. Again the dual entry \code{dual.dog}
-doesn't have the \field{category} set.
-
-Note that the categories may be overridden by the commands,
-such as \csref{bibglsnewindex}, that are used to actually define the
-entries.
-
-For example, if the document contains
-\begin{verbatim}
-\newcommand{\bibglsnewdualentry}[4]{%
- \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}%
-}
-
-\GlsXtrLoadResources[category={animals},src={entries}]
-\end{verbatim}
-then both the \code{dog} and \code{dual.dog} entries will
-have their \field{category} field set to \optfmt{dual} since the
-new definition of \gls{bibglsnewdualentry} has overridden
-the \csopt[animals]{category} option.
-
-\optsection{type}
-
-The \meta{value} may be one of:
-\begin{itemize}
- \item \optfmt{same as entry} set the \field{type} field
- to the entry type (lower case and without the initial \code{@});
-
- \item \optfmt{same as original entry} set the \field{type}
- to the original entry type (lower case and without
- the initial \code{@}) before it was aliased (behaves like
- \optfmt{same as entry} if the entry type wasn't aliased);
-
- \optfmt{same as base} set the \field{type} field
- to the base name of the corresponding \ext{bib} file
- (without the extension);
-
- \item \optfmt{same as category} set the \field{type} field
- to the same value as the \field{category} field
- (\field{type} unchanged if \field{category} not set);
-
- \item\meta{label} sets the \field{type} field to the glossary
- identified by \meta{label}.
-\end{itemize}
-When used with \csopt{entry-type-aliases}, the option \csopt[same as
-entry]{type} refers to the \emph{target} entry type and \csopt[same
-as original entry]{type} refers to the \emph{original} entry type
-given in the \ext{bib} file. It's not possible to have both
-\csopt[same as type]{category} and \csopt[same as category]{type}.
-
-Note that this setting only changes the \field{type} field for
-primary entries. Use \csopt{dual-type} for dual entries.
-
-For example:
-\begin{verbatim}
-\usepackage[record,symbols]{glossaries-extra}
-
-\GlsXtrLoadResources[src={entries-symbols},type=symbols]
-\end{verbatim}
-
-Make sure that the glossary type has already been defined
-(see \sectionref{sec:newglossary}). In the above, the
-\styopt{symbols} option defines the \code{symbols} glossary.
-If you want to use a custom glossary, you need to provide it. For
-example:
-\begin{verbatim}
-\usepackage[record,nomain]{glossaries-extra}
-
-\newglossary*{dictionary}{Dictionary}
-
-\GlsXtrLoadResources[src={entries-symbols},type=dictionary]
-\end{verbatim}
-(The \styopt{nomain} option was added to suppress the
-creation of the default \code{main} glossary.)
-
-\optsection{trigger-type}
-
-The record counting commands, such as \ics{rgls}, use the special
-format \ics{glstriggerrecordformat}, which \bibgls\ also treats
-as an \idx{ignoredrecord}. This means the entry will still be
-identified as having a record for selection purposes, which is
-necessary for the entry to be defined for use in the document, but
-in order to prevent it from appearing in the glossary you need to
-transfer the entry with \csopt[\meta{type}]{trigger-type}.
-This will override the \csopt{type}, \csopt{dual-type},
-\csopt{tertiary-type} and the type specification in
-\csopt{secondary}.
-
-The provided value \meta{type} must be a glossary label (not one of
-the keywords allowed by \csopt{type}).
-You can define the glossary before loading the resource, but
-it's not required as \bibgls\ will write
-\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file
-(see \sectionref{sec:newglossary}).
-
-\optsection{interpret-label-fields}
-
This is a boolean option that determines whether or not the fields
that may only contain labels should have their values interpreted
(\field{parent}, \field{category}, \field{type}, \field{group},
@@ -6381,7 +6554,7 @@
fields. The \csopt{labelify} and \csopt{labelify-list} options
are performed before \csopt{interpret-label-fields}.
-\optsection{labelify}
+\optsection[\subsubsection]{labelify}
This option should take a comma-separated list of recognised field names as the
value. (If a field is present in both \csopt{labelify} and
@@ -6465,7 +6638,7 @@
]
\end{verbatim}
-\optsection{labelify-list}
+\optsection[\subsubsection]{labelify-list}
This option is like \csopt{labelify} but it retains commas, as it's
designed for fields that should be converted into a comma-separated
@@ -6488,7 +6661,7 @@
\end{verbatim}
depending on whether or not \sty{fontspec} was detected.
-\optsection{labelify-replace}
+\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}
@@ -6500,7 +6673,24 @@
match a literal \idx{full-stop} use \cs{cs.string}\ics{cs.period}
rather than just \ics{cs.period} (backslash dot).
-Both \csopt{labelify} and \csopt{labelify-list} use this setting to
+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}
+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
+characters are automatically stripped), but
+\csopt{sort-replace} follows the same rules as
+\csopt{labelify-replace}, and it may be needed
+for that.
+
+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}
@@ -6551,126 +6741,463 @@
\end{verbatim}
depending on whether or not \sty{fontspec} was detected.
-\optsection{strip-missing-parents}
+\optsection[\subsubsection]{label-prefix}
-The \sty{glossaries} package requires that all child entries must be
-defined after the parent entry. An error occurs otherwise, so
-\bibgls\ will omit the \field{parent} field if it can't be found in
-the given \idx{resourceset}. However, when the default
-\csopt[false]{strip-missing-parents} is on, this omission only occurs
-while writing the definitions in the \ext{glstex} file (after
-selection and sorting).
+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.
-Sorting is performed hierarchically and the \field{group} field is set
-accordingly for the top-level entries (but not for child entries),
-which means that an entry with a \field{parent} field will be
-treated by the sort method as a child entry. This can lead to a
-strange result, which \bibgls\ warns about:
-\begin{alltt}
-Parent '\meta{parent id}' not found for entry \meta{child-id}
-\end{alltt}
+For example, if the \ext{bib} file contains
+\begin{verbatim}
+ at entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{duck} or \gls {goose}}
+}
-This is the default behaviour as it may simply be a result of a
-typing mistake in the \field{parent} field. If you actually want
-missing parents to be stripped before sorting (but after the
-selection process) then use \csopt[true]{strip-missing-parents}. If
-you want all parents stripped then use \csopt{flatten} or
-\csopt[parent]{ignore-fields} instead. As from version 1.4, if you
-want \bibgls\ to create the missing parents, then you can use
-\csopt[create]{missing-parents}.
+ at entry{waterfowl,
+ name={waterfowl},
+ description={Any \gls{bird} that lives in or about water},
+ see={[see also]{duck,goose}}
+}
-\optsection{missing-parents}
+ at index{duck}
-As an alternative to \csopt{strip-missing-parents}, as from version
-1.4 you can now use \csopt[\meta{value}]{missing-parents} where
-\meta{value} may be one of:
-\begin{itemize}
-\item \optfmt{strip}: this is equivalent to
-\csopt[true]{strip-missing-parents};
+ at index{goose,plural="geese"}
+\end{verbatim}
+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}
+ at entry{gls.bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{gls.duck} or
+\gls{gls.goose}}
+}
-\item \optfmt{warn}: this is equivalent to the default
-\csopt[false]{strip-missing-parents};
+ at entry{gls.waterfowl,
+ name={waterfowl},
+ description={Any \gls{gls.bird} that lives in or about water},
+ see={[see also]{gls.duck,gls.goose}}
+}
-\item \optfmt{create}: this will create a new \atentry{index}
-entry with the missing parent's label (after it's been processed by
-options such as \csopt{labelify}) with the \field{name} obtained
-from the \emph{original} value of the \field{parent} field (before being
-processed by options like \csopt{labelify}).
-If the child entry has the \field{type} field set, then the new
-parent entry will be given the same value. The \field{category} for
-the new parent entry can be assigned with
-\csopt{missing-parent-category}.
+ at index{gls.duck,name={duck}}
+
+ at index{gls.goose,name={goose},plural="geese"}
+\end{verbatim}
+
+Remember to use this prefix when you reference the terms in the
+document with commands like \ics{gls}.
+
+\optsection[\subsubsection]{duplicate-label-suffix}
+
+The \sty{glossaries} package doesn't permit entries with duplicate
+labels (even if they're in different glossaries). If you
+have multiple \idxpl{resourceset} and an entry that's selected
+in one \idx{resourceset} is also selected in another, by
+default, \bibgls\ will issue a warning, but it will still write the
+entry definition to the \ext{glstex} file, which means you'll also
+get a warning from \sty{glossaries-extra} and the duplicate
+definition will be ignored, but associated internal fields
+set with commands like \cs{GlsXtrSetField} may still be set.
+
+If you actually want the duplicate, you need to specify a
+suffix with \csopt{duplicate-label-suffix}. This suffix is only
+set just before writing the entry definition to the \ext{glstex}
+file, so it doesn't affect selection criteria nor can label
+substitutions be performed in any cross-references. Options such as
+\csopt{set-widest} that reference entry labels are incompatible
+as they will use the unsuffixed label.
+
+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
+the second duplicate, etc.
+
+\optsection[\subsubsection]{record-label-prefix}
+
+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 at record{bird}{}{page}{glsnumberformat}{1}
+\glsxtr at record{waterfowl}{}{page}{glsnumberformat}{1}
+\glsxtr at record{idx.duck}{}{page}{glsnumberformat}{1}
+\glsxtr at record{idx.goose}{}{page}{glsnumberformat}{1}
+\end{verbatim}
+The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
+though the records were given as:
+\begin{verbatim}
+\glsxtr at record{idx.bird}{}{page}{glsnumberformat}{1}
+\glsxtr at record{idx.waterfowl}{}{page}{glsnumberformat}{1}
+\glsxtr at record{idx.duck}{}{page}{glsnumberformat}{1}
+\glsxtr at record{idx.goose}{}{page}{glsnumberformat}{1}
+\end{verbatim}
+
+
+\optsection[\subsubsection]{cs-label-prefix}
+
+If you have commands such as \ics{gls}\margm{label} or
+\ics{glstext}\marg{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}
+\item if \meta{label} starts with \idprefix{dual} then
+\idprefix{dual} will be replaced by the \csopt{dual-prefix} value;
+\item if \meta{label} starts with \idprefix{tertiary} then
+\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value;
+\item if \meta{label} starts with \idprefix{extn} then
+\idprefix{extn} will be replaced by the corresponding
+\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is
+enabled, see \sectionref{sec:resourcesets});
+\item if \meta{label} doesn't start with one of the above recognised
+prefixes then, if \csopt{cs-label-prefix} has been used the supplied
+value will be inserted otherwise the \csopt{label-prefix} setting
+will be inserted.
\end{itemize}
+For example, given
+\begin{verbatim}
+ at entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{duck} or \gls{goose}}
+}
+\end{verbatim}
+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}
+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}
+regardless of the \csopt{label-prefix} setting. Whereas if the
+original entry definition is
+\begin{verbatim}
+ at entry{bird,
+ name={bird},
+ description = {feathered animal, such as a \gls{dual.duck} or
+\gls{dual.goose}}
+}
+\end{verbatim}
+then \idprefix{dual} will be replaced by the value of the
+\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix}
+setting.
-For example, consider the \exfile{books.bib} file which contains
-entries like
+The \csopt{cs-label-prefix} setting doesn't affect labels in the
+fields that have an entry label or label list as the value
+(\field{parent}, \field{alias}, \field{see} and \field{seealso}).
+
+\optsection[\subsubsection]{ext-prefixes}
+
+Any cross-references in the \iext{bib} file that start with
+\idprefix{extn} (where \meta{n} is a positive integer) will be
+substituted with the \meta{n}th tag listed in the comma-separated
+\meta{list}. If there aren't that many items in the list, the
+\idprefix{extn} will simply be removed. The default setting is
+an empty list, which will strip all \idprefix{extn} prefixes.
+Remember that \idx{crossresourceref} mode needs to be enabled for
+this option to work (see \sectionref{sec:resourcesets}).
+
+For example, suppose the file \filefmt{entries-terms.bib} contains:
\begin{verbatim}
- at entry{ubik,
- name={Ubik},
- description={novel by Philip K. Dick},
- identifier={book},
- author={\sortmediacreator{Philip K.}{Dick}},
- year={1969}
+ at entry{set,
+ name={set},
+ description={collection of values, denoted \gls{ext1.set}}
}
\end{verbatim}
-then the field alias
-\begin{codeenv}
-\csopt[author=parent]{field-aliases}
-\end{codeenv}
-will treat
+and the file \filefmt{entries-symbols.bib} contains:
\begin{verbatim}
- author={\sortmediacreator{Philip K.}{Dick}},
+ at symbol{set,
+ name={\ensuremath{\mathcal{S}}},
+ description={a \gls{ext1.set}}
+}
\end{verbatim}
-as though it had been defined as
+
+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
+two files can be loaded without conflict using:
\begin{verbatim}
- parent={\sortmediacreator{Philip K.}{Dick}},
+\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}
-This can be converted into a label with the options:
-\begin{codeenv}
- \csopt[parent]{labelify},
- \csopt[
- \marg{[ \cs{cs.string}\csfmt{.}]}\marg{}
- ]{labelify-replace}
-\end{codeenv}
-If the interpreter has been provided with the definition:
+
+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}
-\providecommand*{\sortmediacreator}[2]{#2 #1}
+collection of values, denoted \gls{sym.set}
\end{verbatim}
-then the \field{parent} field for the \code{ubik} entry
-will become \code{DickPhilipK} but the original value is stored
-internally when \csopt[create]{missing-parents} is set so that it
-can be used as the \field{name} if the parent needs to be created.
-Once all the entries have been processed, if \code{ubik} has been
-selected but no entry can be found with the label \code{DickPhilipK}
-then a new entry will be added as though it had been defined with:
+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}
- at index{DickPhilipK,
- name={\sortmediacreator{Philip K.}{Dick}}
+a \gls{gls.set}
+\end{verbatim}
+
+Note that in this case the \ext{bib} files have to be loaded
+as two separate resources. They can't be combined into a
+single \csopt{src} list as the labels aren't unique.
+
+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}
+ at entry{set,
+ name={set},
+ description={collection of values, denoted \gls{ext1.S}}
}
\end{verbatim}
-This is an alternative approach to the \exfile{sample-authors.tex}
-document from the \hyperref[sec:examples]{examples chapter}.
+and \filefmt{entries-symbols.bib} could contain:
+\begin{verbatim}
+ at symbol{S,
+ name={\ensuremath{\mathcal{S}}},
+ description={a \gls{ext1.set}}
+}
+\end{verbatim}
+Now they can be combined with:
+\begin{verbatim}
+\GlsXtrLoadResources[src={entries-terms,entries-symbols}]
+\end{verbatim}
+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}
+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
+cross-references.
-\optsection{missing-parent-category}
+\optsection[\subsubsection]{save-original-id}
-If a missing parent entry is created through the use of
-\csopt[create]{missing-parents} then the \field{category} field can
-be assigned to the new parent entry with this option. The
-\meta{value} may be one of:
+The \meta{value} may be either the keyword \code{false} or
+the name of an internal field in which to store the entry's original
+label (as given in the \ext{bib} file). The default setting is
+\csopt[false]{save-original-id}. If \meta{value} is omitted,
+\csopt[originalid]{save-original-id} is assumed.
+
+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.
+
+\subsection{Assignments}
+\label{sec:fieldassignments}
+
+\optsection[\subsubsection]{group}
+
+The \csopt{group} option may only be used with the \longarg{group} switch.
+This will set the \field{group} field to \meta{label} unless
+\meta{label} is \optfmt{auto}, in which case the value is
+set automatically during the sorting (see also
+\csopt{group-formation}).
+The corresponding title can be set
+with \gls{glsxtrsetgrouptitle} if the title is different from the
+label. The default behaviour is \csopt[auto]{group}.
+
+For example:
+\begin{verbatim}
+\GlsXtrLoadResources[sort=integer,group={Constants},
+ src={entries-constants}% data in entries-constants.bib
+]
+\GlsXtrLoadResources[sort=letter-case,group={Variables},
+ src={entries-variables}% data in entries-variables.bib
+]
+\end{verbatim}
+In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
+these entries will be added to the same glossary, but will
+be grouped according to each instance of \gls{GlsXtrLoadResources},
+with the provided group label.
+
+
+\optsection[\subsubsection]{category}
+
+The selected entries may all have their \field{category} field
+changed before writing their definitions to the \ext{glstex} file.
+The \meta{value} may be:
\begin{itemize}
- \item \code{same as child}: the parent entry's \field{category}
- field is set to the same value as the child's (if set);
- \item \code{same as base}: the parent entry's \field{category} is
- set to the base name of the \ext{bib} file that provided the
- child entry's definition;
- \item \code{no value}: don't set the \field{category} field;
- \item \meta{label}: the parent entry's \field{category} field is set to
- \meta{label} (which shouldn't contain any special characters).
+\item \optfmt{same as entry}: set the
+\field{category} to the \ext{bib} entry type used to define it
+(\idx!{lowercase} and without the initial \code{@}) after any aliasing,
+if applicable;
+
+\item \optfmt{same as original entry}: (new to v1.4) set the \field{category}
+to the original entry type (\idx!{lowercase} and without
+the initial \code{@}) before it was aliased (behaves like
+\optfmt{same as entry} if the entry type wasn't aliased);
+
+\item \optfmt{same as base}: (new to v1.1) set the \field{category}
+to the base name of the \ext{bib} file (without the extension)
+that provided the entry definition;
+
+\item \optfmt{same as type}: set the \field{category} to the same
+value as the \field{type} field (if that field has been provided
+either in the \ext{bib} file or through the \csopt{type} option);
+
+\item \meta{label}: the \field{category} is set to
+\meta{label} (which mustn't contain any special characters).
\end{itemize}
-The default setting is \csopt[no value]{missing-parent-category}.
+This will override any
+\field{category} fields supplied in the \ext{bib} file.
-\optsection{abbreviation-name-fallback}
+When used with \csopt{entry-type-aliases}, the option \csopt[same as
+entry]{category} refers to the \emph{target} entry type whereas
+\csopt[same as original entry]{category} refers to the
+\emph{original} entry type given in the \ext{bib} file. In both
+cases, the value is converted to \idx!{lowercase} to ensure consistency.
+For example, if the \ext{bib} file contains:
+\begin{verbatim}
+ at entry{bird,
+ name={bird},
+ description = {feathered animal}
+}
+
+ at index{duck}
+
+ at index{goose,plural="geese"}
+
+ at dualentry{dog,
+ name={dog},
+ description={chien}
+}
+\end{verbatim}
+then if the document contains
+\begin{verbatim}
+\GlsXtrLoadResources[category={same as entry},src={entries}]
+\end{verbatim}
+this will set the \field{category} of the \code{bird} term to
+\optfmt{entry} (since it was defined with \atentry{entry}), the \field{category} of the \code{duck} and
+\code{goose} terms to \optfmt{index} (since they were defined
+with \atentry{index}), and the \field{category} of the \code{dog}
+term to \optfmt{dualentry} (since it was
+defined with \atentry{dualentry}). Note that the dual entry
+\code{dual.dog} doesn't have the category set, since that's
+governed by \csopt{dual-category} instead.
+
+If, instead, the document contains
+\begin{verbatim}
+\GlsXtrLoadResources[category={animals},src={entries}]
+\end{verbatim}
+then the \field{category} of all the primary selected entries will
+be set to \optfmt{animals}. Again the dual entry \code{dual.dog}
+doesn't have the \field{category} set.
+
+Note that the categories may be overridden by the commands,
+such as \csref{bibglsnewindex}, that are used to actually define the
+entries.
+
+For example, if the document contains
+\begin{verbatim}
+\newcommand{\bibglsnewdualentry}[4]{%
+ \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}%
+}
+
+\GlsXtrLoadResources[category={animals},src={entries}]
+\end{verbatim}
+then both the \code{dog} and \code{dual.dog} entries will
+have their \field{category} field set to \optfmt{dual} since the
+new definition of \gls{bibglsnewdualentry} has overridden
+the \csopt[animals]{category} option.
+
+\optsection[\subsubsection]{type}
+
+The \meta{value} may be one of:
+\begin{itemize}
+ \item \optfmt{same as entry} set the \field{type} field
+ to the entry type (\idx!{lowercase} and without the initial \code{@});
+
+ \item \optfmt{same as original entry} set the \field{type}
+ to the original entry type (\idx!{lowercase} and without
+ the initial \code{@}) before it was aliased (behaves like
+ \optfmt{same as entry} if the entry type wasn't aliased);
+
+ \optfmt{same as base} set the \field{type} field
+ to the base name of the corresponding \ext{bib} file
+ (without the extension);
+
+ \item \optfmt{same as category} set the \field{type} field
+ to the same value as the \field{category} field
+ (\field{type} unchanged if \field{category} not set);
+
+ \item\meta{label} sets the \field{type} field to the glossary
+ identified by \meta{label}.
+\end{itemize}
+When used with \csopt{entry-type-aliases}, the option \csopt[same as
+entry]{type} refers to the \emph{target} entry type and \csopt[same
+as original entry]{type} refers to the \emph{original} entry type
+given in the \ext{bib} file. It's not possible to have both
+\csopt[same as type]{category} and \csopt[same as category]{type}.
+
+Note that this setting only changes the \field{type} field for
+primary entries. Use \csopt{dual-type} for dual entries.
+
+For example:
+\begin{verbatim}
+\usepackage[record,symbols]{glossaries-extra}
+
+\GlsXtrLoadResources[src={entries-symbols},type=symbols]
+\end{verbatim}
+
+Make sure that the glossary type has already been defined
+(see \sectionref{sec:newglossary}). In the above, the
+\styopt{symbols} option defines the \code{symbols} glossary.
+If you want to use a custom glossary, you need to provide it. For
+example:
+\begin{verbatim}
+\usepackage[record,nomain]{glossaries-extra}
+
+\newglossary*{dictionary}{Dictionary}
+
+\GlsXtrLoadResources[src={entries-symbols},type=dictionary]
+\end{verbatim}
+(The \styopt{nomain} option was added to suppress the
+creation of the default \code{main} glossary.)
+
+\optsection[\subsubsection]{trigger-type}
+
+The record counting commands, such as \ics{rgls}, use the special
+format \ics{glstriggerrecordformat}, which \bibgls\ also treats
+as an \idx{ignoredrecord}. This means the entry will still be
+identified as having a record for selection purposes, which is
+necessary for the entry to be defined for use in the document, but
+in order to prevent it from appearing in the glossary you need to
+transfer the entry with \csopt[\meta{type}]{trigger-type}.
+This will override the \csopt{type}, \csopt{dual-type},
+\csopt{tertiary-type} and the type specification in
+\csopt{secondary}.
+
+The provided value \meta{type} must be a glossary label (not one of
+the keywords allowed by \csopt{type}).
+You can define the glossary before loading the resource, but
+it's not required as \bibgls\ will write
+\ics{provideignoredglossary*}\margm{type} to the \ext{glstex} file
+(see \sectionref{sec:newglossary}).
+
+\optsection[\subsubsection]{abbreviation-name-fallback}
+
The entry types that define abbreviations (such as
\atentry{abbreviation} and \atentry{acronym}) will, by default,
fallback on the \field{short} field if the \field{name} field is
@@ -6681,7 +7208,7 @@
\csopt[long]{abbreviation-name-fallback}.
The \meta{field} value must be a known field label.
-\optsection{ignore-fields}
+\optsection[\subsubsection]{ignore-fields}
The \csopt{ignore-fields} key indicates that you want \bibgls\ to
skip the fields listed in the supplied comma-separated \meta{list} of field
@@ -6710,7 +7237,7 @@
omit the \field{parent} field when writing the entries to the
\ext{glstex} file, you need to use \csopt{flatten} instead.
-\optsection{field-aliases}
+\optsection[\subsubsection]{field-aliases}
You can instruct \bibgls\ to treat one field as though it
was another using this option. The value should be a comma-separated
@@ -6748,7 +7275,7 @@
]
\end{verbatim}
-\optsection{replicate-fields}
+\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
@@ -6833,7 +7360,7 @@
]
\end{verbatim}
-\optsection{replicate-override}
+\optsection[\subsubsection]{replicate-override}
This is a boolean option. The default setting is
\csopt[false]{replicate-override}. If \optfmt{true},
@@ -6840,8 +7367,230 @@
\csopt{replicate-fields} will override the existing value if the
target field is already set.
-\optsection{bibtex-contributor-fields}
+\optsection[\subsubsection]{counter}
+The \csopt{counter} option assigns the default counter to use
+for the selected entries. (This can be overridden with the
+\glsopt{counter} key when using commands like \csfmt{gls}.)
+The value must be the name of a counter. Since \bibgls\ doesn't know
+which counters are defined within the document, there's no check to
+determine if the value is valid (except for ensuring that
+\meta{value} is non-empty).
+
+Note that this will require an extra \LaTeX\ and \bibgls\ call since
+the counter can't be used for the indexing until the entry has been
+defined.
+
+\optsection[\subsubsection]{copy-action-group-field}
+
+This option may only be used when invoking \bibgls\ with the
+\longarg{group} (or \shortargfmt{g}) switch. If an action
+other than the default \csopt[define]{action} is set,
+this option can be used to identify a field in which to save
+the letter group information
+where \meta{value} is the name of the field. This just uses
+\cs{GlsXtrSetField}. You will need to redefine
+\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary.
+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}
+ \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
+\end{alltt}
+
+This option is ignored when used with \csopt[define]{action}.
+This option is not used by \csopt{secondary} which will
+always save the group information in the \field{secondarygroup}
+field. When used with \csopt[define or copy]{action}, entries
+that are defined will have both \field{group} and
+the field given by \csopt{copy-action-group-field} set.
+
+Note that you may do \csopt[group]{copy-action-group-field} which
+will override the \field{group} field from the original definition.
+This may be useful if you don't use grouping in the primary
+glossary. That is, you use \code{nogroupskip} and a non-group
+style. For example:
+\begin{verbatim}
+\printunsrtglossary[nogroupskip,style=index]
+\printunsrtglossary[type=copies,style=indexgroup]
+\end{verbatim}
+
+\optsection[\subsubsection]{copy-alias-to-see}
+
+If set, the value of the \field{alias} field is copied to
+the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
+
+\subsection{Field Adjustments}
+\label{sec:fieldmods}
+
+\optsection[\subsubsection]{post-description-dot}
+
+The \styopt{postdot} package option (or \styopt[false]{nopostdot})
+can be used to append a \idx{full-stop} (\idx{periodchar})\ to the
+end of all the descriptions. This can be awkward if some of the
+descriptions end with punctuation characters. This resource option
+can be used instead. The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{none}: don't append a \idx{full-stop} (default);
+\item\optfmt{all}: append a \idx{full-stop} to all \field{description}
+ fields in this resource set;
+\item\optfmt{check}: selectively append a \idx{full-stop} (see below).
+\end{itemize}
+Note that if you have dual entries and you use this option to
+append a \idx{full-stop}, then it will be copied over to the mapped field.
+This is different to the \styopt{postdot} option which doesn't
+add the dot to the field but incorporates it in the
+\idx{postdescriptionhook}. This means that a dot inserted with
+\csopt{post-description-dot} will come before the
+\idx{postdescriptionhook} whereas with \styopt{postdot} the
+punctuation comes after any category-specific hook.
+
+The \csopt[check]{post-description-dot} setting determines whether
+to append the dot as follows:
+\begin{itemize}
+\item If the \field{description} field ends with
+\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended.
+\item If the \field{description} field doesn't end with a regular
+(ungrouped letter or other) character, then a dot is appended.
+(For example, if the description ends with a control sequence
+or an end group token.)
+\item If the \field{description} field ends with a character
+that belongs to the Unicode category \idx{punctuationclose}
+or \idx{punctuationfinalquote} then the token preceding
+that character is checked.
+\item If the \field{description} field doesn't end with
+a character that belongs to the Unicode category
+\idx{punctuationother} then the dot is added.
+\end{itemize}
+Note that the interpreter isn't used during the check.
+If the \field{description} ends with a command then a dot will be
+appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if
+that command expands in such a way that it ends with a terminating
+punctuation character. This option only applies to the
+\field{description} field.
+
+\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.
+
+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}
+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}
+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}
+because again it's not at the end.
+
+\optsection[\subsubsection]{check-end-punctuation}
+
+This options checks the end of all the fields given in \meta{list} for
+end of sentence punctuation. This is determined as follows, for each
+\meta{field} in the comma-separated \meta{list}:
+\begin{itemize}
+\item if the last character is of type \idx{punctuationclose}
+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}
+in \bibgls's \langxml.
+\end{itemize}
+If a sentence terminator is found, an internal field is created
+called \field{fieldendpunc} that contains the punctuation
+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}
+as:
+\begin{verbatim}
+<entry key="sentence.terminators">.?!</entry>
+\end{verbatim}
+Any character that isn't of type \idx{punctuationother} won't
+match.
+
+For example, the sample \exfile{books.bib} file contains:
+\begin{verbatim}
+ at entry{whydidnttheyaskevans,
+ name={Why Didn't They Ask Evans?},
+ description={novel by Agatha Christie},
+ identifier={book},
+ author={\sortmediacreator{Agatha}{Christie}},
+ year={1934}
+}
+\end{verbatim}
+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
+at the end of the \field{name} field:
+\begin{verbatim}
+\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?}
+\end{verbatim}
+(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}
+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.
+
+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
+\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}%
+}
+\end{verbatim}
+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
+as it introduces implicit scoping, which would interfere with the
+punctuation lookahead.) The other difference between
+\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests
+is the case where the field is set to an empty value. In this case
+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]{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:
@@ -6888,7 +7637,7 @@
Smith|John|Doe|Jane|von|Duck|Dickie
\end{verbatim}
-\optsection{contributor-order}
+\optsection[\subsubsection]{contributor-order}
The \gls{bibglscontributor} command is defined in
\bibgls's interpreter and its definition is dependent on this
@@ -6948,7 +7697,7 @@
\csopt[von]{bibtex-contributor-fields} setting when obtaining the
sort value.
-\optsection{date-time-fields}
+\optsection[\subsubsection]{date-time-fields}
This option indicates that the listed fields all contain
date and time information. Primary entries will have these fields
@@ -6966,7 +7715,7 @@
\idx{nbspchar} is converted to the non-breaking space character
\hex{A0} unless \longarg{break-space} is used.)
-\optsection{date-fields}
+\optsection[\subsubsection]{date-fields}
As \csopt{date-time-fields} but for fields that only contain date
(not time) information. If parsed correctly, the field is converted
@@ -6978,7 +7727,7 @@
\csopt{dual-date-field-format} and
\csopt{dual-date-field-locale} for dual entries.
-\optsection{time-fields}
+\optsection[\subsubsection]{time-fields}
As \csopt{date-time-fields} but for fields that only contain time
(not date) information. If parsed correctly, the field is converted
@@ -6990,7 +7739,7 @@
\csopt{dual-time-field-format} and
\csopt{dual-time-field-locale} for dual entries.
-\optsection{date-time-field-format}
+\optsection[\subsubsection]{date-time-field-format}
This option also sets
\csopt[\meta{value}]{dual-date-time-field-format}.
@@ -6998,7 +7747,7 @@
by \csopt{date-time-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{date-field-format}
+\optsection[\subsubsection]{date-field-format}
This option also sets
\csopt[\meta{value}]{dual-date-field-format}.
@@ -7006,7 +7755,7 @@
by \csopt{date-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{time-field-format}
+\optsection[\subsubsection]{time-field-format}
This option also sets
\csopt[\meta{value}]{dual-time-field-format}.
@@ -7014,7 +7763,7 @@
by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-format}.
-\optsection{date-time-field-locale}
+\optsection[\subsubsection]{date-time-field-locale}
This option also sets
\csopt[\meta{value}]{dual-date-time-field-locale}.
@@ -7022,7 +7771,7 @@
by \csopt{date-time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{date-field-locale}
+\optsection[\subsubsection]{date-field-locale}
This option also sets
\csopt[\meta{value}]{dual-date-field-locale}.
@@ -7030,7 +7779,7 @@
by \csopt{date-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{time-field-locale}
+\optsection[\subsubsection]{time-field-locale}
This option also sets
\csopt[\meta{value}]{dual-time-field-locale}.
@@ -7038,291 +7787,30 @@
by \csopt{time-fields}. The \meta{value} is as for
\csopt{date-sort-locale}.
-\optsection{counter}
+\subsection{Case-Changing}
+\label{sec:fieldcase}
-The \csopt{counter} option assigns the default counter to use
-for the selected entries. (This can be overridden with the
-\glsopt{counter} key when using commands like \csfmt{gls}.)
-The value must be the name of a counter. Since \bibgls\ doesn't know
-which counters are defined within the document, there's no check to
-determine if the value is valid (except for ensuring that
-\meta{value} is non-empty).
+\optsection[\subsubsection]{short-case-change}
-Note that this will require an extra \LaTeX\ and \bibgls\ call since
-the counter can't be used for the indexing until the entry has been
-defined.
-
-\optsection{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}
- at entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{duck} or \gls {goose}}
-}
-
- at entry{waterfowl,
- name={waterfowl},
- description={Any \gls{bird} that lives in or about water},
- see={[see also]{duck,goose}}
-}
-
- at index{duck}
-
- at index{goose,plural="geese"}
-\end{verbatim}
-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}
- at entry{gls.bird,
- name={bird},
- description = {feathered animal, such as a \gls{gls.duck} or
-\gls{gls.goose}}
-}
-
- at entry{gls.waterfowl,
- name={waterfowl},
- description={Any \gls{gls.bird} that lives in or about water},
- see={[see also]{gls.duck,gls.goose}}
-}
-
- at index{gls.duck,name={duck}}
-
- at index{gls.goose,name={goose},plural="geese"}
-\end{verbatim}
-
-Remember to use this prefix when you reference the terms in the
-document with commands like \ics{gls}.
-
-\optsection{duplicate-label-suffix}
-
-The \sty{glossaries} package doesn't permit entries with duplicate
-labels (even if they're in different glossaries). If you
-have multiple \idxpl{resourceset} and an entry that's selected
-in one \idx{resourceset} is also selected in another, by
-default, \bibgls\ will issue a warning, but it will still write the
-entry definition to the \ext{glstex} file, which means you'll also
-get a warning from \sty{glossaries-extra} and the duplicate
-definition will be ignored, but associated internal fields
-set with commands like \cs{GlsXtrSetField} may still be set.
-
-If you actually want the duplicate, you need to specify a
-suffix with \csopt{duplicate-label-suffix}. This suffix is only
-set just before writing the entry definition to the \ext{glstex}
-file, so it doesn't affect selection criteria nor can label
-substitutions be performed in any cross-references. Options such as
-\csopt{set-widest} that reference entry labels are incompatible
-as they will use the unsuffixed label.
-
-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
-the second duplicate, etc.
-
-\optsection{record-label-prefix}
-
-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 at record{bird}{}{page}{glsnumberformat}{1}
-\glsxtr at record{waterfowl}{}{page}{glsnumberformat}{1}
-\glsxtr at record{idx.duck}{}{page}{glsnumberformat}{1}
-\glsxtr at record{idx.goose}{}{page}{glsnumberformat}{1}
-\end{verbatim}
-The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
-though the records were given as:
-\begin{verbatim}
-\glsxtr at record{idx.bird}{}{page}{glsnumberformat}{1}
-\glsxtr at record{idx.waterfowl}{}{page}{glsnumberformat}{1}
-\glsxtr at record{idx.duck}{}{page}{glsnumberformat}{1}
-\glsxtr at record{idx.goose}{}{page}{glsnumberformat}{1}
-\end{verbatim}
-
-
-\optsection{cs-label-prefix}
-
-If you have commands such as \ics{gls}\margm{label} or
-\ics{glstext}\marg{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}
-\item if \meta{label} starts with \idprefix{dual} then
-\idprefix{dual} will be replaced by the \csopt{dual-prefix} value;
-\item if \meta{label} starts with \idprefix{tertiary} then
-\idprefix{tertiary} will be replaced by the \csopt{tertiary-prefix} value;
-\item if \meta{label} starts with \idprefix{extn} then
-\idprefix{extn} will be replaced by the corresponding
-\csopt{ext-prefixes} setting (if \idx{crossresourceref} mode is
-enabled, see \sectionref{sec:resourcesets});
-\item if \meta{label} doesn't start with one of the above recognised
-prefixes then, if \csopt{cs-label-prefix} has been used the supplied
-value will be inserted otherwise the \csopt{label-prefix} setting
-will be inserted.
-\end{itemize}
-For example, given
-\begin{verbatim}
- at entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{duck} or \gls{goose}}
-}
-\end{verbatim}
-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}
-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}
-regardless of the \csopt{label-prefix} setting. Whereas if the
-original entry definition is
-\begin{verbatim}
- at entry{bird,
- name={bird},
- description = {feathered animal, such as a \gls{dual.duck} or
-\gls{dual.goose}}
-}
-\end{verbatim}
-then \idprefix{dual} will be replaced by the value of the
-\csopt{dual-prefix} option regardless of the \csopt{cs-label-prefix}
-setting.
-
-The \csopt{cs-label-prefix} setting doesn't affect labels in the
-fields that have an entry label or label list as the value
-(\field{parent}, \field{alias}, \field{see} and \field{seealso}).
-
-\optsection{ext-prefixes}
-
-Any cross-references in the \iext{bib} file that start with
-\idprefix{extn} (where \meta{n} is a positive integer) will be
-substituted with the \meta{n}th tag listed in the comma-separated
-\meta{list}. If there aren't that many items in the list, the
-\idprefix{extn} will simply be removed. The default setting is
-an empty list, which will strip all \idprefix{extn} prefixes.
-Remember that \idx{crossresourceref} mode needs to be enabled for
-this option to work (see \sectionref{sec:resourcesets}).
-
-For example, suppose the file \filefmt{entries-terms.bib} contains:
-\begin{verbatim}
- at entry{set,
- name={set},
- description={collection of values, denoted \gls{ext1.set}}
-}
-\end{verbatim}
-and the file \filefmt{entries-symbols.bib} contains:
-\begin{verbatim}
- at symbol{set,
- name={\ensuremath{\mathcal{S}}},
- description={a \gls{ext1.set}}
-}
-\end{verbatim}
-
-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
-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}
-
-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}
-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}
-
-Note that in this case the \ext{bib} files have to be loaded
-as two separate resources. They can't be combined into a
-single \csopt{src} list as the labels aren't unique.
-
-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}
- at entry{set,
- name={set},
- description={collection of values, denoted \gls{ext1.S}}
-}
-\end{verbatim}
-and \filefmt{entries-symbols.bib} could contain:
-\begin{verbatim}
- at symbol{S,
- name={\ensuremath{\mathcal{S}}},
- description={a \gls{ext1.set}}
-}
-\end{verbatim}
-Now they can be combined with:
-\begin{verbatim}
-\GlsXtrLoadResources[src={entries-terms,entries-symbols}]
-\end{verbatim}
-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}
-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
-cross-references.
-
-\optsection{short-case-change}
-
The value of the \field{short} field may be automatically converted
-to upper or lower case. This option may take one of the following
+to \idxlink{uppercase}{upper} or \idx{lowercase}. This option may take one of the following
values:
\begin{itemize}
\item \optfmt{none}: don't apply any case-changing (default);
-\item \optfmt{lc}: convert to lower case (ignoring
+\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 upper case (ignoring
+\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 lower case using
+\item \optfmt{lc-cs}: convert to \idx{lowercase} using
\ics{MakeTextLowercase};
-\item \optfmt{uc-cs}: convert to upper case using
+\item \optfmt{uc-cs}: convert to \idx{uppercase} using
\ics{MakeTextUppercase};
-\item \optfmt{firstuc-cs}: convert to first letter upper case using
+\item \optfmt{firstuc-cs}: convert to first letter \idx{uppercase} using
\ics{makefirstuc};
\item \optfmt{firstuc}: convert the first alphabetical letter (or
-group) to upper case. This uses the following rules:
+group) to \idx{uppercase}. This uses 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
@@ -7332,7 +7820,7 @@
\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 upper case and stop;
+\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.
@@ -7481,308 +7969,22 @@
See \csopt{dual-short-case-change} to adjust the \field{dualshort}
field.
-\optsection{name-case-change}
+\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}
-value is first copied to the \field{text} field.
+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
+depends on the entry type) unless the entry type is
+\atentry{abbreviation} or \atentry{acronym}, in which case if
+the \field{name} field is missing no action is performed.
-\optsection{description-case-change}
+\optsection[\subsubsection]{description-case-change}
As \csopt{short-case-change} but is applied to the
\field{description} field.
-\optsection{post-description-dot}
-
-The \styopt{postdot} package option (or \styopt[false]{nopostdot})
-can be used to append a \idx{full-stop} (\idx{periodchar})\ to the
-end of all the descriptions. This can be awkward if some of the
-descriptions end with punctuation characters. This resource option
-can be used instead. The \meta{value} may be one of:
-\begin{itemize}
-\item\optfmt{none}: don't append a \idx{full-stop} (default);
-\item\optfmt{all}: append a \idx{full-stop} to all \field{description}
- fields in this resource set;
-\item\optfmt{check}: selectively append a \idx{full-stop} (see below).
-\end{itemize}
-Note that if you have dual entries and you use this option to
-append a \idx{full-stop}, then it will be copied over to the mapped field.
-This is different to the \styopt{postdot} option which doesn't
-add the dot to the field but incorporates it in the
-\idx{postdescriptionhook}. This means that a dot inserted with
-\csopt{post-description-dot} will come before the
-\idx{postdescriptionhook} whereas with \styopt{postdot} the
-punctuation comes after any category-specific hook.
-
-The \csopt[check]{post-description-dot} setting determines whether
-to append the dot as follows:
-\begin{itemize}
-\item If the \field{description} field ends with
-\ics{nopostdesc} or \ics{glsxtrnopostpunc}, then a dot isn't appended.
-\item If the \field{description} field doesn't end with a regular
-(ungrouped letter or other) character, then a dot is appended.
-(For example, if the description ends with a control sequence
-or an end group token.)
-\item If the \field{description} field ends with a character
-that belongs to the Unicode category \idx{punctuationclose}
-or \idx{punctuationfinalquote} then the token preceding
-that character is checked.
-\item If the \field{description} field doesn't end with
-a character that belongs to the Unicode category
-\idx{punctuationother} then the dot is added.
-\end{itemize}
-Note that the interpreter isn't used during the check.
-If the \field{description} ends with a command then a dot will be
-appended (unless it's \cs{glsxtrnopostpunc} or \cs{nopostdesc}) even if
-that command expands in such a way that it ends with a terminating
-punctuation character. This option only applies to the
-\field{description} field.
-
-\optsection{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.
-
-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}
-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}
-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}
-because again it's not at the end.
-
-\optsection{check-end-punctuation}
-
-This options checks the end of all the fields given in \meta{list} for
-end of sentence punctuation. This is determined as follows, for each
-\meta{field} in the comma-separated \meta{list}:
-\begin{itemize}
-\item if the last character is of type \idx{punctuationclose}
-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}
-in \bibgls's \langxml.
-\end{itemize}
-If a sentence terminator is found, an internal field is created
-called \field{fieldendpunc} that contains the punctuation
-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}
-as:
-\begin{verbatim}
-<entry key="sentence.terminators">.?!</entry>
-\end{verbatim}
-Any character that isn't of type \idx{punctuationother} won't
-match.
-
-For example, the sample \exfile{books.bib} file contains:
-\begin{verbatim}
- at entry{whydidnttheyaskevans,
- name={Why Didn't They Ask Evans?},
- description={novel by Agatha Christie},
- identifier={book},
- author={\sortmediacreator{Agatha}{Christie}},
- year={1934}
-}
-\end{verbatim}
-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
-at the end of the \field{name} field:
-\begin{verbatim}
-\GlsXtrSetField{whydidnttheyaskevans}{nameendpunc}{?}
-\end{verbatim}
-(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}
-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.
-
-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
-\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}%
-}
-\end{verbatim}
-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
-as it introduces implicit scoping, which would interfere with the
-punctuation lookahead.) The other difference between
-\ics{GlsXtrIfFieldUndef} and the other \csfmt{\ldots hasfield} tests
-is the case where the field is set to an empty value. In this case
-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{copy-action-group-field}
-
-This option may only be used when invoking \bibgls\ with the
-\longarg{group} (or \shortargfmt{g}) switch. If an action
-other than the default \csopt[define]{action} is set,
-this option can be used to identify a field in which to save
-the letter group information
-where \meta{value} is the name of the field. This just uses
-\cs{GlsXtrSetField}. You will need to redefine
-\ics{glsxtrgroupfield} to \meta{value} before displaying the glossary.
-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}
- \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
-\end{alltt}
-
-This option is ignored when used with \csopt[define]{action}.
-This option is not used by \csopt{secondary} which will
-always save the group information in the \field{secondarygroup}
-field. When used with \csopt[define or copy]{action}, entries
-that are defined will have both \field{group} and
-the field given by \csopt{copy-action-group-field} set.
-
-Note that you may do \csopt[group]{copy-action-group-field} which
-will override the \field{group} field from the original definition.
-This may be useful if you don't use grouping in the primary
-glossary. That is, you use \code{nogroupskip} and a non-group
-style. For example:
-\begin{verbatim}
-\printunsrtglossary[nogroupskip,style=index]
-\printunsrtglossary[type=copies,style=indexgroup]
-\end{verbatim}
-
-\optsection{save-child-count}
-
-This is a boolean option. The default setting is
-\csopt[false]{save-child-count}.
-If \csopt[true]{save-child-count},
-each entry will be assigned a field called \field{childcount} with
-the value equal to the number of child entries that have been
-selected.
-
-The assignment is done using \ics{GlsXtrSetField} so there's
-no associated key.
-For example, suppose \filefmt{entries.bib} contains:
-\begin{verbatim}
- at index{birds}
- at index{duck,parent={birds}}
- at index{goose,plural={geese},parent={birds}}
- at index{swan,parent={birds}}
-
- at index{minerals}
- at index{quartz,parent={minerals}}
- at index{corundum,parent={minerals}}
- at index{amethyst,parent={minerals}}
- at index{gypsum,parent={minerals}}
- at index{gold,parent={minerals}}
-\end{verbatim}
-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}
-Then the \ext{glstex} file will contain:
-\begin{verbatim}
-\GlsXtrSetField{birds}{childcount}{2}
-\GlsXtrSetField{duck}{childcount}{0}
-\GlsXtrSetField{goose}{childcount}{0}
-\GlsXtrSetField{minerals}{childcount}{3}
-\GlsXtrSetField{amethyst}{childcount}{0}
-\GlsXtrSetField{corundum}{childcount}{0}
-\GlsXtrSetField{quartz}{childcount}{0}
-\end{verbatim}
-Note that although \code{birds} has three children defined in the
-\ext{bib} file, only two have been selected, so the child count is
-set to 2. Similarly the \code{minerals} entry has five children
-defined in the \ext{bib} file, but only three have been selected, so
-the child count is 3.
-
-The 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.)}%
- {}%
-}
-\end{verbatim}
-(\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
-It's slightly more efficient that \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
-grouping.)
-
-\optsection{save-original-id}
-
-The \meta{value} may be either the keyword \code{false} or
-the name of an internal field in which to store the entry's original
-label (as given in the \ext{bib} file). The default setting is
-\csopt[false]{save-original-id}. If \meta{value} is omitted,
-\csopt[originalid]{save-original-id} is assumed.
-
-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{copy-alias-to-see}
-
-If set, the value of the \field{alias} field is copied to
-the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
-
\section{Plurals}
\label{sec:plurals}
@@ -8022,7 +8224,7 @@
(except for the cross-reference which may be placed at the start or
end of the list or omitted).
This is different to \idx!{xindy} and \idx!{makeindex} where you can
-specify the ordering (such as lower case Roman first, then digits,
+specify the ordering (such as \idx!{lowercase} Roman first, then digits,
etc), but unlike those applications, \bibgls\ allows any location,
although it may not be able to work out an integer representation.
(With \idx!{xindy}, you can define new location formats, but you need
@@ -8202,16 +8404,16 @@
are consecutive otherwise they're not consecutive.
\end{enumerate}
\item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
-where \meta{n} is a lower case Roman numeral, which is converted to
+where \meta{n} is a \idx!{lowercase} Roman numeral, which is converted to
a decimal value and the test is performed in the same way as the
above \hyperref[itm:decmatch]{decimal test}.
\item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n}
-where \meta{n} is an upper case Roman numeral, which is converted to
+where \meta{n} is an \idx!{uppercase} Roman numeral, which is converted to
a decimal value and the test is performed
in the same way as the above \hyperref[itm:decmatch]{decimal test}.
\item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c}
-where \meta{c} is either a lower case letter from \code{a} to
-\code{z} or an upper case letter from \code{A} to \code{Z}.
+where \meta{c} is either a \idx!{lowercase} letter from \code{a} to
+\code{z} or an \idx!{uppercase} letter from \code{A} to \code{Z}.
The character is converted to its code point and the test is
performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above.
\item\label{itm:nomatch} If none of the above, the locations aren't considered
@@ -9243,7 +9445,7 @@
The sort methods listed in \tableref{tab:sortoptionsletter}
use letter case comparators. These simply compare the
character codes. The \optfmt{-nocase} options first convert the
-\field{sort} field to lower case before performing the sort.
+\field{sort} field to \idx{lowercase} before performing the sort.
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
@@ -9250,8 +9452,8 @@
show the ordering of the list \code{antelope}, \code{bee}, \code{Africa},
\code{aardvark} and \code{Brazil}.
\begin{itemize}
-\item \optfmt{letter-case}: case-sensitive letter sort. Upper case
-and lower case are in separate letter groups.
+\item \optfmt{letter-case}: case-sensitive letter sort.
+\Idx{uppercase} and \idx{lowercase} are in separate letter groups.
Example:
\code{Africa} (letter group \qt{A}), \code{Brazil}
@@ -9261,7 +9463,8 @@
\item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort.
\item \optfmt{letter-nocase}: case-insensitive letter sort. (All
-upper case characters will have first been converted to lower case.)
+\idx{uppercase} characters will have first been converted to
+\idx{lowercase}.)
Example:
\code{aardvark} (letter group \qt{A}), \code{Africa}
@@ -9272,9 +9475,9 @@
\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort.
\item \optfmt{letter-upperlower}: each character pair is first
-compared according to their lower case values. If these are equal,
+compared according to their \idx{lowercase} values. If these are equal,
then they are compared according to case. This puts upper and lower
-case in the same letter group but the upper case comes first.
+case in the same letter group but the \idx{uppercase} comes first.
Example:
\code{Africa} (letter group \qt{A}), \code{aardvark} (letter group
@@ -9284,9 +9487,9 @@
\item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort.
\item \optfmt{letter-lowerupper}: each character pair is first
-compared according to their lower case values. If these are equal,
-then they are compared according to case. This puts upper and lower
-case in the same letter group but the lower case comes first.
+compared according to their \idx{lowercase} values. If these are equal,
+then they are compared according to case. This puts
+\idxlink{uppercase}{upper} and \idx{lowercase} in the same letter group but the \idx{lowercase} comes first.
Example:
\code{aardvark} (letter group \qt{A}), \code{antelope} (letter group \qt{A}),
@@ -9459,7 +9662,7 @@
\item \optfmt{letternumber-nocase}: case-insensitive
letter-number sort. The sort value is first converted to lower
case. Note that \csopt[between]{letter-number-rule} doesn't make
-sense in this context as there won't be any upper case characters in
+sense in this context as there won't be any \idx!{uppercase} characters in
the sort value, so numbers will always come before letters. Example:
\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
@@ -9478,7 +9681,8 @@
\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 upper and lower case characters if there
+as it will segregate the \idxlink{uppercase}{upper} and
+\idx{lowercase} characters if there
are any numerical sub-strings. Example:
\code{CH\textsubscript{2}O},
@@ -9492,9 +9696,9 @@
\code{Co\textsubscript{2}O\textsubscript{3}}.
The \csopt[between]{letter-number-rule} setting enforces numbers
-after upper-case (for the case-sensitive and upper-lower methods)
-which makes the \code{\textsubscript{5}} come after the upper case
-\code{O} and forces the lower case characters to come after it.
+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.
Compare this with \csopt[before letter]{letter-number-rule} which
results in the order:
@@ -9527,16 +9731,16 @@
\code{CH\textsubscript{2}O}.
The algorithm is reversed which means that when two letters are
-compared then, if both letters have the same lower case version,
-the upper-lower rule is reversed and lower case comes before
-upper case. This means that \code{o} comes before \code{O}.
-If their lower case versions aren't identical, the letter
-with the higher lower case Unicode value comes first. This means
+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
-upper and lower case letters. This puts the numbers (in reverse
+\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
@@ -9573,9 +9777,9 @@
\code{CO}.
The \csopt[between]{letter-number-rule} setting enforces numbers
-after lower-case (for the lower-upper method)
+after \idx{lowercase} (for the lower-upper method)
so the \code{\textsubscript{5}} is put after \code{o}, and forces
-the upper case characters after the numbers.
+the \idx{uppercase} characters after the numbers.
Compare this with \csopt[before letter]{letter-number-rule} which
results in the order:
@@ -9925,6 +10129,26 @@
This option automatically sets \csopt[\meta{boolean}]{dual-trim-sort}
and \csopt[\meta{boolean}]{secondary-trim-sort}.
+\optsection{sort-replace}
+
+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
+\begin{codeenv}
+\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace}
+\end{codeenv}
+can be used to strip the $\approx$ symbol (\hex{2248}) so that the value can
+now be parsed as a number if \csopt[double]{sort} has been used.
+
+Use \csopt{dual-sort-replace} for dual
+and \csopt{secondary-sort-replace} for secondary sort methods.
+
\optsection{sort-rule}
If the \csopt[custom]{sort} option is used, the sort rule must be
@@ -10080,6 +10304,16 @@
which is commonly placed in collation rules before digits but
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)
+use the following instead:
+\begin{codeenv}
+ \csopt[none]{break-at},
+ \csopt[\marg{,? +}\marg{|}]{sort-replace}
+\end{codeenv}
+
You can change the construction of the break points with
\csopt[\meta{option}]{break-at} where \meta{option} may be one of:
\begin{itemize}
@@ -10093,12 +10327,12 @@
characters.
\item \optfmt{character}: break after each character.
\item \optfmt{sentence}: break after each sentence.
-\item \optfmt{upper-notlower}: break after any upper case character
-that's not followed by a lower case character. For example,
+\item \optfmt{upper-notlower}: break after any \idx{uppercase} character
+that's not followed by a \idx{lowercase} character. For example,
\qt{MathML} becomes \verb"MathM|L|" and \qt{W3C} becomes
\verb"W|3C|".
-\item \optfmt{upper-upper}: break after any upper case character
-that's followed by an upper case character.
+\item \optfmt{upper-upper}: break after any \idx{uppercase} character
+that's followed by an \idx{uppercase} character.
\item \optfmt{upper-notlower-word}: first applies break-points
according to \optfmt{upper-notlower} and then according to
\optfmt{word}.
@@ -10106,7 +10340,8 @@
according to \optfmt{upper-upper} and then according to
\optfmt{word}.
\item \optfmt{none}: don't create break points. Use this option to
-emulate \idx{makeindex} or \idx{xindy}'s letter ordering.
+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.
@@ -10616,9 +10851,10 @@
letter.
\item\optfmt{between}: (default) numbers come between letter cases.
With the \optfmt{-case} or \optfmt{-upperlower} sort options,
-this will put numbers after upper case and before lower case.
+this will put numbers after \idx{uppercase} and before
+\idx{lowercase}.
With the \optfmt{-lowerupper} sort option, this will put numbers
-after lower case and before upper case. This setting doesn't make
+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.
\item\optfmt{first}: numbers are considered less than all
@@ -10628,8 +10864,8 @@
\end{itemize}
Note that the reverse sort methods will invert this setting.
Remember also that the case-insensitive letter-number sort methods always
-first convert the \field{sort} field to lower case, which means that
-if you use one of them then there won't be any upper case
+first convert the \field{sort} field to \idx{lowercase}, which means that
+if you use one of them then there won't be any \idx{uppercase}
characters.
Use \csopt{letter-number-punc-rule} to determine the relative
@@ -10846,7 +11082,7 @@
\end{verbatim}
The \code{G} (era) date pattern specifier expects a string, such as
-\qt{AD}. It will match lower case forms, such as \qt{ad}, so if you
+\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
\code{ad} (stripping the text-block command). However, in general
it's best to supply a semantic command that ensures that the
@@ -10905,7 +11141,7 @@
\item\optfmt{codepoint}: the group is set to
\icswithargs{bibglsunicodegroup}, where the first argument is the
-first significant character (converted to lower case and decomposed,
+first significant character (converted to \idx{lowercase} and decomposed,
if applicable) of the sort value.
\item\optfmt{unicode category}: the group is set to
@@ -10912,8 +11148,8 @@
\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 lower case letter and \code{Lu} signifies an upper case
-letter.
+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
@@ -10927,7 +11163,7 @@
\icswithargs{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 lower case Latin letter.
+\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter.
\end{itemize}
This option has no effect with \longarg{no-group} or if no sorting
is applied. Use \csopt{secondary-group-formation} for secondary
@@ -11094,6 +11330,10 @@
As \csopt{trim-sort} but for secondary sorting.
+\optsection{secondary-sort-replace}
+
+As \csopt{sort-replace} but for secondary sorting.
+
\optsection{secondary-sort-rule}
As \csopt{sort-rule} but for secondary custom sorting.
@@ -11303,7 +11543,7 @@
The \meta{value} may be:
\begin{itemize}
\item \optfmt{same as entry}: sets the \field{type} to the entry
-type (lower case and without
+type (\idx!{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{dualentry}, the \field{type} will be set to
\optfmt{dualentry}.
@@ -11312,7 +11552,7 @@
file.
\item \optfmt{same as original entry}: set the \field{type} field
-to the original entry type (lower case and without
+to the original entry type (\idx!{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
\optfmt{same as entry} if the entry type wasn't aliased).
@@ -11361,7 +11601,7 @@
The \meta{value} may be:
\begin{itemize}
\item \optfmt{same as entry}: sets the \field{category} to the entry
-type (lower case and without
+type (\idx{lowercase} and without
the initial \code{@}). For example, if the entry was defined with
\atentry{dualentry}, the \field{category} will be set to
\optfmt{dualentry}.
@@ -11370,7 +11610,7 @@
file.
\item \optfmt{same as original entry}: set the \field{category} field
-to the original entry type (lower case and without
+to the original entry type (\idx{lowercase} and without
the initial \code{@}) before it was aliased (behaves like
\optfmt{same as entry} if the entry type wasn't aliased).
@@ -11411,7 +11651,9 @@
\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 \code{dual} is assumed.
+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}
@@ -11531,6 +11773,10 @@
As \csopt{trim-sort} but for dual sorting.
+\optsection[\subsubsection]{dual-sort-replace}
+
+As \csopt{sort-replace} but for dual sorting.
+
\optsection[\subsubsection]{dual-sort-rule}
As \csopt{sort-rule} but for \csopt[custom]{dual-sort}.
@@ -11820,13 +12066,39 @@
Analogous to \csopt{dual-entry-backlink} but for entries
defined with \atentry{dualabbreviationentry} instead of
-\atentry{dualentry}.
+\atentry{dualentry}. This setting can be problematic as the
+backlinks rely on the relevant field being known to \bibgls.
+Since the abbreviation style typically sets the \field{name}
+field (and sometimes the \field{description} field as well), you may
+find that no backlink appears. A simple workaround is to
+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
+\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
+\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}%
+}
+\setabbreviationstyle{long-short-user}
+\GlsXtrLoadResources[src={entries},dual-field]
+\end{verbatim}
+
\optsection[\subsubsection]{dual-entryabbrv-backlink}
-Analogous to \csopt{dual-entry-backlink} but for entries
+As \csopt{dual-abbrventry-backlink} but for entries
defined with \atentry{dualentryabbreviation} instead of
-\atentry{dualentry}.
+\atentry{dualabbreviationentry}.
\optsection[\subsubsection]{dual-indexentry-backlink}
@@ -11919,7 +12191,7 @@
\longnewglossaryentry*{#1}{name={#3},#2}{#4}%
}
\end{verbatim}
-This uses the starred form of \gls{longnewglossaryentry} that
+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).
@@ -11970,15 +12242,29 @@
\newglossaryentry{#1}{name={#1},category={index},description={},#2}%
}
\end{verbatim}
-This makes the \field{name} default to the \meta{label}, assigns the
+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
\meta{options}.
Note that the \field{description} doesn't include
-\ics{nopostdesc} to allow for the post-description hook used by
+\ics{nopostdesc} to allow for the \idx{postdescriptionhook} used by
category attributes.
+\cssection{bibglsnewindexplural}
+
+\formatdef{bibglsnewindexplural}
+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}%
+}
+\end{verbatim}
+This assigns the \field{category} to \code{indexplural} and sets an empty
+\field{description}. These settings may be overridden by \meta{options}.
+
\cssection{bibglsnewabbreviation}
\formatdef{bibglsnewabbreviation}
@@ -12771,7 +13057,7 @@
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
-\meta{lc} is the lower case version of \meta{title}, then the value
+\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:
\begin{verbatim}
@@ -12779,7 +13065,7 @@
\end{verbatim}
(See the \longarg{group} switch for more details.)
\item \meta{letter} This is the actual letter at the start of the
-given entry's \field{sort} field, which may be lower case or may
+given entry's \field{sort} field, which may be \idx!{lowercase} or may
contain diacritics that don't appear in \meta{title}.
\item \meta{id} A numeric identifier. This may be the collation key
or the code point for the given letter, depending on the sort
@@ -12799,6 +13085,51 @@
is designed to do. Note that non-letter groups are dealt with
separately (see below).
+\cssection{bibglssetlastgrouptitle}
+
+In the last resource (\ext{glstex}) file, after all the relevant
+group titles have been set with the commands listed below, there's a
+final title setting:
+\formatdef{bibglssetlastgrouptitle}
+This does nothing by default, but the arguments are set to
+correspond to the group with the maximum id for that resource file.
+It's provided as a convenient way of overriding the final group
+title without the inconvenience of looking up the group label in the
+\ext{glstex} file. If you have multiple glossaries or if you want to
+override a different group, then you need to inspect the
+\ext{glstex} file to work out the corresponding label (by finding
+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
+\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}
+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}
+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}
+
\cssection{bibglssetlettergrouptitle}
For each \idx{lettergroup} that's detected, \bibgls\ will write the line:
@@ -13105,11 +13436,11 @@
The \meta{label} depends on the \csopt{group-formation} setting:
\begin{itemize}
\item\csopt[codepoint]{group-formation}: the \meta{label} is the
-Unicode value of \meta{character} (converted to lower case and
+Unicode value of \meta{character} (converted to \idx!{lowercase} and
decomposed, if applicable);
\item\csopt[unicode category]{group-formation}: the \meta{label} is the
Unicode category of \meta{character} (for example, \code{Lu} means
-an upper case letter);
+an \idx!{uppercase} letter);
\item\csopt[unicode script]{group-formation}: the \meta{label} is the
Unicode script associated with \meta{character} (for example,
\code{LATIN});
@@ -13136,7 +13467,7 @@
\begin{verbatim}
group={\bibglsunicodegroup{Lu.LATIN}{Å}{C5}{}}
\end{verbatim}
-(upper case Latin letter).
+(\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:
@@ -14358,6 +14689,30 @@
The contents of \filefmt{films.bib} are as follows:
\lstinputlisting[firstline=5]{../examples/films.bib}
+\filesection{citations.bib}
+
+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
+\begin{codeenv}
+entry-type-aliases=\marg{\ics{GlsXtrBibTeXEntryAliases}}
+\end{codeenv}
+The field names will also need to be defined or aliased. For
+example:
+\begin{codeenv}
+field-aliases=\marg{title=name}
+\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
+as ignored records. The \atentry{preamble} provides a formatting
+command that's used by both \BibTeX\ and \bibgls, so \cs{providecommand}
+is required rather than \cs{newcommand} as it will appear in both
+the \iext{bbl} and the \iext{glstex} files. (In general it's best to
+use \cs{providecommand} rather than \cs{newcommand} in the
+\atentry{preamble} but in this case it's essential.)
+The contents of \filefmt{citations.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/citations.bib}
+
\filesection{mathgreek.bib}
The \exfile{mathgreek.bib} file contains Greek letters for use in
@@ -14368,7 +14723,7 @@
the \TeX\ parser library recognises all the mathematical Greek letter commands
provided in the \LaTeX\ kernel. Additionally it recognises
\ics{omicron} which isn't provided by \LaTeX\ (the symbol can be
-reproduced with a lower case Latin \qt{o}). Note that
+reproduced with a \idx!{lowercase} Latin \qt{o}). Note that
\isty{glossaries-extra-bib2gls} (\sty{glossaries-extra} v1.27+)
provides all the missing Greek letters (such as \cs{omicron}).
@@ -14400,7 +14755,7 @@
\end{verbatim}
(With \sty{glossaries-extra} v1.27+, this is no longer needed.)
The \TeX\ parser library and \sty{glossaries-extra-bib2gls}
-similarly provide the missing upper case
+similarly provide the missing \idx!{uppercase}
Greek letters, and these can be dealt with in the same way.
The contents of \filefmt{mathgreek.bib} are as follows:
@@ -16042,7 +16397,7 @@
\csopt[author=parent]{field-aliases}
\end{codeenv}
but the author's label in the \exfile{people.bib}
-file is just the lower case surname.
+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
@@ -16117,8 +16472,6 @@
\lstinputlisting[firstline=5]{../examples/sample-authors.tex}
-\lstinputlisting[firstline=5]{../examples/sample-authors.tex}
-
\begin{figure}
\figcontents
{%
@@ -16128,6 +16481,167 @@
{fig:sample-authors.pdf}
\end{figure}
+\filesection{sample-citations.tex}
+
+This example uses the \BibTeX\ file \exfile{citations.bib} to create
+a document that has both a bibliography created by \BibTeX\ and
+glossaries created by \bibgls\ listing the authors and the titles.
+There are no glossary reference commands, such as \cs{gls}, but
+\bibgls\ can be run with \longarg{cite-as-record} to treat the
+\ics{citation} commands (written to the \ext{aux} file by \ics{cite})
+as ignored records. Since \cs{cite} doesn't record the page number,
+there are no associated locations.
+
+The \code{main} glossary isn't required, so I've used
+\styopt{nomain} to suppress its creation. I want to use both the
+\glostyle{altlist} and \glostyle{indexgroup} styles but none of the
+other styles, so I've used \styopt{nostyles} to prevent the
+automatic loading of the default style packages and
+\styopt{stylemods} to load the \sty{glossary-tree} 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}
+Next I need to create the glossaries for the list of authors and
+list of titles:
+\begin{codeenv}
+\cs{newglossary*}\marg{contributors}\marg{Authors}
+\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
+\begin{codeenv}
+\csopt[contributors]{type}
+\end{codeenv}
+in the \idx{resourceset} and provide a
+modified version of \ics{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}
+}
+\end{codeenv}
+The standard \BibTeX\ entry types need aliasing to
+\atentry{bibtexentry}:
+\begin{codeenv}
+\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
+\end{codeenv}
+and the \fieldfmt{title} field is aliased to \field{name}:
+\begin{codeenv}
+\csopt[title=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:
+\begin{codeenv}
+\csopt[same as original entry]{category}
+\end{codeenv}
+So, for example, an entry that's provided in the \ext{bib} file with
+\atentryfmt{article} has the \field{category} field set to
+\code{article}. (Compare this with \csopt[same as entry]{category}
+which would set the \field{category} to \code{bibtexentry}.)
+The spawned entries are all defined using \atentry{contributor} and
+aren't aliased so both the entry type and the original entry type
+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}
+\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}
+\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}
+\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}
+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}
+}
+\end{codeenv}
+There's no \field{description} field set for these entries, but the
+\idx{postdescriptionhook} can still be used to append information.
+In this case, I've appended a cross-reference to the bibliography.
+Since the bibliography entry and the glossary term both have the
+same label, the citation can easily be obtained with
+\code{\ics{cite}\marg{\cs{glscurrententrylabel}}}:
+\begin{codeenv}
+\cs{newcommand}\marg{\postdeschook{article}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
+\cs{newcommand}\marg{\postdeschook{book}}\marg{\cs{cite}\marg{\cs{glscurrententrylabel}}}
+\end{codeenv}
+Note that this needs to be done for each \BibTeX\ entry type, but in
+this case the \ext{bib} file only contains \atentryfmt{article} and
+\atentryfmt{book} entries. (Similarly for the group titles above.)
+
+The list of contributors can simply be displayed with:
+\begin{codeenv}
+\cs{printunsrtglossary}[type=contributors,style=altlist]
+\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}
+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{glsxtrfieldforlistloop}
+ \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\idx{commentchar}
+ \marg{\csfmt{contributorhandler}}\idx{commentchar}
+ }\idx{commentchar}
+ \marg{\ics{par} No titles.}\idx{commentchar}
+}
+\end{codeenv}
+The handler macro displays the name of the associated
+\atentry{bibtexentry} term and the citation:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\cs{par}\ics{glsentryname}\marg{\idx{param}1} \cs{cite}\marg{\idx{param}1}}
+\end{codeenv}
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-citations
+bib2gls --group --cite-as-record sample-citations
+bibtex sample-citations
+pdflatex sample-citations
+pdflatex sample-citations
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-citations.pdf}.
+
+\lstinputlisting[firstline=7]{../examples/sample-citations.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-citations.pdf}{2}}
+{\caption{\filefmt{sample-citations.pdf}}}
+{fig:sample-citations.pdf}
+\end{figure}
+
\filesection{sample-msymbols.tex}
This example uses \exfile{bigmathsymbols.bib},
@@ -16430,7 +16944,7 @@
The tagging format is governed by \ics{glsxtrtagfont} which
underlines its argument by default. I've redefined it to also
-convert the letter to uppercase:
+convert the letter to \idx{uppercase}:
\begin{verbatim}
\renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}}
\end{verbatim}
@@ -16471,7 +16985,7 @@
indexed.
I decided to convert the first letter of the \field{name} field to
-uppercase. Since the \field{name} is implicitly set for
+\idx{uppercase}. Since the \field{name} is implicitly set for
abbreviations based on the style, I've decided to implement this
through the \catattr{glossname} attribute rather than using
\csopt{name-case-change}:
@@ -17149,7 +17663,7 @@
\end{codeenv}
This method doesn't work as well as the method used in
\exfile{sample-chemical.tex} as it doesn't separate the capitals,
-digits and lower case characters in the way that can be achieved with the
+digits and \idx!{lowercase} characters in the way that can be achieved with the
letter-number methods. An improvement can be made by changing the
break-points. I could use \csopt[upper-upper]{dual-break-at} but
this would put \qt{seal} before \qt{sea lion} in the \code{animal}
@@ -17865,6 +18379,7 @@
{fig:sample-multi2.pdf3}
\end{figure}
+\printstyoptsummary
\printcommandsummary
\bibliographystyle{plain}
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip
===================================================================
(Binary files differ)
More information about the tex-live-commits
mailing list