summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src/bib2gls.tex')
-rw-r--r--support/bib2gls/src/bib2gls.tex22549
1 files changed, 22549 insertions, 0 deletions
diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex
new file mode 100644
index 0000000000..f7ba9c27ef
--- /dev/null
+++ b/support/bib2gls/src/bib2gls.tex
@@ -0,0 +1,22549 @@
+% arara: lualatex
+% arara: bib2gls: {group: on} if missing("glstex") || changed("bib") || found("log", "Warning: Glossary entry")
+% arara: bibtex
+% arara: lualatex if changed("glstex") || missing("toc")
+% arara: bib2gls: {group: on, packages: [mfirstuc-english]}
+% arara: lualatex
+% arara: lualatex if found ("log", "Rerun")
+\documentclass[titlepage=false,index=totoc,bibliography=totoc,
+ fontsize=12pt,captions=tableheading]{scrreprt}
+
+\usepackage[autooneside=false]{scrlayer-scrpage}
+\usepackage{pifont}
+
+% Need support for extended characters
+% and need a mono font that supports hyphenation
+\usepackage[no-math]{fontspec}
+\setmainfont{Linux Libertine O}
+
+\newfontface\cyrillicmono{FreeMono}[Scale=MatchLowercase]
+\newcommand{\textcyrillicmono}[1]{{\cyrillicmono #1}}
+
+\newfontface\greekmono{FreeMono}[Scale=MatchLowercase]
+\newfontface\freeserif{FreeSerif}
+\newcommand{\devone}{{\freeserif\char"0967}}
+\newcommand{\devtwo}{{\freeserif\char"0968}}
+\newcommand{\devsix}{{\freeserif\char"096C}}
+\newcommand{\insularG}{{\freeserif\char"A77D}}
+\newcommand{\insularg}{{\freeserif\char"1D79}}
+\newcommand{\longs}{\char"017F}
+\newcommand{\Wynn}{\char"01F7}
+\newcommand{\wynn}{\char"01BF}
+
+\usepackage[x11names]{xcolor}
+\usepackage{alltt}
+\usepackage{array}
+\usepackage{upquote}
+\usepackage{etoolbox}
+
+\usepackage{hologo}
+\usepackage{amsmath}
+\usepackage{accents}
+\usepackage{tikz}
+\usepackage{tcolorbox}
+\usepackage{datetime2}
+\usepackage{listings}
+\usepackage[hidelinks]{hyperref}
+\usepackage{cleveref}
+\usepackage[% v1.21+
+ record,% use bib2gls
+ index,% create index glossary
+ entrycounter,% enable entry counting
+ subentrycounter,% enable entry counting
+ %debug=showtargets,% debugging information
+ stylemods={mcols,bookindex},% adjust predefined styles and load glossary-mcols.sty and glossary-bookindex.sty
+ style=bookindex
+ ]
+ {glossaries-extra}
+
+\lstset{language={[LaTeX]TeX},upquote,basicstyle={\ttfamily\small},
+ commentstyle={\color{gray}}}
+
+\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}}
+
+\glsxtrprovidestoragekey{note}{}{}
+\glsxtrprovidestoragekey{package}{}{}
+\glsxtrprovidestoragekey{nametitle}{}{}
+
+\providecommand{\omicron}{o}
+
+% put break before dash to avoid confusion with a hyphen
+\newcommand{\dhyphen}{%
+ \texorpdfstring
+ {\discretionary{}{}{}\texttt{-}}%
+ {-}%
+}
+
+% Redefine \- (used in entry names) so that hyphenation in command names,
+% switches options etc uses a serif hyphen to reduce confusion with an
+% actual hyphen in the code.
+\renewrobustcmd{\-}{%
+ \discretionary
+ {{\rmfamily\char\ifnum\hyphenchar\font<0
+ \defaulthyphenchar\else\hyphenchar\font\fi
+ }}%
+ {}{}%
+}
+
+\renewcommand{\glsentrycounterlabel}{}
+\renewcommand{\glssubentrycounterlabel}{}
+\renewcommand\glstreeitem{\par\hangindent10pt}
+\renewcommand\glstreesubitem{\par\hangindent30pt\hspace*{15pt}}
+
+\newcommand{\bibglsseealsosep}{\glstreesubitem}
+
+\renewcommand*{\glsseesep}{, \glstreesubitem\qquad}
+\renewcommand*{\glsseelastsep}{\glstreesubitem\qquad\andname\space}
+
+\newcommand{\glsxtrpostnameabbreviation}{%
+ \space(\glsentrylong{\glscurrententrylabel})%
+}
+
+\newcommand{\glsxtrpostnameenvironment}{\space environment}
+\newcommand{\glsxtrpostnamecounter}{\space counter}
+
+\newcommand*{\csfmtfont}[1]{\texttt{#1}}
+\newcommand*{\csfmtcolourfont}[1]{\texttt{\textcolor{cs}{#1}}}
+
+\newcommand*{\csfmt}[1]{%
+ \texorpdfstring
+ {\csfmtfont{\char`\\ #1}}%
+ {\string\\#1}%
+}
+
+\newcommand{\texparserdefprefix}{}
+\newcommand{\texparserdefnotetarget}{%
+ \raisebox{2ex}{\hypertarget{\texparserdefprefix texparserdef}{}}%
+ \textsuperscript{*}Indicates command is
+ recognised by \bibgls's interpreter although it may have
+ a slightly different implementation.
+}
+\newcommand{\texparserdefnote}{\hyperlink{\texparserdefprefix texparserdef}{*}}
+
+\setabbreviationstyle{long-short-sc}
+\setabbreviationstyle[common]{short-sc-nolong}
+
+\glsxtrprovidestoragekey{unsortedprogeny}{}{}
+
+\GlsXtrLoadResources[
+ entry-type-aliases={
+ bibglscommand=dualindexentry,
+ mainglscommand=spawndualindexentry,
+ glscommand=spawnentry,
+ abbrvstylecommand=spawnentry,
+ glostylecommand=spawnentry,
+ resourceoption=dualindexentry,
+ packageoption=dualindexentry,
+ field=dualindexentry,
+ entrytype=dualindexentry,
+ switch=dualindexentry,
+ samplefile=dualindexentry,
+ examplecommand=dualindexentry,
+ examplesymbol=symbol,
+ exampleabbreviation=abbreviation,
+ exampleentry=entry
+ },
+ field-aliases={topics=adoptparents},
+ replicate-fields={name=nametitle,progeny=unsortedprogeny},
+ field-case-change={nametitle=title},
+ interpret-fields={nametitle},
+ no-case-change-cs={fieldfmt,abbrstylefmt,glostylefmt},
+ short-case-change={lc},
+ dual-short-case-change={lc},
+ unknown-entry-alias={index},
+ save-original-entrytype,
+ 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},
+ match-op={or},
+ match={
+ {category}={.*field},
+ {original entrytype}={.*(gls|style)command},
+ {original entrytype}={.*option},
+ {original entrytype}={abbreviationstyle},
+ {original entrytype}={glossarystyle},
+ },
+ dual-prefix={},
+ dual-type={main},
+ combine-dual-locations={primary},
+ selection={recorded and deps and see},
+ symbol-sort-fallback={name},
+ sort-label-list={progeny:letter-nocase:glsxtrentryparentname},
+ strip-missing-parents,
+ save-child-count
+]
+
+\glsxtraddlabelprefix{}
+\glsxtraddlabelprefix{idx.}
+
+\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z}
+
+\IfFileExists{../java/Bib2Gls.java}
+{
+ \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java}
+}
+{
+ \DTMsavenow{moddate}
+}
+
+\newif\ifmainmatter
+
+% ignore locations outside of main matter
+\GlsXtrSetDefaultNumberFormat{glsignore}
+
+\GlsXtrSetAltModifier{!}{format=glsignore}
+
+\newcommand{\frontmatter}{%
+ \clearpage\pagenumbering{roman}%
+ \pagestyle{scrheadings}%
+ \automark[section]{chapter}%
+ \mainmatterfalse
+}
+\newcommand{\mainmatter}{%
+ \clearpage\pagenumbering{arabic}%
+ \GlsXtrSetDefaultNumberFormat{glsnumberformat}%
+ \mainmattertrue
+}
+
+\newcommand{\rightleftmark}[2]{\ifstrequal{#1}{#2}{#1}{#1: #2}}
+\makeatletter
+\newcommand{\setsecdepth}{\@ifstar\s@setsecdepth\@setsecdepth}
+\newcommand{\s@setsecdepth}[1]{%
+ \setcounter{secnumdepth}{#1}%
+ \automark[section]{chapter}%
+ \let\@rightmark\rightleftmark
+}
+\newcommand{\@setsecdepth}[1]{%
+ \setcounter{secnumdepth}{#1}%
+ \ifnum#1 > 0
+ \automark[section]{chapter}%
+ \else
+ \automark{chapter}%
+ \fi
+ \let\@rightmark\@secondoftwo
+}
+\makeatother
+
+\newtcolorbox{important}{colback=red!5!white,colframe=red}
+
+\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{\langxml}{\hyperref[sec:lang.xml]{language resource file}}
+
+\newcommand{\hex}[1]{0x#1}
+\newcommand{\hexsb}[1]{\textsubscript{\scriptsize\rmfamily#1}}
+\newcommand{\subfigfmt}[1]{(\emph{#1})}
+
+\newcommand{\qt}[1]{``#1''}
+
+\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}}
+
+\newcommand{\qtdelim}[1]{\idx{doublequotechardelim}#1\idx{doublequotechardelim}}
+
+\newcommand{\ifnumhex}[1]{\cs{ifnum}\idx{doublequotecharhex}#1}
+
+\newcommand{\charhex}[1]{\cs{char}\idx{doublequotecharhex}#1}
+\newcommand{\icharhex}[1]{\ics{char}\idx[format=glsnumberformat,noindex=false]{doublequotecharhex}#1}
+
+\newcommand{\era}[1]{\texorpdfstring{\textsc{\MakeLowercase{#1}}}{#1}}
+
+\newcommand{\dequals}{%
+ \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
+}
+
+% 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}}
+
+\newcommand*{\filefmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
+\newcommand*{\metafilefmt}[3]{%
+ \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}%
+}
+
+\newcommand*{\primaryresourcefmt}{%
+ \texorpdfstring
+ {\texttt{\char`\\ jobname.glstex}}%
+ {\string\\jobname.glstex}%
+}
+
+\newcommand*{\suppresourcefmt}[1]{%
+ \texorpdfstring
+ {\texttt{\char`\\ jobname-#1.glstex}}%
+ {\string\\jobname-#1.glstex}%
+}
+
+\definecolor{field}{named}{DarkSlateGray4}
+\definecolor{cs}{named}{DarkSeaGreen4}
+\definecolor{styopt}{named}{DarkOrchid4}
+\definecolor{entry}{named}{SteelBlue4}
+\definecolor{comment}{named}{gray}
+\definecolor{attribute}{named}{Purple4}
+\definecolor{style}{named}{Blue4}
+
+\newcommand{\extstyopt}{\textsuperscript{\textdagger}}
+
+\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
+\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
+\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{cs}{\optfmt{#1}}}{#1}}
+\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{styopt}{\optfmt{#1}}}{#1}}
+\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{field}#1}}{#1}}
+\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{entry}#1}}{#1}}
+\newcommand*{\atentryfmt}[1]{\entryfmt{@#1}}
+\newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}}
+\newcommand*{\idprefixfmt}[1]{%
+ \texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}}
+\newcommand*{\xmltagfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
+
+\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{|}}
+
+\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*{\file}[1]{%
+ \texorpdfstring
+ {\idx{file.#1}}%
+ {#1}%
+}
+
+\newcommand{\texmfcnffmt}[1]{\texttt{#1}}
+
+\glsxtrnewgls{idx.texmfcnf.}{\texmfcnf}
+
+\newcommand*{\extfmt}[1]{\filefmt{.#1}}%
+
+\glsxtrnewgls[format=glsignore]{idx.ext.}{\ext}
+
+\newcommand*{\iext}[1]{%
+ \glsxtrtitleorpdforheading{\idx{ext.#1}}{.#1}{\extfmt{#1}}%
+}
+
+\glsxtrnewgls[format=glsignore]{idx.}{\sty}
+
+\newcommand*{\isty}[1]{%
+ \texorpdfstring{\idx[noindex=false]{#1}}{#1}%
+}
+
+\newcommand*{\env}[1]{%
+ \texorpdfstring{\idx{env.#1}}{#1}%
+}
+
+\newcommand{\glsxtrpostdescenvironment}{environment}
+
+\newcommand*{\abbrstyle}[1]{%
+ \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
+}
+
+\newcommand*{\topicabbrstyle}[1]{%
+ %\texorpdfstring{\idx[prefix=topic.]{abbrstyle.#1}}{#1}%
+ \texorpdfstring{\idx{abbrstyle.#1}}{#1}%
+}
+
+\newcommand*{\glostyle}[1]{%
+ \texorpdfstring{\idx{glostyle.#1}}{#1}%
+}
+
+\newcommand*{\topicglostyle}[1]{%
+ %\texorpdfstring{\idx[prefix=topic.]{glostyle.#1}}{#1}%
+ \texorpdfstring{\idx{glostyle.#1}}{#1}%
+}
+
+\newcommand*{\iglostyle}[1]{%
+ \texorpdfstring{\idx[noindex=false]{glostyle.#1}}{#1}%
+}
+
+\newcommand*{\catattr}[1]{%
+ \texorpdfstring{\idx{catattr.#1}}{#1}%
+}
+
+\newcommand*{\counter}[1]{%
+ \texorpdfstring{\idx{ctr.#1}}{#1}%
+}
+
+\newcommand{\glsxtrpostdesccounter}{counter}
+
+\newcommand*{\idprefix}[1]{%
+ \texorpdfstring{\idx{idprefix.#1}}{#1}%
+}
+
+
+\newcommand*{\styopt}[2][]{%
+ \texorpdfstring%
+ {%
+ \gls{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ }%
+ {#2\ifblank{#1}{}{=#1}}%
+}
+
+\newcommand*{\istyopt}[2][]{%
+ \texorpdfstring%
+ {%
+ \gls[noindex=false]{styopt.#2}\styoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ }%
+ {#2\ifblank{#1}{}{=#1}}%
+}
+
+\newcommand*{\styoptref}[1]{\gls[format=glsignore]{styopt.#1}}
+
+\newcommand*{\keyvallist}{%
+ \texorpdfstring
+ {key\dequals value list}%
+ {key=value list}%
+}
+
+\newcommand{\cssection}[2][\subsection]{%
+ #1{\texorpdfstring{\glsxtrglossentry{#2}}{\string\\#2}}%
+}
+
+\newcommand{\format}[1]{%
+ \gls{#1}\glsentryuseri{#1}%
+}
+
+\newcommand{\formatdef}[1]{%
+ \begin{definition}%
+ \gls[hyper=false]{#1}\glsentryuseri{#1}%
+ \end{definition}\ignorespaces
+}
+
+\newcommand{\nosecformatdef}[1]{%
+ \begin{definition}
+ \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}%
+ \glsadd{#1}\glsxtrglossentry{#1}%
+ \glsentryuseri{#1}%
+ \end{definition}\ignorespaces
+}
+
+\newcommand{\nosecdef}[1]{%
+ \begin{flushleft}\ttfamily
+ \renewcommand{\GlsXtrStandaloneEntryName}[1]{\glstarget{##1}{\strut}\cs{##1}}%
+ \glsadd{#1}\glsxtrglossentry{#1}%
+ \glsentryuseri{#1}%
+ \end{flushleft}\ignorespaces
+}
+
+\newcommand{\inlinedef}[1]{%
+ \code
+ {%
+ \glsadd{#1}\glsxtrglossentry{#1}%
+ \glsentryuseri{#1}%
+ }%
+}
+
+\newcommand*{\csref}{\gls}
+
+\newcommand*{\cs}[1]{%
+ \glsdoifexists{idx.#1}%
+ {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\glsentryname{idx.#1}}}%
+}
+
+\glsxtridentifyglslike{idx.}{\cs}
+
+\newcommand*{\ics}[2][]{\glsadd[#1]{idx.#2}\cs{#2}}
+
+\newcommand*{\csdisp}[2]{%
+ \texorpdfstring
+ {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\csfmt{#2}}}%
+ {\string\\#2}%
+}
+
+\newcommand*{\icsdisp}[3][]{%
+ \glsadd[#1]{idx.#2}\glsdohyperlink{\glolinkprefix cs.idx.#2}{\csfmt{#3}}%
+}
+
+\newcommand*{\encapdisp}[2]{%
+ \texorpdfstring
+ {\glsdohyperlink{\glolinkprefix cs.idx.#1}{\code{#2}}}%
+ {#2}%
+}
+
+\glsxtridentifyglslike{idx.}{\ics}
+
+\newcommand*{\icswithargs}[2][]{\glsadd[#1]{idx.#2}\cs{#2}\glsentryuseri{#2}}
+
+\newcommand*{\postdeschook}[1]{%
+ \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostdesccategory}{\csfmt{glsxtrpostdesc#1}}}
+\newcommand*{\postnamehook}[1]{%
+ \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostnamecategory}{\csfmt{glsxtrpostname#1}}}
+\newcommand*{\postlinkhook}[1]{%
+ \glsdohyperlink{\glolinkprefix cs.idx.glsxtrpostlinkcategory}{\csfmt{glsxtrpostlink#1}}}
+
+\newcommand*{\encap}[2][]{\glsadd[#1]{idx.#2}%
+ {%
+ \let\csfmt\code
+ \glsdohyperlink{\glolinkprefix cs.idx.#2}{\glsentryname{idx.#2}}%
+ }%
+}
+
+\newcommand{\optsection}[2][\subsection]{%
+ \glsxtrifhasfield*{useri}{opt.#2}%
+ {%
+ #1[\texorpdfstring
+ {\glsxtrheadname{opt.#2}\csoptfmt{=\glscurrentfieldvalue}}%
+ {\glsentryname{opt.#2}=\glscurrentfieldvalue}]
+ {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}%
+ \csoptfmt{=\glscurrentfieldvalue}%
+ }%
+ }%
+ {%
+ #1[\texorpdfstring{\glsxtrheadname{opt.#2}}{\glsentryname{opt.#2}}]
+ {\glsadd{opt.#2}\glsxtrglossentry{opt.#2}}%
+ }%
+}
+
+\glsxtrnewgls{file.}{\exfile}
+
+\newcommand{\filesection}[2][\section]{%
+ #1[\texorpdfstring{\glsxtrheadname{file.#2}}{\glsentryname{file.#2}}]
+ {\glsadd{file.#2}\glsxtrglossentry{file.#2}}%
+}
+
+\newcommand*{\csopt}[2][]{\gencsopt{#1}{opt}{#2}}%
+\newcommand*{\glsopt}[2][]{\gencsopt{#1}{idx.gls}{#2}}%
+\newcommand*{\glsaddopt}[2][]{\gencsopt{#1}{idx.glsadd}{#2}}%
+\newcommand*{\printglossopt}[2][]{\gencsopt{#1}{idx.printgloss}{#2}}%
+\newcommand*{\iprintglossopt}[2][]{\glsadd{idx.printgloss.#2}\gencsopt{#1}{idx.printgloss}{#2}}%
+
+\newcommand*{\gencsopt}[3]{%
+ \texorpdfstring%
+ {%
+ \gls{#2.#3}%
+ \csoptfmt{\ifblank{#1}{}{\dequals\marg{#1}}}%
+ }%
+ {#3\ifblank{#1}{}{=#1}}%
+}
+
+\newcommand*{\field}[1]{%
+ \texorpdfstring
+ {\gls{field.#1}}%
+ {#1}%
+}
+
+\newcommand*{\fielddisp}[2]{%
+ \texorpdfstring
+ {\glsdisp{field.#1}{\fieldfmt{#2}}}%
+ {#2}%
+}
+
+\newcommand*{\fielddef}[1]{%
+ \glsadd{field.#1}%
+ \glsxtrglossentry{field.#1}{}%
+}
+
+\newcommand*{\fieldref}[1]{\gls[format=glsignore]{field.#1}}
+
+\newglossarystyle{fieldstyle}{%
+ \renewenvironment{theglossary}%
+ {%
+ \setlength{\glsdescwidth}{\dimexpr\linewidth-\maxnamewidth-4\tabcolsep}%
+ \begin{longtable}{l>{\raggedright}p{\glsdescwidth}}%
+ }%
+ {\end{longtable}}%
+ \renewcommand*{\glossaryheader}{%
+ \noalign{\xdef\dofieldtabcaption{%
+ \noexpand\caption\expandonce\fieldtablelotcaption
+ {\expandonce\fieldtablecaption}}}%
+ \dofieldtabcaption
+ \fieldtablecaptionlabel
+ \fieldtablepostcaption\tabularnewline
+ \bfseries Field & \bfseries Description\tabularnewline
+ \endfirsthead
+ \caption*{\fieldtablecaption\ (Continued)}\tabularnewline
+ \bfseries Field & \bfseries Description\tabularnewline
+ \endhead
+ }%
+ \renewcommand*{\glsgroupheading}[1]{}%
+ \renewcommand{\glossentry}[2]{%
+ \glsadd{##1}%
+ \glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}} &
+ \glossentrydesc{##1}\tabularnewline
+ }%
+ \renewcommand{\subglossentry}[3]{\glossentry{##2}{##3}}%
+ \renewcommand*{\glsgroupskip}{}%
+}
+
+\newcommand*{\fieldhook}[1]{%
+ \edef\currentcategory{\glscategory{#1}}%
+ \glsxtriflabelinlist{\currentcategory}{\fieldcategories}%
+ {%
+ \settowidth{\dimen0}{\glsentryname{#1}}%
+ \ifdim\dimen0>\maxnamewidth \setlength{\maxnamewidth}{\dimen0}\fi
+ }%
+ {\printunsrtglossaryskipentry}%
+}
+
+\newlength\maxnamewidth
+
+%\printfields[postcaption]{category list}[lot caption]{caption}{label}
+\newcommand*{\printfields}[2][]{%
+ \ifstrempty{#1}%
+ {%
+ \def\fieldtablepostcaption{}%
+ }%
+ {%
+ \def\fieldtablepostcaption{%
+ \tabularnewline
+ \multicolumn{2}{p{\linewidth}}{#1}%
+ \tabularnewline
+ }%
+ }%
+ \def\fieldcategories{#2}%
+ \innerprintfields
+}
+
+\newcommand*{\innerprintfields}[3][]{%
+ \printunsrtglossary*[style=fieldstyle]{%
+ \renewcommand*\glossarysection[2][]{}%
+ \ifstrempty{#1}%
+ {%
+ \def\fieldtablelotcaption{}%
+ }%
+ {%
+ \def\fieldtablelotcaption{[#1]}%
+ }%
+ \def\fieldtablecaption{#2}%
+ \def\fieldtablecaptionlabel{\label{#3}}%
+ \setlength{\maxnamewidth}{0pt}%
+ \let\printunsrtglossaryentryprocesshook\fieldhook
+ }%
+}
+
+\renewcommand*{\glsxtrbookindexname}[1]{%
+ \glsxtrifhasfield{dualid}{#1}%
+ {%
+ \glshyperlink[\glossentryname{#1}]{\glscurrentfieldvalue}%
+ }
+ {%
+ \GlsXtrIfFieldEqStr{category}{#1}{command}%
+ {\glsdohyperlink{\glolinkprefix cs.#1}{\glossentryname{#1}}}%
+ {\glossentryname{#1}}%
+ }%
+}
+
+\newcommand{\summarysubheaderfont}[1]{\textbf{\sffamily #1}}
+
+\newcommand{\summaryoptionhandler}[1]{%
+ \par\smallskip\nopagebreak
+ \par\noindent\hspace{1em}%
+ \code{\gls{#1}\glsxtrifhasfield{useri}{#1}{=\glscurrentfieldvalue}{}}%
+ \glsxtrifhasfield{note}{#1}%
+ {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
+ {}%
+ \nopagebreak\par\hangindent2em\noindent\hspace{2em}\Glossentrydesc{#1}%
+}
+
+\newrobustcmd{\donote}[1]{%
+ \glsxtrifhasfield{note}{#1}%
+ {\nolinebreak\hfill\mbox{\normalfont\footnotesize\glscurrentfieldvalue}}%
+ {}%
+}
+
+\newglossarystyle{commandsummary}%
+{%
+ \setglossarystyle{index}%
+ \renewcommand*{\glossaryheader}{\raggedright}%
+ \renewcommand*{\glsgroupheading}[1]{%
+ \glsxtrgetgrouptitle{##1}{\thisgrptitle}%
+ \glsxtrbookindexbookmark{\thisgrptitle}{summary.##1}%
+ \glsxtrbookindexformatheader{\thisgrptitle}%
+ \nopagebreak\indexspace\nopagebreak\csuse{@afterheading}%
+ }%
+ \renewcommand*{\glossentry}[2]{%
+ \glstreeitem \glstarget{cs.##1}{\strut}%
+ \glsxtrifhasfield{dualid}{##1}%
+ {%
+ {%
+ \let\csfmtfont\csfmtcolourfont
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
+ \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
+ \donote{##1}%
+ \nopagebreak\par\hspace{10pt}%
+ \Glossentrydesc{\glscurrentfieldvalue}%
+ \ifglshasdesc{\glscurrentfieldvalue}{\@. }{}%
+ }%
+ {%
+ {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##1}}%
+ \glsxtrifhasfield{useri}{##1}{\glscurrentfieldvalue}{}%
+ \donote{##1}%
+ \nopagebreak\par\hspace{10pt}%
+ \Glossentrydesc{##1}%
+ \ifglshasdesc{##1}{\@. }{}%
+ }%
+ \GlsXtrIfFieldEqStr{originalentrytype}{##1}{glscommand}%
+ {%
+ % Does this entry have options?
+ \GlsXtrIfHasNonZeroChildCount{##1}%
+ {%
+ \glspar\medskip\glspar
+ \summarysubheaderfont{Options:}
+ \glsxtrfieldforlistloop{##1}{childlist}{\summaryoptionhandler}%
+ }%
+ {}%
+ }%
+ {%
+ \GlsXtrIfHasNonZeroChildCount{##1}%
+ {This command has \glscurrentfieldvalue\ forms:}{}%
+ }%
+ %\listtopics{##1}%
+ \par\medskip
+ }%
+ \renewcommand*{\subglossentry}[3]{%
+ \glstreesubitem \glstarget{cs.##2}{\strut}%
+ \glsxtrifhasfield{dualid}{##2}%
+ {%
+ {%
+ \let\csfmtfont\csfmtcolourfont
+ \glshyperlink{\glscurrentfieldvalue}%
+ }%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \donote{##2}%
+ \nopagebreak\par\hspace{20pt}%
+ \ifglshasdesc{\glscurrentfieldvalue}%
+ {\Glossentrydesc{\glscurrentfieldvalue}.}{}%
+ }%
+ {%
+ {\let\csfmtfont\csfmtcolourfont\gls[hyper=false]{##2}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \donote{##2}%
+ \nopagebreak\par\hspace{20pt}%
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
+ }%
+ \par\medskip
+ }%
+}
+
+\newcommand*{\commandsummaryhook}[1]{%
+ \edef\currentcategory{\glscategory{#1}}%
+ \ifdefstring{\currentcategory}{command}%
+ {%
+ \glsxtrifhasfield*{progenitor}{#1}%
+ {\printunsrtglossaryskipentry}{}%
+ }%
+ {\printunsrtglossaryskipentry}%
+}
+
+\newcommand*{\printcommandsummary}{%
+ \printunsrtglossary*[type=index,
+ style=commandsummary,
+ title={General Command Summary},
+ ]%
+ {%
+ \def\glossarypreamble{This is an alphabetical summary of
+ commands referenced in this document. See the
+ relevent user guides for further details.\endgraf\medskip
+ \texparserdefnotetarget}%
+ \let\printunsrtglossaryentryprocesshook\commandsummaryhook
+ \let\csref\cs
+ \glsxtrlocalsetgrouptitle{glssymbols}{}%
+ }%
+}
+
+\newcommand{\topicxrhandler}[1]{%
+ \glsxtrifhasfield{parent}{#1}%
+ {%
+ \let\field\fieldfmt
+ \hyperlink
+ {topic.\glscurrentfieldvalue}%
+ {\glsentryname{\glscurrentfieldvalue}}%
+ }%
+ {%
+ \hyperlink{topic.#1}{\glsentryname{#1}}%
+ }%
+}
+
+% \iffirstprogeny{entry label}{topic label}{true}{false}
+\makeatletter
+\newcommand{\iffirstprogeny}[2]{%
+ \let\doiffirstprogeny\@secondoftwo
+ \def\firstprogeny{}%
+ \glsxtrifhasfield*{unsortedprogeny}{#1}%
+ {%
+ \edef\suppliedprogeny{#2}%
+ \@for\thisprogeny:=\glscurrentfieldvalue\do{%
+ \let\firstprogeny\thisprogeny
+ \ifdefequal{\thisprogeny}{\suppliedprogeny}%
+ {\let\doiffirstprogeny\@firstoftwo}%
+ {\let\doiffirstprogeny\@secondoftwo}%
+ \@endfortrue
+ }%
+ }%
+ {}%
+ \doiffirstprogeny
+}
+\makeatother
+
+\newcommand{\ifstylecommand}[1]{%
+ \letcs\doifstylecommand{@firstoftwo}%
+ \GlsXtrIfFieldEqStr{originalentrytype}{#1}{abbrvstylecommand}%
+ {}%
+ {%
+ \GlsXtrIfFieldEqStr{originalentrytype}{#1}{glostylecommand}%
+ {}%
+ {\global\letcs\doifstylecommand{@secondoftwo}}%
+ }%
+ \doifstylecommand
+}
+
+\newcommand{\listtopics}[1]{%
+ \glsxtrifhasfield{progeny}{#1}%
+ {%
+ \ifdefequal\glscurrentfieldvalue\glscurrententrylabel
+ {}%
+ {%
+ \par\nopagebreak\medskip\par\footnotesize
+ \sloppy
+ \ifstylecommand{#1}%
+ {\summarysubheaderfont{Styles:}}%
+ {\summarysubheaderfont{Topics:}}%
+ \space
+ \let\DTLlistformatitem\topicxrhandler
+ \DTLformatlist{\glscurrentfieldvalue}.\par
+ }%
+ }%
+ {}%
+}
+
+\newglossarystyle{commandtopic}%
+{%
+ \setglossarystyle{index}%
+ %\renewcommand*{\glossaryheader}{\raggedright}%
+ \renewcommand*{\glsgroupheading}[1]{}%
+ \renewcommand*{\glossentry}[2]{%
+ \glsfieldfetch{##1}{nametitle}{\thisvalue}%
+ \section*{%
+ \raisebox{2ex}%
+ {\pdfbookmark[1]{\thisvalue}{topic.##1}\hypertarget{topic.##1}{}}%
+ \glsdisp{##1}{\thisvalue}\donote{##1}%
+ }%
+ \expandafter\sectionmark\expandafter{\thisvalue}%
+ \ifglshasdesc{##1}{\Glossentrydesc{##1}.}{}%
+ \glsxtrifhasfield{seealso}{##1}%
+ {%
+ \par\smallskip
+ \emph{See also:}
+ \let\DTLlistformatitem\topicxrhandler
+ \DTLformatlist{\glscurrentfieldvalue}.%
+ \par\medskip\par
+ }%
+ {}%
+ }%
+ \renewcommand*{\subglossentry}[3]{%
+ \glsifcategory{##2}{command}%
+ {%
+ \glsdohypertarget{topic.##2}{\strut}%
+ \glsxtrifhasfield*{progenitor}{##2}%
+ {\let\originallabel\glscurrentfieldvalue}%
+ {\def\originallabel{##2}}%
+%
+ \ifstylecommand{##2}%
+ {%
+ \iffirstprogeny{\originallabel}{##2}%
+ {\letcs\dothisentry{@firstofone}}%
+ {%
+ \glspar
+ \ifdefempty\firstprogeny
+ {%
+ {\let\csfmtfont\csfmtcolourfont\gls[noindex]{\originallabel}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ }%
+ {%
+ {\let\csfmtfont\csfmtcolourfont
+ \hyperlink{topic.\firstprogeny}{\glsentryname{\firstprogeny}}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \glsxtrifhasfield{parent}{\firstprogeny}%
+ {\hfill
+ {\footnotesize\emph{see} \hyperlink{topic.\glscurrentfieldvalue}%
+ {\glsentryname{\glscurrentfieldvalue}}.}}
+ {}%
+ }%
+ \letcs\dothisentry{@gobble}%
+ }%
+ }%
+ {\letcs\dothisentry{@firstofone}}%
+ \dothisentry
+ {%
+ \par\smallskip\par
+ % hyperlink to index:
+ {\let\csfmtfont\csfmtcolourfont\gls[format=glsignore]{\originallabel}}%
+ \glsxtrifhasfield{useri}{##2}{\glscurrentfieldvalue}{}%
+ \glsxtrifhasfield{note}{##2}%
+ {\nolinebreak\hfill\mbox{\footnotesize\glscurrentfieldvalue}}%
+ {}%
+ \nopagebreak\par\smallskip\par\nopagebreak
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.}{}%
+ % Topics
+ \listtopics\originallabel
+ \par\smallskip
+ }%
+ }%
+ {%
+ \glsfieldfetch{##2}{nametitle}{\thisvalue}%
+ \subsection*{%
+ \raisebox{2ex}%
+ {\hypertarget{topic.##2}{}\pdfbookmark[2]{\thisvalue}{topic.##2}}%
+ \glsdisp{##2}{\thisvalue}\donote{##2}%
+ }%
+ \expandafter\subsectionmark\expandafter{\thisvalue}%
+ \ifglshasdesc{##2}{\Glossentrydesc{##2}.\glspar\nopagebreak\smallskip}{}%
+ }%
+ }%
+}
+
+\newcommand*{\commandtopichook}[1]{%
+ \glsxtrifhasfield*{progenitor}{#1}%
+ {}%
+ {%
+ \GlsXtrIfFieldEqStr*{originalentrytype}{#1}{topic}%
+ {}%
+ {%
+ \glsxtrifhasfield*{parent}{#1}%
+ {%
+ \GlsXtrIfFieldEqStr*{originalentrytype}{\glscurrentfieldvalue}{topic}%
+ {}%
+ {\printunsrtglossaryskipentry}%
+ }%
+ {\printunsrtglossaryskipentry}%
+ }%
+ }%
+}
+
+\newcommand*{\printcommandtopic}{%
+ \setsecdepth*{0}%
+ \automark[subsection]{section}%
+ \printunsrtglossary*[type=index,
+ style=commandtopic,
+ title={Summary by Topic of Glossary Commands},
+ label={sec:topics},
+ nogroupskip,
+ nonumberlist
+ ]%
+ {%
+ \def\texparserdefprefix{topic.}%
+ \def\glossarypreamble{This is a summary of commands provided
+ by \styfmt{glossaries}, \styfmt{glossaries-extra} and
+ their supplementary packages that may be useful to
+ \bibgls\ users. Commands specific to other indexing methods
+ aren't listed unless they've been referenced in this manual.
+ See the appropriate user guides for further details.
+ \endgraf\medskip
+ \texparserdefnotetarget}%
+ \let\abbrstyle\topicabbrstyle
+ \let\glostyle\topicglostyle
+ \let\printunsrtglossaryentryprocesshook\commandtopichook
+ \let\csref\cs
+ }%
+ \setsecdepth{0}%
+}
+
+\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}}%
+}
+
+\newcommand{\entrydef}[1]{\glsadd{entry.#1}\glsxtrglossentry{entry.#1}}
+
+\newcommand*{\atentry}[2][]{%
+ \texorpdfstring
+ {\gls[#1]{entry.#2}}%
+ {#2}%
+}
+
+\newcommand*{\atentrypageref}[1]{%
+ \atentry{#1} (page~\glsxtrpageref{entry.#1})}%
+
+\newcommand*{\atentryref}[1]{\gls[format=glsignore]{entry.#1}}
+
+\newcommand{\argsection}[2][\section]{%
+ \def\switcharg{}%
+ \def\switchalt{}%
+ \def\switchaltpdf{}%
+ \glsxtrifhasfield*{useri}{switch.#2}%
+ {%
+ \edef\switcharg{ \expandonce\glscurrentfieldvalue}%
+ }%
+ {}%
+ \ifglshassymbol{switch.#2}%
+ {%
+ \def\switchalt{ (or \protect\glsentrysymbol{switch.#2}\switcharg)}%
+ }%
+ {}%
+ #1[\texorpdfstring
+ {\glsxtrheadname{switch.#2}}%
+ {\glsentryname{switch.#2}}%
+ \switcharg\switchalt
+ ]
+ {\glsadd{switch.#2}%
+ \glsxtrglossentry{switch.#2}\switcharg\switchalt}%
+}
+
+\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}%
+}
+
+\newcommand*{\longargpageref}[1]{%
+ \longarg{#1} (page~\glsxtrpageref{switch.#1})}%
+
+\newcommand*{\longargorshort}[1]{%
+ \texorpdfstring
+ {\gls{switch.#1}\ifglshassymbol{switch.#1}{ or \glssymbol{switch.#1}}{}}%
+ {\string-\string-#1}%
+}
+
+\newcommand*{\unicodecategoryfmt}[1]{\qt{\textsf{#1}}}
+
+\definecolor{defbackground}{rgb}{1,1,0.75}
+\newsavebox\defsbox
+\newlength\defwidth
+
+\newenvironment{definition}%
+{%
+ \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}%
+ \begin{lrbox}{\defsbox}%
+ \setlength\defwidth\linewidth
+ \addtolength\defwidth{-2\fboxrule}%
+ \addtolength\defwidth{-2\fboxsep}%
+ \begin{minipage}{\defwidth}
+ \flushleft\ttfamily\ignorespaces
+}%
+{%
+ \end{minipage}%
+ \end{lrbox}\par\medskip\noindent
+ \fcolorbox{black}{defbackground}{\usebox\defsbox}%
+ \medskip\par\noindent
+ \ignorespacesafterend
+}
+
+\newcommand{\introguide}{\href{bib2gls-begin.pdf}{\qt{\styfmt{glossaries-extra}
+and \bibgls: An Introductory Guide} (\filefmt{bib2gls-begin.pdf})}}
+
+\setcounter{tocdepth}{4}
+
+\newcommand*{\sectionref}[1]{\cref{#1}}
+\newcommand*{\Sectionref}[1]{\Cref{#1}}
+\newcommand*{\figureref}[1]{\hyperlink{#1-top}{figure~\ref*{#1}}}
+\newcommand*{\Figureref}[1]{\hyperlink{#1-top}{Figure~\ref*{#1}}}
+\newcommand*{\tableref}[1]{\cref{#1}}
+\newcommand*{\Tableref}[1]{\Cref{#1}}
+
+\newcommand{\figcontents}[3]{%
+ \hypertarget{#3-top}{}%
+ \centering
+ #1\par
+ #2\label{#3}%
+}
+
+\newlength\imagewidth
+\newcount\tmpctr
+
+\newcommand*{\pdftwocol}[3][1]{%
+ \renewcommand{\tabcolsep}{2pt}%
+ \setlength{\imagewidth}{\dimexpr.5\linewidth-2\tabcolsep}%
+ \def\tabcontents{\begin{tabular}{@{}cc@{}}}%
+ \tmpctr\numexpr#1-1\relax
+ \loop
+ \advance\tmpctr by 1\relax
+ \eappto\tabcontents{\noexpand\frame{%
+ \noexpand\includegraphics[page=\the\tmpctr,width=\noexpand\imagewidth]{#2}}}%
+ \ifodd\tmpctr
+ \appto\tabcontents{&}%
+ \else
+ \appto\tabcontents{\\}%
+ \fi
+ \ifnum\tmpctr<#3
+ \repeat
+ \appto\tabcontents{\end{tabular}}%
+ \tabcontents
+}
+
+\makeatletter
+\newcommand*{\tablelistcs}[2]{%
+ \tmpctr=0\relax
+ \def\tabcontents{}%
+ \loop
+ \advance\tmpctr by 1\relax
+ \appto\tabcontents{l}%
+ \ifnum\tmpctr<#1
+ \repeat
+%
+ \edef\tabcontents{\noexpand\begin{tabular}{@{}\tabcontents @{}}}%
+ \def\thislist{#2}%
+ \dtlsortlist{\thislist}{\dtlicompare}%
+ \tmpctr=1\relax
+ \@for\thislabel:=\thislist\do{%
+ \eappto\tabcontents{\noexpand\ics{\thislabel}}%
+ \ifnum\tmpctr<#1\relax
+ \appto\tabcontents{&}%
+ \advance\tmpctr by 1\relax
+ \else
+ \appto\tabcontents{\\}%
+ \tmpctr=1\relax
+ \fi
+ }%
+ \appto\tabcontents{\end{tabular}}%
+ \tabcontents
+}
+\makeatother
+
+% This is a bit fiddly. Need to represent \vec{v} in typewriter
+% font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't
+% work)
+\newsavebox\varrow
+\sbox\varrow{$\mathtt{\accentset{\to}{v}}$}
+
+\newcommand*{\mtx}[1]{\boldsymbol{#1}}
+\newcommand*{\set}[1]{\mathcal{#1}}
+\newcommand*{\card}[1]{|\set{#1}|}
+\newcommand*{\imaginary}{i}
+
+\newcommand{\addr}[1]{\\\href{https://www.#1/}{\nolinkurl{#1}}}
+\title{\bibgls: a command line Java application to convert
+\filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource
+files}
+\author{Nicola Talbot\addr{dickimaw-books.com}}
+\date{\DTMusedate{moddate}}
+
+\makeatletter
+\renewcommand{\fps@figure}{htbp}
+
+\newcommand{\code}[1]{\texorpdfstring{{\ttfamily\obeyspaces #1}}{#1}}
+
+\newcommand{\setupcodeenvfmts}{%
+ \def\cmd{\char`\\}%
+ \def\comment##1{\mbox{\textcolor{comment}{\idx{commentchar}\ ##1}}}%
+ \renewcommand*{\styfmt}[1]{##1}%
+ \renewcommand*{\counterfmt}[1]{##1}%
+ \renewcommand*{\catattrfmt}[1]{\textcolor{attribute}{##1}}%
+ \renewcommand*{\abbrstylefmt}[1]{\textcolor{style}{##1}}%
+ \renewcommand*{\csfmtfont}[1]{\textcolor{cs}{##1}}%
+}
+
+\newenvironment{codeenv}
+ {%
+ \renewcommand{\glslinkpresetkeys}{\setkeys{glslink}{noindex}}%
+ \setupcodeenvfmts
+ \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
+ \parindent\z@\parfillskip\@flushglue\parskip\z@skip
+ }
+ {\end{flushleft}\ignorespacesafterend}
+
+\newenvironment{codeenv*}
+ {%
+ \setupcodeenvfmts
+ \begin{flushleft}\ttfamily\obeylines\frenchspacing\@vobeyspaces
+ \parindent\z@\parfillskip\@flushglue\parskip\z@skip
+ }
+ {\end{flushleft}\ignorespacesafterend}
+
+\begingroup
+ \renewcommand{\addr}[1]{}
+ \let\texorpdfstring\@secondoftwo
+ \DTMsetstyle{pdf}
+ \protected@edef\x{\endgroup
+ \noexpand\hypersetup{%
+ pdfinfo={
+ Title={\@title},
+ Author={\@author},
+ CreationDate={\DTMuse{creation}},
+ ModDate={\DTMuse{moddate}},
+ }%
+ }%
+ }\x
+
+\makeatother
+
+\renewcommand{\titlepagestyle}{empty}
+
+\begin{document}
+\maketitle
+\pagenumbering{alph}
+\pagestyle{empty}
+
+\begin{abstract}
+The \bibgls\ command line application can be used to extract
+glossary information stored in a \ext{bib} file and convert it
+into glossary entry definitions that can be read using
+\styfmt{glossaries-extra}'s \gls{GlsXtrLoadResources} command. When used
+in combination with the \styoptfmt{record} package option, \bibgls\
+can select only those entries that have been used in the document,
+as well as any dependent entries, which reduces the \TeX\ resources
+required by not defining unnecessary commands.
+
+Since \bibgls\ can also sort and collate the recorded locations
+present in the \ext{aux} file, it can simultaneously by-pass the
+need to use \idx{makeindex} or \idx{xindy}, although \bibgls\
+can be used together with an external indexing application if required. (For
+example, if a custom \idx{xindy} rule is needed.)
+
+An additional build may be required to ensure the locations are
+up-to-date as the page-breaking may be slightly different on the
+first \LaTeX\ run due to the unknown references being replaced with
+?? which can be significantly shorter than the actual text produced
+when the reference is known.
+
+Note that \bibgls\ is a Java application, and requires at least
+Java~8.\footnote{The \code{List.sort} method used to sort the
+entries was only introduced to Java~8.} Additionally,
+\sty{glossaries-extra} must be at least version 1.12. (Although
+the latest version is recommended.) This application was
+developed in response to the question
+\qt{\href{http://tex.stackexchange.com/q/342544}{Is there a program
+for managing glossary tags?}} on \TeX\ on
+StackExchange~\cite{tex.sx}. The \ext{bib} file can be managed in an
+application such as JabRef.
+
+If you already have a \ext{tex} file containing
+entry definitions using commands like \gls{newglossaryentry}
+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 \introguide\ is an
+introductory guide to the \sty{glossaries-extra} package, which you
+may prefer to start with if you are unfamiliar with the
+\sty{glossaries} and \sty{glossaries-extra} packages.
+\end{abstract}
+
+\frontmatter
+
+\tableofcontents
+\listoftables
+\listoffigures
+
+\mainmatter
+\chapter{Introduction}
+
+If you have extensively used the \styfmt{glossaries}~\cite{glossaries} or
+\styfmt{glossaries-extra}~\cite{glossaries-extra} package,
+you may have found yourself creating a large \iext{tex} file
+containing many definitions that you frequently use in documents.
+This file can then simply be loaded using \ics{input} or
+\ics{loadglsentries}, but a large file like this can be difficult to
+maintain and if the document only actually uses a small proportion
+of those entries, the document build is unnecessarily slow due to
+the time and resources taken on defining the unwanted entries.
+
+The aim of \bibgls\ is to allow the entries to be stored in a
+\iext{bib} file, which can be maintained using a reference system
+such as JabRef. The document build process
+can now be analogous to that used with \idx{bibtex} (or
+\appfmt{biber}), where only those entries that have been recorded in the
+document (and possibly their dependent entries) will be extracted
+from the \ext{bib} file. Since \bibgls\ can also perform
+hierarchical sorting and can collate location lists, it doubles as
+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 \bibgls\ as that command works
+by iterating over all defined entries and calling
+\code{\ics{glsadd}\margm{label}}. On the first \LaTeX\ run there are no
+entries defined, so \ics{glsaddall} does nothing. If you want to
+select all entries, just use \csopt[all]{selection} instead (which
+has the advantage over \ics{glsaddall} in that it doesn't create a
+redundant location for each entry).
+
+Note that \bibgls\ requires the extension package
+\isty{glossaries-extra} and can't be used with just the base
+\isty{glossaries} package, since it requires some of the extension
+commands. See the \styfmt{glossaries-extra} user
+manual~\cite{glossaries-extra} for information
+on the differences between the basic package and the extended
+package, as some of the default settings are different.
+
+Since the information used by \bibgls\ is
+written to the \iext{aux} file, it's not possible to run \bibgls\
+through \TeX's shell escape while the \ext{aux} file is open for
+write access. (The \ext{aux} file is closed \emph{after} the end
+document hook, so it can't be deferred with \ics{AtEndDocument}.)
+This means that if you really want to run \bibgls\
+through \ics{write18} it must be done in the preamble with
+\ics{immediate}. For example:
+\begin{verbatim}
+\immediate\write18{bib2gls \jobname}
+\end{verbatim}
+As from version 1.14 of \styfmt{glossaries-extra}, this can be done
+automatically with the \styopt{automake} option if the \ext{aux}
+file exists. (Remember that this will require the shell escape to be
+enabled.)
+
+\section{Example Use}
+The glossary entries are stored in a \ext{bib} file. For
+example, the file \filefmt{entries.bib} might contain:
+\begin{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal}
+}
+\strut
+\atentry{abbreviation}\marg{html,
+ \field{short}=\qtdelim{html},
+ \field{long}=\marg{hypertext markup language}
+}
+\strut
+\atentry{symbol}\marg{v,
+ \field{name}=\marg{\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}},
+ \field{text}=\marg{\cs{vec}\marg{v}},
+ \field{description}=\marg{a vector}
+}
+\strut
+\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
+\end{codeenv}
+Here's an example document that uses this data:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cs{usepackage}\oarg{\styoptref{record}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[en-GB]{sort}\comment{sort according to 'en-GB' locale}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}.
+Symbol: \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar}.
+Abbreviation: \cs{gls}\marg{html}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+If this document is called \filefmt{myDoc.tex}, the build
+process is:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{verbatim}
+(This manual assumes \appfmt{pdflatex} for simplicity. Replace
+with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as
+appropriate.) If you want \idxpl{lettergroup} (either headed, with
+styles like \glostyle{indexgroup}, or just a blank line separator
+with \styopt[false]{nogroupskip}) then you need to use the
+\longarg{group} switch:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls --group myDoc
+pdflatex myDoc
+\end{verbatim}
+
+You can have multiple instances of \gls{GlsXtrLoadResources}. For
+example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{index},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
+ \csopt[entrytype=\marg{entry}]{match},\comment{only select \atentry{entry}}
+ \csopt[main]{type}\comment{put these entries in the 'main' glossary}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
+ \csopt[entrytype=\marg{abbreviation}]{match},\comment{only select \atentry{abbreviation}}
+ \csopt[abbreviations]{type}\comment{put these in the 'abbreviations' glossary}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[letter-case]{sort},\comment{case-sensitive letter sort}
+ \csopt[entrytype=\marg{symbol}]{match},\comment{only select \atentry{symbol}}
+ \csopt[symbols]{type}\comment{put these entries in the 'symbols' glossary}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[en-GB]{sort},\comment{sort according to 'en-GB' locale}
+ \csopt[entrytype=\marg{index}]{match},\comment{only select \atentry{index}}
+ \csopt[index]{type}\comment{put these entries in the 'index' glossary}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{bird} and \cs{gls}\marg{goose}.
+Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gls}\marg{html}.
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+There are more examples provided in \sectionref{sec:examples}.
+
+Note that there's no need to called \idx!{xindy} or \idx!{makeindex}
+since \bibgls\ automatically sorts the entries and collates the locations
+after selecting the required entries from the \ext{bib} file and
+before writing the temporary file that's input with \gls{glsxtrresourcefile}
+(or the more convenient shortcut
+\gls{GlsXtrLoadResources}).\footnote{This document will mostly use
+the more convenient \gls{GlsXtrLoadResources}.} This
+means the entries are already defined in the correct order, and only
+those entries that are required in the document are defined, so
+\ics{printunsrtglossary} (or \ics{printunsrtglossaries}) may be used.
+(The \qtt{unsrt} part of the command name indicates that all
+defined entries should be listed in the order of definition from
+\styfmt{glossaries-extra}'s point of view, see the supplementary
+document \introguide\ for further details.)
+
+If you don't provide a value with the \styopt{record} option, then
+\styopt[only]{record} is assumed. This saves the same indexing
+information that's used with the \ics{cs.makeglossaries} and
+\ics{makenoidxglossaries} methods (described in the main
+\styfmt{glossaries} user manual~\cite{glossaries}). As from
+\styfmt{glossaries-extra} version 1.37, you can instead use
+\styopt[nameref]{record}, which saves some extra information for
+each location that's not available for the other indexing methods.
+See \longarg{merge-nameref-on} for further details.
+
+If you additionally want to use an indexing application, such
+as \idx{xindy}, you need the package option
+\styopt[alsoindex]{record} and use \ics{cs.makeglossaries}
+and \ics{printglossary} (or the iterative \ics{printglossaries}) as usual.
+This requires a more complicated build process:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+makeglossaries myDoc
+pdflatex myDoc
+\end{verbatim}
+(The entries aren't defined until the second \LaTeX\ run, so the
+indexing files required by \idx!{xindy} or \idx!{makeindex} can't be
+created until then.) In this case, \bibgls\ is simply being used to
+fetch the entry definitions from one or more \ext{bib} files, with
+the sorting and collating performed by the other indexing
+application (so the resource option list would need
+\csopt[none]{sort} and \csopt[false]{save-locations}). In general,
+it's best to avoid this hybrid method unless you have a particular
+set of \idx{xindy} rules that can't be replicated with \bibgls.
+
+\section{Logical Divisions: \field{type} vs \field{group} vs \field{parent}}
+\label{sec:logicaldivisions}
+
+If you have a document with many terms that need listing, it's
+likely that you may want to divide the terms into separate blocks or
+units for easier reading. There are three fields that are used
+for this.
+\begin{description}
+\item[\field{type}] The highest division is the glossary to which
+the entry belongs. The glossary must first be defined (see
+\sectionref{sec:newglossary}) with an associated label used to
+identify it. The title is assigned to the glossary when it is
+defined or it can be overridden with the \printglossopt{title} key.
+The glossary is displayed using \cs{printunsrtglossary} and the
+title is placed in a sectioning command by default.
+
+\begin{important}
+\bibgls\ does not provide any means of sorting glossary types. If
+you use \ics{printunsrtglossaries} the order will be according to
+the order in which the glossaries were defined. You may use
+\cs{printunsrtglossary} to list individual glossaries in your own
+preferred order.
+\end{important}
+
+\item[\field{group}] The entries within a glossary can form groups
+as a by-product of the sorting method. This must be enabled with the
+\longarg{group} switch and isn't available for the sort methods
+listed in \tableref{tab:sortoptionsnosort}. The group label is
+stored in the \field{group} field. This is an internal field that
+typically shouldn't be set in the \ext{bib} file.
+
+You can specify your own custom groups but if you do so you must
+ensure that the terms are ordered in such a way that they are
+gathered according to group. This is typically done by splitting the
+glossary into blocks using a separate \gls{GlsXtrLoadResources} with
+the \csopt{group} option set. You control the order of the groups by
+your ordering of \gls{GlsXtrLoadResources}. The group title can be
+assigned using \gls{glsxtrsetgrouptitle} within the document.
+
+\begin{important}
+\bibgls\ does not sort by group title. At most it can sort by the
+group label (by changing the \csopt{sort-field}) but this is usually
+an indication that you actually have a hierarchical glossary and you
+ought to be using the \field{parent} field instead. (Compare
+\exfile{sample-textsymbols.tex} and
+\exfile{sample-textsymbols2.tex}.)
+\end{important}
+
+\item[\field{parent}] An entry may have one or more sub-entries.
+Most of the sort methods will produce a hierarchical ordering that
+ensures that the sub-entries are listed immediately after their
+parent entry. The parent entry is identified by the \field{parent}
+field which should contain the parent's label.
+
+\begin{important}
+\bibgls\ sorts the parent and child entries using the same
+comparator. The sort methods listed
+in \tableref{tab:sortoptionsnosort} disregard the hierarchical
+level, which can result in child entries becoming detached from
+their parent entry. The other methods sort hierarchically using
+the same comparator but take the hierarchical level into account.
+\end{important}
+
+\end{description}
+
+Suppose you have a mixture of terms, abbreviations and symbols, then
+you might want to have three glossaries that are listed in the table
+of contents. In this case, you use the \field{type} field or the
+\field{type} resource option. The ordering of the glossaries is
+determined by the ordering of the \cs{printunsrtglossary}
+commands within the document. For example:
+\begin{codeenv}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type}}
+\end{codeenv}
+
+Suppose that your list of terms spans many pages and you feel it
+would be helpful to the reader to split it up into letter groups
+then you would need to run \bibgls\ with the \longarg{group} switch
+and use a glossary style that supports letter groups for that
+glossary. For example:
+\begin{codeenv}
+\cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}}
+\end{codeenv}
+
+Suppose that your list of symbols consists of pictographs, Latin characters
+and Greek characters and you want them grouped together
+in that order. Then you would use a separate
+\gls{GlsXtrLoadResources} for each block and assign your own custom
+group. This means ensuring that each \idx{resourceset} only selects
+the terms for that group. The simplest way of doing this is to
+have a separate \ext{bib} file for each set. For example:
+\begin{codeenv}
+\gls{glsxtrsetgrouptitle}\marg{pictographs}\marg{Pictographs}
+\gls{glsxtrsetgrouptitle}\marg{latinsymbols}\marg{Latin Characters}
+\gls{glsxtrsetgrouptitle}\marg{greeksymbols}\marg{Greek Characters}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[generalsymbols]{src},\comment{data in generalsymbols.bib}
+ \csopt[pictographs]{group},
+ \csopt[symbols]{type}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[latinsymbols]{src},\comment{data in latinsymbols.bib}
+ \csopt[latin]{group},
+ \csopt[symbols]{type}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[greeksymbols]{src},\comment{data in greeksymbols.bib}
+ \csopt[greek]{group},
+ \csopt[symbols]{type}
+}
+\end{codeenv}
+
+Suppose instead that you have many of these logical blocks and you
+want them ordered according to the block title. In this case you
+have a hierarchical glossary and you need to use the \field{parent}
+field. You then need to select an appropriate \idx{glossarystyle}.
+
+If you only want to have a single \ext{bib} file that contains all
+your entries and you want to share it across multiple documents then
+the most flexible approach is to use custom fields and entry types
+that can be aliased according to the needs of the
+\idxpl{resourceset}.
+
+For example, the file \filefmt{entries.bib}:
+\begin{codeenv}
+\comment{Encoding: UTF-8}
+\strut
+\atentryfmt{indexplural}\marg{latin,\field{text}=\marg{Latin character}}
+\atentryfmt{indexplural}\marg{greek,\field{text}=\marg{Greek character}}
+\atentryfmt{indexplural}\marg{pictograph}
+\strut
+\atentry{symbol}\marg{fx,
+ \field{name}=\marg{\cs{ensuremath}\marg{f(x)}},
+ \field{description}=\marg{function of \idx{mshiftchar}x\idx{mshiftchar}},
+ \fieldfmt{identifier}=\marg{latin}
+}
+\strut
+\atentry{symbol}\marg{f\idx{aposchar}x,
+ \field{name}={\cs{ensuremath}\marg{f\idx{aposchar}(x)}},
+ \field{description}=\marg{derivative of \cs{gls}\marg{fx}},
+ \fieldfmt{identifier}=\marg{latin}
+}
+\strut
+\atentry{symbol}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{ratio of circumference to diameter},
+ \fieldfmt{identifier}=\marg{greek}
+}
+\strut
+\atentry{symbol}\marg{heart,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{heartsuit}}},
+ \field{description}=\marg{heart},
+ \fieldfmt{identifier}=\marg{pictograph}
+}
+\strut
+\atentry{symbol}\marg{diamond,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{diamondsuit}}},
+ \field{description}=\marg{diamond},
+ \fieldfmt{identifier}=\marg{pictograph}
+}
+\strut
+\atentry{abbreviation}\marg{html,
+ \field{short}=\marg{html},
+ \field{long}=\marg{hypertext markup language},
+ \fieldfmt{identifier}=\marg{markuplanguage}
+}
+\strut
+\atentry{abbreviation}\marg{xml,
+ \field{short}=\marg{xml},
+ \field{long}=\marg{extensible markup language},
+ \fieldfmt{identifier}=\marg{markuplanguage}
+}
+\strut
+\atentry{entry}\marg{duck,
+ \field{name}=\marg{duck},
+ \field{description}=\marg{a waterbird with webbed feet},
+ \fieldfmt{identifier}=\marg{animal}
+}
+\strut
+\atentry{entry}\marg{parrot,
+ \field{name}=\marg{parrot},
+ \field{description}=\marg{mainly tropical bird with bright plumage},
+ \fieldfmt{identifier}=\marg{animal}
+}
+\end{codeenv}
+This has a custom field \fieldfmt{identifier}. This will be ignored
+by \bibgls\ unless defined or aliased in the document.
+
+Here's an example document that creates three glossary types (the
+default \code{main} glossary and the glossaries created with the
+\styopt{abbreviations} and \styopt{symbols} options). They are
+listed in the order of \cs{printunsrtglossary} and their titles are
+added to the table of contents.
+
+The custom \fieldfmt{identifier} fields are ignored for the
+main and abbreviation glossaries, but they are aliased for the
+symbols to the \field{group} field. Since I've split the symbols
+glossary into blocks with each block only containing entries that
+have the same \field{group} value, this isn't a problem. It also
+won't trigger a warning with \longarg{warn-non-bib-fields} as it's
+being aliased rather than set in the \ext{bib} file. The blocks
+appear in the same order as the corresponding \gls{GlsXtrLoadResources}
+commands. The title for each block is provided in the document
+using \gls{glsxtrsetgrouptitle}.
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
+\strut
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{
+ \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{pictograph}\marg{Pictographs}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=pictograph]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{latin}\marg{Latin Characters}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=latin]{match}}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{greek}\marg{Greek Characters}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{group}]{field-aliases},
+ \csopt[\field{group}=greek]{match}}
+\strut
+\cmd{begin}\marg{document}
+\cs{tableofcontents}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{treegroup}]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+In the above example document, the symbols list is divided into
+three groups, listed in the order: Pictographs, Latin characters and
+Greek characters. If you want these titles ordered alphabetically
+then you need a hierarchical structure instead. This can be obtained
+by aliasing the custom \fieldfmt{identifier} field to
+\field{parent}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt[topic]{stylemods},\styopt{abbreviations},\styopt{symbols}}\marg{glossaries-extra}
+\strut
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
+ \csopt[all]{selection},\csopt[entries]{src},\csopt[false]{save-locations}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entrytype=entry]{match}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},
+ \csopt[identifier=\field{parent}]{field-aliases},
+ \csopt[entrytype=symbol,entrytype=indexplural]{match}}
+\strut
+\cmd{begin}\marg{document}
+\cs{tableofcontents}
+\cs{printunsrtglossary}\oarg{\printglossopt[abbreviations]{type}}
+\cs{printunsrtglossary}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt[\glostyle{topic}]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+The style used for the symbols list is now \glostyle{topic} rather
+than \glostyle{treegroup}. This results in a slightly different
+appearance. You can select the most appropriate style according to
+your needs (see the gallery of predefined
+styles~\cite{glossarystylesgallery}). The topic ordering is now:
+Greek characters, Latin characters and Pictographs.
+
+\section{Defining a New Glossary}
+\label{sec:newglossary}
+
+Some of the examples in this manual use \ics{newglossary*} to define
+a new glossary type and some use \ics{newignoredglossary} or
+\ics{newignoredglossary*}. Why the starred forms and why define an
+\idx{ignoredglossary}?
+
+The base \styfmt{glossaries} package was originally designed to work
+with \idx!{makeindex}. Support for \idx!{xindy} was later added, but
+both require three files per glossary type: the transcript file
+(created by the indexing application), the file written by \LaTeX\
+(and input by the indexing application) and the file input by
+\LaTeX\ (and written by the indexing application). So when a new glossary
+is defined with \ics{newglossary}, this not only defines internal
+control sequences that store the list of entry labels associated
+with that glossary, the title and the entry format but also has to
+define internal control sequences that store the three file
+extensions. The starred form \cs{newglossary*} is just a shortcut
+that forms the extensions from the glossary label. For the purposes
+of \bibgls, this is simpler than the unstarred version since the
+extensions are now irrelevant as they are only applicable to
+\idx!{makeindex} and \idx!{xindy}. (Unless, of course, you are using
+a hybrid method with \styopt[alsoindex]{record}.)
+
+Since some users wanted the ability to define entries that were
+common enough to not be worth including in any glossary lists, the
+concept of an \idx{ignoredglossary} was introduced, defined with
+\cs{newignoredglossary}. This only requires an internal control
+sequence to store the list of entry labels associated with that
+glossary\footnote{All entries must be assigned to a glossary. If you
+don't use the \field{type} field the default is used.}\ and the
+associated internal command that governs the way that
+commands like \cs{gls} are displayed for that glossary type.
+Since this type of glossary has no associated files, it can't be
+used with \cs{printglossary} and therefore isn't included in the
+list of glossary labels that's iterated over by commands like
+\cs{printglossaries}. Since there's no glossary list (and therefore
+no targets), \cs{newignoredglossary} additionally disables hyperlinks for that
+glossary type, but it doesn't disable indexing. The indexing macro
+is still called, but because there's no associated file to write to,
+it has no effect. With \bibgls, the indexing is written to the
+\ext{aux} file and so does have an effect.
+
+Although \idxpl{ignoredglossary} can't be used with
+\cs{printglossary}, they can be used with \cs{printunsrtglossary},
+which is designed to work without any indexing, but you need to
+explicitly set the title in the optional argument to override the
+default. The \idxpl{ignoredglossary} still can't be used in
+\cs{printunsrtglossaries}, since they're not included in the list
+that this command iterates over.
+
+So \cs{newignoredglossary} is useful with \bibgls\ if you're happy
+to use \cs{printunsrtglossary} as it reduces the overall number of
+internal control sequences. Since there is now the possibility of
+targets (created within \cs{printunsrtglossary}), it's useful to
+have an \idx{ignoredglossary} that doesn't suppress the hyperlinks,
+which can be obtained with the starred form \ics{newignoredglossary*}
+provided by \styfmt{glossaries-extra}.
+
+Some resource options, such as \csopt{master}, \csopt{secondary} and
+\csopt{trigger-type}, need to ensure that a
+required glossary is defined. In this case, \bibgls\ uses
+\ics{provideignoredglossary*} in the \iext{glstex} file. If you
+haven't already defined that glossary in the document with \cs{newglossary*},
+you'll need to set the title in the optional argument of
+\cs{printunsrtglossary} if you don't want the default. The glossary
+won't be defined on the first run (if the definition is only
+provided in the \ext{glstex} file) but \cs{printunsrtglossary} will
+just give a warning if the type is undefined so it won't interrupt
+the document build.
+
+\section{Resource Sets}
+\label{sec:resourcesets}
+
+Each instance of \gls{glsxtrresourcefile} or
+\gls{GlsXtrLoadResources} in the document represents a \idx{resourceset}. Each
+\idx{resourceset} has one or more associated \iext{bib} files
+that provides the data for that set. Command line switches
+(\sectionref{sec:switches}) are applied to all \idxpl{resourceset}.
+Resource options (\sectionref{sec:resourceopts}) are only applied to
+that specific \idx{resourceset}. Each \idx{resourceset} is processed
+in stages:
+\begin{description}
+
+\item[Stage 1 (Initialisation)] Occurs after the \ext{aux} file has
+been read, this stage parses the resource option list and ensures
+options are valid and don't cause a conflict. The transcript will
+show the message
+\begin{alltt}
+Initialising resource \meta{resource-name}
+\end{alltt}
+at this point.
+
+\item[Stage 2 (Parsing)] All the \iext{bib} files associated with
+the \idx{resourceset} are parsed. Entry aliases (identified by
+\csopt{entry-type-aliases}) are performed. The
+\hyperref[sec:multientry]{multi-entry types}, such as
+\atentry{bibtexentry} and \atentry{progenitor}, spawn their
+associated primary entries. Preamble information (provided by
+\atentry{preamble}) is saved but is not interpreted at this stage.
+The transcript will show the message
+\begin{alltt}
+Parsing bib files for resource \meta{resource-name}
+\end{alltt}
+at this point.
+
+\item[Stage 3 (Processing Entries)]
+The transcript will show the message
+\begin{alltt}
+Processing resource \meta{resource-name}
+\end{alltt}
+at this point.
+For each entry that was found in
+the corresponding set of \ext{bib} files:
+\begin{itemize}
+\item Records are transferred to aliases if required (\csopt{alias-loc}).
+\item Field checks and modifications are performed:
+ \begin{itemize}
+ \item field aliases are performed (\csopt{field-aliases});
+
+ \item ignored fields (identified by \csopt{ignore-fields}) are
+ removed;
+
+ \item case-changes (for example, \csopt{short-case-change}) are
+ performed, except for the \field{name} field and fields identified
+ with \csopt{field-case-change};
+
+ \item suffixes are appended if required (for example, with
+ \csopt{short-plural-suffix});
+
+ \item field replications are made (\csopt{replicate-fields}),
+ and any of the above case-change or suffixes required
+ on the replicated fields are performed;
+
+ \item the \field{group} field is assigned if \csopt[\meta{label}]{group}
+ is set;
+
+ \item any variables (identified by \atentry{string}) are expanded
+ (if not already done in any of the previous steps);
+
+ \item any fields that have been identified by
+ \csopt{bibtex-contributor-fields} are converted;
+
+ \item any fields that have been identified with
+ \csopt{encapsulate-fields} are converted;
+
+ \item any fields that have been identified with
+ \csopt{encapsulate-fields*} are converted;
+
+ \item any fields that must be converted into a label form
+ (\csopt{labelify} or \csopt{labelify-list}) are processed;
+
+ \item any fields identified by \csopt{dependency-fields} are parsed for
+ dependent entries;
+
+ \item any fields whose value must be a label are interpreted
+ if \csopt{interpret-label-fields} is set;
+
+ \item the \field{parent} field is adjusted according to the label prefix
+ settings (\csopt{label-prefix} etc);
+
+ \item \ics{makefirstuc} protection is applied according to
+ \longarg{mfirstuc-protection} and \longarg{mfirstuc-math-protection};
+
+ \item fields are parsed for commands like \cs{gls} or
+ \cs{glshyperlink} and also checked for nested links if
+ \longarg{nested-link-check} is set;
+
+ \item the \field{description} field is adjusted according to
+ \csopt{strip-trailing-nopost};
+
+ \item end punctuation is checked according to
+ \csopt{check-end-punctuation};
+
+ \item \field{name} case-change is performed if
+ \csopt{name-case-change} is set;
+
+ \item if \csopt[true]{copy-alias-to-see} the \field{alias} is copied
+ to the \field{see} field;
+
+ \item general field case changes identified by
+ \csopt{field-case-change} are performed;
+
+ \item any fields that have been identified with
+ \csopt{interpret-fields} are replaced with their interpreted
+ values.
+ \end{itemize}
+\item The dual version (if appropriate) is created.
+\item Records are added to the entry's location list (or transferred
+to the dual\slash primary according to \csopt{combine-dual-locations}).
+\item The \field{type}, \field{category} and \field{counter} fields
+are set according to \csopt{type}, \csopt{dual-type},
+\csopt{category}, \csopt{dual-category}, \csopt{counter} and
+\csopt{dual-counter}.
+\item Filtering is applied (according to options like \csopt{match}
+but not \csopt{selection} or \csopt{limit}).
+\item Required fields are checked for existence.
+\item Dependencies are registered (if
+\csopt[recorded and deps]{selection} or \csopt[recorded and deps and
+see]{selection}).
+\item Any fields that have been identified by
+\csopt{date-time-fields}, \csopt{date-fields} or \csopt{time-fields}
+are converted.
+\end{itemize}
+If \csopt[recorded and deps and see]{selection} then any recorded
+entries that have been cross-referenced by an unrecorded entry, will
+register a dependency with the unrecorded entry. Finally,
+supplemental records are added to entries.
+
+\item[Stage 4 (Selection, Sorting, Writing)] Entries are selected
+from the list according to the \csopt{selection} setting, sorting is
+performed (if required), truncation is applied (if \csopt{limit} is
+set) and the \iext{glstex} file is written.
+The transcript will show the message
+\begin{alltt}
+Selecting entries for resource \meta{resource-name}
+\end{alltt}
+or (if \csopt{master})
+\begin{alltt}
+Processing master \meta{resource-name}
+\end{alltt}
+at this point.
+
+\end{description}
+
+Parent entries must always be in the same \idx{resourceset} as their
+child entries. (They may be defined in different \ext{bib} files as
+long as all those \ext{bib} files are listed in the same \csopt{src}.)
+Other forms of dependencies may be in a
+different \idx{resourceset} under certain circumstances. These types
+of dependencies are instances of commands such as \cs{gls} being
+found (for example, in the \field{description} field), or the
+cross-reference fields (\field{see}, \field{seealso} or
+\field{alias} or fields identified with \csopt{dependency-fields})
+in recorded entries that reference unrecorded entries.
+
+The \qt{cross-referenced by} dependencies enabled with
+\csopt[recorded and deps and see]{selection} (where an unrecorded
+entry references a recorded entry through the cross-reference
+fields) \emph{aren't supported} across \idxpl{resourceset} (even with
+\longarg{force-cross-resource-refs}).
+
+A \idx{crossresourceref} is a reference from a recorded entry provided in one
+\idx{resourceset} to an unrecorded entry in another \idx{resourceset}.
+Since
+the contents of each \idx{resourceset}['s] preamble must be
+processed before fields can be interpreted and one
+\idx{resourceset}['s] preamble may contain definitions that override
+another, \idxpl{crossresourceref} can't be supported if fields
+containing cross-referencing information need to be interpreted.
+
+The \idx{crossresourceref} mode determines whether or not \bibgls\
+can support \idxpl{crossresourceref}. If enabled, the message
+\begin{verbatim}
+Cross-resource references allowed.
+\end{verbatim}
+will be written to the transcript otherwise the message is
+\begin{verbatim}
+Cross-resource references disabled.
+\end{verbatim}
+The mode can only be enabled if the following condition is satisfied:
+\begin{itemize}
+\item the interpreter is off (\longarg{no-interpret}), or
+\item every \idx{resourceset} either doesn't have a preamble
+(\atentry{preamble}) or has \csopt[false]{interpret-preamble} set.
+\end{itemize}
+If you know the preamble contents won't cause a problem, you
+can force the \idxpl{crossresourceref} mode on with
+\longarg{force-cross-resource-refs}.
+
+If you don't use either \csopt[recorded and
+deps]{selection} or \csopt[recorded and deps and see]{selection}
+then the dependencies aren't picked up for that \idx{resourceset}
+(and so can't be cross-referenced from another \idx{resourceset}).
+
+Trails don't work with \idxpl{crossresourceref}. For example, if
+entry $A$ has been recorded and depends on entry $B$ that hasn't been
+recorded, then $B$ can be picked up from a different
+\idx{resourceset}, but if $A$ and $B$ are in the same
+\idx{resourceset} and $B$ is dependent on $C$ which is in a
+different \idx{resourceset} then $C$ won't be picked up if it hasn't
+been recorded because $B$ hasn't been recorded and is in a different
+\idx{resourceset}.
+
+If the \idx{crossresourceref} mode is enabled then stage~3 and
+stage~4 are processed in separate loops, otherwise they are
+processed in the same loop.
+
+\section{Indexing}
+
+The dual index entries such as \atentry{dualindexentry} (described in
+\sectionref{sec:dualentry}) are designed to provide a way of
+including an entry in a glossary (with a description) and also
+include the term (without the description) in an index. Additional
+terms that should only appear in the index can be defined with
+\atentry{index}. (See, for example, the \exfile{sample-multi1.tex}
+and \exfile{sample-multi2.tex} sample files.)
+
+Although \bibgls\ is designed to create indexes as well as glossary
+lists using the same interface (\cs{gls} etc), it is
+possible to have a mixture of \bibgls\ and \ics{index}. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{report}
+\strut
+\cmd{usepackage}\marg{makeidx}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
+\strut
+\cmd{makeindex}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\ics{glssetcategoryattribute}\marg{general}\marg{dualindex}\marg{true}
+\cs{glssetcategoryattribute}\marg{symbol}\marg{dualindex}\marg{true}
+\cs{glssetcategoryattribute}\marg{abbreviation}\marg{dualindex}\marg{true}
+\strut
+\cs{glssetcategoryattribute}\marg{general}\marg{indexname}\marg{hyperbf}
+\cs{glssetcategoryattribute}\marg{symbol}\marg{indexname}\marg{hyperbf}
+\cs{glssetcategoryattribute}\marg{abbreviation}\marg{indexname}\marg{hyperbf}
+\strut
+\cmd{begin}\marg{document}
+\cmd{chapter}\marg{Example}
+\cs{gls}\marg{bird}, \cs{gls}\marg{html}, \idx{mshiftchar}\cs{gls}\marg{v}\idx{mshiftchar} and \cs{glspl}\marg{goose}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{printindex}
+\cmd{end}\marg{document}
+\end{codeenv}
+If the document is called \filefmt{myDoc.tex} then the document
+build is:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+makeindex myDoc.idx
+pdflatex myDoc
+\end{verbatim}
+This requires an additional \LaTeX\ call between \bibgls\ and
+\idx{makeindex} since the entries must be defined before they can be
+indexed (and they can't be defined until \bibgls\ creates the
+associated \ext{glstex} files).
+
+Note that this method will use the \field{sort} value obtained by \bibgls\
+as the \meta{sort} part within
+\code{\cs{index}\marg{\meta{sort}@\meta{actual}}}.
+Be careful if you use \idx{makeindex} as this can result in Unicode
+characters appearing in the sort value, which \idx{makeindex}
+doesn't support.
+The \meta{actual} part is given by
+\code{\ics{glsentryname}\margm{label}}.
+(You can change the \meta{sort} and \meta{actual} parts by
+redefining \ics{glsxtrautoindexassignsort} and
+\ics{glsxtrautoindexentry}. See the \sty{glossaries-extra} manual
+for further details.)
+
+\section{Security}
+
+\TeX\ Live come with security settings
+\texmfcnf{openinany} and \texmfcnf{openoutany} that, respectively,
+govern read and write file access (in addition to the operating
+system's file permissions). \bibgls\ uses \idx{kpsewhich} to
+determine these values and honours them. MikTeX doesn't use these
+settings, so if these values are unset, \bibgls\ will default to
+\code{a} (any) for \texmfcnf{openinany} and \code{p} (paranoid) for
+\texmfcnf{openoutany}.
+
+The only external processes that are run by \bibgls\ are calls to
+\idx{kpsewhich} to check the security settings and locate files on
+\TeX's path. These are started with Java's \code{ProcessBuilder}
+class so there should be no issues with spaces or shell special characters
+in the argument. The \longarg{debug} switch will write the process
+call in the transcript file and will delimit the argument in the log
+with single quote characters for convenience, but the process isn't
+actually called in that way.
+
+\bibgls\ creates files with the extension \ext{glstex}, which are
+input by \gls{glsxtrresourcefile} (and therefore by the shortcut
+\gls{GlsXtrLoadResources}). This extension is fixed and is imposed
+by both \bibgls\ and \gls{glsxtrresourcefile}. \bibgls\ also creates
+a transcript file with the default extension \ext{glg}. This may be
+overridden by the \longarg{log-file} switch, but \bibgls\ always
+forbids write access to any file with the following extensions:
+\extfmt{tex}, \extfmt{ltx}, \extfmt{sty}, \extfmt{cls},
+\extfmt{bib}, \extfmt{dtx}, \extfmt{ins}, \extfmt{def} and
+\extfmt{ldf}.
+
+\section{Localisation}
+\label{sec:lang.xml}
+
+The messages produced by \bibgls\ are fetched from a resource file
+called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a
+valid \idx{IETF} language tag.
+
+The appropriate file is searched for in the following order, where
+\meta{locale} is the operating system's locale or the value supplied
+by the \longarg{locale} switch:
+\begin{enumerate}
+\item \meta{lang} exactly matches \meta{locale}.
+For example, my locale is \code{en-GB}, so \bibgls\ will first search
+for \filefmt{bib2gls-en-GB.xml}. This file doesn't exist, so it will
+try again.
+
+\item If \meta{locale} has an associated script, the
+next try is with \meta{lang} set to \meta{lang
+code}\code{-}\meta{script} where \meta{lang code} is the two
+letter ISO language code and \meta{script} is the script code.
+For example, if \meta{locale} is \code{sr-RS-Latn}
+then \bibgls\ will search for \filefmt{bib2gls-sr-Latn.xml} if
+\filefmt{bib2gls-sr-RS-Latn.xml} doesn't exist.
+
+\item The final attempt is with \meta{lang} set to just the two
+letter ISO language code. For example, \filefmt{bib2gls-sr.xml}.
+\end{enumerate}
+
+If there is no match, \bibgls\ will fallback on the English resource file
+\file{bib2gls-en.xml}.
+(Currently only \file{bib2gls-en.xml} exists as my language skills aren't up
+to translating it. Any volunteers who want to provide other language
+resource files would be much appreciated.)
+
+Note that if you use the \csopt[true]{loc-prefix} option, the
+textual labels (\qt{Page} and \qt{Pages} in English) will be taken
+from the resource file. In the event that the loaded resource file
+doesn't match the document language, you will have to manually set
+the correct translation (in English, this would be
+\csopt[Page\dcomma Pages]{loc-prefix}). The default definition of
+\gls!{bibglspassim} is also obtained from the resource file.
+
+\section{Conditional Document Build}
+
+If you are using a document build method that tries to determine
+whether or not \bibgls\ should be run, you can find the information
+by searching the \iext{aux} file for instances of
+\nosecdef{glsxtr@resource}
+Each instance corresponds to an instance of \gls{glsxtrresourcefile}
+where \meta{filename} is the base name of the \iext{glstex} file
+that \bibgls\ needs to create for this resource set. If the
+\meta{options} part is missing the \csopt{src} option, then
+\meta{filename} also indicates the base name for the \iext{bib} file.
+
+So the simplest check to determine if \bibgls\ needs to be run is to test
+if the \iext{aux} file contains \gls{glsxtr@resource}. For
+example, with \idx{arara} version 4.0:
+\begin{codeenv}
+\% arara: bib2gls if found("aux", "glsxtr@resource")
+\end{codeenv}
+A sophisticated method could check if
+\meta{filename}\ext{glstex} is missing or is older than the document
+\ext{tex} file for each instance of \gls{glsxtr@resource} found in
+the \ext{aux} file.
+
+It might also be possible, although far more complex, to
+parse the \meta{options} part in each instance of \gls{glsxtr@resource}
+for \csopt{src} and determine if the corresponding \ext{bib} file or
+files are newer than the \ext{tex} file.
+
+It's not possible to determine if the location lists require
+updating, just as it's not possible to do this for the
+\idx{toc}, list of figures, list of tables etc. (Or, if it could
+be implemented, the required code would make the document build far
+more complicated.)
+
+In general, the basic algorithm is:
+\begin{enumerate}
+\item Run \LaTeX\ (or PDF\LaTeX\ etc).
+
+\item If \gls{glsxtr@resource} is found in the \ext{aux} file then:
+
+ \begin{enumerate}
+ \item run \bibgls;
+ \item run \LaTeX\ (or PDF\LaTeX\ etc).
+ \end{enumerate}
+
+\item If \ics{@istfilename} is found in the \ext{aux} file then:
+
+ \begin{enumerate}
+ \item run \idx{makeglossaries} (or \idx{makeglossaries-lite});
+ \item run \LaTeX\ (or PDF\LaTeX\ etc).
+ \end{enumerate}
+
+\end{enumerate}
+This allows for the \styopt[alsoindex]{record} package option. See
+also
+\href{https://www.dickimaw-books.com/latex/buildglossaries}{\qt{Incorporating
+\idx[hyper=false,noindex]{makeglossaries} or
+\idx[hyper=false,noindex]{makeglossaries-lite} or \bibgls\ into
+the document build}}~\cite{buildglossaries}.
+
+\section{Manual Installation}
+
+If you are unable to install \bibgls\ through your \TeX\ package
+manager, you can install manually using the instructions below.
+Replace \meta{TEXMF} with the path to your local or home TEXMF tree
+(for example, \filefmt{\glstildechar/texmf}).
+
+Copy the files provided to the following locations:
+\begin{itemize}
+\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bib2gls.jar}
+(Java application.)
+\item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar}
+(Java application.)
+\item \meta{TEXMF}\filefmt{/scripts/bib2gls/texparserlib.jar}
+(Java library.)
+\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-en.xml}
+(English resource file.)
+\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf}
+(This document.)
+\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf}
+(Introductory guide.)
+\end{itemize}
+If you use the Unix \appfmt{man} command, copy the
+\filefmt{bib2gls.1} and \filefmt{convertgls2bib.1} files to the
+appropriate location.
+
+If you are using a Unix-like system, there are also bash scripts
+provided called \file{bib2gls.sh} and \file{convertgls2bib.sh}.
+Either copy then directly to somewhere on your path without the \iext{sh}
+extension, for example:
+\begin{verbatim}
+cp bib2gls.sh ~/bin/bib2gls
+cp convertgls2bib.sh ~/bin/convertgls2bib
+\end{verbatim}
+or copy the files to
+\meta{TEXMF}\filefmt{/scripts/bib2gls/} and create a
+symbolic link to them called just \filefmt{bib2gls} and
+\filefmt{convertgls2bib} from somewhere on
+your path, for example:
+\begin{verbatim}
+cp bib2gls.sh ~/texmf/scripts/bib2gls/
+cp convertgls2bib.sh ~/texmf/scripts/bib2gls/
+cd ~/bin
+ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls
+ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib
+\end{verbatim}
+The \file{texparserlib.jar} file isn't an application but is a
+library used by both \file{bib2gls.jar} and
+\file{convertgls2bib.jar}, and so needs to be in the same class path.
+(The library is in a separate
+\href{https://github.com/nlct/texparser}{GitHub
+repository}~\cite{texparser} as it's
+also used by some of my other applications.)
+
+Windows users can create a \iext{bat} file that works in a
+similar way to the bash scripts. To do this, create a file called
+\file{bib2gls.bat} that contains the following:
+\begin{verbatim}
+@ECHO OFF
+FOR /F "tokens=*" %%I IN ('kpsewhich --progname=bib2gls --format=texmfscripts
+bib2gls.jar') DO SET JARPATH=%%I
+java -Djava.locale.providers=CLDR,JRE -jar "%JARPATH%" %*
+\end{verbatim}
+Save this file to somewhere on your system's path.
+(Similarly for \filefmt{convertgls2bib}.) Note that \TeX\
+distributions for Windows usually convert \iext{jar} files to
+executables.
+
+You may need to refresh \TeX's database to ensure that
+\idx{kpsewhich} can find the \iext{jar} files.
+To test that the application has been successfully installed, open a
+command prompt or terminal and run the following command:
+\begin{verbatim}
+bib2gls --version
+convertgls2bib --version
+\end{verbatim}
+This should display the version information for both applications.
+
+\chapter{\texorpdfstring{\TeX}{TeX}\ Parser Library}
+\label{sec:texparserlib}
+
+The \bibgls\ application requires the \TeX\ Parser Library
+\file{texparserlib.jar}\footnote{\url{https://github.com/nlct/texparser}}
+which is used to parse the \iext{aux} and \iext{bib} files.
+
+With the \longarg{interpret} switch on (default), this library is
+also used to interpret the sort value when it contains a backslash
+\idx{escchar} or a tilde \idx{nbspchar} or a dollar symbol
+\idx{mshiftchar} or braces \idx{bgroupchar} \idx{egroupchar}
+(and when the \csopt{sort} option is not
+\optfmt{unsrt} or \optfmt{none} or \optfmt{use}).\footnote{The other
+special characters are omitted from the check: the comment symbol
+\idx{commentchar} is best avoided in field values, the subscript and
+superscript characters \idx{sbchar} and \idx{spchar} should
+either be encapsulated by \idx{mshiftchar} or by \cs{ensuremath}, which
+will be picked up by the check for \idx{mshiftchar} or
+\idx{escchar}, and the other special characters would
+indicate something too complex for the interpreter to handle.}
+
+The other cases that the interpreter is used for are:
+\begin{itemize}
+\item when \csopt{set-widest} is used to determine the width of
+the \field{name} field;
+\item if \csopt{labelify} or \csopt{labelify-list} are set the
+identified field values are first interpreted (if they contain
+\idx{escchar} \idx{bgroupchar} \idx{egroupchar}
+\idx{nbspchar} or \idx{mshiftchar}) before being converted to labels;
+\item if \csopt[true]{interpret-label-fields} is set and the
+\field{parent}, \field{category}, \field{type}, \field{group},
+\field{seealso} or \field{alias} fields contain \idx{escchar}
+or \idx{bgroupchar} or \idx{egroupchar} the interpreter is used
+since these fields must be just a label
+(other special characters aren't checked as they won't expand to
+characters allowed in a label).
+\end{itemize}
+
+Information in the \ext{aux} file is parsed for specific commands
+but the arguments of those commands are not interpreted so, for
+example, UTF-8 characters that occur in any resource options will
+need to be detokenized when using \sty{inputenc} to prevent
+expansion when they are written to the \ext{aux} file. (In some
+options, such as \csopt{sort-rule}, you can use \cs{glshex}\meta{hex}
+syntax to specify a UTF-8 character.)
+
+The \longarg{no-interpret} switch will turn off the interpreter, but
+the library will still be used to parse the \ext{aux} and \ext{bib}
+files. Note that the \field{see} field doesn't use the interpreter
+with \csopt[true]{interpret-label-fields} as
+it may legitimately contain \LaTeX\ code in the optional tag part
+(such as \cs{seealsoname}).
+
+The parser has a different concept of expansion to \TeX\
+and will expand some things that aren't expanded by \LaTeX\
+(such as \ics{MakeUppercase} and \ics{char}) and won't expand other commands
+that would be expanded by \LaTeX\ (such as commands defined
+in terms of complicated internals).
+
+If you get a \idx{StackOverflowError} while a field is being
+interpreted (with a long stack trace that contains repeated file names and
+line numbers) then it's likely you have an infinite loop. For
+example, this can be triggered if a field contains \csfmt{foo} that
+has been defined as:
+\begin{codeenv}
+\cs{def}\cmd{foo}\marg{\cmd{foo}}
+\end{codeenv}
+This will obviously also cause an error in the \LaTeX\ document as
+well (unless the document has a different definition that doesn't
+have this unbounded recursion).
+
+The \file{texparserlib.jar} library is not a \TeX\ engine and there
+are plenty of situations where it doesn't work. In particular, in
+this case it's being used in a fragmented context without knowing
+most of the packages used by the document or any custom commands or
+environments provided within the document.
+
+\bibgls\ can detect from the log file a small
+number of packages that the parser recognises. Note that in
+some cases there's only very limited support. For example,
+\isty{siunitx}'s \ics{si} command is recognised but other
+commands from that package aren't. See
+\longargpageref{list-known-packages} for further details.
+
+Since the parser doesn't have a full set of commands available
+within the \LaTeX\ document, when it encounters \ics{renewcommand} it
+won't check if the command is undefined. If the command isn't
+defined, it will simply behave like \cs{newcommand}. Whereas
+with \ics{providecommand} the parser will only define the command
+if it's unrecognised.
+
+The interpreter has its own internal implementation of the
+glossary-related commands listed in \tableref{tab:bibglsdefs}. These
+may be overridden by custom packages provided with the
+\longarg{custom-packages} switch. Note that commands that reference
+an entry, such as \cs{glsentryname}, aren't guaranteed to work
+across \idxpl{resourceset} and will only be able to look up field
+values that are known to \bibgls. (For example, the \field{name}
+field for abbreviations is typically set by the associated
+abbreviation style, which isn't available to \bibgls.)
+
+\begin{table}[htbp]
+\caption{Glossary-Related Commands Implemented by the \bibgls\ Interpreter}
+\label{tab:bibglsdefs}
+\setlength{\tabcolsep}{4pt}%
+\centering
+\tablelistcs{3}{glsxtrprovidecommand,bibglsuppercase,bibglslowercase,bibglsfirstuc,%
+bibglstitlecase,GlsXtrEnableInitialTagging,bibglscontributorlist,%
+bibglshyperlink,glshyperlink,bibglscontributor,bibglsdatetime,%
+bibglsdate,bibglstime,glsentryname,glsentrytext,glsentryshort,%
+glsentrylong,glsentryfirst,glsentrysymbol,glsentryuseri,%
+glsentryuserii,glsentryuseriii,glsentryuseriv,glsentryuserv,%
+glsentryuservi,glsentryplural,glsentryfirstplural,glsentryshortpl,%
+glsentrylongpl,glsentrysymbolplural,Glsentryname,Glsentrytext,%
+Glsentryshort,Glsentrylong,Glsentryfirst,Glsentrysymbol,%
+Glsentryuseri,Glsentryuserii,Glsentryuseriii,Glsentryuseriv,%
+Glsentryuserv,Glsentryuservi,Glsentryplural,Glsentryfirstplural,Glsentryshortpl,%
+Glsentrylongpl,Glsentrysymbolplural,bibglshashchar,bibglsunderscorechar,%
+bibglsdollarchar,bibglsampersandchar,bibglscircumchar,glsbackslash,glstildechar,glsopenbrace,glsclosebrace,glspercentchar,%
+glsxtrusefield,Glsxtrusefield,GLSxtrusefield,glsentrytitlecase,%
+glsxtrhiernamesep,glsxtrhiername,Glsxtrhiername,GlsXtrhiername,%
+GLSxtrhiername,GLSXTRhiername}
+\end{table}
+
+If a command isn't recognised, you can provide it in the
+\atentry{preamble} and use \ics{char} to map a symbol to the most
+appropriate Unicode character. For example, suppose your document
+loads a package that provides symbols for use on maps, such as
+\csfmt{Harbour}, \csfmt{Battlefield} and \csfmt{Stadium}, then you
+can provide versions of these commands just for \bibgls's
+use:\footnote{These commands won't work with PDF\LaTeX, as the
+\cs{char} values are too large, but they're fine for \bibgls.}
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}}
+\cs{providecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
+\cs{providecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}}
+\end{codeenv}
+Since these use \cs{providecommand}, they won't overwrite the
+document's version (provided these commands have been defined before
+\gls!{GlsXtrLoadResources}). Alternatively, you can instruct \bibgls\
+to not write the \atentry{preamble} contents to the resource file
+using \csopt[false]{write-preamble}. Now you can either sort these
+symbols by
+their Unicode values (\csopt[letter-case]{sort}) or provide a custom
+rule that recognises these Unicode characters (for example,
+\csopt[custom]{sort},
+\csopt[\cs{glshex}2694 \string< \cs{glshex}2693 \string< \cs{glshex}26BD]{sort-rule}).
+
+\TeX\ syntax can be quite complicated and, in some cases, far too
+complicated for simple \idxpl!{regex}. The \TeX\ parser library performs
+better than a simple pattern match, and that's the purpose of
+\file{texparserlib.jar} and why it's used by \bibgls\ (and by
+\idx{convertgls2bib}). When the \longarg{debug} mode is on, any
+warnings or errors triggered by the interpreter will be written to
+the transcript prefixed with \code{texparserlib:} (the results of
+the conversions will be included in the transcript as informational
+messages prefixed with \code{texparserlib:} even with
+\longarg{no-debug}).
+
+For example, suppose the \ext{bib} file includes:
+\begin{codeenv}
+\atentry{preamble}\marg{
+\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{set}}[1]\marg{\ics{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
+\cs{providecommand}\marg{\cmd{imaginary}}\marg{i}}}
+\strut
+\atentry{entry}\marg{M,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{mtx}\marg{M}},
+ \field{description}=\marg{a matrix}
+}
+\strut
+\atentry{entry}\marg{v,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cs{vec}\marg{v}\idx{mshiftchar}},
+ \field{text}=\marg{\cs{vec}\marg{v}},
+ \field{description}=\marg{a vector}
+}
+\strut
+\atentry{entry}\marg{S,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{set}\marg{S}},
+ \field{description}=\marg{a set}
+}
+\strut
+\atentry{entry}\marg{card,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{card}\marg{S}},
+ \field{description}=\marg{the cardinality of the set \idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}}
+}
+\strut
+\atentry{entry}\marg{i,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{imaginary}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{imaginary}},
+ \field{description}=\marg{square root of minus one (\idx{mshiftchar}\cmd{sqrt}\marg{-1}\idx{mshiftchar})}
+}
+\end{codeenv}
+(The empty group at the start of the \field{name} fields
+protects against the possibility that the \catattr{glossname}
+category attribute might be set to \optfmt{firstuc}, which
+automatically converts the first letter of the name to
+\idx{uppercase} when displaying the glossary. See also
+\longarg{mfirstuc-protection} and
+\longarg{mfirstuc-math-protection}.)
+
+None of these entries have a \field{sort} field so the \field{name}
+is used. If the entry type had been \atentry{symbol} instead,
+the fallback would be the entry's label.
+This means that with \atentry{symbol} instead of \atentry{entry}, and the default
+\csopt[sort]{sort-field}, and with
+\csopt[letter-case]{sort}, these entries will be defined in
+the order: \code{M}, \code{S}, \code{card}, \code{i}, \code{v} (since
+this is the case-sensitive letter order of the labels) whereas
+with \csopt[letter-nocase]{sort-field}, the order will be:
+\code{card}, \code{i}, \code{M}, \code{S}, \code{v} (since this
+is the case-insensitive letter order of the labels).
+
+However, with \atentry{entry}, the fallback field will be taken from
+the \field{name} which in the above example contains \TeX\ code, so
+\bibgls\ will use \file{texparserlib.jar} to interpret this code.
+The library has several different ways of writing the processed
+code. For simplicity, \bibgls\ uses the library's HTML output and
+then strips the HTML markup and trims any leading or trailing
+spaces. The library method that writes \idx{non-ASCII} characters
+using \qtt{\&x\meta{hex};} markup is overridden by \bibgls\ to just
+write the actual Unicode character, which means that the letter-based
+sorting options will sort according to the integer value \meta{hex}
+rather than the string \qtt{\&x\meta{hex};}.
+
+The interpreter is first passed the code provided with
+\atentry{preamble}:
+\begin{codeenv}
+\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
+\cs{providecommand}\marg{\cmd{imaginary}}\marg{i}
+\end{codeenv}
+(unless \csopt[false]{interpret-preamble}).
+This means that the provided commands are now recognised by the
+interpreter when it has to parse the fields later.
+
+In the case of the \code{M} entry in the example above, the
+code that's passed to the interpreter is:
+\begin{verbatim}
+{}$\mtx{M}$
+\end{verbatim}
+The transcript (\iext{glg}) file will show the results of the
+conversion:
+\begin{verbatim}
+texparserlib: {}$\mtx{M}$ -> M
+\end{verbatim}
+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 \idx!{uppercase} letter \qtt{M}, decimal value 77).
+
+For the \code{v} entry, the code is:
+\begin{verbatim}
+{}$\vec{v}$
+\end{verbatim}
+The transcript shows:
+\begin{alltt}
+texparserlib: \marg{}\$\ics{vec}\marg{v}\$ -> \usebox\varrow
+\end{alltt}
+So the \field{sort} value for this entry is set to \qtt{\usebox\varrow},
+which consists of two Unicode characters \hex{76}
+(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:
+\begin{verbatim}
+{}$\set{S}$
+\end{verbatim}
+The transcript shows:
+\begin{verbatim}
+texparserlib: {}$\set{S}$ -> S
+\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 \idx!{uppercase} letter \qtt{S}, decimal value~83).
+
+For the \code{card} entry, the code is:
+\begin{verbatim}
+{}$\card{S}$
+\end{verbatim}
+The transcript shows:
+\begin{verbatim}
+texparserlib: {}$\card{S}$ -> |S|
+\end{verbatim}
+So the \field{sort} value for this entry is set to \qtt{|S|}
+(the \textbar\ characters from the definition of \csfmt{card} provided
+in \atentry{preamble} have been included, but the
+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 \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}
+as the sort value.
+
+(Note that if \ics{vert} is used instead of \textbar\ then it would
+be converted into the mathematical operator \hex{2223} and result in
+a different order.)
+
+For the \code{i} entry, the code is:
+\begin{verbatim}
+{}$\imaginary$
+\end{verbatim}
+The transcript shows:
+\begin{verbatim}
+texparserlib: {}$\imaginary$ -> i
+\end{verbatim}
+So the \field{sort} value for this entry is set to \qtt{i}.
+If \csopt[false]{interpret-preamble} had been used, \csfmt{imaginary}
+wouldn't be recognised and would be discarded, leaving an empty sort
+value.
+
+This means that in the case of the default \csopt[sort]{sort-field} with
+\csopt[letter-case]{sort}, these entries will be defined in
+the order: \code{M} ($\mtx{M}$), \code{S} ($\set{S}$),
+\code{i} ($\imaginary$), \code{v} ($\vec{v}$) and
+\code{card} ($\card{S}$).
+In this case, the entries have been sorted according to
+the character codes. If you run \bibgls\ with \longarg{verbose}
+the decimal character codes will be included in the transcript.
+For this example:
+\begin{alltt}
+i -> 'i' [105]
+card -> '|S|' [124 83 124]
+M -> 'M' [77]
+S -> 'S' [83]
+v -> '\usebox\varrow' [118 8407]
+\end{alltt}
+
+The \longarg{group} option (in addition to \longarg{verbose})
+will place the letter group in
+parentheses before the character code list:
+\begin{alltt}
+i -> 'i' (i) [105]
+card -> '|S|' [124 83 124]
+M -> 'M' (M) [77]
+S -> 'S' (S) [83]
+v -> '\usebox\varrow' (v) [118 8407]
+\end{alltt}
+(Note that the \code{card} entry doesn't have a letter
+group since the vertical bar character isn't considered a
+letter.)
+
+If \csopt[letter-nocase]{sort} is used instead then, after conversion
+by the interpreter, the sort values will all be changed to
+\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
+\begin{alltt}
+i -> 'i' [105]
+card -> '|s|' [124 115 124]
+M -> 'm' [109]
+S -> 's' [115]
+v -> '\usebox\varrow' [118 8407]
+\end{alltt}
+With \longarg{group} (in addition to \longarg{verbose})
+the letter groups are again included:
+\begin{alltt}
+i -> 'i' (I) [105]
+card -> '|s|' [124 115 124]
+M -> 'm' (M) [109]
+S -> 's' (S) [115]
+v -> '\usebox\varrow' (V) [118 8407]
+\end{alltt}
+Note that the letter groups are \idx{uppercase} not \idx{lowercase}.
+Again the \code{card} entry doesn't have an associated
+letter group.
+
+If a locale-based sort is used, the ordering will follow the
+locale's alphabet rules. For example, with \csopt[en]{sort}
+(English, no region or variant), the order becomes:
+\code{card} ($\card{S}$), \code{i} ($\imaginary$),
+\code{M} ($\mtx{M}$), \code{S} ($\set{S}$) and
+\code{v} ($\vec{v}$). The transcript (with \longarg{verbose})
+shows the collation keys instead:
+\begin{alltt}
+i -> 'i' [0 92 0 0 0 0]
+card -> '|S|' [0 66 0 102 0 66 0 0 0 0]
+M -> 'M' [0 96 0 0 0 0]
+S -> 'S' [0 102 0 0 0 0]
+v -> '\usebox\varrow' [0 105 0 0 0 0]
+\end{alltt}
+Again the addition of the \longarg{group} switch will show
+the letter groups.\footnote{For more information on collation keys see the
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}{CollationKey}
+class in Java's API~\cite{collationkey}.}
+
+Suppose I add a new symbol to my \ext{bib} file:
+\begin{codeenv}
+\atentry{symbol}\marg{angstrom,
+ \field{name}=\marg{\ics{AA}},
+ \field{description}=\marg{\cs{AA} ngstr\ics{umlaut}om}
+}
+\end{codeenv}
+and I also use this entry in the document.\footnote{A better method
+is to use \sty{siunitx} instead.} Then with
+\csopt[en]{sort}, the order is: \code{card} ($\card{S}$),
+\code{angstrom} (\AA), \code{i} ($\imaginary$), \code{M}
+($\mtx{M}$), \code{S} ($\set{S}$), and \code{v} ($\vec{v}$).
+The \longarg{group} switch shows that the \code{angstrom} entry
+(\AA) has been placed in the \qt{A} letter group.
+
+However, if I change the locale to \csopt[sv]{sort}, the
+\code{angstrom} entry is moved to the end of the list and the
+\longarg{group} switch shows that it's been placed in the \qt{\AA}
+letter group.
+
+\label{locale.provider}If you are using Java~8, you can set the
+\code{java.locale.providers} property~\cite{javacldr} to use
+the \idx{CLDR} \idx{localeprovider}, which has more extensive
+support for locales than the native \idx{JRE}. For example:
+\begin{verbatim}
+java.locale.providers=CLDR,JRE
+\end{verbatim}
+This should be enabled by default for Java~9. The property
+can either be set in a script that runs \bibgls, for example,
+\begin{verbatim}
+java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@"
+\end{verbatim}
+(where \verb|$jarpath| is the path to the \file{bib2gls.jar}
+file and \verb|"$@"| is the argument list) or you can set the
+property as the default for all Java applications by adding
+the definition to the \code{JAVA\_TOOL\_OPTIONS} environment
+variable~\cite{javaoptions}.
+For example, in a bash shell:
+\begin{verbatim}
+export JAVA_TOOL_OPTIONS='-Djava.locale.providers=CLDR,JRE,SPI'
+\end{verbatim}
+or in Windows:
+\begin{verbatim}
+set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI
+\end{verbatim}
+
+\chapter{Command Line Options}
+\label{sec:switches}
+\setsecdepth{0}
+
+The syntax of \bibgls\ is:
+\begin{alltt}
+bib2gls \oargm{options} \meta{filename}
+\end{alltt}
+where \meta{filename} is the name of the \ext{aux} file. (The
+extension may be omitted.) Only one \meta{filename} is permitted.
+Available options are listed below.
+
+\argsection{help}
+
+Display the help message and quit.
+
+\argsection{version}
+
+Display the version information and quit.
+
+\argsection{debug}
+
+Switch on debugging mode. If \meta{n} is present, it must be a
+non-negative integer indicating the debugging level. If omitted 1 is
+assumed. This option also switches on the verbose mode. A value of 0
+is equivalent to \longargfmt{no-debug}.
+
+\argsection{no-debug}
+
+Switches off the debugging mode.
+
+\argsection{verbose}
+
+Switches on the verbose mode. This writes extra information to the
+terminal and transcript file.
+
+\argsection{no-verbose}
+
+Switches off the verbose mode. This is the default behaviour.
+Some messages are written to the terminal. To completely suppress
+all messages (except errors), switch on the silent mode.
+For additional information messages, switch on the verbose mode.
+
+\argsection{silent}
+
+Suppresses all messages except for errors that would normally be
+written to the terminal. Warnings and informational messages are
+written to the transcript file, which can be inspected afterwards.
+
+\argsection{locale}
+
+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
+same as the \iext{aux} file but with a \iext{glg} extension. Note that
+if you use \bibgls\ in combination with \idx{xindy} or
+\idx{makeindex}, you will need to change the transcript file name to
+prevent conflict.
+
+\argsection{dir}
+
+By default \bibgls\ assumes that the output files should be written
+in the current working directory. The input \iext{bib} files are assumed to be
+either in the current working directory or on \TeX's path (in which
+case \idx{kpsewhich} will be used to find them).
+
+If your \iext{aux} file isn't in the current working directory (for
+example, you have run \TeX\ with \shortargfmt{output-directory})
+then you need to take care how you invoke \bibgls.
+
+Suppose I have a file called \filefmt{test-entries.bib} that
+contains my entry definitions and a document called
+\filefmt{mydoc.tex} that selects the \ext{bib} file using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[test-entries]{src}}
+\end{codeenv}
+(\filefmt{test-entries.bib} is in the same directory as
+\filefmt{mydoc.tex}).
+If I compile this document using
+\begin{verbatim}
+pdflatex -output-directory tmp mydoc
+\end{verbatim}
+then the auxiliary file \filefmt{mydoc.aux} will be written to the
+\filefmt{tmp} sub-directory. The resource information is listed in
+the \ext{aux} file as
+\begin{codeenv}
+\gls{glsxtr@resource}\marg{\csopt[test-entries]{src}}\marg{mydoc}
+\end{codeenv}
+If I run \bibgls\ from the \filefmt{tmp} directory, then it won't
+be able to find the \filefmt{test-entries.bib} file (since it's in
+the parent directory).
+
+If I run \bibgls\ from the same directory as \filefmt{mydoc.tex}
+using
+\begin{verbatim}
+bib2gls tmp/mydoc
+\end{verbatim}
+then the \ext{aux} file is found and the transcript file is
+\filefmt{tmp/mydoc.glg} (since the default path name is the same as the
+\ext{aux} file but with the extension changed to \iext{glg}) but the
+output file \filefmt{mydoc.glstex} will be written to the current
+directory.
+
+This works fine from \TeX's point of view as it can find the
+\iext{glstex} file, but it may be that you'd rather the \ext{glstex}
+file was tidied away into the \filefmt{tmp} directory along with all
+the other files. In this case you need to invoke \bibgls\ with the
+\longargorshort{dir} option:
+\begin{verbatim}
+bib2gls -d tmp mydoc
+\end{verbatim}
+
+\argsection{interpret}
+
+Switch on the interpreter mode (default). See \sectionref{sec:texparserlib}
+for more details.
+
+\argsection{no-interpret}
+
+Switch off the interpreter mode. See \sectionref{sec:texparserlib}
+for more details about the interpreter.
+
+\argsection{no-break-space}
+
+The interpreter treats a tilde character \idx{nbspchar} as a non-breakable
+space (default).
+
+\argsection{break-space}
+
+The interpreter treats a tilde character \idx{nbspchar} as a normal
+space.
+
+\argsection{cite-as-record}
+
+Treat instances of \code{\ics{citation}\margm{label}} found in the
+\ext{aux} file as though it was actually an \idx{ignoredrecord}:
+\begin{codeenv}
+\gls{glsxtr@record}\margm{label}\marg{}\marg{\counter{page}}\marg{\encap{glsignore}}\marg{}
+\end{codeenv}
+Note that \code{\cs{citation}\marg{*}} will always be skipped. Use
+\csopt[all]{selection} to select all entries.
+This switch is most useful in conjunction with
+\atentrypageref{bibtexentry}.
+
+\argsection{no-cite-as-record}
+
+Don't check for instances of \ics{citation} in the \ext{aux} file
+(default).
+
+\argsection{warn-non-bib-fields}
+
+If any internal fields are found in the \ext{bib} file, this setting
+will issue a warning as their use can cause unexpected results.
+The fields checked for are those listed in Tables~\ref{tab:internalfields}
+and \ref{tab:baseinternalfields} with a few exceptions, notably
+\field{type} and \field{sort}. Ideally you shouldn't need to use
+\field{sort} as there should be an appropriate fallback set up to
+use if \field{sort} isn't set, such as the label for symbols or the
+name for terms or the short form for abbreviations.
+
+This is the default setting and was added as some users were
+confused over which fields could be used in the \ext{bib} file.
+The use of these fields can break \bibgls's normal behaviour and
+cause unexpected results.
+
+The check is performed before field aliasing, so it's possible to
+alias a field to an internal field, such as \field{group}, without
+triggering this warning. If you do this you need to make sure you
+have taken appropriate precautions to avoid unexpected results.
+
+\argsection{no-warn-non-bib-fields}
+
+Switches off the check for non-bib fields. If you use this option
+you need to make sure you have taken appropriate precautions to
+avoid unexpected results.
+
+\argsection{warn-unknown-entry-types}
+
+If any unknown entry types are found in the \ext{bib} file, \bibgls\
+will issue a warning with this option set (default).
+
+\argsection{no-warn-unknown-entry-types}
+
+This option will suppress the warning if an unknown entry types are
+found in the \ext{bib} file.
+
+\argsection{merge-wrglossary-records}
+
+For use with the \styopt{indexcounter} package option
+(\styfmt{glossaries-extra} v1.29+), this switch merges an entry's
+\counter{wrglossary} records for the same page location. This is the
+default setting. (See also \csopt{save-index-counter}.)
+
+\argsection{no-merge-wrglossary-records}
+
+Don't merge an entry's \counter{wrglossary} records. This means that you
+may end up with duplicate page numbers in the entry's location list,
+but they will link to different parts of the page.
+
+\argsection{merge-nameref-on}
+
+The \styopt[nameref]{record} package option (introduced to
+\sty{glossaries-extra} version 1.37) provides extra information
+in the record when indexing, obtained from \ics{@currentlabelname},
+\ics{@currentHref} and \ics{theHentrycounter}. Instead of writing the record as:
+\begin{codeenv}
+\format{glsxtr@record}
+\end{codeenv}
+the record is written as:
+\nosecdef{glsxtr@record@nameref}
+If \isty{hyperref} hasn't been loaded \meta{title} and \meta{href}
+will always be empty. The most reliable target is given by
+\code{\meta{counter}.\meta{hcounter}}, where \meta{counter} is the
+associated counter name and \meta{hcounter} is
+obtained from \cs{theHentrycounter}, which is set to the hyper
+target command \csfmt{theH}\meta{counter} during indexing. Since
+this information can't be included in the location when indexing
+with \idx!{makeindex} or \idx!{xindy}, the base \sty{glossaries}
+package tries to obtain a prefix from which the target name can be
+formed. This doesn't work if \csfmt{theH}\meta{counter} can't be
+formed from \meta{prefix}\csfmt{the}\meta{counter}, which results in
+broken links. Since \bibgls\ doesn't have the same restrictions, the
+actual target can be included in the record. You can then customize
+the document to choose whether to use \meta{href} (to link to the
+nearest anchor) or \meta{hcounter} to link to the place where the
+indexing counter was incremented.
+
+The \code{nameref} record will be written to the \idx{locationlist} using:
+\nosecdef{glsxtrdisplaylocnameref}
+The \meta{file} part will be empty for normal internal locations,
+and will be set to the corresponding file name for supplemental
+locations.
+
+With \sty{hyperref}, \meta{title} is initially empty. The \meta{href} will be
+\code{Doc-Start} at the start of the document and is updated
+globally on every instance of \ics{refstepcounter}. The
+\meta{title} is updated locally by certain commands, such as
+\ics{section} or \ics{caption}. This means that the \meta{href}
+may not always correspond to the \meta{title}, so using
+the \styopt[nameref]{record} package option can have unpredictable
+results if the \meta{title} is used as link text with \meta{href} as
+the target.
+
+For compactness, \bibgls\ tries to merge duplicate or near
+duplicate records. There are four possible rules that it will
+use for \code{nameref} records, identified by \meta{rule} in the
+\longarg{merge-nameref-on} switch:
+\begin{itemize}
+\item \optfmt{location}: merge records that match on the
+\meta{prefix}, \meta{counter} and \meta{location} parts (as regular
+records);
+\item \optfmt{title}: merge records that match on the \meta{counter}
+and \meta{title} parts;
+\item \optfmt{href}: merge records that match on the \meta{counter}
+and \meta{href} parts;
+\item \optfmt{hcounter}: merge records that match on the \meta{counter}
+and \meta{hcounter} parts.
+\end{itemize}
+The default \meta{rule} is \optfmt{hcounter}. Note that for all
+rules the \meta{counter} must match. See the \qt{Nameref Record}
+section of the \sty{glossaries-extra} user manual for further
+details.
+
+\argsection{force-cross-resource-refs}
+
+Force \idx{crossresourceref} mode on (see
+\sectionref{sec:resourcesets}).
+
+\argsection{no-force-cross-resource-refs}
+
+Don't force \idx{crossresourceref} mode on (default).
+The mode will be enabled if applicable (see
+\sectionref{sec:resourcesets}).
+
+\argsection{support-unicode-script}
+
+Text superscript (\ics{textsuperscript}) and subscript
+(\ics{textsubscript}) will use Unicode super/subscript characters
+if available (default). For example,
+\begin{codeenv}
+\cs{textsuperscript}\marg{(2)}
+\end{codeenv}
+will be converted to \code{\textsuperscript{(2)}}, which consists
+of: \hex{207D} (superscript left parenthesis)
+\hex{00B2} (superscript two) \hex{207E} (superscript right
+parenthesis). If the entire contents of the argument can't be
+represented by Unicode characters, the interpreter uses \verb|<sup>|
+and \verb|<sub>| markup, which is then stripped by \bibgls. For
+example,
+\begin{codeenv}
+\cs{textsuperscript}\marg{(2,3)}
+\end{codeenv}
+will be converted to
+\begin{verbatim}
+<sup>(2,3)</sup>
+\end{verbatim}
+(since there's no superscript comma). The markup is stripped leaving
+just \code{(2,3)}.
+
+Superscripts and subscripts in maths mode always use markup
+regardless of this setting. Some supported packages that use
+\idx{spchar} or \idx{sbchar} as shortcuts within an encapsulating
+command may internally use the same code as \cs{textsuperscript} and
+\cs{textsubscript}, in which case they will be sensitive to this
+setting.
+
+\argsection{no-support-unicode-script}
+
+Text superscript (\cs{textsuperscript}) and subscript
+(\cs{textsubscript}) won't use Unicode super/subscript characters.
+Note that if other commands are provided that expand to Unicode
+superscript or subscript characters, then they won't be affected by
+this setting. For example, if \csfmt{superiortwo} is defined as
+\begin{codeenv}
+\cs{providecommand}\marg{\cmd{superiortwo}}\marg{\charhex{B2}}
+\end{codeenv}
+then it will be interpreted as \hex{00B2} (superscript two) even if
+this setting is on.
+
+\argsection{list-known-packages}
+
+This option will list all the packages supported by the \TeX\ parser
+library and will then exit \bibgls. The results are divided into two
+sections: those packages that are searched for in the \iext{log}
+file and those packages that aren't searched for in the \iext{log}
+file but have some support available. Some of the support is very
+limited. Package options aren't detected.
+The transcript file is always searched for \isty{glossaries-extra}
+to ensure that the version is new enough to support \bibgls.
+
+Packages that fall into the first category are:
+\isty{amsmath}, \isty{amssymb}, \isty{bpchem}, \isty{fontenc},
+\isty{fontspec}, \isty{fourier},
+\isty{hyperref}, \isty{lipsum}, \isty{MnSymbol}, \isty{mhchem}, \isty{natbib},
+\isty{pifont}, \isty{siunitx} (limited), \isty{stix},
+\isty{textcase}, \isty{textcomp}, \isty{tipa}, \isty{upgreek} and
+\isty{wasysym}. (You can omit checking for specific packages with
+\longarg{ignore-packages}.) These are packages that provide commands
+that might be needed within entry fields. The check for
+\isty{fontspec} is to simply determine whether or not UTF-8
+characters are allowed in labels (for \csopt{labelify} and
+\csopt{labelify-list}).
+
+Packages that fall into the second category are:
+\isty{booktabs}, \isty{color}, \isty{datatool-base} (very limited),
+\isty{datatool} (very limited), \isty{etoolbox} (very limited), \isty{graphics},
+\isty{graphicx}, \isty{ifthen}, \isty{jmlrutils},
+\isty{mfirstuc-english}, \isty{probsoln}, \isty{shortvrb},
+and \isty{xspace}. These are less likely to be needed within fields
+and so aren't checked for by default. If they are needed then you
+can instruct \bibgls\ to support them with \longarg{packages}.
+
+Note that \sty{mfirstuc} is always automatically loaded, but
+\sty{mfirstuc-english} is not implemented unless explicitly
+requested with \code{\longarg{packages} mfirstuc-english}.
+
+If you're wondering about the selection, the \file{texparserlib.jar}
+library was originally written for another application that required
+support for some of them.
+
+\argsection{packages}
+
+Instruct the interpreter to assume the packages listed
+in \meta{list} have been used by the document.
+This option has a cumulative action so \code{\longarg{packages}
+"wasysym,pifont"} is the same as \code{\longarg{packages} wasysym
+\longarg{packages} pifont}.
+
+Note that there's only a limited number of packages supported by the
+\TeX\ parser library. This option is provided for cases where you're
+using a command from a package that the interpreter doesn't support
+but it happens to have the same name and meaning as a command from
+a package that the interpreter does support. You can also use it to
+provide support for known packages that aren't checked for when the
+\ext{log} file is parsed. If you want \bibgls\ to parse an
+unsupported package use \longarg{custom-packages}.
+
+\argsection{custom-packages}
+
+Instruct the interpreter to parse the package files identified in
+\meta{list}. The package files need to be quite simple. When this
+switch is used, the interpreter can recognise \ics{ProvidesPackage},
+\ics{DeclareOption} (and \ics{DeclareOption*}),
+\ics{ProcessOptions}, \ics{PackageError} and \ics{RequirePackage},
+but it can't deal with complicated code. In the case of
+\ics{RequirePackage}, support will also be governed by
+\longargfmt{custom-packages}. This option has a cumulative action.
+
+\argsection{ignore-packages}
+
+This option is cumulative. When the document \iext{log} file is
+parsed for known packages, \bibgls\ will skip the check for any
+listed in \meta{list}. Note that this option simply instructs
+\bibgls\ to ignore the package information in the log file. Any packages
+that are identified with \longarg{packages} will be passed to the
+interpreter if support is available, even if the package is also
+listed in \longargfmt{ignore-packages}. Note that
+unknown packages can't be included in the ignored \meta{list}.
+
+\argsection{mfirstuc-protection}
+
+Commands like \ics{Gls} use \ics{makefirstuc} provided by the
+\isty{mfirstuc} package. This command has limitations and one of the
+things that can break it is the use of a referencing command
+at the start of its argument. The \sty{glossaries-extra} package has
+more detail about the problem in the \qt{Nested Links} section of
+the user manual~\cite{glossaries-extra}. If a glossary field starts
+with one of these problematic commands, the recommended method (if
+the command can't be replaced) is to insert an empty group in front
+of it.
+
+For example, the following definition
+\begin{codeenv}
+\gls{newabbreviation}\marg{shtml}\marg{shtml}\marg{\ics{glsps}\marg{ssi} enabled \cs{glsps}\marg{short}\marg{html}}
+\end{codeenv}
+will cause a problem for \code{\cs{Gls}\marg{shtml}} on first use.
+The above example would be written in a \ext{bib} file as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{shtml,
+ \field{short}=\marg{shtml},
+ \field{long}=\marg{\cs{glsps}\marg{ssi} enabled \cs{glsps}\marg{html}}
+}
+\end{codeenv}
+The default \sty{mfirstuc} protection will automatically insert an empty
+group before \code{\cs{glsps}\marg{ssi}} when writing the definition
+in the \ext{glstex} file.
+
+The argument for this switch should either be a comma-separated list
+of fields or the keyword \code{all} (which indicates all fields).
+\bibgls\ will automatically insert an empty group at the start of
+the listed fields that start with a problematic command, and a
+warning will be written to the transcript. Unknown fields are
+skipped even if they're included in the list. An empty argument is
+equivalent to \longarg{no-mfirstuc-protection}. The default value is
+\code{all}.
+
+\argsection{no-mfirstuc-protection}
+
+Switches off the \isty{mfirstuc} protection mechanism described
+above.
+
+\argsection{mfirstuc-math-protection}
+
+This works in the same way as \longarg{mfirstuc-protection} but
+guards against fields starting with inline maths
+(\idx{mshiftchar}\ldots\idx{mshiftchar}). For example, if the
+\field{name} field starts with
+\code{\idx{mshiftchar}x\idx{mshiftchar}} and the glossary style
+automatically tries to convert the first letter of the name to
+\idx{uppercase}, then this will cause a problem.
+
+With \longarg{mfirstuc-math-protection} set, \bibgls\ will
+automatically insert an empty group at the start of the field and
+write a warning in the transcript. This setting is on by default.
+
+\argsection{no-mfirstuc-math-protection}
+
+Switches off the above.
+
+\argsection{nested-link-check}
+
+By default, \bibgls\ will parse certain fields for potential nested links.
+(See the section \qt{Nested Links} in the \sty{glossaries-extra}
+user manual~\cite{glossaries-extra}.)
+
+The default set of fields to check are: \field{name}, \field{text},
+\field{plural}, \field{first}, \field{firstplural}, \field{long},
+\field{longplural}, \field{short}, \field{shortplural} and
+\field{symbol}.
+
+You can change this set of fields using
+\longarg{nested-link-check} \meta{value} where \meta{value} may be
+\optfmt{none} (don't parse any of the fields) or a comma-separated
+list of fields to be checked.
+
+\argsection{no-nested-link-check}
+
+Equivalent to \longarg{nested-link-check} \optfmt{none}.
+
+\argsection{shortcuts}
+
+Some entries may reference another entry within a field, using
+commands like \ics{gls}, so \bibgls\ parses the fields for these
+commands to determine dependent entries to allow them to be selected
+even if they haven't been used within the document.
+The \styopt{shortcuts} package option provided by
+\styfmt{glossaries-extra} defines various synonyms, such as \ics{ac}
+which is equivalent to \ics{gls}. By default the value of the
+\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the
+\iext{aux} file. This then allows \bibgls\ to additionally search for
+those shortcut commands while parsing the fields.
+
+You can override the \styopt{shortcuts} setting using
+\longarg{shortcuts} \meta{value} (where \meta{value} may take
+any of the allowed values for the \styopt{shortcuts} package option),
+but in general there is little need to use this switch.
+
+\argsection{map-format}
+
+This sets up the rule of precedence for partial location
+matches (see \sectionref{sec:locationopts}). The argument may be
+a comma-separated list of \meta{map}\code{:}\meta{value} pairs.
+Alternatively, you can have multiple instances of
+\longarg{map-format} \meta{map}\dcolon\meta{value} which have a
+cumulative effect.
+
+For example,
+\begin{verbatim}
+bib2gls --map-format "emph:hyperbf" mydoc
+\end{verbatim}
+This essentially means that if there's a record conflict
+involving \encap{emph}, try replacing \encap{emph} with
+\encap{hyperbf} and see if that resolves the conflict.
+
+Note that if the conflict includes a range formation, the
+range takes precedence.
+The mapping tests are applied as the records are
+read. For example, suppose the records are listed in the \ext{aux}
+file as:
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{emph}}\marg{3}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hypersf}}\marg{3}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{3}
+\end{codeenv}
+and \bibgls\ is invoked with
+\begin{verbatim}
+bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc
+\end{verbatim}
+or
+\begin{verbatim}
+bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc
+\end{verbatim}
+then \bibgls\ will process these records as follows:
+\begin{enumerate}
+\item Accept the first record (\encap{emph}) since there's
+currently no conflict. (This is the first record for page~3 for the
+entry given by \code{gls.sample}.)
+\item The second record (\encap{hypersf}) conflicts
+with the existing record (\encap{emph}). Neither has
+the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ consults
+the mappings provided by \longargfmt{map-format}.
+\begin{itemize}
+\item The \encap{hypersf} format (from the new record) is mapped to
+\encap{hyperit},
+so \bibgls\ checks if the existing record
+has this format. In this case it doesn't (the format is
+\code{emph}). So \bibgls\ moves on to the next test:
+
+\item The \encap{emph} format (from the existing record) is mapped
+to \encap{hyperbf},
+so \bibgls\ checks if the new record has this format.
+In this case it doesn't (the format is \encap{hypersf}).
+
+Since the provided mappings haven't resolved this conflict,
+the new record is discarded with a warning. Note that there's
+no look ahead to the next record. (There may be other
+records for other entries also used on page~3 interspersed between these records.)
+\end{itemize}
+\item The third record (\encap{hyperbf}) conflicts
+with the existing record (\encap{emph}). Neither has
+the format \encap{glsnumberformat} or \encap{glsignore} so \bibgls\ again consults
+the mappings provided by \longargfmt{map-format}.
+\begin{itemize}
+\item The new record's \encap{hyperbf} format has no mapping provided,
+so \bibgls\ moves on to the next test:
+
+\item The existing record's \encap{emph} format has a mapping
+provided (\encap{hyperbf}). This matches the new record's format,
+so the new record takes precedence.
+
+This means that the location list ends up with the \encap{hyperbf}
+location for page~3.
+\end{itemize}
+\end{enumerate}
+
+If, on the other hand, the mappings are given as
+\begin{verbatim}
+--map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit"
+\end{verbatim}
+then all the three conflicting records (\encap{emph},
+\encap{hypersf} and \encap{hyperbf}) will end up being replaced
+by a single record with \encap{hyperit} as the format.
+
+Multiple conflicts will typically be rare as there's usually little
+reason for more than two or three different location formats within
+the same list. (For example, \encap{glsnumberformat} as the default
+and \encap{hyperbf} or \encap{hyperit} for a primary reference.)
+
+\argsection{group}
+
+The \styfmt{glossaries-extra} \styopt{record} package option
+automatically creates a new internal field called \field{group}. If the
+\longarg{group} switch is used with the default \csopt[auto]{group}
+option then, when sorting, \bibgls\ will try
+to determine the letter group for each entry and assign it to the
+\field{group} field. (Some \csopt{sort} options ignore this
+setting.) This value will be picked up by \ics{printunsrtglossary}
+if group headings are required (for example with the
+\glostyle{indexgroup} style) or if group separators are required
+(for example, the \glostyle{index} style with the default
+\styopt[false]{nogroupskip}). If you don't require grouping within
+the glossary, there's no need to use this switch. Note that this
+switch doesn't automatically select an appropriate glossary style.
+
+\begin{important}
+The \field{group} field should typically not be set in the \ext{bib}
+file and will trigger a warning if found. The explicit use of the
+\field{group} key will override \bibgls's normal group formation behaviour,
+which can cause unexpected results. The custom use of the
+\field{group} field requires some care. As a general rule, if you
+find yourself wanting to use the \field{group} field in the \ext{bib} file,
+then the chances are that what you actually have is a hierarchical
+glossary (list of topics) and what you really need is the \field{parent} field.
+Compare the example files \exfile{sample-textsymbols.tex} and
+\exfile{sample-textsymbols2.tex}. See also \sectionref{sec:logicaldivisions}.
+\end{important}
+There are eight types of groups:
+\begin{description}
+\item[\idx{lettergroup}] The first non-ignored character of the
+sort value is alphabetic. This type of group occurs when using the
+alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
+with the letter sort methods listed in
+\tableref{tab:sortoptionsletter} or with the letter-number sort
+methods listed in \tableref{tab:sortoptionsletternumber}. The group
+label is obtained from \gls!{bibglslettergroup}.
+
+\item[\idx{nonlettergroup} (or \idx{symbolgroup})]
+The first non-ignored character of all the sort values within this group
+are non-alphabetical. This type of group occurs when using the
+alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or
+with the letter sort methods listed in
+\tableref{tab:sortoptionsletter} or with the letter-number sort
+methods listed in \tableref{tab:sortoptionsletternumber}.
+The alphabetic sort methods ignore many punctuation
+characters, so an entry that has a non-alphabetic initial
+character in the sort value may actually be placed in a
+\idx{lettergroup}.
+The group label is obtained from \gls!{bibglsothergroup}.
+
+\item[\idx{emptygroup}] The sort value is empty when sorting with an
+alphabetical, letter or letter-number method, typically a
+result of the original value consisting solely of commands that \bibgls\
+can't interpret. The group label is obtained from \gls!{bibglsemptygroup}.
+
+\item[\idx{numbergroup}] The entries were sorted by one of the
+numeric comparisons listed in \tableref{tab:sortoptionsnumerical}.
+The group label is obtained from \gls!{bibglsnumbergroup}.
+
+\item[\idx{datetimegroup}] The entries were sorted by one of the date-time
+comparisons listed in \tableref{tab:sortoptionsdatetime} (where both
+date and time are present).
+The group label is obtained from \gls!{bibglsdatetimegroup}.
+
+\item[\idx{dategroup}] The entries were sorted by one of the date
+comparisons (where the time is omitted).
+The group label is obtained from \gls!{bibglsdategroup}.
+
+\item[\idx{timegroup}] The entries were sorted by one of the time
+comparisons (where the date is omitted).
+The group label is obtained from \gls!{bibglstimegroup}.
+
+\item[\idx{customgroup}] The group label is explicitly set either by
+aliasing a field (with \csopt{field-aliases}) or by using the
+\csopt[\meta{label}]{group} resource option. You will need to use
+\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the
+\meta{label} isn't the same as the title. Remember that the label
+can't contain any active characters, so you can't use non-ASCII
+characters in \meta{label} with \sty{inputenc} (but you can use
+non-ASCII alphanumerics with \sty{fontspec}).
+
+\end{description}
+
+The \idx{lettergroup} titles will typically have the first character
+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
+characters) or \idx{trigraph} (three characters).
+
+For example, if the sort rule recognises the digraph \qt{dz} as a
+letter, then it will be converted to \qt{Dz} for the group title.
+There are some exceptions to this. For example, the Dutch digraph
+\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated
+by the following line in the \langxml:
+\begin{verbatim}
+<entry key="grouptitle.case.ij">IJ</entry>
+\end{verbatim}
+If there isn't a \idx{grouptitle.case.lc} key (where
+\meta{lc} is the \idx!{lowercase} version), then only the first character
+will be converted to \idx{uppercase} otherwise the value supplied by the
+resource file is used. This resource key is only checked for
+the alphabetical comparisons listed in
+\tableref{tab:sortoptionsrule}. If the initial part of the sort
+value isn't recognised as a letter according to the sort rule, then
+the entry will be in a \idx{nonlettergroup} (even if the character is
+alphabetical).
+
+The letter (\tableref{tab:sortoptionsletter}) and letter-number
+(\tableref{tab:sortoptionsletternumber}) methods only select the
+first character of the sort value for the group. If the character is
+alphabetical\footnote{according to Java's
+\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 \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
+\glostyle{indexhypergroup}) require an extra run for the ordinary
+\cs{cs.makeglossaries} and \cs{makenoidxglossaries} methods. For
+example, for the document \filefmt{myDoc.tex}:
+\begin{verbatim}
+pdflatex myDoc
+makeglossaries myDoc
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+On the first \appfmt{pdflatex} call, there's no glossary. On the second
+\appfmt{pdflatex}, there's a glossary but the glossary must be
+processed to find the group information, which is written to the
+\iext{aux} file as
+\nosecdef{@gls@hypergroup}
+The third \appfmt{pdflatex} reads this information and is then able
+to create the navigation links.
+
+With \bibgls, if the \optfmt{type} is provided (through the
+\field{type} field or via options such as \csopt{type} and
+\csopt{dual-type}) then this information can be determined when
+\bibgls\ is ready to write the \iext{glstex} file, which means that
+the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know
+the glossary type then it will fallback on the original method
+which requires an extra \LaTeX\ run.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[main]{type}\comment{put these entries in the 'main' glossary}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib}
+ \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary}
+}
+\end{codeenv}
+Here the \csopt{type} is set and \bibgls\ can detect that
+\isty{hyperref} has been loaded, so if the \longargfmt{group} switch
+is used, then the group hyperlinks can be set (using
+\gls!{bibglshypergroup}). This means that the build process is
+just:
+\begin{verbatim}
+pdflatex myDoc
+bibtex --group myDoc
+pdflatex myDoc
+\end{verbatim}
+Note that this requires \isty{glossaries} v4.32+. If your version of
+\sty{glossaries} is too old then \bibgls\ can't override
+the default behaviour of \isty{glossary-hypernav}'s
+\ics{glsnavhypertarget}.
+
+If \isty{hyperref} isn't loaded or the \longargfmt{group} switch
+isn't used or the \field{type} isn't set or your version of
+\sty{glossaries} is too old, then the information can't be saved in
+the \ext{glstex} file.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib}
+\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib}
+\end{codeenv}
+This requires the build process:
+\begin{verbatim}
+pdflatex myDoc
+bibtex --group myDoc
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+because the group hyperlink information can't be determined by
+\bibgls, so it's best to always set the \optfmt{type} if you want
+hyper-group styles, and make sure you have an up-to-date version of
+\styfmt{glossaries} (and \styfmt{glossaries-extra}).
+
+\argsection{no-group}
+
+Don't automatically set the \field{group} field with
+\csopt[auto]{group} (default). The glossary won't have groups even if a
+group style, such as \glostyle{indexgroup}, is used (unless the
+\field{group} field is set to a custom value).
+
+\argsection{tex-encoding}
+
+\bibgls\ tries to determine the character encoding to use for the
+output files. If the document has loaded the \isty{inputenc} package then
+\bibgls\ can obtain the value of the encoding from the
+\iext{aux} file. This is then converted to a name
+recognised by Java. For example, \code{utf8} will be mapped to
+\code{UTF-8}. If the \isty{fontspec} package has been loaded,
+\styfmt{glossaries-extra} will assume the encoding is \code{utf8} and
+write that value to the \ext{aux} file.
+
+If neither package has been loaded, \bibgls\ will assume the \idx{JVM}['s]
+default encoding (identified by the \code{file.encoding} property). If this is
+incorrect or if \bibgls\ can't work out the appropriate mapping then you can
+specify the correct encoding using \longargfmt{tex-encoding} \meta{name} where
+\meta{name} is the encoding name (such as \code{UTF-8}).
+
+If you have a problem with non-ASCII characters not displaying
+correctly in your document:
+\begin{itemize}
+\item Check that the file encoding of your document \ext{tex} file (or files)
+has been correctly set by your text editor.
+\item Check that your document supports that encoding (for example,
+through the \isty{inputenc} package).
+\item Check \bibgls's transcript file (\ext{glg}) for the line that
+starts
+\begin{verbatim}
+TeX character encoding:
+\end{verbatim}
+This should be followed by the encoding used by \bibgls\ when
+creating the \ext{glstex} files. If this is incorrect use
+\longargfmt{tex-encoding}.
+\item Check that the encoding of the \ext{bib} files (set by your
+text editor or bibliographic management system) matches the encoding
+line in the \ext{bib} file or the \csopt{charset} resource option.
+\end{itemize}
+
+\argsection{no-expand-fields}
+
+By default, \gls{newglossaryentry} and similar commands expand field values
+(except for \field{name}, \field{symbol} and \field{description}).
+This is useful if constructing field values programmatically
+(for example in a loop) but can cause a problem if certain fragile
+commands are included in the field.
+
+The switch \longarg{no-expand-fields} makes \bibgls\ write
+\gls{glsnoexpandfields} to the \iext{glstex} file, which
+switches off the expansion. Since \bibgls\ is simply
+fetching the data from \iext{bib} files, it's unlikely
+that this automatic expansion is required and since it can
+also be problematic this option is on by default. You can
+switch it off with \longarg{expand-fields}.
+
+\argsection{expand-fields}
+
+Don't write \gls{glsnoexpandfields} to the \iext{glstex} file,
+allowing fields to expand when the entries are defined.
+Remember that this doesn't include the \field{name}, \field{symbol}
+or \field{description} fields, which need to have their
+expansion switched on with \gls{glssetexpandfield}
+before the entries are defined (that is, before using
+\gls!{GlsXtrLoadResources}).
+
+\argsection{trim-fields}
+
+Trim leading and trailing spaces from field values. For example,
+if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{entry}\marg{sample,
+ \field{name} = \marg{ sample },
+ \field{description} = \marg{
+ an example
+ }
+}
+\end{codeenv}
+This will cause spurious spaces. Using \longarg{trim-fields} will
+automatically trim the values before writing the \iext{glstex} file.
+
+\argsection{no-trim-fields}
+
+Don't trim any leading or trailing spaces from field values.
+This is the default setting.
+
+\argsection{record-count}
+
+Switch on record counting. This will ensure that when each entry
+is written to the \iext{glstex} file, \bibgls\ will additionally
+set the following fields
+\begin{itemize}
+\item \field{recordcount}: set to the total
+number of records found for the entry;
+\item \field{recordcount.counter}: set to the total
+number of records found for the entry for the given counter.
+\end{itemize}
+These fields can then be used with the \gls{rgls}-like commands.
+The default behaviour of
+\nosecdef{rgls}
+is to check the \field{recordcount} field against the \catattr{recordcount}
+attribute value. This attribute can be set with
+\nosecdef{GlsXtrSetRecordCountAttribute}
+where \meta{category list} is a comma-separated list
+of category labels and \meta{value} is a positive integer.
+If the value of the \field{recordcount} field is greater than
+\meta{value} then \gls{rgls} behaves like \ics{gls}, otherwise
+it does
+\nosecdef{rglsformat}
+instead.
+If the use of \gls{rglsformat} is triggered in this way,
+then \gls{rgls} writes a record to the \iext{aux} file
+with the \glsopt{format} set to \encap{glstriggerrecordformat}.
+This ensures that the record count is correct on the next run,
+but the record isn't added to the location list as
+\bibgls\ recognises it as a special \idx{ignoredrecord}.
+Note that the entry will still appear in the usual glossary unless
+you assign it to a different one with \csopt{trigger-type}.
+
+If the \catattr{recordcount} attribute hasn't been set
+\gls{rgls} behaves like \ics{gls}. (That is, \gls{rgls}
+uses the same internal command used by \ics{gls}.) You can use
+\ics{glsxtrenablerecordcount} to redefine \ics{gls}
+to \gls{rgls}, so that you can continue to use \ics{gls}
+without having to switch command name.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[abbrevs]{src},\comment{entries defined in abbrevs.bib}
+ \csopt[ignored]{trigger-type},
+ \csopt[abbreviation]{category}
+}
+\cs{glsxtrenablerecordcount}
+\gls{GlsXtrSetRecordCountAttribute}\marg{abbreviation}\marg{1}
+\end{codeenv}
+See the \sty{glossaries-extra} user manual~\cite{glossaries-extra}
+for further details.
+
+\argsection{no-record-count}
+
+Switch off record counting. (Default.)
+
+\argsection{record-count-unit}
+
+Automatically implements \longarg{record-count} and additionally
+sets the \field{recordcount.counter.location} fields.
+These fields can then be used with the \gls{rgls}-like
+commands.
+
+\argsection{no-record-count-unit}
+
+Switches off unit record counting. (Default.)
+Note that you need \longarg{no-record-count} to completely
+switch off record counting.
+
+\chapter{\iext{bib} Format}
+\label{sec:bib}
+\setsecdepth{1}
+
+\bibgls\ recognises certain entry types. Any unrecognised types will
+be ignored and a warning will be written to the transcript file.
+Entries are defined in the usual \ext{bib} format:
+\begin{codeenv*}
+\idx{atchar}\meta{entry-type}\marg{\meta{id},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\end{codeenv*}
+where \meta{entry-type} is the entry type (listed below),
+\meta{field-name-1}, \ldots, \meta{field-name-n} are the field names and
+\meta{id} is a unique label. The label can't contain any spaces or
+commas, and most special characters are forbidden. The hyphen character and
+some other punctuation characters are allowed by \bibgls, but you need to make
+sure that your document hasn't made them active. In general it's best to
+stick with alpha-numeric labels. The field values may be delimited by braces
+\margm{text} or double-quotes \code{\qtdelim{\meta{text}}}.
+
+The \csopt{label-prefix} option can be used to instruct \bibgls\ to
+insert prefixes to the labels (\meta{id}) when the data is read.
+Remember to use these prefixes when you reference the entries in the
+document, but don't include them when you reference them in the
+\ext{bib} file. There are some special prefixes that have a
+particular meaning to \bibgls: \qt{\idprefix{dual}} and
+\qt{\idprefix{extn}} where \meta{n} is a positive integer.
+In the first case, \idprefix{dual} references the dual element of a
+dual entry (see \atentry{dualentry}). This prefix will be
+replaced by the value of the \csopt{dual-prefix} option. The
+\idprefix{extn} prefix is used to reference an entry from a
+different set of resources (loaded by another
+\gls{GlsXtrLoadResources} command). This prefix is replaced by the
+corresponding element of the list supplied by \csopt{ext-prefixes},
+but this is only supported if the \idx{crossresourceref} mode is enabled
+(see \sectionref{sec:resourcesets}).
+
+In the event that the \field{sort} value falls back on the label,
+the original label supplied in the \ext{bib} file is used, not the
+prefixed label.
+
+\section{Encoding}
+\label{sec:bibencoding}
+
+Avoid \idx{non-ASCII} characters in the \meta{id} if your document uses the
+\isty{inputenc} package. (This isn't a problem for \XeLaTeX\ or
+\LuaLaTeX, but you still need to avoid special characters.)
+You can set the character \idx{encoding} in the \ext{bib} file using:
+\begin{codeenv}
+\idx{commentchar} Encoding: \meta{encoding-name}
+\end{codeenv}
+where \meta{encoding-name} is the name of the character encoding.
+For example:
+\begin{verbatim}
+% Encoding: UTF-8
+\end{verbatim}
+You can also set the encoding using the \csopt{charset} option,
+but it's simpler to include the above comment on the first line of
+the \ext{bib} file. (This comment is also searched for by JabRef
+to determine the encoding, so it works for both applications.)
+If you don't use either method \bibgls\ will
+have to search the entire \ext{bib} file, which is inefficient and
+you may end up with a mismatched encoding.
+
+\section{Comments}
+\label{sec:bibcomments}
+
+The original \ext{bib} file format as defined by \BibTeX\ doesn't
+have a designated comment character, but instead treats anything
+outside of \code{@\meta{entry}\margm{data}} as unwanted material
+that's ignored. This can catch out users who try to do something
+like:
+\begin{verbatim}
+%@misc{sample, title={Sample} }
+\end{verbatim}
+In this case, the percent character is simply discarded and the
+line is treated as:
+\begin{verbatim}
+@misc{sample, title={Sample} }
+\end{verbatim}
+Some applications that parse \ext{bib} files are less tolerant of
+unwanted material. In the case of \bibgls, the percent character is
+treated as a comment character and other unwanted material
+should be omitted. Avoid using comments within field values.
+Comments are best placed outside of entry definitions.
+
+The most common type of comment is the encoding comment, described
+above. \BibTeX's \entrydef{comment} is also supported by \bibgls\
+for general comments, but not for the encoding. For example, JabRef
+uses \atentryfmt{Comment} for metadata.
+\begin{codeenv}
+\atentryfmt{Comment}\marg{jabref-meta: databaseType:bib2gls;}
+\end{codeenv}
+
+\section{Fields}
+\label{sec:fields}
+
+Each entry type may have required fields, optional fields and
+ignored fields. These are set using a \keyvallist\ within
+\code{@\meta{entry-type}\marg{\meta{id},\meta{fields}}} in the
+\ext{bib} file. Most keys recognised by
+\gls{newglossaryentry} may be used as a field unless \bibgls\
+considers them an internal field (see below). In general, you
+shouldn't need to use the \field{sort} field.
+
+If an optional field is missing and \bibgls\ needs to access it for
+some reason, \bibgls\ will try to fallback on another value. The
+actual fallback value depends on the entry type. The most common
+fallback is that used if the \field{sort} field is missing, which is
+typically the case. This approach allows different entry types to
+have different fields used for sorting.
+
+Predefined fields for use in \ext{bib} files are listed in
+Tables~\ref{tab:fields}, \ref{tab:bib2glsfields},
+\ref{tab:prefixfields} and~\ref{tab:accsuppfields}. If you add any
+custom keys in your document using \ics{glsaddkey} or
+\ics{glsaddstoragekey}, those commands must be placed before the
+first use of \gls{GlsXtrLoadResources} to ensure that \bibgls\
+recognises them as a valid field name.
+
+Internal fields that may be assigned within the document (the
+\LaTeX\ assignment code having been written by \bibgls\ in the
+\iext{glstex} file) are listed in Table~\ref{tab:internalfields}.
+These typically shouldn't be used in the \ext{bib} file. Some of
+these fields can be set for a particular document using a resource
+option, such as \csopt{type} or \csopt{group}. With
+\longarg{warn-non-bib-fields} set, \bibgls\ will check for internal
+fields that can cause interference with its normal operations and
+will warn if any are found in the \ext{bib} file.
+
+There are also some fields that are set and used by
+\styfmt{glossaries} or \styfmt{glossaries-extra} listed in
+Table~\ref{tab:baseinternalfields} that aren't recognised by \bibgls.
+In most cases these fields don't have a designated key and are only
+intended for internal use by \bibgls\ or by the \styfmt{glossaries} or
+\styfmt{glossaries-extra} package. Note that the value of the \field{sort} field
+written to the \ext{bib} file doesn't always exactly match the sort
+value used by \bibgls\ (which is stored in \field{bib2gls@sort}).
+Any special characters found in the sort value are always substituted
+before writing the \ext{bib} file to avoid syntax errors.
+
+Any unrecognised fields will be ignored by \bibgls. This is more
+convenient than using \ics{input} or \ics{loadglsentries}, which
+requires all the keys used in the file to be defined, regardless of
+whether or not you actually need them in the document.
+
+Other entries can be cross-referenced using the \field{see},
+\field{seealso} or \field{alias} fields or
+by using commands like \ics{gls} or \ics{glsxtrp} in any of the
+recognised fields. These will automatically be selected if the
+\csopt{selection} setting includes dependencies, but you may need to
+rebuild the document to ensure the location lists are correct. Use
+of the \ics{glssee} command will create an \idx{ignoredrecord} and the
+\field{see} field will be set to the relevant information. If an
+entry has the \field{see} field already set, any instance of
+\ics{glssee} in the document for that entry will be appended to the
+\field{see} field (provided you have at least v1.14 of
+\sty{glossaries-extra}). In general, it's best just to use the
+\field{see} field and not use \ics{glssee}.
+
+The \field{seealso} key was only added to \sty{glossaries-extra}
+v1.16, but this field may be used with \bibgls\ even if you only
+have version 1.14 or 1.15. If the key isn't available,
+\code{\field{seealso}=\margm{xr-list}} will be treated as
+\code{\field{see}=\marg{[\ics{seealsoname}]\meta{xr-list}}} (the resource
+option \csopt{seealso} won't have an effect). You can't use both
+\field{see} and \field{seealso} for the same entry with \bibgls.
+Note that the \field{seealso} field doesn't allow for the optional
+\oargm{tag} part. If you need a different tag, either use \field{see}
+or change the definition of \ics{seealsoname} or
+\ics{glsxtruseseealsoformat}. Note that, unless you are using
+\idx{xindy}, \ics{glsxtrindexseealso} just does
+\ics{glssee}\oarg{\ics{seealsoname}}, and so will be treated as \field{see}
+rather than \field{seealso} by \bibgls. Again, it's better to just
+use the \field{seealso} field directly.
+
+You can identify an arbitrary field as containing a list of dependent entry
+labels with \csopt{dependency-fields}. This instructs \bibgls\ to parse the
+listed fields for dependencies in a similar manner to the \field{see} field,
+but it doesn't add any information to the cross-referencing part of the
+location list. The option may be used in combination with the \field{see} or
+\field{seealso} fields.
+
+\clearpage
+
+\printfields
+ {basefield,extrafield}
+ {Fields Provided by \styfmt{glossaries-extra}}
+ {tab:fields}
+
+\clearpage
+
+\printfields
+ {bib2glsfield}
+ {Fields Provided by \bibgls}
+ {tab:bib2glsfields}
+
+\printfields
+ {prefixfield}%
+ [Fields Provided by \styfmt{glossaries-prefix}]%
+ {Fields Provided by \isty{glossaries-prefix}}
+ {tab:prefixfields}
+
+\printfields
+ [%
+ Don't load \isty{glossaries-accsupp} directly (with \ics{usepackage})
+ when using \styfmt{glossaries-extra}. Load using the \styopt{accsupp}
+ package option instead.
+%\begin{codeenv}
+%\cs{usepackage}\oarg{\styopt{record},\styopt{accsupp}}\marg{glossaries-extra}
+%\end{codeenv}
+ ]%
+ {accessfield}%
+ [Fields Provided by \styfmt{glossaries-accsupp}]%
+ {Fields Provided by \isty{glossaries-accsupp}}
+ {tab:accsuppfields}
+
+\printfields
+ [%
+ You may define and assign \field{bibtextype} as a key (although it's more
+ likely to be aliased). Don't define any of the others listed in this
+ table, and don't use any of them in the \ext{bib} file. A possible
+ exception is the \field{type} field, but it's more flexible to set
+ that through a resource option. The explicit use of \field{group}
+ within a \ext{bib} file can cause unpredictable
+ results and is best set through a resource option or by \bibgls.
+ In general, you shouldn't need to set the \field{sort} field as
+ appropriate fallbacks should produce useful sort values.%
+ ]%
+ {internalfield}%
+ [Fields Set by \bibgls]%
+ {Fields Sometimes Set by \bibgls\ in the \iext{glstex} File}%
+ {tab:internalfields}
+
+\printfields
+ [%
+ Don't define any of these as keys and don't use any of them in the \ext{bib}
+ file.%
+ ]%
+ {baseinternalfield}%
+ [Internal Fields Set by \styfmt{glossaries} or \styfmt{glossaries-extra}
+ or \bibgls]%
+ {Internal Fields Set by \isty{glossaries} or \isty{glossaries-extra}
+ or \bibgls}%
+ {tab:baseinternalfields}
+
+\clearpage
+
+\section{Standard Entry Types}
+\label{sec:standardentry}
+
+\entrysection{string}
+
+The standard \atentry{string} is available and can be used to define
+variables that may be used in field values. Don't include braces or
+double-quote delimiters when referencing a variable. You can use
+\idx{stringconcat} to concatenate strings.
+For example:
+\begin{codeenv}
+\atentry{string}\marg{ssi=\marg{server-side includes}}
+\atentry{string}\marg{html=\marg{hypertext markup language}}
+\strut
+\atentry{abbreviation}\marg{shtml,
+ \field{short}=\qtdelim{shtml},
+ \field{long}=ssi \idx{stringconcat} \qtdelim{ enabled } \idx{stringconcat} html,
+ \field{see}=\marg{ssi,html}
+}
+\strut
+\atentry{abbreviation}\marg{html,
+ \field{short}=\qtdelim{html},
+ \field{long}=html
+}
+\strut
+\atentry{abbreviation}\marg{ssi,
+ \field{short}=\qtdelim{ssi},
+ \field{long}=ssi
+}
+\end{codeenv}
+Note the difference between \code{=\qtdelim{ssi}} (a field value delimited by
+double-quotes), the undelimited \code{=ssi} (a reference to the
+variable), the grouped \code{=\marg{ssi,html}} (a field value
+delimited by braces) and \code{ssi} the entry label.
+
+\entrysection{preamble}
+
+The standard \atentry{preamble} is available and can be used to
+provide command definitions used within field values.
+For example:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}}
+\strut
+\atentry{entry}\marg{matrix,
+ \field{name}=\marg{matrix},
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values, denoted \idx{mshiftchar}\cmd{mtx}\marg{M}\idx{mshiftchar}}
+}
+\end{codeenv}
+Alternatively you can use \ics{glsxtrprovidecommand} which behaves
+the same as \ics{providecommand} within the document but behaves
+like \ics{renewcommand} within \bibgls, which allows you to change
+\bibgls's internal definition of a command without affecting the
+definition within the document (if it's already been defined before
+the resource file is input). In general, it's best to just use
+\cs{providecommand}.
+
+The \TeX\ parser library used by \bibgls\ will parse the contents of
+\atentry{preamble} before trying to interpret the field value used
+as a fallback when \field{sort} is omitted (unless
+\csopt[false]{interpret-preamble} is set in the resource options).
+For example:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}}
+\strut
+\atentry{entry}\marg{S,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{set}\marg{S}},
+ \field{description}=\marg{a set}
+}
+\atentry{entry}\marg{card,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{card}\marg{S}},
+ \field{description}=\marg{the cardinality of \cs{gls}\marg{S}}
+}
+\end{codeenv}
+Neither entry has the \field{sort} field, so \bibgls\ has to fall
+back on the \field{name} field and, since this contains the special
+characters \idx{escchar} (backslash), \idx{mshiftchar} (maths
+shift), \idx{bgroupchar} (begin group) and
+\idx{egroupchar} (end group), the \TeX\ parser library is used to interpret it.
+The definitions provided by \atentry{preamble} allow \bibgls\ to
+deduce that the \field{sort} value of the \code{S} entry is just
+\code{S} and the \field{sort} value of the \code{card} entry is
+\verb"|S|" (see \sectionref{sec:texparserlib}).
+
+What happens if you also need to use these commands in the document?
+The definitions provided in \atentry{preamble} won't be available
+until the \iext{glstex} file has been created, which means the
+commands won't be defined on the first \LaTeX\ run.
+
+There are several approaches:
+\begin{enumerate}
+\item Just define the commands in the document. This means the
+commands are available, but \bibgls\ won't be able to correctly
+interpret the \field{name} fields.
+
+\item Define the commands in both the document and in
+\atentry{preamble}. For example:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{newcommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
+\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
+\end{codeenv}
+Alternatively:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
+\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}
+\end{codeenv}
+If the provided definitions match those given in the \ext{bib} file,
+there's no difference. If they don't match then in the first example
+the document definitions will take precedence (but the interpreter
+will use the \atentry{preamble} definitions) and in the second
+example the \atentry{preamble} definitions will take precedence.
+For example, the document may define \csfmt{card} as:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{card}}[1]\marg{\ics{vert}\cmd{set}\marg{\idx{param}1}\cs{vert}}
+\end{codeenv}
+
+\item Make use of \gls{glsxtrfmt} provided by \styfmt{glossaries-extra} which
+allows you to store the name of the formatting command in a field.
+The default is the \field{user1} field, but this can be changed to
+another field by redefining \ics{GlsXtrFmtField}.
+
+The \ext{bib} file can now look like this:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{set}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{card}}[1]\marg{|\cmd{set}\marg{\idx{param}1}|}}}
+\strut
+\atentry{symbol}\marg{S,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{set}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{set}\marg{S}},
+ \field{user1}=\marg{set},
+ \field{description}=\marg{a set}
+}
+\atentry{symbol}\marg{cardS,
+ \field{name}=\marg{\marg{}\idx{mshiftchar}\cmd{card}\marg{S}\idx{mshiftchar}},
+ \field{text}=\marg{\cmd{card}\marg{S}},
+ \field{user1}=\marg{card},
+ \field{description}=\marg{the cardinality of \cs{gls}\marg{S}}
+}
+\end{codeenv}
+Within the document, you can format \meta{text} using the formatting
+command provided in the \field{user1} field with:
+\nosecformatdef{glsxtrfmt}
+(which internally uses \ics{glslink}) or
+\nosecformatdef{glsxtrentryfmt}
+which just applies the appropriate formatting command to
+\meta{text}. Version 1.23+ of \sty{glossaries-extra} also provides a
+starred form of the linking command:
+\nosecformatdef{glsxtrfmt*}
+which inserts additional material inside the link text but outside
+the formatting command.
+
+If the entry given by \meta{label} hasn't been defined,
+then \gls!{glsxtrfmt} just does \meta{text} (followed by \meta{insert} for
+the starred version) and a warning is issued. (There's no warning
+if the entry is defined but the field hasn't been set.)
+The \meta{options} are as for \ics{glslink} but \ics{glslink} will
+actually be using:
+\begin{codeenv}
+\ics{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\cmd{}\meta{csname}\margm{text}\meta{insert}}
+\end{codeenv}
+where the default options \meta{def-options} are given by
+\ics{GlsXtrFmtDefaultOptions}. The default definition of this is
+just \code{noindex} which suppresses the automatic indexing or
+recording action. (See the \sty{glossaries-extra}
+manual~\cite{glossaries-extra} for further details.) The
+\meta{insert} part is omitted for the unstarred form.
+
+This means that the document doesn't need to actually provide
+\verb|\set| or \verb|\card| but can instead use, for example,
+\begin{codeenv}
+\gls{glsxtrfmt}\marg{S}\marg{A}
+\gls{glsxtrentryfmt}\marg{cardS}\marg{B}
+\end{codeenv}
+instead of:
+\begin{verbatim}
+\set{A}
+\card{B}
+\end{verbatim}
+The first \LaTeX\ run will simply ignore the formatting and produce
+a warning.
+
+Since this is a bit cumbersome to write, you can provide shortcut
+commands. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[my-data]{src}}
+\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{S}\marg{\idx{param}2}}
+\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardS}\marg{\idx{param}2}}
+\end{codeenv}
+Whilst this doesn't seem a great deal different from simply
+providing the definitions of \csfmt{set} and \csfmt{card} in the
+document, this means you don't have to worry about remembering
+the names of the actual commands provided in the \ext{bib} file
+(just the entry labels) and the use of \gls{glsxtrfmt} will
+automatically produce a hyperlink to the glossary entry if the
+\isty{hyperref} package has been loaded.
+\end{enumerate}
+
+Here's an alternative \ext{bib} that defines entries with a term, a
+description and a symbol:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\cmd{setfmt}\marg{\idx{param}1}|}}}
+\strut
+\atentry{entry}\marg{set,
+ \field{name}=\marg{set},
+ \field{symbol}=\marg{\cmd{setfmt}\marg{S}},
+ \field{user1}=\marg{setfmt},
+ \field{description}=\marg{collection of values}
+}
+\atentry{entry}\marg{cardinality,
+ \field{name}=\marg{cardinality},
+ \field{symbol}=\marg{\cmd{cardfmt}\marg{S}},
+ \field{user1}=\marg{cardfmt},
+ \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}}
+}
+\end{codeenv}
+I've changed the entry labels and the names of the formatting commands.
+The definitions in the document need to reflect the change in label
+but not the change in the formatting commands:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{gset}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}}
+\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}}
+\end{codeenv}
+
+Here's another approach that allows for a more complicated argument
+for the cardinality. (For example, if the argument is an expression
+involving set unions or intersections.)
+The \ext{bib} file is now:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{setfmt}}[1]\marg{\cs{mathcal}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{cardfmt}}[1]\marg{|\idx{param}1|}}}
+\strut
+\atentry{entry}\marg{set,
+ \field{name}=\marg{set},
+ \field{symbol}=\marg{\cmd{setfmt}\marg{S}},
+ \field{user1}=\marg{setfmt},
+ \field{description}=\marg{collection of values}
+}
+\atentry{entry}\marg{cardinality,
+ \field{name}=\marg{cardinality},
+ \field{symbol}=\marg{\cmd{cardfmt}\marg{\cmd{setfmt}\marg{S}}},
+ \field{user1}=\marg{cardfmt},
+ \field{description}=\marg{the number of elements in the \cs{gls}\marg{set} \idx{mshiftchar}\cs{glssymbol}\marg{set}\idx{mshiftchar}}
+}
+\end{codeenv}
+This has removed the \csfmt{setfmt} command from the definition of
+\csfmt{cardfmt}. Now the definitions in the document are:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
+\cs{newcommand}\marg{\cmd{gcard}}[2][]\marg{\gls{glsxtrfmt}\oarg{\idx{param}1}\marg{cardinality}\marg{\idx{param}2}}
+\end{codeenv}
+This allows for code such as:
+\begin{verbatim}
+\[ \gcard{\gset{A} \cap \gset{B}} \]
+\end{verbatim}
+which will link back to the \code{cardinality} entry in the
+glossary and avoids any hyperlinking with \csfmt{gset}.
+Alternatively to avoid links with \csfmt{gcard} as well:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{gset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
+\cs{newcommand}\marg{\cmd{gcard}}[1]\marg{\gls{glsxtrentryfmt}\marg{cardinality}\marg{\idx{param}1}}
+\end{codeenv}
+Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands,
+but their actual definitions are determined in the \ext{bib} file.
+
+\section{Single Entry Types}
+\label{sec:singleentry}
+
+The entry types described in this section create a single glossary
+definition per entry (from \styfmt{glossaries-extra}'s point of view).
+For example:
+\begin{codeenv}
+\atentry{entry}\marg{matrix,
+ \field{name}=\marg{matrix},
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values}
+}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{matrix}\comment{label}
+\marg{\comment{fields}
+ \field{name}=\marg{matrix},
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values}
+}
+\end{codeenv}
+The \csopt{secondary} option allows the creation of a fake glossary
+with the entry labels in its internal list in a different order.
+This means that the same data can be displayed in two separate lists
+without duplicating the resources required by each glossary entry.
+
+\Sectionref{sec:dualentry} describes \bibgls\ entry types
+that create two separate (but related) \styfmt{glossaries-extra}
+definitions per \ext{bib} entry.
+
+\entrysection{entry}
+
+Regular terms are defined by the \atentry{entry} field. This requires the
+\field{description} field and either \field{name} or \field{parent}.
+For example:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{mtx}}[1]\marg{\cs{boldsymbol}\marg{\idx{param}1}}}}
+\strut
+\atentry{entry}\marg{matrix,
+ \field{name}=\marg{matrix},
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values, denoted \cs{gls}\marg{M}},
+ \field{seealso}=\marg{vector}
+}
+\strut
+\atentry{entry}\marg{M,
+ \field{name}=\marg{\cs{ensuremath}\marg{M}},
+ \field{description}=\marg{a \cs{gls}\marg{matrix}}
+}
+\strut
+\atentry{entry}\marg{vector,
+ \field{name} = \qtdelim{vector},
+ \field{description} = \marg{column or row of values, denoted \cs{gls}\marg{v}},
+ \field{seealso}=\marg{matrix}
+}
+\strut
+\atentry{entry}\marg{v,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{vec}\marg{v}}},
+ \field{description}=\marg{a \cs{gls}\marg{vector}}
+}
+\end{codeenv}
+
+If the \field{sort} field is missing the default is obtained from
+the \field{name} field (unless overridden by
+\csopt{entry-sort-fallback}). For hierarchical entries, if the
+\field{name} field is omitted it will be obtained from the parent's
+\field{name}.
+
+Terms defined using \atentry{entry} will be written to the output
+(\ext{glstex}) file using the command \gls!{bibglsnewentry}.
+
+\entrysection{symbol}
+
+The \atentry{symbol} entry type is much like \atentry{entry}, but it's
+designed specifically for symbols, so in the previous example, the
+\code{M} and \code{v} terms would be better defined using the
+\atentry{symbol} entry type instead. For example:
+\begin{codeenv}
+\atentry{symbol}\marg{M,
+ \field{name}=\marg{\cs{ensuremath}\marg{M}},
+ \field{description}=\marg{a \cs{gls}\marg{matrix}}
+}
+\end{codeenv}
+
+The required fields are \field{name} or \field{parent}. The
+\field{description} field is required if the \field{name} field is
+missing. If the \field{sort} field is omitted, the default sort is
+given by the entry label (unless overridden by
+\csopt{symbol-sort-fallback}). Note that this is different from
+\atentry{entry} where the sort defaults to \field{name} if omitted.
+
+Terms that are defined using \atentry{symbol} will be written to
+the output file using the command \gls!{bibglsnewsymbol}.
+
+\entrysection{number}
+
+The \atentry{number} entry type is like \atentry{symbol}, but it's for
+numbers. The numbers don't have to be explicit digits and may have a
+symbolic representation. There's no real difference between the
+behaviour of \atentry{number} and \atentry{symbol} except that terms
+defined using \atentry{number} will be written to the output file
+using the command \gls!{bibglsnewnumber}.
+
+For example, the file \filefmt{constants.bib} might define
+mathematical constants like this:
+\begin{codeenv}
+\atentry{number}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
+ \field{description}=\marg{the ratio of the length of the circumference
+ of a circle to its diameter},
+ \field{user1}=\marg{3.14159}
+}
+\strut
+\atentry{number}\marg{e,
+ \field{name}=\marg{\cs{ensuremath}\marg{e}},
+ \field{description}=\marg{base of natural logarithms},
+ \field{user1}=\marg{2.71828}
+}
+\end{codeenv}
+This stores the approximate value in the \field{user1} field. This
+can be used to sort the entries in numerical order according to the
+values rather than the symbols:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[constants]{src},\comment{constants.bib}
+ \csopt[number]{category},\comment{set the category for all selected entries}
+ \csopt[double]{sort},\comment{numerical double-precision sort}
+ \csopt[user1]{sort-field}\comment{sort according to 'user1' field}
+}
+\end{codeenv}
+The \csopt[number]{category} option makes it easy to adjust the
+glossary format to include the \field{user1} field:
+\begin{codeenv}
+\ics{glsdefpostdesc}\marg{number}\marg{\comment{}
+ \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+
+\entrysection{index}
+
+The \atentry{index} entry type is designed for entries that don't
+have a description. Only the label is required. If \field{name} is
+omitted, it's assumed to be the same as the label, even if
+\field{parent} is present. (Note this is different to the fallback
+behaviour of \atentry{entry}, which fetches the name from the parent
+entry.) If the name contains any characters that can't be used in
+the label, you must use the \field{name} field. If the \field{sort}
+field is missing the default is obtained from the \field{name}.
+Note that the \atentry{index} entry type is \emph{not} governed by
+\csopt{entry-sort-fallback}. This allows \atentry{index} and
+\atentry{entry} to have different fallbacks if the \field{sort}
+field is missing.
+
+Example:
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\atentry{index}\marg{goose,\field{plural}=\marg{geese}}
+\atentry{index}\marg{sealion,\field{name}=\marg{sea lion}}
+\atentry{index}\marg{facade,\field{name}=\marg{fa\ics{c}\marg{c}ade}}
+\end{codeenv}
+
+Terms that are defined using \atentry{index} will be written to the output
+file using the command \gls!{bibglsnewindex}.
+
+\entrysection{indexplural}
+
+The \atentry{indexplural} entry type is similar to the
+\atentry{index} entry type except that the \field{name} field, if
+missing, is obtained from the \field{plural} field. If the
+\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. (As with \atentry{index}, \atentry{indexplural}
+is \emph{not} governed by \csopt{entry-sort-fallback}.)
+All fields are optional. For example:
+\begin{codeenv}
+\atentry{indexplural}\marg{goose,
+ \field{plural} = \marg{geese}
+}
+\strut
+\atentry{indexplural}\marg{duck}
+\strut
+\atentry{indexplural}\marg{chateau,
+ \field{text} = \marg{ch\ics{cs.circum}ateau},
+ \field{plural} = \marg{ch\cs{cs.circum}ateaux}
+}
+\end{codeenv}
+This is equivalent to:
+\begin{codeenv}
+\atentry{indexplural}\marg{goose,
+ \field{name} = \marg{geese},
+ \field{text} = \marg{goose},
+ \field{plural} = \marg{geese}
+}
+\strut
+\atentry{indexplural}\marg{duck,
+ \field{name} = \marg{ducks},
+ \field{text} = \marg{duck},
+ \field{plural} = \marg{ducks}
+}
+\strut
+\atentry{indexplural}\marg{chateau,
+ \field{name} = \marg{ch\cs{cs.circum}ateaux},
+ \field{text} = {ch\cs{cs.circum}ateau},
+ \field{plural} = {ch\cs{cs.circum}ateaux}
+}
+\end{codeenv}
+
+Terms that are defined using \atentry{indexplural} will be written to the output
+file using the command \gls!{bibglsnewindexplural}.
+
+\entrysection{abbreviation}
+
+The \atentry{abbreviation} entry type is designed for abbreviations.
+The required fields are \field{short} and \field{long}. If the
+\field{sort} key is missing, \bibgls\ will use the field given by
+\csopt{abbreviation-sort-fallback}, which defaults to the \field{short} field.
+(If you want an equivalent of \gls!{newdualentry}, use
+\atentry{dualabbreviationentry} instead.)
+
+If you use \csopt[name]{sort-field} (rather than the default
+\csopt[sort]{sort-field}), then the fallback for the
+\field{name} field is always the \field{short} field, regardless of
+the \csopt{abbreviation-sort-fallback} setting, unless you use
+\csopt{abbreviation-name-fallback} to change the fallback for the
+\field{name} field.
+
+Note that you must set the abbreviation style before loading the
+resource file to ensure that the abbreviations are defined
+correctly, however \bibgls\ has no knowledge of the abbreviation
+style so it doesn't know if the \field{description} field must be
+included or if the default \field{sort} value isn't simply the value
+of the \field{short} field.
+
+You can instruct \bibgls\ to sort by the \field{long} field instead
+using \csopt[long]{abbreviation-sort-fallback}. You can also tell \bibgls\ to
+ignore certain fields using \csopt{ignore-fields}, so you can
+include a \field{description} field in the \ext{bib} file if
+you sometimes need it, and then instruct \bibgls\ to ignore it when
+you don't want it.
+
+For example:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{hypertext markup language},
+ \field{description} = \marg{a markup language for creating web pages}
+}
+\end{codeenv}
+If you want the \abbrstyle{long-noshort-desc} style, then you can put
+the following in your document (where the \ext{bib} file is called
+\filefmt{entries-abbrv.bib}):
+\begin{codeenv}
+\ics{setabbreviationstyle}\marg{long-noshort-desc}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
+ \csopt[long]{abbreviation-sort-fallback}}
+\end{codeenv}
+Whereas, if you want the \abbrstyle{long-short-sc} style, then you can
+instead do:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-sc}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},\csopt[description]{ignore-fields}}
+\end{codeenv}
+or to convert the short value to \idx{uppercase} and use the
+\abbrstyle{long-short-sm} style instead:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-sm}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
+ \csopt[uc]{short-case-change},\comment{convert short value to upper case}
+ \csopt[description]{ignore-fields}}
+\end{codeenv}
+
+Case-changing can be applied with \csopt{short-case-change} to
+convert the case of the \field{short} field, as illustrated above.
+If you use a style that obtains the \field{description} from the
+\field{long} form, but you want to apply a case-change to the
+\field{description} field with \csopt{description-case-change}, then
+you can copy the \field{long} field to the \field{description} with
+\csopt[\field{long}=\field{description}]{replicate-fields}.
+
+For example, if \filefmt{entries-abbrv.bib} contains:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+then the document may include:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-sc}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
+ \csopt[firstuc]{description-case-change},
+ \csopt[\field{long}=\field{description}]{replicate-fields}}
+\end{codeenv}
+Note that this can cause a problem for styles that set the
+\field{description} field to the \field{long} form encapsulated by a
+style command (such as with the \abbrstyle{long-em-short-em} style)
+as this will override the style setting.
+
+Similarly, if you want to change the case of the \field{name} field:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-sc}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-abbrv]{src},
+ \csopt[firstuc]{description-case-change},
+ \csopt[uc]{name-case-change},
+ \csopt[\field{long}=\field{description},\field{short}=\field{name}]{replicate-fields}}
+\end{codeenv}
+Again, this will lose any custom formatting command that would
+usually be applied by the abbreviation style to the \field{name}
+field (and \field{description}, if applicable).
+
+Terms defined using \atentry{abbreviation} will be written to the output
+file using the command \gls!{bibglsnewabbreviation}.
+
+\entrysection{acronym}
+
+The \atentry{acronym} entry type is like \atentry{abbreviation} except that
+the term is written to the output file using the command
+\gls!{bibglsnewacronym}.
+
+\entrysection{contributor}
+
+The \atentry{contributor} entry type is primarily provided for use
+by the \atentry{bibtexentry} type. You may use it explicitly
+if you want, but you need to take care that it doesn't clash with
+\atentry{bibtexentry}. It behaves much like \atentry{index} except that the
+term is written to the \ext{glstex} file using the command
+\gls!{bibglsnewcontributor}. There are no required fields. As with
+\atentry{index}, if the \field{name} field is missing, the fallback
+value is the entry's label. When this entry type is automatically
+created by \atentry{bibtexentry}, the \field{name} is set to
+\begin{codeenv}
+\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}
+\end{codeenv}
+
+If you do explicitly use \atentry{contributor} you need to make sure it's
+defined \emph{before} the first instance of \atentry{bibtexentry} that
+tries to access it, but within the same resource set. If you ensure that
+the label of \atentry{contributor} matches the contributor label generated by
+\atentry{bibtexentry} then they can have their dependency lists
+updated, and
+the \field{bibtexentry} and \field{bibtexentry@entrytype} internal
+fields can be set for the
+\atentry{contributor} entry. For example:
+\begin{codeenv}
+\atentry{contributor}\marg{KnuthDonaldE,
+ \field{name}=\marg{\gls{bibglscontributor}\marg{Donald E.}\marg{}\marg{Knuth}\marg{}},
+ \field{description}=\marg{Famous mathematician and computer scientist who
+ created \cmd{TeX}}
+}
+\strut
+@book\marg{texbook,
+ title = \marg{The {\cmd{TeX} book}},
+ author = \marg{Donald E. Knuth},
+ publisher = \marg{Addison-Wesley},
+ year = 1986
+}
+\end{codeenv}
+The resource options then need to include:
+\begin{codeenv}
+ \csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases},
+ \csopt[
+ \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{}
+ ]{labelify-replace}
+\end{codeenv}
+
+If the \atentry{contributor} entry is deferred until after the
+corresponding \atentry{bibtexentry} then you will end up with a label clash.
+
+\section{Dual Entry Types}
+\label{sec:dualentry}
+
+The entry types described in this section create two separate (but
+related) \styfmt{glossaries-extra} entry definitions per \ext{bib}
+entry. The first of these entries is considered the
+\idx{primary} entry, and the second is the \idx{dual} entry
+(also referred to as the \idx{secondary} entry, but is not
+related to the \csopt{secondary} option). The naming scheme is
+\code{@dual}\meta{entry-type} where both the primary and dual are
+considered to have the same type of entry (such as
+\atentry{dualsymbol} where both the primary and dual are
+functionally like \atentry{symbol}) or
+\code{@dual}\meta{primary}\meta{dual} where the primary
+is functionally like \code{@}\meta{primary} and the dual is
+functionally like \code{@}\meta{dual}.
+
+For example:
+\begin{codeenv}
+\atentry{dualabbreviationentry}\marg{svm,
+ \field{short} = \marg{SVM},
+ \field{long} = \marg{support vector machine},
+ \field{description} = \marg{statistical pattern recognition technique}
+}
+\end{codeenv}
+is like:
+\begin{codeenv}
+\atentry{abbreviation}\marg{svm,
+ \field{short} = \marg{SVM},
+ \field{long} = \marg{support vector machine},
+}
+\atentry{entry}\marg{dual.svm,
+ \field{text} = \marg{SVM},
+ \field{name} = \marg{support vector machine},
+ \field{description} = \marg{statistical pattern recognition technique}
+}
+\end{codeenv}
+and is analogous to:
+\begin{codeenv}
+\gls{newabbreviation}\marg{svm}\marg{SVM}\marg{support vector machine}
+\gls{newglossaryentry}\marg{dual.svm}\marg{\field{name}=\marg{support vector machine},\field{text}=\marg{SVM},
+ \field{description}=\marg{statistical pattern recognition technique}}
+\end{codeenv}
+but both entries are considered dependent on each other. This means
+that if you only reference the primary entry (using \ics{gls} etc)
+then the dual entry will still be selected if the \csopt{selection}
+setting includes dependencies.
+
+The creation of the dual entry involves mapping or copying fields
+from the primary entry. Each dual entry type has a set of mappings.
+If a field in the set of mappings is missing, its fallback value is
+used. Any fields that aren't listed in the mappings are simply copied,
+except for the \field{alias} field, which will never be copied to
+the dual entry, nor can it be mapped. The alias will only apply to
+the primary entry. The dual entry is given the label
+\meta{prefix}\meta{id} where \meta{prefix} is set by the
+\csopt{dual-prefix} option and \meta{id} is the label supplied in
+the \ext{bib} file.
+
+If \csopt[combine]{dual-sort} then the dual entries will be sorted
+along with the primary entries, otherwise the \csopt{dual-sort}
+indicates how to sort the dual entries and the dual entries will be
+appended to the end of the \ext{glstex} file. The
+\csopt{dual-sort-field} determines what field to use for the sort
+value if the dual entries should be sorted separately.
+
+Take care if you have a mixture of entry types (such as
+\atentry{dualindexentry}, \atentry{dualindexsymbol}
+and \atentry{index}) and you're not
+using the default \csopt[combine]{dual-sort}. Remember that the
+primary entries are all sorted together along with the single
+entries types described in \sectionref{sec:dualentry} (but they may
+be assigned to different glossary types), and then the dual entries
+are sorted together (but may be assigned to different glossary
+types). This may result in an odd ordering if some of the primaries
+and some of the duals are assigned to the same glossary. For
+example, don't mix \atentry{dualindexabbreviation} (duals are
+abbreviations) with \atentry{dualabbreviationentry} (primaries
+are abbreviations) when you aren't using \csopt[combine]{dual-sort}
+(unless you have two different glossaries for the primary vs dual
+abbreviations).
+
+Remember that \bibgls\ is designed to take advantage of
+\ics{printunsrtglossary}, which simply iterates over all defined
+entries in the order in which they were defined (or, more precisely,
+the order of the internal list of entry labels associated with that
+glossary). The aim of \bibgls\ is to write the entry definitions to
+the \ext{glstex} file so that the internal list of labels is in the
+appropriate order.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{aardvark}
+\atentry{index}\marg{mouse}
+\atentry{index}\marg{zebra}
+\atentry{dualindexabbreviation}\marg{xml,
+ \field{short}=\marg{XML},
+ \field{long}=\marg{extensible markup language}
+}
+\atentry{dualabbreviationentry}\marg{ssi,
+ \field{short}=\marg{SSI},
+ \field{long}=\marg{server-side includes},
+ \field{description}=\marg{directives placed in \cs{gls}\marg{html} pages
+ evaluated by the server}
+}
+\atentry{dualindexabbreviation}\marg{html,
+ \field{short}=\marg{HTML},
+ \field{long}=\marg{hypertext markup language}
+}
+\atentry{dualabbreviationentry}\marg{css,
+ \field{short}=\marg{CSS},
+ \field{long}=\marg{cascading stylesheets},
+ \field{description}=\marg{a language that describes the style of an
+ \cs{gls}\marg{html} document}
+}
+\end{codeenv}
+This contains a mixture of entry types, including
+\atentry{dualindexabbreviation} (where the dual is the
+abbreviation) and \atentry{dualabbreviationentry} (where the
+primary is the abbreviation).
+
+Now consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt{abbreviations}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[all]{selection},\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+This uses the default \csopt[combine]{sort}, so all the entries are
+sorted together, resulting in the order:
+\code{aardvark},
+\code{dual.css},
+\code{css},
+\code{html},
+\code{dual.html},
+\code{mouse},
+\code{dual.ssi},
+\code{ssi},
+\code{xml},
+\code{dual.xml},
+\code{zebra}.
+
+The \LaTeX\ code written to the \iext{glstex} file is essentially
+(but not exactly):
+\begin{codeenv}
+\comment{from \atentry{index}\marg{aardvark}:}
+\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}}
+\strut
+\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
+\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\marg{text}=\marg{CSS},
+ \field{description}=\marg{a language that describes the style of an
+ \cs{glsxtrshort}\marg{html} document}}
+\strut
+\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
+\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets}
+\strut
+\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
+\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}}
+\strut
+\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
+\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
+\strut
+\comment{from \atentry{index}\marg{mouse}:}
+\gls{newglossaryentry}\marg{mouse}{\marg{name}=\marg{mouse},\field{description}=\marg{}}
+\strut
+\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
+\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI},
+ \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages
+ evaluated by the server}}
+\strut
+\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
+\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\strut
+\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
+\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}}
+\strut
+\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
+\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language}
+\strut
+\comment{from \atentry{index}\marg{zebra}:}
+\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}}
+\end{codeenv}
+Since the document uses the \styopt{abbreviations} package option,
+\gls{newabbreviation} automatically assigns the abbreviation
+to the \code{abbreviations} glossary (created through that package
+option). This means that the \code{main} (default) glossary
+contains the entries (in order):
+\begin{itemize}
+\item \code{aardvark} (name: aardvark),
+\item \code{dual.css} (name: cascading stylesheets),
+\item \code{html} (name: HTML),
+\item \code{mouse} (name: mouse),
+\item \code{dual.ssi} (name: server-side includes),
+\item \code{xml} (name: XML),
+\item \code{zebra} (name: zebra).
+\end{itemize}
+The \code{abbreviations} glossary contains:
+\begin{itemize}
+\item \code{css} (short: CSS),
+\item \code{dual.html} (short: HTML),
+\item \code{ssi} (short: SSI),
+\item \code{dual.xml} (short: XML).
+\end{itemize}
+
+Since all the entries were combined and sorted together, the
+resulting glossaries are both ordered alphabetically (using
+\field{short} for the abbreviations and \field{name} for the rest),
+but note that you need to take care when referencing the
+abbreviations if you want to make use of the abbreviation style. You
+need \verb|\gls{css}| and \verb|\gls{ssi}| for the primary
+abbreviations created with \atentry{dualabbreviationentry} and
+\verb|\gls{dual.html}| and \verb|\gls{dual.xml}| for the dual
+abbreviations created with \atentry{dualindexabbreviation}. Also
+the \field{name} of the primary\slash dual alternative of the
+abbreviations is also inconsistent (short form for \code{html} and
+\code{xml} and long form for \code{dual.css} and \code{dual.ssi}),
+as different field mappings are used.
+
+If the document is changed so that the dual entries are now
+sorted and written after all the primary entries have been dealt
+with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[letter-nocase]{dual-sort},
+ \csopt[all]{selection}
+}
+\end{codeenv}
+then \bibgls\ first orders the primaries:
+\begin{itemize}
+\item \code{aardvark} (name: aardvark),
+\item \code{css} (short: CSS),
+\item \code{html} (name: HTML),
+\item \code{mouse} (name: mouse),
+\item \code{ssi} (short: SSI),
+\item \code{xml} (name: XML),
+\item \code{zebra} (name: zebra)
+\end{itemize}
+and writes them to the \ext{glstex} file
+(functionally like):
+\begin{codeenv}
+\comment{from \atentry{index}\marg{aardvark}:}
+\gls{newglossaryentry}\marg{aardvark}\marg{\field{name}=\marg{aardvark},\field{description}=\marg{}}
+\strut
+\comment{primary of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
+\gls{newabbreviation}\marg{css}\marg{CSS}\marg{cascading stylesheets}
+\strut
+\comment{primary of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
+\gls{newglossaryentry}\marg{html}\marg{\field{name}=\marg{HTML},\field{description}=\marg{}}
+\strut
+\comment{from \atentry{index}\marg{mouse}:}
+\gls{newglossaryentry}\marg{mouse}\marg{\field{name}=\marg{mouse},\field{description}=\marg{}}
+\strut
+\comment{primary of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
+\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes}
+\strut
+\comment{primary of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
+\gls{newglossaryentry}\marg{xml}\marg{\field{name}=\marg{XML},\field{description}=\marg{}}
+\strut
+\comment{from \atentry{index}\marg{zebra}:}
+\gls{newglossaryentry}\marg{zebra}\marg{\field{name}=\marg{zebra},\field{description}=\marg{}}
+\end{codeenv}
+Then \bibgls\ orders the duals:
+\begin{itemize}
+\item \code{dual.css} (name: cascading stylesheets),
+\item \code{dual.html} (short: HTML),
+\item \code{dual.ssi} (name: server-side includes),
+\item \code{dual.xml} (short: XML)
+\end{itemize}
+and writes them to the \ext{glstex} file
+(functionally like):
+\begin{codeenv}
+\comment{dual of \atentry{dualabbreviationentry}\marg{css,\ldots}:}
+\gls{newglossaryentry}\marg{dual.css}\marg{\field{name}=\marg{cascading stylesheets},\field{text}=\marg{CSS},
+ \field{description}=\marg{a language that describes the style of an
+ \cs{glsxtrshort}\marg{html} document}}
+\strut
+\comment{dual of \atentry{dualindexabbreviation}\marg{html,\ldots}:}
+\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
+\strut
+\comment{dual of \atentry{dualabbreviationentry}\marg{ssi,\ldots}:}
+\gls{newglossaryentry}\marg{dual.ssi}\marg{\field{name}=\marg{server-side includes},\field{text}=\marg{SSI},
+ \field{description}=\marg{directives placed in \cs{glsxtrshort}\marg{html} pages
+ evaluated by the server}}
+\strut
+\comment{dual of \atentry{dualindexabbreviation}\marg{xml,\ldots}:}
+\gls{newabbreviation}\marg{dual.xml}\marg{XML}\marg{extensible markup language}
+\end{codeenv}
+When the \ext{glstex} file is input (during the next \LaTeX\ run)
+the entries are defined in the order:
+\begin{enumerate}
+\item \code{aardvark} (type: \code{main}),
+\item \code{css} (type: \code{abbreviations}),
+\item \code{html} (type: \code{main}),
+\item \code{mouse} (type: \code{main}),
+\item \code{ssi} (type: \code{abbreviations}),
+\item \code{xml} (type: \code{main}),
+\item \code{zebra} (type: \code{main}),
+\item \code{dual.css} (type: \code{main}),
+\item \code{dual.html} (type: \code{abbreviations}),
+\item \code{dual.ssi} (type: \code{main}),
+\item \code{dual.xml} (type: \code{abbreviations}).
+\end{enumerate}
+This means that the \code{main} glossary's internal list is in the
+order:
+\begin{itemize}
+\item \code{aardvark} (aardvark),
+\item \code{html} (HTML),
+\item \code{mouse} (mouse),
+\item \code{xml} (XML),
+\item \code{zebra} (zebra),
+\item \code{dual.css} (cascading stylesheets),
+\item \code{dual.ssi} (server-side includes)
+\end{itemize}
+and the \code{abbreviations} glossary's internal list is in the order:
+\begin{itemize}
+\item \code{css} (CSS),
+\item \code{ssi} (SSI),
+\item \code{dual.html} (HTML),
+\item \code{dual.xml} (XML).
+\end{itemize}
+The lists are no longer in alphabetical order as they have a mixture
+of primary and dual entries that were separated before sorting.
+
+The above is a fairly contrived example as it wouldn't make sense
+in a real document to have glossary terms (that include a
+description) mixed with index terms (that don't include a
+description).
+A better solution would be to use
+\atentry{tertiaryindexabbreviationentry} instead of
+\atentry{dualabbreviationentry}.
+
+\entrysection{dualentry}
+
+The \atentry{dualentry} entry type is similar to \atentry{entry} but
+actually defines two entries.
+The dual entry contains the same information as the primary entry
+but some of the fields are swapped around.
+The default mappings are:
+\begin{itemize}
+\item \field{name} $\mapsto$ \field{description}
+\item \field{plural} $\mapsto$ \field{descriptionplural}
+\item \field{description} $\mapsto$ \field{name}
+\item \field{descriptionplural} $\mapsto$ \field{plural}
+\end{itemize}
+The required fields are as for \atentry{entry}.
+
+For example:
+\begin{codeenv}
+\atentry{dualentry}\marg{child,
+ \field{name}=\marg{child},
+ \field{plural}=\marg{children},
+ \field{description}=\marg{enfant}
+}
+\end{codeenv}
+is like:
+\begin{codeenv}
+\atentry{entry}\marg{child,
+ \field{name}=\marg{child},
+ \field{plural}=\marg{children},
+ \field{description}=\marg{enfant}
+ \field{descriptionplural}=\marg{enfants}
+}
+\strut
+\atentry{entry}\marg{dual.child,
+ \field{description}=\marg{child},
+ \field{descriptionplural}=\marg{children},
+ \field{name}=\marg{enfant}
+ \field{plural}=\marg{enfants}
+}
+\end{codeenv}
+where \idprefix{dual} is replaced by the value of the
+\csopt{dual-prefix} option. However, instead of defining the entries
+with \csfmt{bibglsnewentry} both the primary and dual entries are
+defined using \gls!{bibglsnewdualentry}. The \field{category}
+and \field{type} fields can be set for the dual entry using the
+\csopt{dual-category} and \csopt{dual-type} options.
+
+For example:
+\begin{codeenv}
+\cs{newglossary*}\marg{english}\marg{English}
+\cs{newglossary*}\marg{french}\marg{French}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-dual]{src},\comment{data in entries-dual.bib}
+ \csopt[english]{type},\comment{put primary entries in glossary 'english'}
+ \csopt[french]{dual-type},\comment{put dual entries in glossary 'french'}
+ \csopt[dictionary]{category},\comment{set the primary category to 'dictionary'}
+ \csopt[dictionary]{dual-category},\comment{set the dual category to 'dictionary'}
+ \csopt[en]{sort},\comment{sort primary entries according to language 'en'}
+ \csopt[fr]{dual-sort}\comment{sort dual entries according to language 'fr'}
+}
+\end{codeenv}
+
+\entrysection{dualindexentry}
+
+There are no required fields. The primary
+entry behaves like \atentry{index} and the dual entry behaves
+like \atentry{entry}. The default field mapping is:
+\begin{itemize}
+\item \field{name} $\mapsto$ \field{name}
+\end{itemize}
+This doesn't actually perform any swapping of fields, but it
+provides the field used for backlinks (if
+\csopt{dual-indexentry-backlink} is set). The reason that the primary
+(rather than the dual) is like \atentry{index} is to allow the
+primaries to merge with any \atentry{index} entries found in the
+resource set, since glossary entries with descriptions are likely to
+be a subset of all indexed entries.
+
+If no \field{name} is given, the dual entry is assigned the
+(unprefixed) entry label. For example:
+\begin{codeenv}
+\atentry{dualindexentry}\marg{array,
+ \field{description}=\marg{ordered list of values}
+}
+\end{codeenv}
+This is effectively like:
+\begin{codeenv}
+\atentry{index}\marg{array}
+\strut
+\atentry{entry}\marg{dual.array,
+ \field{name}=\marg{array},
+ \field{description}=\marg{ordered list of values}
+}
+\end{codeenv}
+The primary entries are defined using
+\gls!{bibglsnewdualindexentry},
+which by default sets the \field{category} to \optfmt{index}
+(although this may be overridden, for example, by the \csopt{category} option).
+The dual entries are defined with
+\gls!{bibglsnewdualindexentrysecondary}.
+
+This is the most convenient way of having an entry that's also
+automatically indexed. For example, suppose the file
+\filefmt{terms.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\atentry{index}\marg{zebra}
+\atentry{index}\marg{aardvark}
+\end{codeenv}
+and suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{dualindexentry}\marg{array,
+ \field{description}=\marg{ordered list of values}
+}
+\strut
+\atentry{dualindexentry}\marg{vector,
+ \field{name}=\marg{vector},
+ \field{description}=\marg{column or row of values}
+}
+\strut
+\atentry{dualindexentry}\marg{set,
+ \field{description}=\marg{collection of values}
+}
+\strut
+\atentry{dualindexentry}\marg{matrix,
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values}
+}
+\end{codeenv}
+These entries can be used in an example document that has an
+index and a glossary:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[terms,entries]{src},
+ \csopt[index]{type},
+ \csopt[idx.]{label-prefix},
+ \csopt[gls.]{dual-prefix},
+ \csopt[primary]{combine-dual-locations},
+ \csopt[main]{dual-type}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
+\strut
+\cs{gls}\marg{idx.duck}, \cs{gls}\marg{idx.aardvark}, \cs{gls}\marg{idx.zebra}.
+\strut
+\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\ics{textsc}\marg{\idx{param}1}}
+\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt[index]{style},\iprintglossopt{nogroupskip}}
+\strut
+\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
+\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[mcolindexgroup]{style}}
+\cmd{end}\marg{document}
+\end{codeenv}
+This uses \csopt{combine-dual-locations} to combine the locations
+for the primary and dual entries so that they only appear in the
+index.
+
+To avoid the inconvenience of remembering which prefix to use, you can
+set up the prefixes with \ics{glsxtraddlabelprefix} and reference entries
+with \ics{dgls}, \ics{dGls} etc instead of \cs{gls}, \cs{Gls} etc.
+
+\entrysection{dualindexabbreviation}
+
+The \atentry{dualindexabbreviation} entry type is similar to
+\atentry{dualindexentry} and again, by default, the
+field mapping is:
+\begin{itemize}
+\item \field{name} $\mapsto$ \field{name}
+\end{itemize}
+However in this case the required fields are \field{short} and
+\field{long}. The \field{name} for the primary entry defaults to
+\field{short} if omitted. (This may be changed with the
+\csopt{abbreviation-name-fallback} option.) The fallback for the
+\field{sort} field is given by \csopt{abbreviation-sort-fallback},
+which defaults to the \field{short} field.
+
+For example:
+\begin{codeenv}
+\atentry{dualindexabbreviation}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+is like:
+\begin{codeenv}
+\atentry{index}\marg{html,\field{name}=\marg{HTML}}
+\strut
+\atentry{abbreviation}\marg{dual.html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+The primary term is defined using
+\gls!{bibglsnewdualindexabbreviation}, which encapsulates the
+\field{name} to match the font used by
+the dual abbreviation. The encapsulation command depends
+on the \csopt{abbreviation-name-fallback} value. If it's
+the \field{short} field then \gls{bibglsuseabbrvfont} is
+used, otherwise \gls{bibglsuselongfont} is used.
+
+The primary definition also
+by default sets the \field{category} to \optfmt{index} (although
+this again may be overridden).
+The dual term is defined using
+\gls!{bibglsnewdualindexabbreviationsecondary}.
+
+\entrysection{dualindexsymbol}
+
+The \atentry{dualindexsymbol} entry type is similar to
+\atentry{dualindexentry}, but by default the
+field mappings are:
+\begin{itemize}
+\item \field{symbol} $\mapsto$ \field{name}
+\item \field{name} $\mapsto$ \field{symbol}
+\item \field{symbolplural} $\mapsto$ \field{plural}
+\item \field{plural} $\mapsto$ \field{symbolplural}
+\end{itemize}
+The required field is: \field{symbol}.
+If the \field{name} field is omitted, the dual entry is assigned a
+symbol from the original (unprefixed) label.
+The primary entries are defined using
+\gls!{bibglsnewdualindexsymbol},
+which by default sets the \field{category} to \optfmt{index},
+and the dual entries are defined using
+\gls!{bibglsnewdualindexsymbolsecondary},
+which by default sets the \field{category} to \optfmt{symbol}.
+For example:
+\begin{codeenv}
+\atentry{dualindexsymbol}\marg{pi,
+ \field{symbol}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
+ \field{description}=\marg{ratio of a circle's circumference to its diameter}
+}
+\end{codeenv}
+is like:
+\begin{codeenv}
+\atentry{index}\marg{pi,\field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}}}
+\strut
+\atentry{symbol}\marg{dual.pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{symbol}=\marg{pi},
+ \field{description}=\marg{ratio of a circle's circumference to its diameter}
+}
+\end{codeenv}
+
+For example, suppose I have a file called \filefmt{symbols.bib} that
+contains:
+\begin{codeenv}
+\atentry{dualindexsymbol}\marg{pi,
+ \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{ratio of a circle's circumference to its diameter}
+}
+\strut
+\atentry{dualindexsymbol}\marg{e,
+ \field{name}=\marg{Euler's number},
+ \field{symbol}=\marg{\cs{ensuremath}\marg{e}},
+ \field{description}=\marg{base of the natural logarithm}
+}
+\end{codeenv}
+Then the previous example document can be modified to have an index,
+a glossary and a list of symbols:
+\begin{codeenv}
+\cmd{documentclass}\marg{report}
+\strut
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt{symbols},\styopt{index},\styopt[mcols]{stylemods}]\marg{glossaries-extra}
+\strut
+\cs{newcommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=symbol,\comment{}
+ \field{symbol}=\marg{\idx{param}4},\idx{param}2,\field{type}=\marg{symbols}}\marg{\idx{param}5}\comment{}
+}
+\strut
+\cs{newcommand}\marg{\cmd{indexprimary}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{idx.\idx{param}1}}
+\strut
+\cs{glsdefpostdesc}\marg{symbol}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}}
+\cs{glsdefpostdesc}\marg{general}\marg{\cmd{indexprimary}\marg{\cs{glscurrententrylabel}}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries,terms,symbols]{src},
+ \csopt[index]{type},
+ \csopt{set-widest},
+ \csopt[idx.]{label-prefix},
+ \csopt[\empty]{dual-prefix},
+ \csopt[primary]{combine-dual-locations},
+ \csopt[letter-case]{dual-sort},
+ \csopt[main]{dual-type}
+}
+\strut
+\gls{glsxtrnewglslike}\oarg{\glsopt[false]{hyper}}\marg{idx.}\marg{\cmd{idx}}\marg{\cmd{idxpl}}\marg{\cmd{Idx}}\marg{\cmd{Idxpl}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{glspl}\marg{matrix}.
+\cmd{idx}\marg{duck}, \cmd{idx}\marg{aardvark}, \cmd{idx}\marg{zebra}.
+\cs{gls}\marg{e} and \cs{gls}\marg{pi}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{array}, \cmd{idx}\marg{vector}, \cmd{idx}\marg{set}, \cs{gls}\marg{matrix}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{array}, \cs{gls}\marg{vector}, \cs{gls}\marg{set}, \cs{gls}\marg{matrix}.
+\strut
+\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textsc}\marg{\idx{param}1}}
+\cs{printunsrtglossary}\oarg{\printglossopt[main]{type},\printglossopt{nogroupskip},\printglossopt[\glostyle{alttree}]{style}}
+\strut
+\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cs{printunsrtglossary}\oarg{\printglossopt[symbols]{type},\printglossopt{nogroupskip},\printglossopt[index]{style}}
+\strut
+\cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
+\cs{printunsrtglossary}\oarg{\printglossopt[index]{type},\printglossopt[\glostyle{mcolindexgroup}]{style}}
+\strut
+\cmd{end}\marg{document}
+\end{codeenv}
+Here I've provided some convenient commands for referencing the
+primary (index) terms (\csfmt{idx}, \csfmt{idxpl}, \csfmt{Idx}
+and \csfmt{Idxpl}). This means I don't need to worry about the
+label prefix and it also switches off the hyperlinks (with
+\code{\glsopt[false]{hyper}}). These custom
+commands are defined using:
+\nosecformatdef{glsxtrnewglslike}
+which, in this case, essentially does:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{idx}}[2][]\marg{\cs{gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
+\cs{newcommand}\marg{\cmd{Idx}}[2][]\marg{\cs{Gls}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
+\cs{newcommand}\marg{\cmd{idxpl}}[2][]\marg{\cs{glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
+\cs{newcommand}\marg{\cmd{Idxpl}}[2][]\marg{\cs{Glspl}\oarg{\glsopt[false]{hyper},\idx{param}1}\marg{idx.\idx{param}2}}
+\end{codeenv}
+but the new commands will also recognise the \ics{gls} modifiers, so
+\verb|\idx+| will behave like \verb|\gls+| which wouldn't be
+possible if \csfmt{idx} was defined using \ics{newcommand} in the
+above manner. There's a similar command:
+\nosecformatdef{glsxtrnewgls}
+if no case-changing versions are required.
+
+I've also redefined \gls!{bibglsnewdualindexsymbolsecondary} to put
+the dual entries created with \atentry{dualindexsymbol} into
+the \code{symbols} glossary (which is created with the
+\styopt{symbols} package option), so it overrides the
+\csopt[main]{dual-type} setting.
+
+This command also sets the \field{category}
+to \code{symbol}, so I can redefine the post-description hook
+for symbols (\ics{glsxtrpostdescsymbol}) to automatically index
+the symbol definition. Similarly for the \code{general}
+post-description hook \ics{glsxtrpostdescgeneral}.
+
+Since the post-description hook isn't done until the glossary has
+been created, this requires a slightly longer build process. If the
+document file is called \filefmt{myDoc.tex}, then the complete
+document build is:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls -g myDoc
+pdflatex myDoc
+bib2gls -g myDoc
+pdflatex myDoc
+\end{verbatim}
+
+As from \sty{glossaries-extra-bib2gls} version 1.37, an alternative
+method is to identify possible label prefixes with
+\ics{glsxtraddlabelprefix} or \ics{glsxtrprependlabelprefix} and use
+\ics{dgls}, \ics{dglspl}, \ics{dGls} or \ics{dGlspl}. See the
+\styfmt{glossaries-extra} user manual~\cite{glossaries-extra} for
+further details.
+
+\entrysection{dualindexnumber}
+
+The \atentry{dualindexnumber} entry type is almost identical to
+\atentry{dualindexsymbol}, but the primary entries are defined using
+\gls!{bibglsnewdualindexnumber},
+which by default sets the \field{category} to \optfmt{index},
+and the dual entries are defined using
+\gls!{bibglsnewdualindexnumbersecondary},
+which by default sets the \field{category} to \optfmt{number}.
+
+\entrysection{dualabbreviationentry}
+
+The \atentry{dualabbreviationentry} entry type is similar to
+\atentry{dualentry}, but by default the
+field mappings are:
+\begin{itemize}
+\item \field{long} $\mapsto$ \field{name}
+\item \field{longplural} $\mapsto$ \field{plural}
+\item \field{short} $\mapsto$ \field{text}
+\end{itemize}
+You may need to add a mapping from \field{shortplural} to
+\field{plural} if the default is inappropriate.
+(In \bibgls\ version 1.0 this entry type was originally called
+\atentry{dualentryabbreviation}. In version 1.1, it was renamed
+\atentry{dualabbreviationentry} which makes for a more consistent naming scheme
+\code{@dual}\meta{primary}\meta{dual}.)
+
+The required fields are: \field{short}, \field{long} and
+\field{description}. This entry type is designed to emulate the
+example \gls{newdualentry} command given in the \sty{glossaries}
+user manual~\cite{glossaries}. The primary entry is an abbreviation with the given
+\field{short} and \field{long} fields (but not the
+\field{description}) and the secondary entry is a regular entry with
+the \field{name} copied from the \field{long} field.
+The fallback for the \field{sort} is given by
+\csopt{abbreviation-sort-fallback}, which defaults to the
+\field{short} field.
+
+For example:
+\begin{codeenv}
+\atentry{dualabbreviationentry}\marg{svm,
+ \field{long} = \marg{support vector machine},
+ \field{short} = \marg{SVM},
+ \field{description} = \marg{statistical pattern recognition technique}
+}
+\end{codeenv}
+is rather like doing:
+\begin{codeenv}
+\atentry{abbreviation}\marg{svm,
+ \field{long} = \marg{support vector machine},
+ \field{short} = \marg{SVM}
+}
+\strut
+\atentry{entry}\marg{dual.svm,
+ \field{name} = \marg{support vector machine},
+ \field{description} = \marg{statistical pattern recognition technique}
+}
+\end{codeenv}
+but \code{dual.svm} will automatically be selected if \code{svm}
+is indexed in the document. If \code{dual.svm} isn't explicitly
+indexed, it won't have a location list.
+
+If the \field{sort} field is missing \bibgls\ by default falls back
+on the \field{name} field. If this is missing, this sort value will
+fallback on the \field{short} field. This means that if \field{name}
+isn't explicitly given in \atentry{dualabbreviationentry}, then the
+primary entry will be sorted according to \field{short} but the dual
+will be sorted according its \field{name} (which has been copied
+from the primary \field{long}).
+
+Entries provided using \atentry{dualabbreviationentry} will be defined
+with:
+\begin{codeenv}
+\gls{bibglsnewdualabbreviationentry}
+\end{codeenv}
+(which uses \gls{newabbreviation}) for the primary entries and with :
+\begin{codeenv}
+\gls{bibglsnewdualabbreviationentrysecondary}
+\end{codeenv}
+(which uses \gls{longnewglossaryentry}) for the secondary entries.
+This means that if the \styopt{abbreviations}
+package option is used, the primary entry will be put in the
+\optfmt{abbreviations} glossary and the secondary entry in the
+\optfmt{main} glossary. Use the \csopt{type} and
+\csopt{dual-type} options to override this.
+
+\entrysection{dualentryabbreviation}
+
+This entry type is deprecated as from \bibgls\ version 1.1. It's functionally
+equivalent to \atentry{dualabbreviationentry} but its name
+doesn't fit the general dual entry naming scheme.
+
+\entrysection{dualsymbol}
+
+This is like \atentry{dualentry} but the default mappings are:
+\begin{itemize}
+\item \field{name} $\mapsto$ \field{symbol}
+\item \field{plural} $\mapsto$ \field{symbolplural}
+\item \field{symbol} $\mapsto$ \field{name}
+\item \field{symbolplural} $\mapsto$ \field{plural}
+\end{itemize}
+The \field{name} and \field{symbol} fields are required.
+For example:
+\begin{codeenv}
+\atentry{dualsymbol}\marg{pi,
+ \field{name}=\marg{pi},
+ \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{the ratio of the length of the circumference
+ of a circle to its diameter}
+}
+\end{codeenv}
+
+Entries are defined using \gls!{bibglsnewdualsymbol}, which by
+default sets the \field{category} to \optfmt{symbol}.
+
+\entrysection{dualnumber}
+
+This is almost identical to \atentry{dualsymbol} but entries are
+defined using \gls!{bibglsnewdualnumber}, which by default sets
+the \field{category} to \optfmt{number}.
+
+The above example could be defined as a number since $\pi$ is a
+constant:
+\begin{codeenv}
+\atentry{dualnumber}\marg{pi,
+ \field{name}=\marg{pi},
+ \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{pi}}},
+ \field{description}=\marg{the ratio of the length of the circumference
+ of a circle to its diameter},
+ \field{user1}=\marg{3.14159}
+}
+\end{codeenv}
+
+This has stored the approximate value in the \field{user1} field.
+The post-description hook could then be adapted to show this.
+\begin{codeenv}
+\cs{glsdefpostdesc}\marg{number}\marg{\comment{}
+ \cs{ifglshasfield}\marg{useri}\marg{\cs{glscurrententrylabel}}
+ \marg{ (approximate value: \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+
+This use of the \field{user1} field means that the dual entries
+could be sorted numerically according to the approximate value:
+\begin{codeenv}
+\cmd{usepackage}[\styopt{record},\styopt{postdot},\styopt{numbers},\styopt[index]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{entries.bib}
+ \csopt[numbers]{dual-type},
+ \csopt[double]{dual-sort},\comment{decimal sort}
+ \csopt[user1]{dual-sort-field}
+}
+\end{codeenv}
+
+\entrysection{dualabbreviation}
+
+The \atentry{dualabbreviation} entry type is similar to
+\atentry{dualentry}, but by default the
+field mappings are:
+\begin{itemize}
+\item \field{short} $\mapsto$ \field{dualshort}
+\item \field{shortplural} $\mapsto$ \field{dualshortplural}
+\item \field{long} $\mapsto$ \field{duallong}
+\item \field{longplural} $\mapsto$ \field{duallongplural}
+\item \field{dualshort} $\mapsto$ \field{short}
+\item \field{dualshortplural} $\mapsto$ \field{shortplural}
+\item \field{duallong} $\mapsto$ \field{long}
+\item \field{duallongplural} $\mapsto$ \field{longplural}
+\end{itemize}
+The required fields are: \field{short}, \field{long},
+\field{dualshort} and \field{duallong}.
+This includes some new fields: \field{dualshort},
+\field{dualshortplural}, \field{duallong} and
+\field{duallongplural}. If these aren't already defined, they
+will be provided in the \iext{glstex} file with
+\begin{codeenv}
+\ics{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{}
+\end{codeenv}
+Note that this use with an empty third argument prevents
+the creation of a field access command (analogous to
+\ics{glsentrytext}). The value can be accessed with
+\ics{glsxtrusefield} instead. Remember that the field won't be
+available until the \ext{glstex} file has been created.
+
+Note that \bibgls\ doesn't know what abbreviation styles
+are in used, so if the \field{sort} field is missing
+it will fallback on the \field{short} field. If the abbreviations
+need to be sorted according to the \field{long} field instead,
+use \csopt[long]{abbreviation-sort-fallback}.
+
+Terms that are defined using \atentry{dualabbreviation} will be
+written to the output file using \gls!{bibglsnewdualabbreviation}.
+
+If the \csopt{dual-abbrv-backlink} option is on, the default field
+used for the backlinks is the \field{dualshort} field, so you'll need
+to make sure you adapt the glossary style to show that field. The
+simplest way to do this is through the category \idx{postdescriptionhook}.
+
+For example, if the entries all have the \field{category} set
+to \optfmt{abbreviation}, then this requires redefining
+\ics{glsxtrpostdescabbreviation} (either with \cs{renewcommand}
+or via \cs{glsdefpostdesc}).
+
+Here's an example dual abbreviation for a document where English is
+the primary language and German is the secondary language:
+\begin{codeenv}
+\atentry{dualabbreviation}\marg{rna,
+ \field{short}=\marg{RNA},
+ \field{dualshort}=\marg{RNS},
+ \field{long}=\marg{ribonucleic acid},
+ \field{duallong}=\marg{Ribonukleins\"aure}
+}
+\end{codeenv}
+If the abbreviation is in the file called
+\filefmt{entries-dual-abbrv.bib}, then here's an example document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[T1]\marg{fontenc}
+\cmd{usepackage}[utf8]\marg{inputenc}
+\strut
+\cmd{usepackage}[ngerman,main=english]\marg{babel}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
+\strut
+\cs{newglossary*}\marg{english}\marg{English}
+\cs{newglossary*}\marg{german}\marg{German}
+\strut
+\cs{setabbreviationstyle}\marg{long-short}
+\strut
+\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
+ \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{}
+ \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-dual-abbrv]{src},\comment{entries-dual-abbrv.bib}
+ \csopt[english]{type},\comment{put primary entries in glossary 'english'}
+ \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'}
+ \csopt[en.]{label-prefix},\comment{primary label prefix}
+ \csopt[de.]{dual-prefix},\comment{dual label prefix}
+ \csopt[en]{sort},\comment{sort primary entries according to language 'en'}
+ \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'}
+ \comment{(German new orthography)}
+ \csopt{dual-abbrv-backlink}\comment{add links in the glossary to the opposite entry}
+}
+\strut
+\cmd{begin}\marg{document}
+\strut
+English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}.
+\strut
+German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+If the \csopt{label-prefix} is omitted, then only the dual entries
+will have a prefix:
+\begin{codeenv}
+English: \cs{gls}\marg{rna}; \cs{gls}\marg{rna}.
+\strut
+German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
+\end{codeenv}
+Another variation is to use the \abbrstyle{long-short-user}
+abbreviation style and modify the associated \ics{glsxtruserfield} so that
+the \field{duallong} field is selected for the parenthetical
+material:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
+\end{codeenv}
+This means that the first use of the primary entry is displayed as
+\begin{quote}
+ribonucleic acid (RNA, Ribonukleins\"aure)
+\end{quote}
+and the first use of the dual entry is displayed as:
+\begin{quote}
+Ribonukleins\"aure (RNS, ribonucleic acid)
+\end{quote}
+
+Here's an example to be used with the \abbrstyle{long-short-desc}
+style:
+\begin{codeenv}
+\atentry{dualabbreviation}\marg{rna,
+ \field{short}=\marg{RNA},
+ \field{dualshort}=\marg{RNS},
+ \field{long}=\marg{ribonucleic acid},
+ \field{duallong}=\marg{Ribonukleins\"aure}
+ \field{description}=\marg{a polymeric molecule},
+ \field{user1}=\marg{Ein polymeres Molek\"ul}
+}
+\end{codeenv}
+This stores the dual description in the \field{user1} field,
+so this needs a mapping.
+The new example document is much the same as the previous one, except
+that the \csopt{dual-abbrv-map} option is needed to include the
+mapping between the \field{description} and \field{user1} fields:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[T1]\marg{fontenc}
+\cmd{usepackage}[utf8]\marg{inputenc}
+\strut
+\cmd{usepackage}[ngerman,main=english]\marg{babel}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
+\strut
+\cs{newglossary*}\marg{english}\marg{English}
+\cs{newglossary*}\marg{german}\marg{German}
+\strut
+\cs{setabbreviationstyle}\marg{long-short-desc}
+\strut
+\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
+ \cs{ifglshasfield}\marg{dualshort}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{}
+ \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-dual-abbrv-desc]{src},\comment{entries-dual-abbrv-desc.bib}
+ \csopt[english]{type},\comment{put primary entries in glossary 'english'}
+ \csopt[german]{dual-type},\comment{put primary entries in glossary 'german'}
+ \csopt[en.]{label-prefix},\comment{primary label prefix}
+ \csopt[de.]{dual-prefix},\comment{dual label prefix}
+ \csopt[en]{sort},\comment{sort primary entries according to language 'en'}
+ \csopt[long]{abbreviation-sort-fallback},\comment{fallback on 'long' field}
+ \csopt[de-1996]{dual-sort},\comment{sort dual entries according to 'de-1996'}
+ \comment{(German new orthography)}
+ \csopt{dual-abbrv-backlink},\comment{add links in the glossary to the opposite entry}
+\comment{ dual key mappings:}
+ \csopt[\comment{}
+ \marg{short,shortplural,long,longplural,dualshort,dualshortplural,
+ duallong,duallongplural,description,user1},
+ \marg{dualshort,dualshortplural,duallong,duallongplural,short,shortplural,
+ long,longplural,user1,description}
+ ]{dual-abbrv-map}
+}
+\strut
+\cmd{begin}\marg{document}
+\strut
+English: \cs{gls}\marg{en.rna}; \cs{gls}\marg{en.rna}.
+\strut
+German: \cs{gls}\marg{de.rna}; \cs{gls}\marg{de.rna}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Note that since this document uses the \abbrstyle{long-short-desc}
+abbreviation style, the \csopt{abbreviation-sort-fallback} needs to be changed
+to \optfmt{long}.
+
+If I change the order of the mapping to:
+\begin{codeenv}
+ \csopt[\comment{}
+ \marg{long,longplural,short,shortplural,dualshort,dualshortplural,
+ duallong,duallongplural,description,user1},
+ \marg{duallong,duallongplural,dualshort,dualshortplural,short,shortplural,
+ long,longplural,user1,description}
+ ]{dual-abbrv-map}
+\end{codeenv}
+Then the back-link field will switch to \field{duallong}. The
+\idx{postdescriptionhook} can be modified to allow for this:
+\begin{codeenv}
+\cs{glsdefpostdesc}\marg{abbreviation}\marg{\comment{}
+ \cs{ifglshasfield}\marg{duallong}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{}
+ \cmd{space}(\cs{glscurrentfieldvalue})\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+
+An alternative is to use the \abbrstyle{long-short-user-desc} style
+without the \idx!{postdescriptionhook}:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-user-desc}
+\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
+\end{codeenv}
+However be careful with this approach as it can cause nested
+hyperlinks. In this case it's better to use the
+\abbrstyle{long-postshort-user-desc} style which defers the
+parenthetical material until after the link-text:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-postshort-user-desc}
+\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{duallong}
+\end{codeenv}
+If the back-link field has been switched to \field{duallong} then
+the \idx!{postdescriptionhook} is no longer required.
+
+\entrysection{dualacronym}
+
+As \atentry{dualabbreviation} but defines the entries with
+\gls!{bibglsnewdualacronym}.
+
+\section{Tertiary Entry Types}
+\label{sec:tertiaryentry}
+
+A tertiary entry type is essentially a dual entry that creates three
+separate (but related) \styfmt{glossaries-extra} entry definitions per
+\ext{bib} entry. As with dual entries, the first and second of these
+are the primary and secondary. The third of these is the
+\idx{tertiary} which is effectively an appendage of the
+secondary, and is defined by the same associated
+\csfmt{bibglsnew\ldots secondary} command that defines the secondary
+entry. Therefore the secondary and tertiary are both considered the
+dual and are treated as a single entry for the purposes of sorting
+and collating.
+
+The tertiary entry will never have any locations. Any records found
+will be assigned to the secondary (and may then be moved to the
+primary with \csopt[primary]{combine-dual-locations}). The tertiary
+will always have the same order as the secondary and will have the same
+\field{group} value. You can set the \field{type} for the tertiary
+with \csopt{tertiary-type} and the \field{category} with
+\csopt{tertiary-category}. The label prefix defaults to
+\idprefix{tertiary} and can be changed with \csopt{tertiary-prefix}.
+
+\entrysection{tertiaryindexabbreviationentry}
+
+This entry type is very similar to
+\atentry{dualindexabbreviation} but creates a tertiary entry as
+well. The required fields are: \field{short} and \field{long} (as for
+\atentry{dualindexabbreviation}) and also \field{description}. The
+mappings are shared by both entry types. For example:
+\begin{codeenv}
+\atentry{tertiaryindexabbreviationentry}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language},
+ \field{description} = \marg{a markup language for creating web pages}
+}
+\end{codeenv}
+is analogous to:
+\begin{codeenv}
+\gls{newglossaryentry}\marg{html,\field{name}=\marg{HTML},\field{description}=\marg{}}
+\strut
+\gls{newabbreviation}\marg{dual.html}\marg{HTML}\marg{hypertext markup language}
+\strut
+\gls{newglossaryentry}\marg{tertiary.html,
+ \field{name}=\marg{hypertext markup language},
+ \field{description}=\marg{a markup language for creating web pages}
+}
+\end{codeenv}
+The last two are actually defined using one command:
+\begin{codeenv}
+\gls{bibglsnewtertiaryindexabbreviationentrysecondary}
+ \marg{dual.html}\comment{secondary label}
+ \marg{tertiary.html}\comment{tertiary label}
+ \marg{\ldots}\comment{secondary fields}
+ \marg{\ldots}\comment{tertiary fields}
+ \marg{HTML}\comment{primary name}
+ \marg{HTML}\comment{short}
+ \marg{hypertext markup language}\comment{long}
+ \marg{a markup language for creating web pages}\comment{description}
+\end{codeenv}
+The \gls!{bibglsnewtertiaryindexabbreviationentrysecondary}
+command is provided in the \iext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{}
+ \marg{\field{name}=\marg{\cmd{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\ics{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{}
+ \marg{\idx{param}8}\comment{}
+}
+\end{codeenv}
+which defines the secondary as an abbreviation using
+\csfmt{newabbreviation} and the tertiary as a regular entry using
+\csfmt{longnewglossaryentry}. This means that the tertiary entry is
+always defined immediately after the corresponding secondary entry.
+The primary may be defined earlier or later in the file depending on the
+way the entries are sorted and on the \csopt{dual-sort} setting.
+
+\section{Multi-Entry Types}
+\label{sec:multientry}
+
+A multi-entry type is an entry that may spawn multiple
+primary entries. This means that both the main entry and the
+spawned entries are sorted together along with all the other primary
+entries. In the case of \atentry{spawndualindexentry}, the main and
+spawned entries are primary. The main entry's dual is created as per
+\atentry{dualindexentry}.
+
+\entrysection{bibtexentry}
+
+The \atentry{bibtexentry} type will typically need to be aliased
+as it's designed for converting \BibTeX\ entries into \bibgls\
+entries. For example, to make \bibgls\ treat \atentryfmt{article}
+and \atentryfmt{book} as though they were both
+\atentry{bibtexentry}:
+\begin{codeenv}
+\csopt[
+ article=bibtexentry,
+ book=bibtexentry
+]{entry-type-aliases}
+\end{codeenv}
+For convenience, \isty{glossaries-extra-bib2gls} v1.29+
+provides \ics{GlsXtrBibTeXEntryAliases} which covers all the
+standard \BibTeX\ entry types. Alternatively, you can use
+\csopt[bibtexentry]{unknown-entry-alias} to alias all entries
+that aren't recognised by \bibgls. If you use
+\csopt[same as original entry]{category}, the \field{category}
+field will be set to the original entry type (for example,
+\code{article} or \code{book}). Similarly you can use
+\csopt[same as original entry]{type} to set the \field{type}
+field (but remember that the glossary types will need to be defined
+in the document).
+
+There are no required fields. The fallback for the \field{sort}
+field is given by \csopt{bibtexentry-sort-fallback}. If you want to
+access any of the \BibTeX\ fields, you will need to alias or define
+them. For example:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{title}=\field{name}
+]{field-aliases}
+\end{codeenv}
+Since \BibTeX's \fieldfmt{type} field conflicts with \bibgls's
+\field{type} field, when \bibgls\ parses \atentry{bibtexentry}
+if will convert \fieldfmt{type} to \field{bibtextype}, so you
+must use \field{bibtextype} as the identifier when aliasing.
+
+Alternatively, you can use \ics{GlsXtrProvideBibTeXFields} which
+uses \ics{glsaddstoragekey} to provide all the standard \BibTeX\
+fields. (Remember that new fields must be defined before the first
+\idx{resourceset}.)
+
+The \atentry{bibtexentry} essentially creates an \atentry{index}
+form of entry, but it additionally defines a \atentry{contributor}
+entry for each listed author or editor
+and updates the dependency lists: each \atentry{contributor} is
+added to the main
+\atentry{bibtexentry}'s list of dependencies (so if the
+\atentry{bibtexentry} has a record then all its satellite
+\atentry{contributor}s are selected with the default
+\csopt[recorded and deps]{selection}), and
+each \atentry{contributor} is treated as having a cross-reference to
+the main \atentry{bibtexentry} (so if a \atentry{contributor}
+has a record then all the linked \atentry{bibtexentry} terms will
+be selected if \csopt[recorded and deps and see]{selection}).
+You can instruct \bibgls\ to treat \ics{citation} as an
+\idx{ignoredrecord} using \longarg{cite-as-record}.
+
+Each contributor is effectively defined as:
+\begin{codeenv}
+\atentry{contributor}\marg{\meta{label},
+ \field{name}=\marg{\gls{bibglscontributor}\margm{forenames}\margm{von}\margm{surname}\margm{suffix}}
+}
+\end{codeenv}
+The label is obtained by converting the \field{name}
+to a label, using the same function as \csopt{labelify} (which
+means it's governed by \csopt{labelify-replace}).
+
+The \fieldfmt{author} and \fieldfmt{editor} fields are always
+checked, even if those fields aren't recognised by \bibgls, (which
+they aren't by default). These checks are performed before field
+aliases are applied. If neither field is present, no additional
+entries are spawned. If the dependent \atentry{contributor} entry
+has already been defined, it won't be redefined, but will have the
+new \atentry{bibtexentry} added to its internal \field{bibtexentry}
+field.
+
+The main \atentry{bibtexentry} is defined using
+\gls{bibglsnewbibtexentry} and is followed by:
+\begin{codeenv}
+\gls{glsxtrfieldlistadd}\margm{id}\marg{bibtexcontributor}\margm{contributor-id}
+\end{codeenv}
+where \meta{id} is the label identifying the main
+\atentry{bibtexentry} and \meta{contributor-id} is the
+label identifying the contributor, for each contributor that has
+been selected.
+
+Each contributor is defined using \gls{bibglsnewcontributor}. The definition
+is followed by:
+\begin{codeenv}
+\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry}\margm{id}
+\gls{glsxtrfieldlistadd}\margm{contributor-id}\marg{bibtexentry@\meta{entry-type}}\margm{id}
+\end{codeenv}
+for each selected \atentry{bibtexentry} associated with that contributor. The
+second line provides the internal list field
+\field{bibtexentry@entrytype}, where \meta{entry-type} is the
+original entry type (before it was aliased to
+\atentry{bibtexentry} and converted to \idx!{lowercase}).
+For example \code{article} or \code{book}.
+
+You can iterate over these internal list fields using
+\ics{glsxtrfielddolistloop} or \ics{glsxtrfieldforlistloop}.
+For example:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\cs{glsentryname}\marg{\#1}}
+
+\cs{newcommand}\marg{\postdeschook{contributor}}\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrfieldforlistloop}
+ \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{}
+ \marg{\csfmt{contributorhandler}}\comment{}
+ }\comment{}
+ \marg{\csfmt{par} No titles.}\comment{}
+}
+\end{codeenv}
+(where the resource option \csopt[\fieldfmt{title}=\field{name}]{field-aliases}
+has been used).
+
+Here's an example that uses the test \file{xampl.bib} file that's
+provided with \TeX\ distributions:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
+\strut
+\cs{newglossary*}\marg{contributors}\marg{Authors/Editors}
+\cs{newglossary*}\marg{titles}\marg{Titles}
+\strut
+\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}={\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[xampl]{src},
+ \csopt[false]{write-preamble},
+ \csopt[
+ \ics{GlsXtrBibTeXEntryAliases}
+ ]{entry-type-aliases},
+ \csopt[
+ \fieldfmt{title}=\field{name}
+ ]{field-aliases},
+ \csopt[
+ \fieldfmt{note}=\field{name}
+ ]{replicate-fields},
+ \csopt[
+ \marg{[ \cs{cs.string}\csfmt{-}\cs{cs.string}\csfmt{.}]}\marg{}
+ ]{labelify-replace},
+ \csopt[contributors]{type},
+ \csopt[same as original entry]{category},
+ \csopt[\field{category}]{sort-field},
+ \csopt[\field{name}]{sort-suffix}
+}
+\strut
+\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles}
+\gls{glsxtrsetgrouptitle}\marg{booklet}\marg{Booklets}
+\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books}
+\gls{glsxtrsetgrouptitle}\marg{inbook}\marg{Book Chapters}
+\gls{glsxtrsetgrouptitle}\marg{misc}\marg{Miscellaneous}
+\strut
+\cs{newcommand}\marg{\csfmt{contributorhandler}}[1]\marg{\csfmt{par}\ics{glsentryname}\marg{\idx{param}1} (\idx{param}1)}
+\strut
+\cs{newcommand}\marg{\postdeschook{contributor}}{\comment{}
+ \cs{glsxtrifhasfield}\marg{bibtexentry}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\comment{}
+ \ics{glsxtrfieldforlistloop}
+ \marg{\cs{glscurrententrylabel}}\marg{bibtexentry}\comment{}
+ \marg{\csfmt{contributorhandler}}\comment{}
+ }\comment{}
+ \marg{\csfmt{par} No titles.}\comment{}
+}
+\strut
+\csfmt{begin}\marg{document}
+Sample\idx{nbspchar}\ics{cite}\marg{book-minimal,article-full,inbook-full,misc-minimal}.
+Another sample\idx{nbspchar}\cs{cite}\marg{booklet-minimal,misc-full,article-minimal}.
+\strut
+\csfmt{bibliographystyle}\marg{plain}
+\ics{bibliography}\marg{xampl}
+\strut
+\cs{printunsrtglossary}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}]
+\cs{printunsrtglossary*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}]
+\marg{\comment{}
+ \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{category}\comment{}
+ \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{}
+ \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{}
+}
+\strut
+\csfmt{end}\marg{document}
+\end{codeenv}
+If the file is called \filefmt{myDoc.tex} then the document build
+is:
+\begin{codeenv}
+pdflatex myDoc
+bib2gls \longarg{cite-as-record} myDoc
+bibtex myDoc
+pdflatex myDoc
+pdflatex myDoc
+\end{codeenv}
+
+\entrysection{progenitor}
+
+The \atentryfmt{progenitor} type of entries are the only place where
+the \field{adoptparents} field is permitted. The value should be a
+comma-separated list of labels. The \field{adoptparents} field
+must be set and must contain a least one label. If the value
+contains any of the characters \idx{backslashchar} (backslash),
+\idx{bgroupchar} (open brace) or \idx{egroupchar} (close brace) then
+the field will be interpreted (if the default \longarg{interpret} settings
+is on).
+
+Since entries are spawned before fields are processed, the
+\field{adoptparents} field is parsed before any field aliases
+(\csopt{field-aliases}) or replication (\csopt{replicate-fields})
+takes place. However, if the \field{adoptparents} field isn't found,
+\bibgls\ will check for a simple mapping in both the
+\csopt{field-aliases} and \csopt{replicate-fields} settings.
+
+This entry type creates a main \idx[textformat=emph]{progenitor}
+term (with all the given fields except \field{adoptparents})
+and $n$ spawned \idx[textformat=emph]{progeny} terms, where
+$n$ is the number of elements in the \field{adoptparents} field,
+that are dependent on the main term.
+
+Each of the spawned \idx{progeny} entries have the field identified by
+\csopt{adopted-parent-field} (\field{parent} by default) set to the
+corresponding element in the \field{adoptparents} field.
+
+All fields from the original definition are copied except for the
+\field{adoptparents}, \field{alias} and \field{parent} fields. The
+\field{parent} field is never copied, regardless of the value of
+\csopt{adopted-parent-field}. If the adopted parent field is
+changed to one that's contained in the original entry, it's value
+will be from \field{adoptparents} not the value from the original
+entry.
+
+The copied fields follow the same conditions as normal
+entries. (For example, unknown fields are ignored, case-changes are
+applied, if appropriate, and the \field{type} field must reference a
+valid glossary, if set.) If \csopt{progenitor-type} is set, then
+this assignment is made after the \idx{progeny} are created
+and only applies to the main \idx{progenitor} entry. The
+type for the \idx{progeny} can be set with \csopt{progeny-type}.
+For example, \csopt[same as parent]{progeny-type} will ensure
+that the \idx{progeny} are in the same glossary type as
+their parent entry.
+
+For example, an entry defined as:
+\begin{codeenv}
+\atentry{progenitor}\marg{\meta{id},
+ \field{adoptparents} = \marg{\meta{parent-1 id},\ldots,\meta{parent-N id}},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\end{codeenv}
+is essentially like:
+\begin{codeenv}
+\atentry{index}\marg{\meta{id},
+ \field{progeny} = \marg{\meta{parent-1 id}.\meta{id},\ldots,\meta{parent-N id}.\meta{id}},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\strut
+\atentry{index}\marg{\meta{parent-1 id}.\meta{id},
+ \field{progenitor} = \margm{id},
+ \field{parent} = \margm{parent-1 id},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\strut
+\ldots
+\strut
+\atentry{index}\marg{\meta{parent-N id}.\meta{id},
+ \field{progenitor} = \margm{id},
+ \field{parent} = \margm{parent-N id},
+ \meta{field-name-1} = \margm{text},
+ \ldots
+ \meta{field-name-n} = \margm{text}
+}
+\end{codeenv}
+This creates the main (\idx{progenitor}) \meta{id} entry, which
+contains all the fields (except for \field{adoptparents}) that were
+in the original \atentry{progenitor} definition and has the new
+field \field{progeny} set to the comma-separated list of spawned
+entry labels. The main entries are defined in the \ext{glstex} file
+with \gls{bibglsnewprogenitor}.
+
+In addition to the main \meta{id} entry, the above also creates the
+spawned \idx{progeny} entries \code{\meta{parent-1 id}.\meta{id}}, \ldots,
+\code{\meta{parent-N id}.\meta{id}} that are dependent on the main
+\meta{id} entry.
+
+The spawned entries have the \field{parent} field set to the
+corresponding label obtained from the \field{adoptparents} list.
+This parent entry must also be defined, as usual for the
+\field{parent} field. (This restriction obviously doesn't apply if
+\csopt{adopted-parent-field} is changed from the default
+\field{parent}.) The spawned entries are defined in the \ext{glstex}
+file with \gls{bibglsnewspawnedindex}
+
+If the main \idx{progenitor} entry is referenced in the document
+then (assuming the default selection criteria) the spawned entries
+will also be automatically selected. You can check for the existence
+of the \field{progenitor} field using \cs{glsxtrifhasfield} and
+fetch the \field{location} field from the main entry, if required.
+
+Although the spawned entries are considered dependents of the main
+entry, the reverse doesn't apply. If a spawned entry is referenced
+in the document (with \code{\meta{parent-id}.\meta{id}}) then the
+main entry and its other spawned entries aren't automatically
+selected.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{indexplural}\marg{stylesheet, \field{text}=\marg{stylesheet language}}
+\strut
+\atentry{index}\marg{webdesign, \field{name}=\marg{web design}}
+\strut
+\atentry{indexplural}\marg{markup, \field{text}=\marg{markup language}}
+\strut
+\atentry{progenitor}\marg{xml,
+ \field{name}=\marg{XML},
+ \field{adoptparents}=\marg{markup}
+}
+\strut
+\atentry{progenitor}\marg{css,
+ \field{name}=\marg{CSS},
+ \field{adoptparents}=\marg{stylesheet,webdesign}
+}
+\strut
+\atentry{progenitor}\marg{html,
+ \field{name}=\marg{HTML},
+ \field{adoptparents}=\marg{markup,webdesign}
+}
+\strut
+\atentry{progenitor}\marg{xsl,
+ \field{name}=\marg{XSL},
+ \field{adoptparents}=\marg{stylesheet}
+}
+\end{codeenv}
+and if the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{stylemods},\styopt[index]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[all]{selection}}
+\strut
+\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cmd{begin}\marg{document}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Then the resulting list will be:
+\begin{quote}
+\setlength{\parindent}{0pt}%
+\setlength{\parskip}{0pt plus 0.3pt}%
+\glstreeitem CSS\par
+\glstreeitem HTML\par
+\glstreeitem markup language\par
+\glstreesubitem HTML\par
+\glstreesubitem XML\par
+\glstreeitem stylesheet language\par
+\glstreesubitem CSS\par
+\glstreesubitem XSL\par
+\glstreeitem web design\par
+\glstreesubitem CSS\par
+\glstreesubitem HTML\par
+\glstreeitem XML\par
+\glstreeitem XSL\par
+\end{quote}
+This allows the HTML and CSS entries to be listed under multiple
+parents.
+
+The following \atentryfmt{spawn\meta{single-type}} commands are all forms
+of \atentry{progenitor} that create the given
+\atentryfmt{\meta{single-type}} of entry. The spawned entries are actually
+created with the private entry type \atentryfmt{spawned\meta{type}}. In the
+case of \atentry{progenitor}, the spawned entries are defined as
+a \atentryfmt{spawnedindex} entry. These special
+\atentryfmt{spawned\meta{type}} entry types aren't intended for use
+in the \ext{bib} file, but if you reference the entry type (for
+example, with \csopt[same as entry]{category}) you will get
+\atentryfmt{spawned\meta{type}} as the entry type. The
+original entry type for the spawned entries is the same as
+the original entry for the main \atentry{progenitor} entry.
+
+There is currently only one form of dual \atentry{progenitor} entry and that's
+\atentry{spawndualindexentry}. Only the main \idx{progenitor} entry
+is a dual entry. The spawned \idx{progeny} are all \atentry{index}
+primary entries.
+
+\entrysection{spawnindex}
+
+As \atentry{progenitor}, but the main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnindex} and the
+spawned entries are defined with \gls{bibglsnewspawnedindex}.
+
+\entrysection{spawnindexplural}
+
+As \atentry{progenitor}, except that it creates
+\atentry{indexplural} terms instead of \atentry{index}.
+As with \atentry{indexplural}, if the \field{name} field isn't set,
+it's assigned to the same value as the \field{plural} field (or the
+fallback for the \field{plural}, if not defined).
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnindexplural} and the
+spawned entries are defined with \gls{bibglsnewspawnedindexplural}.
+
+\entrysection{spawnentry}
+
+As \atentry{progenitor}, except that it creates
+\atentry{entry} terms instead of \atentry{index}.
+As with \atentry{entry}, the \field{description} field is required
+and either \field{name} or \field{parent}.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnentry} and the
+spawned entries are defined with \gls{bibglsnewspawnedentry}.
+
+\entrysection{spawnabbreviation}
+
+As \atentry{progenitor}, except that it creates
+\atentry{abbreviation} terms instead of \atentry{index}.
+As with \atentry{abbreviation}, the \field{short} and \field{long}
+fields are required.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnabbreviation} and the
+spawned entries are defined with \gls{bibglsnewspawnedabbreviation}.
+
+\entrysection{spawnacronym}
+
+As \atentry{progenitor}, except that it creates
+\atentry{acronym} terms instead of \atentry{index}.
+As with \atentry{acronym}, the \field{short} and \field{long}
+fields are required.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnacronym} and the
+spawned entries are defined with \gls{bibglsnewspawnedacronym}.
+
+\entrysection{spawnsymbol}
+
+As \atentry{progenitor}, except that it creates
+\atentry{symbol} terms instead of \atentry{index}.
+As with \atentry{symbol}, the required fields are \field{name} or
+\field{parent}, and the \field{description} field is required if the
+\field{name} field is missing.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnsymbol} and the
+spawned entries are defined with \gls{bibglsnewspawnedsymbol}.
+
+\entrysection{spawnnumber}
+
+As \atentry{progenitor}, except that it creates
+\atentry{number} terms instead of \atentry{index}.
+As with \atentry{number}, the required fields are \field{name} or
+\field{parent}, and the \field{description} field is required if the
+\field{name} field is missing.
+
+The main entries are defined in the
+\ext{glstex} file with \gls{bibglsnewspawnnumber} and the
+spawned entries are defined with \gls{bibglsnewspawnednumber}.
+
+\entrysection{spawndualindexentry}
+
+As \atentry{progenitor}, except that the main (\idx{progenitor})
+entry behaves like \atentry{dualindexentry}. The spawned
+\idx{progeny} behave like \atentry{index} are so are all considered primary
+entries. The \field{adoptparents} field should therefore reference
+primary entries with the default \csopt[parent]{adopted-parent-field}.
+
+The main primary and secondary (dual) entries are defined in the
+\ext{glstex} file with
+\gls{bibglsnewspawndualindexentry} and
+\gls{bibglsnewspawndualindexentrysecondary}. The spawned
+\idx{progeny} are defined with \gls{bibglsnewspawnedindex}.
+
+\chapter{Resource File Options}
+\label{sec:resourceopts}
+
+Make sure that you use \isty{glossaries-extra} with the
+\styopt{record} package option. This ensures that \bibgls\ can pick
+up the required information from the \iext{aux} file, and both
+\styopt[only]{record} and \styopt[nameref]{record} additionally
+load the supplementary \isty{glossaries-extra-bib2gls} package.
+These two \styopt{record} option values also
+switch on the \styopt[none]{sort} package option (if you have a new
+enough version of the base \isty{glossaries} package), which means
+that there's no attempt to assign or process the \field{sort} key if
+it's omitted from \gls{newglossaryentry} (or similar commands). The
+\field{sort} key will be provided by \bibgls\ for informational
+purposes, but there's no need for \LaTeX\ to write it to any
+external files (unless you use the hybrid \styopt[alsoindex]{record},
+in which case you need to prevent \bibgls\ from sorting using the
+\csopt[none]{sort} resource option).
+
+The \iext{glstex} resource files created by \bibgls\ are loaded in
+the document using
+\nosecformatdef{glsxtrresourcefile}
+where \meta{filename} is the name of the resource file without the
+\ext{glstex} extension.
+You can have multiple \gls{glsxtrresourcefile} commands within your
+document, but each \meta{filename} must be unique, otherwise \LaTeX\
+would attempt to input the same \ext{glstex} file multiple times
+(\bibgls\ checks for non-unique file names). The associated data for each
+resource file is called the \idx{resourceset} (see
+\sectionref{sec:resourcesets}).
+
+There's a shortcut command that uses
+\ics{jobname} in the \meta{filename}:
+\nosecformatdef{GlsXtrLoadResources}
+The first instance of this command is equivalent to:
+\begin{codeenv}
+\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}}
+\end{codeenv}
+Any additional use of \gls{GlsXtrLoadResources} is equivalent to:
+\begin{codeenv}
+\gls{glsxtrresourcefile}\oargm{options}\marg{\ics{jobname}-\meta{n}}
+\end{codeenv}
+where \meta{n} is number. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}}
+\end{codeenv}
+This is equivalent to:
+\begin{codeenv}
+\gls{glsxtrresourcefile}\oarg{\csopt[entries-en]{src},\csopt[en]{sort}}\marg{\cs{jobname}}
+\gls{glsxtrresourcefile}\oarg{\csopt[entries-fr]{src},\csopt[fr]{sort}}\marg{\cs{jobname}-1}
+\gls{glsxtrresourcefile}\oarg{\csopt[entries-de]{src},\csopt[de-1996]{sort}}\marg{\cs{jobname}-2}
+\end{codeenv}
+In general, it's simplest just to use \gls{GlsXtrLoadResources}.
+
+The optional argument \meta{options} is a comma-separated
+\keyvallist. Allowed options are listed below. The option list
+applies only to that specific \meta{filename}\ext{glstex} and are
+not carried over to the next instance of \gls{glsxtrresourcefile}.
+Only the definitions provided in \atentry{preamble} (if the
+interpreter is on and \csopt[true]{interpret-preamble}) are carried
+over to the next resource set and, possibly,
+\idxpl{crossresourceref} if permitted (see
+\sectionref{sec:resourcesets}). The \sty{glossaries-extra} package
+doesn't parse the options, but just writes the information to the
+\ext{aux} file. This means that any invalid options will be reported
+by \bibgls\ not by \sty{glossaries-extra}.
+
+As from \sty{glossaries-extra} v1.40 you can provide a default set
+of options by redefining:
+\nosecdef{GlsXtrDefaultResourceOptions}
+This command will be inserted at the start of the options list for
+all resource commands (and will expand as it's written to
+the \ext{aux} file). For example:
+\begin{codeenv}
+\cs{renewcommand}\marg{\gls{GlsXtrDefaultResourceOptions}}\marg{\comment{}
+ \csopt[all]{selection},\csopt[entries]{src}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[symbols]{type},
+ \csopt[entrytype=symbol]{match}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\end{codeenv}
+This acts like:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},\csopt[entries]{src},
+ \csopt[symbols]{type},
+ \csopt[entrytype=symbol]{match}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},\csopt[entries]{src},
+ \csopt[abbreviations]{type},
+ \csopt[entrytype=abbreviation]{match}}
+\end{codeenv}
+
+If you have multiple \ext{bib} files you can either select them all
+using \csopt[\meta{bib list}]{src} in a single
+\gls{glsxtrresourcefile} call, if they all require the same settings,
+or you can load them separately with different settings applied.
+
+For example, if the files \filefmt{entries-terms.bib} and
+\filefmt{entries-symbols.bib} have the same settings:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
+\end{codeenv}
+Alternatively, if they have different settings:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},\csopt[main]{type}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[use]{sort},\csopt[symbols]{type}}
+\end{codeenv}
+
+Note that the sorting is applied to each \idx{resourceset} independently
+of other \idxpl{resourceset}. This means that if you have multiple instances
+of \gls{glsxtrresourcefile} but only one glossary type, the glossary
+will effectively contain blocks of sorted entries. For example, if
+\filefmt{file1.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\atentry{index}\marg{zebra}
+\atentry{index}\marg{aardvark}
+\end{codeenv}
+and \filefmt{file2.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{caterpillar}
+\atentry{index}\marg{bee}
+\atentry{index}\marg{wombat}
+\end{codeenv}
+then
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[file1,file2]{src}}
+\end{codeenv}
+will result in the list: aardvark, bee, caterpillar, duck, wombat,
+zebra. These six entries are all defined when
+\csfmt{jobname}\filefmt{.glstex} is read.
+Whereas
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[file1]{src}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[file2]{src}}
+\end{codeenv}
+will result in the list: aardvark, duck, zebra, bee, caterpillar,
+wombat. The first three (aardvark, duck, zebra) are defined when
+\csfmt{jobname}\filefmt{.glstex} is read. The second three (bee,
+caterpillar, wombat) are defined when \csfmt{jobname}\filefmt{-1.glstex}
+is read. Since \ics{printunsrtglossary} simply iterates over all
+defined entries, this is the ordering used.
+
+Abbreviation styles must be set (using \ics{setabbreviationstyle})
+before the resource command that selects the abbreviations from the
+appropriate \ext{bib} file, since the entries are defined (through
+\gls{newabbreviation} or \gls{newacronym}) when
+\gls{glsxtrresourcefile} inputs the \ext{glstex} file. (Similarly for any
+associated abbreviation style commands that must be set before
+abbreviations are defined, such as \cs{glsxtrlongshortdescname}.)
+
+Note \bibgls\ allows \iext{bib} files that don't provide any entries.
+This can be used to provide commands in \atentry{preamble}.
+For example, suppose I have \filefmt{defs.bib} that just contains:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{strong}}[1]\marg{\cs{textbf}\marg{\ics{cs.color}\marg{red}\idx{param}1}}
+\cs{providecommand}\marg{\cmd{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}}
+\end{codeenv}
+This provides two commands:
+\nosecdef{strong}
+(which sets the font weight and colour) and
+\nosecdef{parenswap}
+(which just displays its second argument followed by the first in parentheses).
+
+Suppose I also have \filefmt{entries.bib} that contains:
+\begin{codeenv}
+\atentry{index}\marg{example,
+ \field{name}=\marg{\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}}
+}
+\atentry{index}\marg{sample}
+\atentry{index}\marg{test}
+\atentry{index}\marg{foo}
+\atentry{index}\marg{bar}
+\end{codeenv}
+This contains an entry that requires the commands provided in
+\filefmt{defs.bib}, so to ensure those commands are defined, I can
+do:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src}}
+\end{codeenv}
+Unfortunately this results in the sort value for \code{example} being
+set to \code{redexample (stuff)} because the interpreter has
+detected the provided commands and expanded:
+\begin{codeenv}
+\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}
+\end{codeenv}
+to:
+\begin{codeenv}
+\cs{textbf}\marg{\cs{cs.color}\marg{red}example (stuff)}
+\end{codeenv}
+It discards font changes, so \cs{textbf} is ignored, but it doesn't
+recognise \cs{cs.color} and so doesn't know that the first argument is
+just the colour specifier and therefore doesn't discard it.
+This means that \qt{\textbf{\color{red}example (stuff)}} is placed
+between \qt{foo} and \qt{sample} instead of between \qt{bar} and
+\qt{foo}.
+
+I can prevent the interpreter from parsing \atentry{preamble}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[defs,entries]{src},\csopt[false]{interpret-preamble}}
+\end{codeenv}
+Now when the sort value for \code{example} is obtained from:
+\begin{codeenv}
+\gls{strong}\marg{\gls{parenswap}\marg{stuff}\marg{example}}
+\end{codeenv}
+no expansion occurs (since \gls{strong} and \gls{parenswap} are now
+unrecognised) so the sort value ends up as:
+\code{stuffexample}
+which places \qt{\textbf{\color{red}example (stuff)}} between
+\qt{sample} and \qt{test}, which is again incorrect.
+
+The best thing to do in this situation is to split the provided
+commands into two \iext{bib} files: one that shouldn't be interpreted
+and one that should.
+
+For example, \filefmt{defs-nointerpret.bib}:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{strong}}[1]\marg{\cs{textbf}\marg{\cs{cs.color}\marg{red}\idx{param}1}}}}
+\end{codeenv}
+and \filefmt{defs-interpret.bib}:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{parenswap}}[2]\marg{\idx{param}2 (\idx{param}1)}}}
+\end{codeenv}
+Now the first one can be loaded with \csopt[false]{interpret-preamble}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[defs-nointerpret]{src},\csopt[false]{interpret-preamble}}
+\end{codeenv}
+This creates a \iext{glstex} file that provides \gls{strong} but
+doesn't define any entries. The other file \filefmt{defs-interpret.bib} can
+then be loaded with the default \csopt[true]{interpret-preamble}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret,entries]{src}}
+\end{codeenv}
+The provided commands are remembered by the interpreter, so you can
+also do:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[defs-interpret]{src}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\end{codeenv}
+The \emph{contents} of \atentry{preamble} are only written to the
+associated \iext{glstex} file, but the definitions contained within
+the \atentry{preamble} are retained by the interpreter for subsequent
+\idxpl{resourceset}.
+
+\section{General Options}
+\label{sec:generalopts}
+
+\optsection{charset}
+
+If the character \idx{encoding} hasn't been supplied in the \iext{bib} file
+with the encoding comment
+\begin{alltt}
+\idx{commentchar} Encoding: \meta{encoding-name}
+\end{alltt}
+then you can supply the correct encoding using
+\csopt[encoding-name]{charset}. In general, it's better to include
+the encoding in the \ext{bib} file where it can also be read by
+a \ext{bib} managing systems, such as JabRef.
+
+See \longarg{tex-encoding} for the encoding used to write the \ext{glstex}
+file.
+
+\optsection{interpret-preamble}
+
+This is a boolean option that determines whether or not the
+interpreter should parse the contents of \atentry{preamble}.
+The default is \optfmt{true}. If \optfmt{false}, the preamble
+contents will still be written to the \iext{glstex} file, but any
+commands provided in the preamble won't be recognised by the
+interpreter (see \sectionref{sec:texparserlib}).
+
+Related options are: \csopt{set-widest} (which uses the interpreter to determine
+the widest name for the \glostyle{alttree} style or the
+\isty{glossary-longextra} styles), \csopt{interpret-label-fields} (which governs
+whether or not fields that must only contain a label should be interpreted),
+\csopt{labelify} (which converts a field into a string suitable for use as a
+label), and \csopt{labelify-list} (which converts a field into a string suitable
+for use as a comma-separated list of labels).
+
+\optsection{write-preamble}
+
+This is a boolean option that determines whether or not the
+preamble should be written to the \ext{glstex} file. The default
+is \optfmt{true}. Note that the preamble will
+still be parsed if \csopt[true]{interpret-preamble} even if
+\csopt[false]{write-preamble}. This means it's possible to
+provide \bibgls\ command definitions in \atentry{preamble}
+that don't get seen by \LaTeX.
+
+\optsection{set-widest}
+
+The \glostyle{alttree} glossary style needs to know the widest
+\field{name} (for each level, if hierarchical). This can be set
+using \ics{glssetwidest} provided by the \styfmt{glossary-tree}
+package (or similar commands like \ics{glsupdatewidest} provided by
+\styfmt{glossaries-extra-stylemods}), but this requires knowing
+which name is the widest. Alternatively, one of the iterative commands
+such as \ics{glsFindWidestTopLevelName} can be used, which slows the
+document build as it has to iterate over all defined entries.
+
+The \isty{glossary-longextra} package, provided with
+\sty{glossaries-extra} v1.37+, also needs to know the widest name,
+but in this case only the top-level is needed. If this has already
+been found through the commands provided with the \glostyle{alttree}
+style then that value will be used as the default, but you can set another
+value that's only used for the \sty{glossary-longextra} styles with
+\ics{glslongextraSetWidest}.
+
+The \sty{glossaries-extra-bib2gls} package provides \ics{glsxtrSetWidest},
+which sets the widest name for those styles that need it. As from version
+1.8, \bibgls\ now checks for the existence of this command and will use it with
+\csopt{set-widest} to allow for the new styles provided by the
+\sty{glossary-longextra} package.
+
+The boolean option \csopt[true]{set-widest} will try to calculate
+the widest names for each hierarchical level to help remove the need
+to determine the correct value within the document.
+Since \bibgls\ doesn't know the fonts that will be used
+in the document or if there are any non-standard commands that
+aren't provided in the \ext{bib} files preamble, \emph{this option may not
+work}. For example, if one entry has the \field{name} defined as:
+\begin{codeenv}
+\field{name}=\marg{some \marg{\cmd{Huge} huge} text}
+\end{codeenv}
+and another entry has the \field{name} defined as:
+\begin{codeenv}
+\field{name}=\marg{some \marg{\cmd{small} small} text}
+\end{codeenv}
+then \bibgls\ will determine that the second name is the widest
+although the first will actually be wider when it's rendered in the
+document.
+
+When using this option, the transcript file will include the message:
+\begin{alltt}
+Calculated width of '\meta{text}': \meta{number}
+\end{alltt}
+where \meta{text} is \bibgls's interpretation of the contents of the
+\field{name} field and \meta{number} is a rough guide to the width
+of \meta{text} assuming the operating system's default serif font.
+The entry that has the largest \meta{number} is the one that will be
+selected. This will then be implemented as follows:
+\begin{itemize}
+\item If the \field{type} is unknown then:
+ \begin{itemize}
+ \item if the interpreter resolves all \field{name} fields to the
+ empty string (that is the \field{name} fields all consist of
+ unknown commands) then
+ \begin{itemize}
+ \item if there are child entries \gls{bibglssetwidestfallback}
+ is used,
+ \item otherwise \gls{bibglssetwidesttoplevelfallback} is used;
+ \end{itemize}
+ \item otherwise \gls{bibglssetwidest} is used.
+ \end{itemize}
+\item If the \field{type} is known then:
+ \begin{itemize}
+ \item if the interpreter resolves all \field{name} fields for that
+ type to the empty string (that is the \field{name} fields all consist of
+ unknown commands) then
+ \begin{itemize}
+ \item if there are child entries \gls{bibglssetwidestfortypefallback}
+ is used,
+ \item otherwise
+ \gls{bibglssetwidesttoplevelfortypefallback} is used;
+ \end{itemize}
+ \item otherwise \gls{bibglssetwidestfortype} is used.
+ \end{itemize}
+\end{itemize}
+This leaves \TeX\ to compute the width according to the document
+fonts. If \bibgls\ can't correctly determine the widest entry then
+you will need to use one of the commands provided by
+\sty{glossary-tree}, \sty{glossary-longextra} or
+\sty{glossaries-extra-stylemods} to set it.
+
+In general, if you have more than one glossary it's best to
+set the \field{type} using options like \csopt{type} and
+\csopt{dual-type} if you use \csopt{set-widest}.
+
+\optsection{entry-type-aliases}
+
+In the \ext{bib} file, the data is identified by
+\code{@\meta{entry-type}}, such as \atentry[noindex]{abbreviation}.
+It may be that you want to replace all instances of
+\code{@\meta{entry-type}} with a different
+type of entry. For example, suppose my \ext{bib} file
+contains abbreviations defined in the form:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{hypertext markup language},
+ \field{description} = \marg{a markup language for creating web pages}
+}
+\end{codeenv}
+but suppose in one of my documents I actually want all these
+abbreviations defined with \atentry[noindex]{dualabbreviationentry}
+instead of \atentry[noindex]{abbreviation}. Instead of editing
+the \ext{bib} file I can just supply a mapping:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[abbreviation=dualabbreviationentry]{entry-type-aliases}
+}
+\end{codeenv}
+This makes all instances of \atentry[noindex]{abbreviation}
+behave as \atentry[noindex]{dualabbreviationentry}. You can have more than
+one mapping. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[
+ \comment{\atentry{abbreviation} -> \atentry{dualabbreviationentry}:}
+ abbreviation=dualabbreviationentry,
+ \comment{\atentry{entry} -> \atentry{index}:}
+ entry=index
+ ]{entry-type-aliases}
+}
+\end{codeenv}
+This option isn't cumulative. Multiple instances of
+\csopt{entry-type-aliases} override previous instances.
+If \meta{\keyvallist} is empty there will be no mappings.
+You can save the original entry type in the
+\field{originalentrytype} field with
+\csopt{save-original-entrytype}.
+
+Here's another example entry in a \ext{bib} file:
+\begin{codeenv}
+@foo\marg{html,
+ \field{name} = \marg{HTML},
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language},
+ \field{description} = \marg{hypertext markup language}
+}
+\end{codeenv}
+Ordinarily this entry would be ignored since \code{@foo}
+isn't recognised, but it can be mapped like this:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[short,long]{ignore-fields},
+ \csopt[foo=entry]{entry-type-aliases}
+}
+\end{codeenv}
+This treats the entry as though it had been defined as:
+\begin{codeenv}
+\atentry{entry}\marg{html,
+ \field{name} = \marg{HTML},
+ \field{description} = \marg{hypertext markup language}
+}
+\end{codeenv}
+whereas:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[name,description]{ignore-fields},
+ \csopt[foo=abbreviation]{entry-type-aliases}
+}
+\end{codeenv}
+treats the entry as though it had been defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+
+\optsection{unknown-entry-alias}
+
+If this option is set, the \meta{value} is used as the alias for any
+unknown entry types (after any aliases provided with
+\csopt{entry-type-aliases} have been applied). If the value is
+missing or empty, unknown entry types will be ignored with a
+warning.
+
+\optsection{action}
+
+This governs how the entries are written in the \iext{glstex} file.
+The \meta{value} may be one of:
+\begin{itemize}
+\item\code{define}: define the entries;
+\item\code{copy}: copy the entries;
+\item\code{define or copy}: copy existing entries and define
+non-existing entries.
+\end{itemize}
+The default setting is \csopt[define]{action}, which writes the entry
+definition to the \ext{glstex} file using one of the commands
+described in \sectionref{sec:newentrydefs}. Since the \styopt{record}
+package option automatically switches on the \styopt[warn]{undefaction}
+option, any attempt at defining an entry that's already been defined
+will generate a warning rather than an error. The duplicate
+definition will be ignored. (The warnings can be found in the
+\ext{log} file since they are warnings produce by
+\sty{glossaries-extra} not by \bibgls.)
+
+For example, if you try:
+\begin{codeenv}
+\cs{newglossary*}\marg{copies}\marg{Copies}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[use]{sort},\csopt[copies]{type},\csopt[entries]{src}}
+\end{codeenv}
+you'll find that the \code{copies} glossary is empty and there will
+be warnings in the \ext{log} file when the second resource file is
+loaded.
+
+There are various ways of having the same entries in multiple
+glossaries. The simplest method is to use \csopt{secondary}, but
+another method is to use \csopt[copy]{action} which simply writes
+\nosecformatdef{glsxtrcopytoglossary}
+instead of using one of the commands listed in
+\sectionref{sec:newentrydefs}. This copies the entries rather than
+defining them, which means the entries must already have been
+defined. The \meta{type} is determined as follows:
+\begin{itemize}
+\item if the entry has the \field{type} field set, that's used;
+\item if the entry is a tertiary and \csopt{tertiary-type} is set, that's
+used;
+\item if the entry is a dual and \csopt{dual-type} is set, that's
+used;
+\item otherwise the value of the \csopt{type} option is used.
+\end{itemize}
+If you're not sure whether the entries may already be defined, you
+can use \csopt[define or copy]{action} which will use
+\ics{ifglsentryexists} in the resource file to determine whether to
+define or copy the entry.
+
+Options that set or modify fields, such as \csopt{category},
+\csopt{group}, \csopt{save-locations}, \csopt{flatten} or
+\csopt{name-case-change}, will be ignored if entries are copied.
+However the \csopt{copy-action-group-field} may be used to copy
+the \field{group} field (which may have been locally set by the
+\csopt{sort} method) to another field. This ensures that the
+original \field{group} value from the entry definition in an earlier
+resource set won't be overwritten (unless you set
+\csopt[group]{copy-action-group-field}).
+
+Remember that \gls{glsxtrcopytoglossary} simply copies the entry's
+label to the glossary's internal list. The only checks that \bibgls\
+performs if \csopt{action} is not \code{define} is to ensure that
+the \csopt{master} or \csopt{secondary} options have not been used,
+since they're incompatible, and that the \csopt{type} option is set,
+since it's required as a fallback for any entries that don't have
+the \field{type} field set. (There are too many options that alter
+field values to check them all and some may be used to alter the
+sorting.) The purpose of the copy action is simply to provide a
+duplicate list in a different order.
+
+Remember that if you are using \sty{hyperref}, you need to use
+\code{\printglossopt[false]{target}} in the optional argument of
+\ics{printunsrtglossary} for the glossary containing the copies to
+prevent duplicate hypertargets. Commands like \cs{gls} will link to
+the original entries. For example, in the preamble:
+\begin{codeenv}
+\cs{newignoredglossary}\marg{copies}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[use]{sort},
+ \csopt[copy]{action},
+ \csopt[copies]{type},
+ \csopt[entries]{src}
+}
+\end{codeenv}
+and later in the document:
+\begin{codeenv}
+\cs{printunsrtglossary}\oarg{\printglossopt[Glossary (Alphabetical)]{title},\printglossopt[\glostyle{indexgroup}]{style}}
+\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Glossary (Order of Use)]{title},
+ \printglossopt[index]{style},\printglossopt{nogroupskip},\comment{no grouping}
+ \printglossopt[false]{target}}
+\end{codeenv}
+Note also the need to use \code{nogroupskip} and a non-group style
+for the duplicates since the \field{group} field will have been
+assigned in the first resource set if \bibgls\ was invoked with
+\longarg{group}. The grouping is appropriate for alphabetical
+ordering but not for order of use.
+
+If you want different grouping for the duplicates, you can specify
+the field name to use in which to store the group information using
+\csopt{copy-action-group-field}. Unlike \csopt{secondary}, you
+will need to redefine \ics{glsxtrgroupfield} to the relevant field
+before you display the glossary. The simplest way to do this is with
+the starred form of \cs{printunsrtglossary}.
+For example, if \csopt[dupgroup]{copy-action-group-field} is added to
+the options for the second resource set:
+\begin{codeenv}
+\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[\glostyle{indexgroup}]{style}}
+ \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
+\end{codeenv}
+This just does:
+\begin{codeenv}
+\cmd{begingroup}
+ \cs{renewcommand}\marg{\ics{glsxtrgroupfield}}\marg{dupgroup}\comment{}
+ \cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[Duplicates]{title},\printglossopt[indexgroup]{style}}
+\cmd{endgroup}
+\end{codeenv}
+
+
+\section{Selection Options}
+\label{sec:selectionopts}
+
+\optsection{src}
+
+This identifies the \iext{bib} files containing the entry
+definitions. The value should be a comma-separated list of the
+required \ext{bib} files. These may either be in the current working
+directory or in the directory given by the \longarg{dir} switch or on
+\TeX's path (in which case \idx{kpsewhich} will be used to find
+them). The \ext{bib} extension may be omitted. Remember that if
+\meta{list} contains multiple files it must be grouped to protect
+the comma from the \meta{options} list.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
+\end{codeenv}
+indicates that \bibgls\ must read the files
+\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} and
+create the file given by \ics{jobname}\iext{glstex} on the first
+instance or \ics{jobname}\code{-}\meta{n}\ext{glstex} on subsequent
+use.
+
+With \code{\gls!{glsxtrresourcefile}\oargm{options}\margm{filename}}, if
+the \csopt{src} option is omitted,
+the \ext{bib} file is assumed to be \meta{filename}\ext{bib}. For example:
+\begin{codeenv}
+\gls{glsxtrresourcefile}\marg{entries-symbols}
+\end{codeenv}
+indicates that \bibgls\ needs to read the file
+\filefmt{entries-symbols.bib}, which contains the entry data, and create the file
+\filefmt{entries-symbols.glstex}. If the \ext{bib} file is
+different or if you have multiple \ext{bib} files, you need to use
+the \csopt{src} option.
+
+\gls{GlsXtrLoadResources} uses \ics{jobname} as the argument of
+\gls{glsxtrresourcefile} on the first instance, so:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{}
+\end{codeenv}
+will assume \csopt[\ics{jobname}]{src}. Remember that subsequent uses
+of \gls{GlsXtrLoadResources} append a suffix, so in general it's
+best to always supply \csopt{src}.
+
+If you have non-ASCII characters in the \ext{bib} filename but
+aren't using \XeLaTeX\ or \LuaLaTeX, then you will need to use
+\ics{detokenize} to prevent expansion when the information is
+written to the \ext{aux} file. Similarly for any special characters
+that need protecting (although it's better not to use special
+characters in filenames). For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{T2A}\marg{fontenc}
+\cmd{usepackage}\oarg{utf8}\marg{inputenc}
+\cmd{usepackage}\oarg{russian}\marg{babel}
+\cmd{usepackage}\oarg{record}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[\cs{detokenize}\marg{\textcyrillicmono{кириллица}}]{src},\comment{data in \textcyrillicmono{кириллица.bib}}
+ \csopt[all]{selection}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+\optsection{selection}
+
+By default all entries that have records in the \iext{aux} file will
+be selected as well as all their dependent entries. The dependent
+entries that don't have corresponding records on the first \LaTeX\
+run, may need an additional build to ensure their location lists
+are updated.
+
+Remember that on the first \LaTeX\ run the \iext{glstex} files don't
+exist. This means that the entries aren't defined at that point. The
+\styopt{record} package option additionally switches on the
+\styopt[warn]{undefaction} option, which means that you'll only get
+warnings rather than errors when you reference entries in the
+document. You can't use \ics{glsaddall} with
+\bibgls\ because the glossary lists are empty on the first run, so
+there's nothing for \ics{glsaddall} to iterate over.
+Instead, if you want to add all defined entries, you need to
+instruct \bibgls\ to do this with the \csopt{selection} option. The
+following values are allowed:
+\begin{itemize}
+\item \optfmt{recorded and deps}: add all recorded entries and
+their dependencies (default).
+\item \optfmt{recorded and deps and see}: as above but will also
+add unrecorded entries whose \field{see} or \field{seealso} field refers to a recorded entry.
+\item \optfmt{recorded no deps}: add all recorded entries but not
+their dependencies. The dependencies include those referenced in the
+\field{see} or \field{seealso} field or fields identified by
+\csopt{dependency-fields}, \field{parent} entries and those found referenced
+with commands like \ics{gls} in the field values that are parsed by
+\bibgls. With this setting, parents will be omitted unless they've
+been referenced in the document through commands like \ics{gls}.
+\item \optfmt{recorded and ancestors}: this is like the previous
+setting but parents are added even if they haven't been referenced
+in the document. The other dependent entries are omitted if they
+haven't been referenced in the document.
+\item \optfmt{all}: add all entries found in the \ext{bib} files
+supplied in the \csopt{src} option.
+\end{itemize}
+The \meta{value} must be supplied.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{run}
+\atentry{index}\marg{sprint,\field{see}=\marg{run}}
+\atentry{index}\marg{dash,\field{see}=\marg{sprint}}
+\end{codeenv}
+If the document only references the \qt{run} entry (for example,
+using \code{\cs{gls}\marg{run}}) then:
+\begin{itemize}
+\item If \csopt[recorded and deps]{selection}, only the \qt{run}
+entry is selected. The \qt{run} entry has a record, so it's
+selected, but it has no dependencies. Neither \qt{sprint} nor
+\qt{dash} have records, so they're not selected.
+\item If \csopt[recorded and deps and see]{selection}, the \qt{run}
+and \qt{sprint} entries are selected, but not the \qt{dash} entry.
+The \qt{run} entry is selected because it has a record. The
+\qt{sprint} entry doesn't have a record but its \field{see} field
+includes \qt{run}, which does have a record, so \qt{sprint} is also
+selected. The \qt{dash} entry doesn't have a record. Its
+\field{see} field references \qt{sprint}. Although \qt{sprint} has
+been selected, it doesn't have any records, so \qt{dash} isn't
+selected.
+\end{itemize}
+The above is just an example. The circuitous redirection of
+\qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and
+is best avoided (especially for an index where there are no accompanying
+descriptions and no \idx{locationlist} for the intermediate \qt{sprint}).
+A better method would be:
+\begin{codeenv}
+\atentry{index}\marg{run}
+\atentry{index}\marg{sprint,\field{see}=\marg{run}}
+\atentry{index}\marg{dash,\field{see}=\marg{run}}
+\end{codeenv}
+The \csopt[recorded and deps and see]{selection} in this case will
+select all three entries, and the document won't send the reader on a
+long-winded detour.
+
+Now suppose that the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{run,
+ \field{name} = \marg{run},
+ \field{description}=\marg{move fast using legs}
+}
+\strut
+\atentry{entry}\marg{sprint,
+ \field{name} = \marg{sprint},
+ \field{description}=\marg{run at full speed over short distance},
+ \field{seealso}=\marg{run}
+}
+\strut
+\atentry{entry}\marg{dash,
+ \field{name} = \marg{dash},
+ \field{description}=\marg{run in a great hurry},
+ \field{seealso}=\marg{sprint}
+}
+\end{codeenv}
+and suppose the document only references \qt{dash} (for example, with
+\code{\cs{gls}\marg{dash}}), then with the default \csopt[recorded and deps]{selection}
+\qt{dash} will be selected because it has a record, and \qt{sprint}
+will be selected because \qt{dash} requires it (for the cross-reference),
+and \qt{run} will be selected because \qt{sprint} requires it
+(for the cross-reference). In this case, neither \qt{sprint} nor \qt{run}
+have a \idx{locationlist} but they do both provide additional information
+for the reader in their descriptions.
+
+A better method here would be for each entry to have a cross-reference
+list that includes all related terms:
+\begin{codeenv}
+\atentry{entry}\marg{run,
+ \field{name} = \marg{run},
+ \field{description}=\marg{move fast using legs},
+ \field{seealso}=\marg{sprint,dash}
+}
+\strut
+\atentry{entry}\marg{sprint,
+ \field{name} = \marg{sprint},
+ \field{description}=\marg{run at full speed over short distance},
+ \field{seealso}=\marg{run,dash}
+}
+\strut
+\atentry{entry}\marg{dash,
+ \field{name} = \marg{dash},
+ \field{description}=\marg{run in a great hurry},
+ \field{seealso}=\marg{sprint,run}
+}
+\end{codeenv}
+Now, whichever one is indexed in the document, the other two will automatically
+be selected.
+
+\optsection{match}
+
+It's possible to filter the selection by matching field values.
+The value is required for this key but may be empty, which indicates
+that the setting is switched off, otherwise
+\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where
+\meta{key} is the name of a field or \optfmt{id} for the entry's
+label or \optfmt{entrytype} for the \bibgls\ entry type (as in
+the part after \verb|@| identifying the entry not the \field{type}
+field identifying the glossary label). If you've used
+\csopt{entry-type-aliases}, this refers to the target entry type not
+the original entry type specified in the \ext{bib} file.
+
+The \meta{regex} part should be a \idx{regex} conforming
+to
+\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
+Pattern class}~\cite{pattern}. The pattern is anchored
+(\code{oo}\idx{matchanydot}\idx{zeroormore} matches
+\code{oops} but not \code{loops}) and \meta{regexp} can't be
+empty. Remember that \TeX\ will expand the option list as
+it writes the information to the \ext{aux} file so take
+care with special characters. For example, to match a literal
+period use \cs{cs.string}\idx{cs.period} not \idx{cs.period} (backslash dot).
+
+If the field is missing its value it is assumed to be empty for
+the purposes of the pattern match even if it will be assigned a
+non-empty default value when the entry is defined. If the field is
+unrecognised by \bibgls\ any reference to it in \meta{\keyvallist} will
+be ignored.
+
+If a field is listed multiple times, the pattern for that
+field is concatenated using:
+\begin{alltt}
+(?:\meta{pattern-1})|(?:\meta{pattern-2})
+\end{alltt}
+where \meta{pattern-1} is the current pattern for that field
+and \meta{pattern-2} is the new pattern. This means it performs a
+logical OR\@. For the non-duplicate
+fields the logical operator is given by \csopt{match-op}.
+For example:
+\begin{codeenv}
+\csopt[and]{match-op},
+\csopt[
+ \field{category}=animals,
+ \fieldfmt{topic}=biology,
+ \field{category}=vegetables
+]{match}
+\end{codeenv}
+This will keep all the selected entries that satisfy:
+\begin{itemize}
+\item \field{category} matches \verb"(?:animals)|(?:vegetables)"
+
+(the \field{category} is either \optfmt{animals} or
+\optfmt{vegetables})
+
+\item[AND]
+
+\item \fieldfmt{topic} (custom key provided by user) is \code{biology}.
+\end{itemize}
+and will discard any entries that don't satisfy this condition.
+A message will be written to the log file for each entry
+that's discarded.
+
+Patterns for unknown fields will be ignored. If the entire
+list consists of patterns for unknown fields it will be
+treated as \csopt[\empty]{match}. That is, no filtering will be
+applied. In the above example, the custom \fieldfmt{topic} key must
+be provided before the first \gls{GlsXtrLoadResources} with
+\ics{glsaddkey} or \ics{glsaddstoragekey}.
+
+\optsection{match-op}
+
+If the value of \csopt{match} contains more than one
+\meta{key}=\meta{pattern} element, the \csopt{match-op}
+determines whether to apply a logical AND or a logical OR.
+The \meta{value} may be either \optfmt{and} or \optfmt{or}.
+The default is \csopt[and]{match-op}.
+
+\optsection{not-match}
+
+If \csopt[\meta{\keyvallist}]{match} would cause an entry to be
+selected then \csopt[\meta{\keyvallist}]{not-match} would cause that
+entry to be ignored. The value is required for this key but may be
+empty, which indicates that the setting is switched off. If you
+have both \csopt{match} and \csopt{not-match} in the same resource
+set, the last one listed takes precedence.
+
+\optsection{match-action}
+
+The default behaviour with \csopt{match} or \csopt{not-match}
+is to filter the selection. This may be changed to append to the
+selection instead. The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{filter}: (default) filter selection;
+\item\optfmt{add}: append any matches (with \csopt{match}) or
+non-matches (with \csopt{not-match}) to the selection.
+This setting can't be used with \csopt[use]{sort}.
+\end{itemize}
+For example, if I want to select all record entries and their
+dependencies, but I also want to make sure that any entries with
+the category set to \code{important} are always selected regardless
+of whether or not they have any records:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[add]{match-action},
+ \csopt[\field{category}=important]{match}
+}
+\end{codeenv}
+
+\optsection{limit}
+
+If \meta{number} is greater than 0 then this will truncate the
+list of selected entries after sorting to \meta{number} (if the list
+size is greater than that value). The transcript will show the
+message:
+\begin{alltt}
+Truncating according to limit=\meta{number}
+\end{alltt}
+When used with \csopt{shuffle}, this provides a means of randomly
+selecting at most \meta{number} entries. The default setting is
+\csopt[0]{limit} (no truncation). A negative value of \meta{number} is not
+permitted.
+
+If you have any dual entries, then the truncation will be applied to
+the combined list of primary and duals if \csopt[combine]{dual-sort}
+otherwise each list will be truncated separately by \meta{number},
+which results in a maximum of $2 \times \meta{number}$. Remember
+that tertiary entries are created when dual entries are defined in
+the \ext{glstex} file, so this will increase the total number of
+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{codeenv}
+\atentry{index}\marg{birds}
+\atentry{index}\marg{duck,\field{parent}=\marg{birds}}
+\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}}
+\atentry{index}\marg{swan,\field{parent}=\marg{birds}}
+\strut
+\atentry{index}\marg{minerals}
+\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{gold,\field{parent}=\marg{minerals}}
+\end{codeenv}
+and the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{save-child-count}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{duck} and \cs{gls}\marg{goose}.
+\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Then the \ext{glstex} file will contain:
+\begin{codeenv}
+\cs{GlsXtrSetField}\marg{birds}\marg{childcount}\marg{2}
+\cs{GlsXtrSetField}\marg{duck}\marg{childcount}\marg{0}
+\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{duck}
+\cs{GlsXtrSetField}\marg{goose}\marg{childcount}\marg{0}
+\gls{glsxtrfieldlistadd}\marg{birds}\marg{childlist}\marg{goose}
+\cs{GlsXtrSetField}\marg{minerals}\marg{childcount}\marg{3}
+\cs{GlsXtrSetField}\marg{amethyst}\marg{childcount}\marg{0}
+\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{amethyst}
+\cs{GlsXtrSetField}\marg{corundum}\marg{childcount}\marg{0}
+\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{corundum}
+\cs{GlsXtrSetField}\marg{quartz}\marg{childcount}\marg{0}
+\gls{glsxtrfieldlistadd}\marg{minerals}\marg{childlist}\marg{quartz}
+\end{codeenv}
+Note that although \code{birds} has three children defined in the
+\ext{bib} file, only two have been selected, so the child count is
+set to~2. Similarly the \code{minerals} entry has five children
+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{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[general]{category},\csopt{save-child-count}}
+\strut
+\cs{glsdefpostdesc}\marg{general}\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{childcount}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (child count: \cs{glscurrentfieldvalue}.)}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+\ics{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19.
+It's slightly more efficient than \ics{ifglshasfield} provided by
+the base \styfmt{glossaries} package, and it doesn't complain if the
+entry or field don't exist, but note that \ics{glsxtrifhasfield}
+implicitly scopes its content. Use the starred version to omit the
+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}.
+If \csopt[true]{flatten}, the sorting will ignore hierarchy and
+the \field{parent} field will be omitted when writing
+the definitions to the \ext{glstex} file, but the parent entries
+will still be considered a dependent ancestor from the
+\csopt{selection} point of view.
+
+Note the difference between this option and using
+\csopt[parent]{ignore-fields} which will remove the dependency
+(unless a dependency is established through another field).
+
+\optsection{flatten-lonely}
+
+This may take one of three values: \optfmt{false} (default),
+\optfmt{presort} and \optfmt{postsort}. The value must be supplied.
+
+Unlike the \csopt{flatten} option, which completely
+removes the hierarchy, the \csopt{flatten-lonely} option can be used
+to selectively alter the hierarchy. In this case only those entries
+that have a parent but have no siblings are considered. This option
+is affected by the \csopt{flatten-lonely-rule} setting. The conditions for
+moving a child up one hierarchical level are as follows:
+\begin{itemize}
+\item The child must have a parent, and
+\item the child can't have any selected siblings, and
+\item if \csopt[only unrecorded parents]{flatten-lonely-rule}
+ then the parent can't have a location list, where the location list
+ includes records and \field{see} or \field{seealso}
+ cross-references (for the other rules the parent may have a location
+ list as long as it only has the one child selected).
+\end{itemize}
+If the child is selected for hierarchical adjustment, the parent
+will be removed if:
+\begin{itemize}
+\item The parent has no location list, and
+\item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}.
+\end{itemize}
+
+The value of \csopt{flatten-lonely} determines whether the
+adjustment should be made before sorting (\optfmt{presort})
+or after sorting (\optfmt{postsort}). To disable this function
+use \csopt[false]{flatten-lonely}.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{birds}
+\atentry{index}\marg{duck,\field{parent}=\marg{birds}}
+\atentry{index}\marg{goose,\field{plural}=\marg{geese},\field{parent}=\marg{birds}}
+\atentry{index}\marg{swan,\field{parent}=\marg{birds}}
+\atentry{index}\marg{chicken,\field{parent}=\marg{birds}}
+\strut
+\atentry{index}\marg{vegetable}
+\atentry{index}\marg{cabbage,\field{parent}=\marg{vegetable}}
+\strut
+\atentry{index}\marg{minerals}
+\atentry{index}\marg{quartz,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{corundum,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{amethyst,\field{parent}=\marg{minerals}}
+\atentry{index}\marg{gypsum,\field{parent}=\marg{minerals}}
+\strut
+\atentry{index}\marg{aardvark}
+\atentry{index}\marg{bard}
+\atentry{index}\marg{buzz}
+\strut
+\atentry{index}\marg{item}
+\atentry{index}\marg{subitem,\field{parent}=\marg{item}}
+\atentry{index}\marg{subsubitem,\field{parent}=\marg{subitem}}
+\end{codeenv}
+and suppose the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{duck}.
+\cs{gls}\marg{quartz}, \cs{gls}\marg{corundum}, \cs{gls}\marg{amethyst}.
+\cs{gls}\marg{aardvark}, \cs{gls}\marg{bard}, \cs{gls}\marg{buzz}.
+\cs{gls}\marg{vegetable}, \cs{gls}\marg{cabbage}.
+\cs{gls}\marg{subsubitem}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Although the \code{duck} entry has siblings in the
+\filefmt{entries.bib} file, none of them have been recorded
+(indexed) in the document, nor has the parent \code{birds} entry.
+
+This document hasn't used \csopt{flatten-lonely}, so the default
+\csopt[false]{flatten-lonely} is assumed. This results in the
+hierarchical structure:
+\begin{description}\setlength\itemsep{0pt}%
+\item[A] \null
+\item[aardvark] 1
+\item[B] \null
+\item[bard] 1
+\item[birds] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[duck] 1
+ \end{description}
+\item[buzz] 1
+\item[I] \null
+\item[item] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[subitem] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[subsubitem] 1
+ \end{description}
+ \end{description}
+\item[M] \null
+\item[minerals] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[amethyst] 1
+ \item[corundum] 1
+ \item[quartz] 1
+ \end{description}
+\item[V] \null
+\item[vegetable] 1
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[cabbage] 1
+ \end{description}
+\end{description}
+(The \qt{1} in the above indicates the page number.)
+There are some entries here that look a little odd: \code{duck},
+\code{cabbage} and \code{subsubitem}. In each case they are a
+lone child entry. It would look better if they could be compressed,
+but I don't want to use the \csopt{flatten} option, as I still want
+to keep the mineral hierarchy.
+
+If I now add \csopt[postsort]{flatten-lonely}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[postsort]{flatten-lonely}}
+\end{codeenv}
+the hierarchy becomes:
+\begin{description}\setlength\itemsep{0pt}%
+\item[A] \null
+\item[aardvark] 1
+\item[B] \null
+\item[bard] 1
+\item[birds, duck] 1
+\item[buzz] 1
+\item[I] \null
+\item[item, subitem, subsubitem] 1
+\item[M] \null
+\item[minerals] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[amethyst] 1
+ \item[corundum] 1
+ \item[quartz] 1
+ \end{description}
+\item[V] \null
+\item[vegetable] 1
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[cabbage] 1
+ \end{description}
+\end{description}
+The \field{name} field of the \code{duck} entry has been
+set to:
+\begin{codeenv}
+\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{birds}\marg{duck}}
+\end{codeenv}
+the \field{text} field has been set to:
+\begin{codeenv}
+\field{text}=\marg{duck}
+\end{codeenv}
+the \field{group} field is copied over from the parent entry (\qt{B}),
+and the \field{parent} field has been adjusted, moving \code{duck}
+up one hierarchical level.
+Finally, the former parent \code{birds} entry has been removed (the default
+\csopt[only unrecorded parents]{flatten-lonely-rule} is in effect).
+
+The default definition of \gls!{bibglsflattenedchildpostsort}
+formats its arguments so that they are separated by a comma and
+space (\qt{birds, duck}). If the \field{text} field had been set
+in the original \atentry{index} definition of \text{duck}, it
+wouldn't have been altered. This adjustment ensures that in the
+document \code{\cs{gls}\marg{duck}} still produces \qt{duck} rather than
+\qt{birds, duck}.
+(If the child and parent \field{name} fields are identical,
+the terms are considered homographs. See below for further details.)
+
+The \code{subsubitem} entry has also been adjusted. This was done
+in a multi-stage process, starting with sub-items and then moving down
+the hierarchical levels:
+\begin{itemize}
+\item The \code{subitem} entry was adjusted, moving it from a
+sub-entry to a top-level entry. The \field{name} field was then
+modified to:
+\begin{codeenv}
+\field{name}=\marg{\gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}}
+\end{codeenv}
+This now means that the \code{subsubitem} entry is now a sub-entry
+(rather than a sub-sub-entry). The \code{subitem} entry now has no
+parent, but at this stage the \code{subsubitem} entry still has
+\code{subitem} as its parent.
+\item The \code{subsubitem} entry is then adjusted moving from a
+sub-entry to a top-level entry. The \field{name} field was then
+modified to:
+\begin{codeenv}
+\field{name}=
+\marg{\comment{}
+ \gls{bibglsflattenedchildpostsort}
+ \marg{\comment{}
+ \comment{name from former parent}
+ \gls{bibglsflattenedchildpostsort}\marg{item}\marg{subitem}\comment{}
+ }\comment{}
+ \marg{subsubitem}\comment{original name}
+}
+\end{codeenv}
+The first argument of \gls!{bibglsflattenedchildpostsort} is
+obtained from the \field{name} field of the entry's former parent
+(which is removed from the child's set of ancestors). This field
+value was changed in the previous step, and the change is
+reflected here.
+
+This means that the name for \code{subitem} will be displayed as
+\qt{item, subitem} and the name for \code{subsubitem} will be
+displayed as \qt{item, subitem, subsubitem}.
+
+\item The parent entries \code{item} and \code{subitem}
+are removed from the selection as they have no location lists.
+\end{itemize}
+
+Note that the \code{cabbage} sub-entry hasn't been adjusted. It
+doesn't have any siblings but its parent entry (\code{vegetable})
+has a location list so it can't be discarded.
+If I change the rule:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
+ \csopt[discard unrecorded]{flatten-lonely-rule},
+ \csopt[postsort]{flatten-lonely}
+}
+\end{codeenv}
+then this will move the \code{cabbage} entry up a level but the
+original parent entry \code{vegetable} will remain:
+\begin{description}\setlength\itemsep{0pt}%
+\item[A] \null
+\item[aardvark] 1
+\item[B] \null
+\item[bard] 1
+\item[birds, duck] 1
+\item[buzz] 1
+\item[I] \null
+\item[item, subitem, subsubitem] 1
+\item[M] \null
+\item[minerals] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[amethyst] 1
+ \item[corundum] 1
+ \item[quartz] 1
+ \end{description}
+\item[V] \null
+\item[vegetable] 1
+\item[vegetable, cabbage] 1
+\end{description}
+
+Remember that \csopt[postsort]{flatten-lonely} performs the
+adjustment after sorting. This means that the entries are still in
+the same relative location that they were in with the original
+\csopt[false]{flatten-lonely} setting. For example, \code{duck}
+remains in the B letter group before \qt{buzz}.
+
+With \csopt[presort]{flatten-lonely} the adjustments are made before
+the sorting is performed. For example, using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
+ \csopt[discard unrecorded]{flatten-lonely-rule},
+ \csopt[presort]{flatten-lonely}
+}
+\end{codeenv}
+the hierarchical order is now:
+\begin{description}\setlength\itemsep{0pt}%
+\item[A] \null
+\item[aardvark] 1
+\item[B] \null
+\item[bard] 1
+\item[buzz] 1
+\item[C] \null
+\item[cabbage] 1
+\item[D] \null
+\item[duck] 1
+\item[M] \null
+\item[minerals] \mbox{}
+ \begin{description}\setlength\itemsep{0pt}%
+ \item[amethyst] 1
+ \item[corundum] 1
+ \item[quartz] 1
+ \end{description}
+\item[S] \null
+\item[subsubitem] 1
+\item[V] \null
+\item[vegetable] 1
+\end{description}
+This method uses a different format for the modified \field{name}
+field. For example, the \code{duck} entry now has:
+\begin{codeenv}
+\field{name}=\marg{\gls{bibglsflattenedchildpresort}\marg{duck}\marg{birds}}
+\end{codeenv}
+The default definition of \gls{bibglsflattenedchildpresort} simply
+does the first argument and ignores the second. The sorting is then
+performed, but the interpreter recognises this command and can
+deduce that the sort value for this entry should be \code{duck},
+so \qt{duck} now ends up in the D letter group.
+
+If you provide a definition of \gls{bibglsflattenedchildpresort} in
+the \atentry{preamble}, it will be picked up by the interpreter.
+For example:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}}
+\end{codeenv}
+
+Note that the \field{text} field is only changed if not already set.
+This option may have unpredictable results for abbreviations as the
+\field{name} field (and sometimes the \field{text} field) is
+typically set by the abbreviation style. Remember that
+if the parent entry doesn't have a \idx{locationlist} and the rule isn't
+set to \optfmt{no discard} then the parent entry will be discarded
+after all relevant entries and their dependencies have been
+selected, so any cross-references within the parent entry (such as
+\ics{gls} occurring in the description) may end up being selected
+even if they wouldn't be selected if the parent entry didn't exist.
+
+With both \optfmt{presort} and \optfmt{postsort},
+if the parent \field{name} is the same as the child's \field{name}
+then the child is considered a homograph and
+the child's name is set to:
+\begin{codeenv*}
+\format{bibglsflattenedhomograph}
+\end{codeenv*}
+instead of the corresponding \csfmt{bibglsflattenedchild\ldots sort}.
+This defaults to just \meta{name}.
+
+
+\optsection{flatten-lonely-rule}
+
+This option governs the rule used by \csopt{flatten-lonely} to
+determine which sub-entries (that have no siblings) to adjust and
+which parents to remove. The value may be one of the following:
+\begin{description}
+\item[\optfmt{only unrecorded parents}] Only the sub-entries
+that have a parent without a \idx{locationlist} will be altered.
+The parent entry will be removed from the selection.
+This value is the default setting.
+\item[\optfmt{discard unrecorded}] This setting will adjust all
+sub-entries that have no siblings regardless of whether or not the
+parent has a \idx{locationlist}.
+Only the parent entries that don't have a location list will be
+removed from the selection.
+\item[\optfmt{no discard}] This setting will adjust all
+sub-entries that don't have siblings regardless of whether or not the
+parent has a \idx{locationlist}. No entries will be discarded, so parent
+entries that don't have a \idx{locationlist} will still appear in the
+glossary.
+\end{description}
+In the above, the \idx{locationlist} includes records and
+cross-references obtained from the \field{see} or \field{seealso}
+fields. See \csopt{flatten-lonely} for further details.
+
+\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{codeenv}
+\atentry{entry}\marg{ubik,
+ \field{name}=\marg{Ubik},
+ \field{description}=\marg{novel by Philip K. Dick},
+ \fieldfmt{identifier}=\marg{book},
+ \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
+ \fieldfmt{year}=\marg{1969}
+}
+\end{codeenv}
+then the field alias:
+\begin{codeenv}
+\csopt[\fieldfmt{author}=\field{parent}]{field-aliases}
+\end{codeenv}
+will treat:
+\begin{codeenv}
+ \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
+\end{codeenv}
+as though it had been defined as:
+\begin{codeenv}
+ \field{parent}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}},
+\end{codeenv}
+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{codeenv}
+\cs{providecommand}*\marg{\gls{sortmediacreator}}[2]\marg{\idx{param}2 \idx{param}1}
+\end{codeenv}
+then the \field{parent} field for the \code{ubik} entry
+will become \code{DickPhilipK} but the original value is stored
+internally when \csopt[create]{missing-parents} is set so that it
+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{codeenv}
+\atentry{index}\marg{DickPhilipK,
+ \field{name}=\marg{\gls{sortmediacreator}\marg{Philip K.}\marg{Dick}}
+}
+\end{codeenv}
+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}
+
+Suppose you have two documents \filefmt{mybook.tex} and
+\filefmt{myarticle.tex} that share a common glossary that's shown
+in \filefmt{mybook.pdf} but not in \filefmt{myarticle.pdf}.
+Furthermore, you'd like to use \isty{hyperref} and be able to click
+on a term in \filefmt{myarticle.pdf} and be taken to the relevant
+page in \filefmt{mybook.pdf} where the term is listed in the
+glossary.
+
+This can be achieved with the \catattr{targeturl} and
+\catattr{targetname} category attributes. For example, without
+\bibgls\ the file \filefmt{mybook.tex} might look like:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\cs{cs.makeglossaries}
+\strut
+\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}}
+\strut
+\cmd{begin}\marg{document}
+\cs{chapter}\marg{Example}
+\cs{gls}\marg{sample}.
+\strut
+\cs{printglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+The other document \filefmt{myarticle.tex} might look like:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}\marg{glossaries-extra}
+\strut
+\cs{newignoredglossary*}\marg{external}
+\ics{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf}
+\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}}
+\strut
+\gls{newglossaryentry}\marg{sample}\marg{\field{type}=external,\field{category}=external,
+ \field{name}=\marg{sample},\field{description}=\marg{an example}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{sample}.
+\cmd{end}\marg{document}
+\end{codeenv}
+In this case the \optfmt{main} glossary isn't used, but the category
+attributes allow a mixture of internal and external references, so
+the \optfmt{main} glossary could be used for the internal
+references. (In which case, \csfmt{makeglossaries} and
+\csfmt{printglossaries} would need to be added back to
+\filefmt{myarticle.tex}.)
+
+Note that both documents had to define the common terms. The above
+documents can be rewritten to work with \bibgls. First a \ext{bib}
+file needs to be created:
+\begin{codeenv}
+\atentry{entry}\marg{sample,
+ \field{name}=\marg{sample},
+ \field{description}=\marg{an example}
+}
+\end{codeenv}
+Assuming this file is called \filefmt{myentries.bib}, then
+\filefmt{mybook.tex} can be changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{book}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[record]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{chapter}\marg{Example}
+\cs{gls}\marg{sample}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+and \filefmt{myarticle.tex} can be changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[record]\marg{glossaries-extra}
+\strut
+\cs{newignoredglossary*}\marg{external}
+\cs{glssetcategoryattribute}\marg{external}\marg{targeturl}\marg{mybook.pdf}
+\cs{glssetcategoryattribute}\marg{external}\marg{targetname}\marg{\cs{glolinkprefix}\cs{glslabel}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[myentries]{src},
+ \csopt[none]{sort},
+ \csopt[external]{type},
+ \csopt[external]{category}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{sample}.
+\cmd{end}\marg{document}
+\end{codeenv}
+Most of the options related to sorting and the glossary format are
+unneeded here since the glossary isn't being displayed. This may be
+sufficient for your needs, but it may be that the book has changed
+various settings that have been written to \filefmt{mybook.glstex}
+but aren't present in the \iext{bib} file (such as
+\csopt[uc]{short-case-change}). In this case, you could just remember to copy
+over the settings from \filefmt{mybook.tex} to
+\filefmt{myarticle.tex}, but
+another possibility is to simply make \filefmt{myarticle.tex} input
+\filefmt{mybook.glstex} instead of using \gls{GlsXtrLoadResources}. This
+can work but it's not so convenient to set the label prefix, the
+type and the category. The \optfmt{master} option allows this, but
+it has limitations (see below), so in complex cases (in particular
+different label prefixes combined with hierarchical entries or cross-references) you'll have to use
+the method shown in the example code above.
+
+\optsection{master}
+
+This option will disable most of the options that relate to
+parsing and processing data contained in \iext{bib} files
+(since this option doesn't actually read any \ext{bib} files).
+It also can't be used with \csopt[copy]{action} or \csopt[define
+or copy]{action}.
+
+The use of \optfmt{master} isn't always suitable. In particular
+if any of the terms cross-reference each other, such as through
+the \field{see} or \field{seealso} field or the \field{parent} field or
+using commands like \ics{gls} in any of the other fields when
+the labels have been assigned prefixes. In this
+case you will need to use the method described in the example above.
+
+The \meta{name} is the name of the \iext{aux} file for the master
+document without the extension (in this case, \filefmt{mybook}). It
+needs to be relative to the document referencing it or an absolute
+path using forward slashes as the directory divider. Remember that
+if it's a relative path, the PDF files (\filefmt{mybook.pdf} and
+\filefmt{myarticle.pdf}) will also need to be located in the same
+relative position.
+
+When \bibgls\ detects the \csopt{master} option, it won't search for
+entries in any \ext{bib} files (for that particular resource set)
+but will create a \iext{glstex} file that inputs the master
+document's
+\ext{glstex} files, but it will additionally temporarily
+adjust the internal commands used to define entries so that
+the prefix given by \csopt{label-prefix}, the glossary type and the
+category type are all automatically inserted. If the \csopt{type}
+or \csopt{category} options haven't been used, the corresponding
+value will default to \optfmt{master}. The \catattr{targeturl}
+and \catattr{targetname} category attributes will automatically be
+set, and the glossary type will be provided using
+\code{\ics{provideignoredglossary*}\margm{type}}.
+
+The above \filefmt{myarticle.tex} can be changed to:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[record]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{book.sample}.
+\cmd{end}\marg{document}
+\end{codeenv}
+
+There are some settings from the master document that you
+still need to repeat in the other document. These include
+the label prefixes set when the master document loaded
+the resource files, and any settings in the master document
+that relate to the master document's entries.
+
+For example, if the master document loaded a resource file
+with \csopt[term.]{label-prefix} then you also need this
+prefix when you reference the entries in the dependent document
+in addition to the \optfmt{label-prefix} for the dependent document.
+Suppose \filefmt{mybook.tex} loads the resources using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[myentries]{src},\csopt[term.]{label-prefix}}
+\end{codeenv}
+and \filefmt{myarticle.tex} loads the resources using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[book.]{label-prefix},\csopt[mybook]{master}}
+\end{codeenv}
+Then the entries referenced in \filefmt{myarticle.tex} need
+to use the prefix \optfmt{book.term.}\ as in:
+\begin{codeenv}
+This is a \cs{gls}\marg{book.term.sample} term.
+\end{codeenv}
+
+Remember that the category labels will need adjusting to reflect the
+change in category label in the dependent document.
+
+For example, if \filefmt{mybook.tex} included:
+\begin{codeenv}
+\cs{setabbreviationstyle}\marg{long-short-sc}
+\end{codeenv}
+then \filefmt{myarticle.tex} will need:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{master}\marg{long-short-sc}
+\end{codeenv}
+(change \optfmt{master} to \meta{value} if you have used
+\csopt[\meta{value}]{category}). You can, of course, choose
+a different abbreviation style for the dependent document,
+but the category in the optional argument needs to be correct.
+
+\optsection{master-resources}
+
+If the master document has multiple resource files
+then by default all the master document's
+\iext{glstex} files will be input. If you don't want them all
+you can use \optfmt{master-resources} to specify
+only those files that should be included. The value \meta{list} is
+a comma-separated list of names, where each name corresponds
+to the final argument of \gls!{glsxtrresourcefile}.
+Remember that \gls{GlsXtrLoadResources} is just a shortcut
+for \gls{glsxtrresourcefile} that bases the name on \ics{jobname}.
+(Note that, as with the argument of \gls{glsxtrresourcefile},
+the \ext{glstex} extension should not be included in \meta{list}.) The file
+\primaryresourcefmt\ is considered the primary
+resource file and the files \suppresourcefmt{\meta{n}}
+(starting with \meta{n} equal to 1) are considered the supplementary resource files.
+
+For example, to just select the first and third of the
+supplementary resource files (omitting the primary
+\filefmt{mybook.glstex}):
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[mybook]{master},
+ \csopt[mybook-1,mybook-3]{master-resources}
+}
+\end{codeenv}
+
+\section{Field and Label Options}
+\label{sec:fieldlabelopts}
+
+The options in this section may be used to set or adjust field
+values or labels. Some field values are expected to be labels (such
+as \field{group}). These labels must not contain special
+characters or commands, but it's possible to convert a field value
+into a valid label using options such as \csopt{labelify}.
+
+\subsection{Label Options}
+\label{sec:labelopts}
+
+\optsection[\subsubsection]{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},
+\field{seealso} and \field{alias}). Although this option interprets
+commands within those fields, it doesn't strip any characters that
+can't be used within a label. The \field{see} field isn't included
+as it may optionally start with \code{\oargm{tag}} where \meta{tag}
+may legitimately contain \LaTeX\ code that shouldn't be interpreted.
+
+The default setting is \csopt[false]{interpret-label-fields}.
+Note that if this setting is on, \idxpl{crossresourceref} aren't
+permitted. This setting has no effect if the interpreter has been
+disabled.
+
+Related settings are \csopt{labelify} and
+\csopt{labelify-list} which can be used to strip content that
+can't be used in labels and may be used more generally for other
+fields. The \csopt{labelify} and \csopt{labelify-list} options
+are performed before \csopt{interpret-label-fields}.
+
+\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
+\csopt{labelify-list}, then \csopt{labelify-list} takes precedence.)
+Note that if this setting is on, \idxpl{crossresourceref} aren't
+permitted. The value is required for this key but may be empty,
+which indicates an empty set of fields (that is, the setting is
+switched off).
+
+Each listed field will be converted into a string suitable
+for use as a label. (Not necessarily a glossary entry label, but
+any label that may be used in the construction of a control sequence
+name.)
+
+The conversion is performed in the following order:
+\begin{enumerate}
+\item If the interpreter is on and the field value contains
+any of the characters \idx{escchar}~(backslash),
+\idx{bgroupchar}~(begin group), \idx{egroupchar}~(end group),
+\idx{nbspchar}~(non-breakable space) or \idx{mshiftchar}~(maths shift),
+then the value is interpreted.
+
+\item Any substitutions that have been specified with
+\csopt{labelify-replace} are performed.
+
+\item All characters that aren't alphanumeric or the space character
+ or any of the following punctuation
+characters \code{.}~(full stop), \code{-}~(hyphen), \code{+}~(plus),
+\code{:}~(colon), \code{;}~(semi-colon), \code{\string|}~(pipe),
+\code{/}~(forward slash), \code{!}~(exclamation mark),
+\code{?}~(question mark), \code{*}~(asterisk), \code{<}~(less than),
+\code{>}~(greater than), \code{\textasciigrave}~(backtick),
+\code{'}~(apostrophe) or \code{@}~(at-sign) are stripped. If you want to
+retain commas, use \csopt{labelify-list} instead. If you want to
+strip any of the allowed punctuation, use \csopt{labelify-replace} to
+remove the unwanted characters. (Remember that \sty{babel} can make
+some of these punctuation characters active, in which case they need
+to be stripped.)
+
+\item If \bibgls\ hasn't detected \sty{fontspec} in the document's
+transcript file, the value is then decomposed and all non-ASCII
+characters are removed.
+\end{enumerate}
+
+For example, suppose the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{index}\marg{sample,
+ \field{name}=\marg{\ics{AA} ngstr\ics{umlaut}om, \ics{O} stergaard, d'Arcy, and Fotheringay-Smythe}
+}
+\end{codeenv}
+Then:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[name]{labelify}
+}
+\end{codeenv}
+will convert the \field{name} field into:
+\begin{verbatim}
+Angstrom stergaard d'Arcy and Fotheringay-Smythe
+\end{verbatim}
+if the document hasn't used \sty{fontspec} otherwise it will be:
+\begin{verbatim}
+Ångström Østergaard d'Arcy and Fotheringay-Smythe
+\end{verbatim}
+Note that \O\ is considered an unmodified letter and so can't
+be decomposed into a basic Latin letter with a combining diacritic.
+It's therefore removed completely from the non-\sty{fontspec}
+version. Whereas \AA\ can be decomposed into \qt{A} followed by the
+\qt{combining ring above} character and \"o can be decomposed into \qt{o}
+followed by the \qt{combining diaresis} character. You can use
+\csopt{labelify-replace} to replace non-ASCII characters into
+the closest match. Alternatively, switch to using \XeLaTeX\ or
+\LuaLaTeX.
+
+You can use this option with \csopt{replicate-fields} if you need
+to retain the original:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
+ \csopt[\field{user1}]{labelify}
+}
+\end{codeenv}
+
+\optsection[\subsubsection]{labelify-list}
+
+This option is like \csopt{labelify} but it retains commas, as it's
+designed for fields that should be converted into a comma-separated
+list of labels. Any empty elements are removed. For example, with
+the \ext{bib} entry from above:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
+ \csopt[\field{user1}]{labelify-list}
+}
+\end{codeenv}
+will convert the \field{user1} field into:
+\begin{verbatim}
+Angstrom, stergaard, d'Arcy, and Fotheringay-Smythe
+\end{verbatim}
+or:
+\begin{verbatim}
+Ångström, Østergaard, d'Arcy, and Fotheringay-Smythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
+\optsection[\subsubsection]{labelify-replace}
+
+This option takes a comma-separated list as a value with each
+element in the list in the form \code{\margm{regex}\margm{replacement}}
+where \meta{regex} is a \idx{regex} (that conforms to \href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's
+Pattern class}~\cite{pattern}) and \meta{replacement}
+is the replacement text. The value is required for this key but
+may be empty, which indicates that the
+setting is switched off.
+
+Remember that the argument of
+\gls{GlsXtrLoadResources} is expanded when written to the \ext{aux}
+file so take care to protect any special characters. For example, to
+match a literal \idx{full-stop} use \cs{cs.string}\idx{cs.period}
+rather than just \idx{cs.period} (backslash dot).
+
+In the \meta{replacement} part, you can use
+\ics{glscapturedgroup}\meta{n} to reference a captured sub-sequence.
+For example:
+\begin{codeenv}
+\csopt[\marg{([A-Z])\ics{cs.string}\idx{cs.period}}\marg{\cs{glscapturedgroup}1}]{labelify-replace}
+\end{codeenv}
+This removes any \idx{full-stop} that follows any of the characters
+A,\ldots,Z. Alternatively, you can just use \verb|\string\$|
+instead of \cs{glscapturedgroup}. If you want a literal dollar
+character, you need to use \cs{glshex}\code{24} (or
+\verb|\string\u24|). This isn't recommended for labels (since special
+characters are automatically stripped), but
+\csopt{sort-replace} follows the same rules as
+\csopt{labelify-replace}, and it may be needed
+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{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
+ \csopt[\marg{ and }\marg{,}]{labelify-replace},
+ \csopt[\field{user1}]{labelify-list}
+}
+\end{codeenv}
+The earlier example will now end up as:
+\begin{verbatim}
+Angstrom, stergaard, d'Arcy,Fotheringay-Smythe
+\end{verbatim}
+or:
+\begin{verbatim}
+Ångström, Østergaard, d'Arcy,Fotheringay-Smythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
+Note that this produces the same result regardless of whether or not
+the Oxford comma is present as \verb*|, and | would first be
+converted to \verb|,,| and then the empty element is removed
+resulting in a single comma.
+
+You can have more than one replacement:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[\field{name}=\marg{\field{user1}}]{replicate-fields},
+ \csopt[
+ \marg{ and }\marg{,},\comment{first substitution}
+ \marg{[ '\cs{cs.string}\cmd{-}]}\marg{},\comment{second substitution}
+ \marg{\ics{glshex}00D8}\marg{O}\comment{third substitution}
+ ]{labelify-replace},
+ \csopt[\field{user1}]{labelify-list}
+}
+\end{codeenv}
+This additionally removes the space, apostrophe and hyphen
+characters (second substitution) and replaces \qt{\O} (\hex{00D8})
+with \qt{O} (third substitution) so the string now ends up as:
+\begin{verbatim}
+Angstrom,Ostergaard,dArcy,FotheringaySmythe
+\end{verbatim}
+or:
+\begin{verbatim}
+Ångström,Ostergaard,dArcy,FotheringaySmythe
+\end{verbatim}
+depending on whether or not \sty{fontspec} was detected.
+
+\optsection[\subsubsection]{label-prefix}
+
+The \csopt{label-prefix} option prepends \meta{tag} to each entry's label. This
+\meta{tag} will also be inserted in front of any cross-references, unless they
+start with \idprefix{dual} or \idprefix{tertiary} or \idprefix{extn} (where
+\meta{n} is an integer). Use \csopt{dual-prefix} to change the dual label
+prefixes and \csopt{ext-prefixes} to change the external label prefixes.
+
+As from version 1.8, the primary label prefix is identified
+in the \ext{glstex} file with:
+\begin{codeenv}
+\format{bibglsprimaryprefixlabel}
+\end{codeenv}
+
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}}
+}
+\strut
+\atentry{entry}\marg{waterfowl,
+ \field{name}=\marg{waterfowl},
+ \field{description}=\marg{Any \cs{gls}\marg{bird} that lives in or about water},
+ \field{see}=\marg{[see also]\marg{duck,goose}}
+}
+\strut
+\atentry{index}\marg{duck}
+\strut
+\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
+\end{codeenv}
+Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix}
+it's as though the entries had been defined as:
+\begin{codeenv}
+\atentry{entry}\marg{gls.bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or \cs{gls}\marg{gls.goose}}
+}
+\strut
+\atentry{entry}\marg{gls.waterfowl,
+ \field{name}=\marg{waterfowl},
+ \field{description}=\marg{Any \cs{gls}\marg{gls.bird} that lives in or about water},
+ \field{see}=\marg{[see also]\marg{gls.duck,gls.goose}}
+}
+\strut
+\atentry{index}\marg{gls.duck,\field{name}=\marg{duck}}
+\strut
+\atentry{index}\marg{gls.goose,\field{name}=\marg{goose},\field{plural}=\qtdelim{geese}}
+\end{codeenv}
+
+Remember to use this prefix when you reference the terms in the
+document with commands like \ics{gls}.
+
+\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}, and \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{codeenv}
+\gls{glsxtr@record}\marg{bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\end{codeenv}
+The use of \csopt[idx.]{record-label-prefix} makes \bibgls\ act as
+though the records were given as:
+\begin{codeenv}
+\gls{glsxtr@record}\marg{idx.bird}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{idx.waterfowl}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{idx.duck}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{idx.goose}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\end{codeenv}
+
+
+\optsection[\subsubsection]{cs-label-prefix}
+
+If you have commands such as \code{\ics{gls}\margm{label}} or
+\code{\ics{glstext}\margm{label}} in field
+values (in situations where nested link text won't cause a problem)
+the \meta{label} will be converted as follows:
+\begin{itemize}
+\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{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{duck} or \cs{gls}\marg{goose}}
+}
+\end{codeenv}
+then if \csopt[idx.]{label-prefix} is set but \csopt{cs-label-prefix}
+isn't included in the resource option list this will convert the
+\field{description} field to:
+\begin{codeenv}
+\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{idx.duck} or
+\cs{gls}\marg{idx.goose}}
+\end{codeenv}
+However with \csopt[gls.]{cs-label-prefix} the \field{description}
+field will be converted to:
+\begin{codeenv}
+\field{description} = \marg{feathered animal, such as a \cs{gls}\marg{gls.duck} or
+\cs{gls}\marg{gls.goose}}
+\end{codeenv}
+regardless of the \csopt{label-prefix} setting. Whereas if the
+original entry definition is:
+\begin{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal, such as a \cs{gls}\marg{dual.duck} or
+\cs{gls}\marg{dual.goose}}
+}
+\end{codeenv}
+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[\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}).
+
+As from version 1.8, the external label prefixes are identified
+in the \ext{glstex} file with:
+\begin{codeenv}
+\format{bibglsexternalprefixlabel}
+\end{codeenv}
+
+For example, suppose the file \filefmt{entries-terms.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{set,
+ \field{name}=\marg{set},
+ \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.set}}
+}
+\end{codeenv}
+and the file \filefmt{entries-symbols.bib} contains:
+\begin{codeenv}
+\atentry{symbol}\marg{set,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}},
+ \field{description}=\marg{a \cs{gls}\marg{ext1.set}}
+}
+\end{codeenv}
+
+These files both contain an entry with the label \code{set}
+but the \field{description} field includes \code{\cs{gls}\marg{ext1.set}}
+which is referencing the entry from the other file. These
+two files can be loaded without conflict using:
+\begin{codeenv}
+\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms]{src},
+ \csopt[gls.]{label-prefix},
+ \csopt[sym.]{ext-prefixes}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},
+ \csopt[symbols]{type},
+ \csopt[sym.]{label-prefix},
+ \csopt[gls.]{ext-prefixes}
+}
+\end{codeenv}
+
+Now the \code{set} entry from \filefmt{entries-terms.bib}
+will be defined with the label \code{gls.set} and the
+description will be:
+\begin{codeenv}
+collection of values, denoted \cs{gls}\marg{sym.set}
+\end{codeenv}
+The \code{set} entry
+from \filefmt{entries-symbols.bib} will be defined with the label
+\code{sym.set} and the description will be:
+\begin{codeenv}
+a \cs{gls}\marg{gls.set}
+\end{codeenv}
+
+Note that in this case the \ext{bib} files have to be loaded
+as two separate resources. They can't be combined into a
+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{codeenv}
+\atentry{entry}\marg{set,
+ \field{name}=\marg{set},
+ \field{description}=\marg{collection of values, denoted \cs{gls}\marg{ext1.S}}
+}
+\end{codeenv}
+and \filefmt{entries-symbols.bib} could contain:
+\begin{codeenv}
+\atentry{symbol}\marg{S,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{mathcal}\marg{S}}},
+ \field{description}=\marg{a \cs{gls}\marg{ext1.set}}
+}
+\end{codeenv}
+Now they can be combined with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src}}
+\end{codeenv}
+which will simply strip the \glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}}
+prefix from the cross-references. Alternatively:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-terms,entries-symbols]{src},
+ \csopt[gls.]{label-prefix},
+ \csopt[gls.]{ext-prefixes}
+}
+\end{codeenv}
+which will insert the supplied \csopt{label-prefix} at the
+start of the labels in the entry definitions and will replace
+the \idprefixfmt{ext1} prefix with \idprefixfmt{gls} in the
+cross-references.
+
+\optsection[\subsubsection]{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[\subsubsection]{dependency-fields}
+
+The \meta{list} should be a comma-separated list of fields that
+have values in the form \code{\oargm{tag}\meta{id-list}} where
+\meta{id-list} is a comma-separated list of entry labels. The value
+is required for this key but may be empty, which indicates an empty
+set of fields (that is, the setting is switched off).
+
+This setting makes those fields act like the \field{see} field by
+identifying the listed entries as dependencies, but the information
+isn't added to the cross-reference part of the location list. This
+action is performed after \csopt{labelify-list}, if that's also set.
+
+For example, suppose the file \filefmt{entries-en.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{cat,
+ \fieldfmt{translations-pt}=\marg{gato,gatinho},
+ \field{seealso}=\marg{kitten}
+}
+\strut
+\atentry{index}\marg{kitten,
+ \fieldfmt{translations-pt}=\marg{gato,gatinho}
+}
+\strut
+\atentry{index}\marg{staple}
+\atentry{index}\marg{rivet}
+\atentry{index}\marg{mat}
+\atentry{index}\marg{carpet}
+\atentry{index}\marg{rug}
+\atentry{index}\marg{tapestry}
+\atentry{index}\marg{doormat}
+\atentry{index}\marg{matting}
+\atentry{index}\marg{coconut-matting,
+ \field{name}=\marg{coconut matting}
+}
+\atentry{index}\marg{track}
+\atentry{index}\marg{furrow}
+\end{codeenv}
+and suppose the file \filefmt{entries-pt.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{gato,
+ \field{prefix}=\marg{o},
+ \fieldfmt{translations-en}=\marg{cat,staple,rivet},
+ \field{seealso}=\marg{gatinho}
+}
+\strut
+\atentry{index}\marg{gatinho,
+ \fieldfmt{translations-en}=\marg{kitten}
+}
+\strut
+\atentry{index}\marg{tapete,
+ \fieldfmt{translations-en}=\marg{carpet,rug,mat,tapestry}
+}
+\strut
+\atentry{index}\marg{esteira,
+ \field{prefix}=\marg{a},
+ \fieldfmt{translations-en}=\marg{mat,track,matting,furrow}
+}
+\strut
+\atentry{index}\marg{capacho,
+ \field{prefix}=\marg{o},
+ \fieldfmt{translations-en}=\marg{doormat,matting,mat,coconut-matting}
+}
+\end{codeenv}
+The aim here is to have a document containing an
+English-to-Portuguese and a Portuguese-to-English dictionary. The
+custom \fieldfmt{translations-pt} and \fieldfmt{translations-pt}
+fields contain comma-separated lists of possible translations. In
+this case I don't want to use the \field{see} field (and, in fact,
+can't for the entries that have the \field{seealso} field set), but
+I can identify the values of those fields as dependent entries to
+ensure that they are selected even if they're not referenced in the
+document.
+
+For convenience I've aliased the custom fields to \field{user1}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[T1]\marg{fontenc}
+\cmd{usepackage}[utf8]\marg{inputenc}
+\cmd{usepackage}[british,brazilian]\marg{babel}
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt{nomain},
+ \styopt{nostyles},
+ \styopt[bookindex]{stylemods},
+ \styopt[\glostyle{bookindex}]{style}
+}\marg{glossaries-extra}
+\cmd{usepackage}\marg{\isty{glossaries-prefix}}
+\strut
+\cs{newglossary*}\marg{en}\marg{English Terms}
+\cs{newglossary*}\marg{pt}\marg{Portuguese Terms}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[en]{type},
+ \csopt[entries-en]{src},
+ \csopt[en-GB]{sort},
+ \csopt[en]{category},
+ \csopt[\fieldfmt{translations-pt}=\field{user1}]{field-aliases},
+ \csopt[\field{user1}]{dependency-fields},
+ \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[pt]{type},
+ \csopt[entries-pt]{src},
+ \csopt[pt-BR]{sort},
+ \csopt[pt]{category},
+ \csopt[\fieldfmt{translations-en}=\field{user1}]{field-aliases},
+ \csopt[\field{user1}]{dependency-fields},
+ \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list}
+}
+\strut
+\cs{apptoglossarypreamble}\oarg{en}\marg{\cs{selectlanguage}\marg{british}}
+\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}}
+\strut
+\cmd{begin}\marg{document}
+\cs{selectlanguage}\marg{british}
+The \cs{gls}\marg{cat} sat on the \cs{gls}\marg{mat}.
+\strut
+\cs{selectlanguage}\marg{brazilian}
+O \cs{gls}\marg{gato} sentou-se no \cs{gls}\marg{tapete}.
+\strut
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{prefix}}\marg{\idx{param}1}\marg{\ics{xmakefirstuc}\cs{glscurrentfieldvalue}\cs{cs.space}}\marg{}\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\idx{param}1}
+ \marg{; translations: \cs{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{}
+}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+\subsection{Assignments}
+\label{sec:fieldassignments}
+
+\optsection[\subsubsection]{group}
+
+The \csopt{group} option will set the \field{group} field to \meta{label}
+unless \meta{label} is \optfmt{auto}. If \csopt[auto]{group} then if
+the \longarg{group} switch is used the value of the \field{group}
+field is set automatically during the sorting (see also \csopt{group-formation}
+and \sectionref{sec:logicaldivisions}). If the \longarg{no-group}
+setting is on then \csopt[auto]{group} does nothing.
+
+The corresponding group title can be set with
+\gls{glsxtrsetgrouptitle} in the document if the title is different
+from the label. The default behaviour is \csopt[auto]{group}.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[integer]{sort},\csopt[Constants]{group},
+ \csopt[entries-constants]{src}\comment{data in entries-constants.bib}
+}
+\gls{GlsXtrLoadResources}\oarg{\csopt[letter-case]{sort},\csopt[Variables]{group},
+ \csopt[entries-variables]{src}\comment{data in entries-variables.bib}
+}
+\end{codeenv}
+In this case, if the \field{type} field hasn't been set in the \ext{bib} files,
+these entries will be added to the same glossary, but will
+be grouped according to each instance of \gls{GlsXtrLoadResources},
+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 \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}
+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 \idx!{lowercase} to ensure consistency.
+
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description} = \marg{feathered animal}
+}
+\strut
+\atentry{index}\marg{duck}
+\strut
+\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
+\strut
+\atentry{dualentry}\marg{dog,
+ \field{name}=\marg{dog},
+ \field{description}=\marg{chien}
+}
+\end{codeenv}
+then if the document contains:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[same as entry]{category},\csopt[entries]{src}}
+\end{codeenv}
+this will set the \field{category} of the \code{bird} term to \optfmt{entry}
+(since it was defined with \atentry{entry}), the \field{category} of the
+\code{duck} and \code{goose} terms to \optfmt{index} (since they were defined
+with \atentry{index}), and the \field{category} of the \code{dog} term to
+\optfmt{dualentry} (since it was defined with \atentry{dualentry}). Note that
+the dual entry \code{dual.dog} doesn't have the category set, since that's
+governed by \csopt{dual-category} instead.
+
+If, instead, the document contains:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}}
+\end{codeenv}
+then the \field{category} of all the primary selected entries will
+be set to \optfmt{animals}. Again the dual entry \code{dual.dog}
+doesn't have the \field{category} set.
+
+Note that the categories may be overridden by the commands that are used to
+actually define the entries (such as \gls!{bibglsnewindex}).
+
+For example, if the document contains:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{category}=\marg{dual}}\marg{\idx{param}4}\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[animals]{category},\csopt[entries]{src}}
+\end{codeenv}
+then both the \code{dog} and \code{dual.dog} entries will
+have their \field{category} field set to \optfmt{dual} since the
+new definition of \gls{bibglsnewdualentry} has overridden
+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 \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's parent (new to v1.9). If the entry doesn't have a parent
+or if the parent doesn't have the \field{type} field set, then
+no change is made. Entries should always have the same type
+as their parent, but it's possible for spawned entries to
+pick up the \field{type} field from their \idx{progenitor} entry
+(if it was explicitly set in the \ext{bib} file),
+which may be inappropriate.
+
+ \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{codeenv}
+\cmd{usepackage}[\styopt{record},\styopt{symbols}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[symbols]{type}}
+\end{codeenv}
+
+Make sure that the glossary type has already been defined
+(see \sectionref{sec:newglossary}). In the above, the
+\styopt{symbols} option defines the \code{symbols} glossary.
+If you want to use a custom glossary, you need to provide it. For
+example:
+\begin{codeenv}
+\cmd{usepackage}[\styopt{record},\styopt{nomain}]\marg{glossaries-extra}
+\strut
+\cs{newglossary*}\marg{dictionary}\marg{Dictionary}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries-symbols]{src},\csopt[dictionary]{type}}
+\end{codeenv}
+(The \styopt{nomain} option was added to suppress the
+creation of the default \code{main} glossary.)
+
+\optsection[\subsubsection]{trigger-type}
+
+The record counting commands, such as \gls{rgls}, use the special
+format \ics{glstriggerrecordformat}, which \bibgls\ also treats
+as an \idx{ignoredrecord}. This means the entry will still be
+identified as having a record for selection purposes, which is
+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
+\code{\ics{provideignoredglossary*}\margm{type}} to the \ext{glstex} file
+(see \sectionref{sec:newglossary}).
+
+\optsection[\subsubsection]{progenitor-type}
+
+This sets the default \field{type} field for the main term defined by
+\atentry{progenitor}-like entries. The \meta{value} is as for
+\csopt{type}. This doesn't change the \field{type} for the spawned
+\idx{progeny}.
+
+\optsection[\subsubsection]{progeny-type}
+
+This sets the default \field{type} field for the \idx{progeny} term
+spawned by
+\atentry{progenitor}-like entries. The \meta{value} is as for
+\csopt{type}. This doesn't change the \field{type} for the main
+\idx{progenitor}. Remember that with the default
+\csopt[parent]{adopted-parent-field} setting, the given type
+should match the type of the parent entry.
+
+\optsection[\subsubsection]{adopted-parent-field}
+
+This identifies the target field to be set to the corresponding
+value of the \field{adoptparents} list by the \idx{progeny}
+entries spawned by the \atentry{progenitor} type of entry.
+The default is \field{parent}.
+
+\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
+missing and it's required for some reason (for example, with
+\csopt[name]{sort-field}). If you prefer to
+fallback on a different field, then you can use this option to
+specify the field. For example,
+\csopt[long]{abbreviation-name-fallback}.
+The \meta{field} value must be a known field label.
+
+\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
+labels. Remember that unrecognised fields will always be skipped.
+
+For example, suppose my \ext{bib} file contains:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} =\qtdelim{html},
+ \field{long} = \marg{hypertext markup language},
+ \field{description}=\marg{a markup language for creating web pages},
+ \field{seealso}=\marg{xml}
+}
+\end{codeenv}
+but I want to use the \abbrstyle{short-long} style and I don't want
+the cross-referenced term, then I can use
+\csopt[seealso,description]{ignore-fields}.
+
+Note that \csopt[parent]{ignore-fields} removes the \field{parent}
+before determining the dependency lists. This means that
+\csopt[recorded and deps]{selection} and
+\csopt[recorded and ancestors]{selection} won't pick up the
+label in the \field{parent} field.
+
+If you want to maintain the dependency and ancestor relationship but
+omit the \field{parent} field when writing the entries to the
+\ext{glstex} file, you need to use \csopt{flatten} instead.
+
+\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
+list of \meta{field1}\dequals\meta{field2} pairs, where
+\meta{field1} and \meta{field2} are field names. Identical
+mappings and trails aren't permitted. (That is, \meta{field1}
+and \meta{field2} can't be the same nor can you have both
+\meta{field1}\dequals\meta{field2} and
+\meta{field2}\dequals\meta{field3}.) If you want to swap
+fields you need to use one of the dual entry types instead.
+Field aliases are performed before \csopt{ignore-fields},
+so if \meta{field1} is listed in \csopt{ignore-fields} it won't
+be ignored (unless \meta{field2} is in \csopt{ignore-fields}).
+
+For example, suppose \filefmt{people.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{alexander,
+ \field{name}=\marg{Alexander III of Macedon},
+ \field{description}=\marg{Ancient Greek king of Macedon},
+ \fieldfmt{born}=\marg{20 July 356 BC},
+ \fieldfmt{died}=\marg{10 June 323 BC},
+ \fieldfmt{othername}=\marg{Alexander the Great}
+}
+\end{codeenv}
+This contains three non-standard fields: \fieldfmt{born},
+\fieldfmt{died} and \fieldfmt{othername}. I could define
+these fields using \ics{glsaddkey}, but another possibility
+is to map these onto the user keys \field{user1}, \field{user2}
+and \field{user3}, which saves the overhead of providing new
+keys:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
+}
+\end{codeenv}
+
+\optsection[\subsubsection]{replicate-fields}
+
+The value of one field can be copied to other fields using
+this option where each \meta{key}\dequals\meta{value} pair
+is in the form
+\code{\meta{field1}\dequals\marg{\meta{field2},\meta{field3},\ldots}}
+where all values are field names. The value is required for this key
+but may be empty, which indicates that the setting is switched off.
+
+This option copies the contents
+of \meta{field1} to \meta{field2}, \meta{field3}, \ldots\
+(only if the target field isn't already set with
+\csopt[false]{replicate-override}). This action is
+performed after \csopt{ignore-fields} (see
+\sectionref{sec:resourcesets}). If the source field is missing, the
+\csopt{replicate-missing-field-action} setting determines the
+action.
+
+For example, suppose \filefmt{people.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{alexander,
+ \field{name}=\marg{Alexander III of Macedon (Alexander the Great)},
+ \field{text}=\marg{Alexander},
+ \field{description}=\marg{Ancient Greek king of Macedon}
+}
+\end{codeenv}
+Since the \field{first} field hasn't been supplied, it
+will default to the value of the \field{text} field, but
+perhaps for one of my documents I'd like the \field{first}
+field to be the same as the \field{name} field. Rather than
+editing the \ext{bib} file, I can just do:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\field{name}=\field{first}]{replicate-fields}
+}
+\end{codeenv}
+This copies the contents of the \field{name} field into the
+\field{first} field. If you have more than one field
+in the list take care to brace the lists to avoid confusion.
+For example, if for some reason I want to copy the value
+of the \field{name} field to both \field{first} and
+\field{firstplural} and copy the value of the \field{text}
+field to the \field{plural} field, then this requires braces
+for the inner list:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\field{name}=\marg{\field{first},\field{firstplural}},\field{text}=\field{plural}]{replicate-fields}
+}
+\end{codeenv}
+
+If my \filefmt{people.bib} file instead contained:
+\begin{codeenv}
+\atentry{entry}\marg{alexander,
+ \field{name}=\marg{Alexander III of Macedon (Alexander the Great)},
+ \field{first}=\marg{Alexander the Great},
+ \field{text}=\marg{Alexander},
+ \field{description}=\marg{Ancient Greek king of Macedon}
+}
+\end{codeenv}
+then:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\field{name}=\field{first}]{replicate-fields}
+}
+\end{codeenv}
+won't alter the \field{first} field since \csopt{replicate-fields}
+doesn't override existing values by default. You can use
+\csopt{replicate-override} to change this. Alternatively, since
+\csopt{replicate-fields} is always performed after \csopt{ignore-fields}
+it's possible to ignore the \field{first} field which means that the
+\field{name} value can then be copied into it:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\field{first}]{ignore-fields},
+ \csopt[\field{name}=\field{first}]{replicate-fields}
+}
+\end{codeenv}
+Note that the ordering within the resource options doesn't
+make a difference. The same result occurs with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},\comment{data in people.bib}
+ \csopt[\field{name}=\field{first}]{replicate-fields},
+ \csopt[\field{first}]{ignore-fields}
+}
+\end{codeenv}
+
+\optsection[\subsubsection]{replicate-override}
+
+This is a boolean option. The default setting is
+\csopt[false]{replicate-override}. If \optfmt{true},
+\csopt{replicate-fields} will override the existing value if the
+target field is already set.
+
+\optsection[\subsubsection]{replicate-missing-field-action}
+
+This option indicates what to do if a source field identified in
+\csopt{replicate-fields} is missing. The value may be one of:
+\begin{itemize}
+\item \optfmt{skip}: skip the replication of the missing field
+(default);
+\item \optfmt{fallback}: use the fallback for the missing field, if
+one is available (otherwise skip);
+\item \optfmt{empty}: make the target field empty.
+\end{itemize}
+
+\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{codeenv}
+\ics{printunsrtglossary*}\oarg{\printglossopt[copies]{type},\printglossopt[\glostyle{indexgroup}]{style}}
+ \marg{\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{dupgroup}}
+\end{codeenv}
+
+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{codeenv}
+\cs{printunsrtglossary}\oarg{\printglossopt{nogroupskip},\printglossopt[\glostyle{index}]{style}}
+\cs{printunsrtglossary}\oarg{\printglossopt[copies]{type},\printglossopt[indexgroup]{style}}
+\end{codeenv}
+
+\optsection[\subsubsection]{copy-alias-to-see}
+
+If set, the value of the \field{alias} field is copied to
+the \field{see} field. The default setting is \csopt[false]{copy-alias-to-see}.
+
+\optsection[\subsubsection]{save-original-entrytype}
+
+If this is set to \optfmt{true}, the original entry type
+(without the leading \idx{atchar}) is stored in the
+\field{originalentrytype} field. If no entry aliasing has been
+applied (with \csopt{entry-type-aliases}) the field will be set to
+the actual entry type.
+
+\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}.
+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{codeenv}
+\field{description}=\marg{sample\cs{nopostdesc}}
+\end{codeenv}
+since it's at the end. It will also be stripped from:
+\begin{codeenv}
+\field{description}=\marg{sample\cs{nopostdesc} }
+\end{codeenv}
+since the trailing space is ignored as it follows a control
+word. It won't be stripped from:
+\begin{codeenv}
+\field{description}=\marg{sample\cs{nopostdesc}\marg{} }
+\end{codeenv}
+because the final space is now significant, but even without the
+space it still won't be stripped as the field ends with
+an empty group not with \cs{nopostdesc}. Similarly it won't be
+stripped from:
+\begin{codeenv}
+\field{description}=\marg{sample\cs{nopostdesc}\cmd{relax}}
+\end{codeenv}
+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 \idx{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 \idx{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{codeenv}
+\atentry{entry}\marg{whydidnttheyaskevans,
+ \field{name}=\marg{Why Didn't They Ask Evans?},
+ \field{description}=\marg{novel by Agatha Christie},
+ \fieldfmt{identifier}=\marg{book},
+ \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Agatha}\marg{Christie}},
+ \fieldfmt{year}=\marg{1934}
+}
+\end{codeenv}
+With \csopt[name]{check-end-punctuation}, this entry will be
+assigned an internal field called
+\fielddisp{fieldendpunc}{nameendpunc} set to \code{?}\
+as that's included in \idx{sentence.terminators} and is found
+at the end of the \field{name} field:
+\begin{codeenv}
+\cs{GlsXtrSetField}\marg{whydidnttheyaskevans}\marg{nameendpunc}\marg{?}
+\end{codeenv}
+(Note that \csopt[first,text]{check-end-punctuation} won't match
+as there's no \field{first} or \field{text} field supplied.)
+
+If you have a field that ends with an abbreviation followed by a
+\idx{full-stop}, this will be considered an end of sentence terminator, but
+the main purpose of this option is to provide a way to deal with
+cases like:
+\begin{codeenv}
+Agatha Christie wrote \cs{gls}\marg{whydidnttheyaskevans}.
+\end{codeenv}
+where the end of sentence punctuation following \cs{gls} needs to be
+discarded. This is needed regardless of whether or not
+the link text ends with an abbreviation or is a complete sentence.
+
+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{codeenv}
+\cs{renewcommand}*\marg{\gls{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
+ \cs{GlsXtrIfFieldUndef}\marg{nameendpunc}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+This uses \ics{GlsXtrIfFieldUndef} rather than
+\ics{glsxtrifhasfield*} since there's no need to access the field's
+value. (The unstarred form \ics{glsxtrifhasfield} can't be used
+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]{sort-label-list}
+
+This option takes a list as the value with each element in the list
+in the form:
+\begin{codeenv}
+\code{\meta{field-list}:\meta{sort}:\meta{csname}}
+\end{codeenv}
+or:
+\begin{codeenv}
+\code{\meta{field-list}:\meta{sort}}
+\end{codeenv}
+where:
+\begin{itemize}
+\item \meta{field-list} is a comma-separated list of valid fields;
+\item \meta{sort} is a valid sort method as per the \csopt{sort}
+option, but not including \optfmt{none} or \optfmt{unsrt};
+\item \meta{csname} is the name (without a leading backslash) of a
+command that takes a label as its sole mandatory argument that's
+recognised by \bibgls' interpreter (such as those listed in
+\tableref{tab:bibglsdefs}).
+\end{itemize}
+The final \code{:\meta{csname}} part may be omitted if no command
+need be applied. (That is, sort by label.) The value is required for this key but
+may be empty, which indicates the setting is switched off.
+
+The sorting options are as those for the main list. For example,
+for entries in the primary list the break point is obtained from the
+\csopt{break-at} setting and for entries in the dual list the break
+point is obtained from \csopt{dual-break-at}. (Remember that if
+\csopt[combine]{dual-sort} then there is only one list that contains both
+the primary and dual entries, which is governed by the primary
+options only.)
+
+If the \meta{field-list} has more than one element
+take care to use braces \code{\marg{}} to avoid confusion for the
+list-parser. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[\marg{see,seealso}:en:glsentryname]{sort-label-list}
+}
+\end{codeenv}
+
+Note that strange results may occur if this setting is used on any
+fields that don't simply contain a list of entry labels or if any of
+the referenced entries are processed in different
+\idxpl{resourceset} (see \sectionref{sec:resourcesets}).
+
+After the main sorting of each set of selected entries is performed
+(as per \csopt{sort} or \csopt{dual-sort}), if this
+option is set, then for each
+\code{\margm{field-list}:\meta{sort}:\meta{csname}} the following
+steps are performed:
+\begin{enumerate}
+\item For each entry \meta{id}:
+ \begin{enumerate}
+ \item For each \meta{field} in \meta{field-list}, if the field is
+ set for entry \meta{id} then:
+
+ \begin{enumerate}
+ \item The field value must be in the form
+ \code{\oargm{tag}\meta{label-list}} where
+ \code{\oargm{tag}} is optional and
+ \meta{label-list} is a comma-separated list of entry labels
+ \meta{label$_1$}, \ldots, \meta{label$_n$};
+ \item A new list is constructed where the $i$th element is:
+ \code{\marg{\csfmt{}\meta{csname}\margm{label$_i$}}}
+ unless \meta{csname} hasn't been set, in which case the
+ $i$th element is just \margm{label$_i$} (the optional
+ \oargm{tag} part is omitted);
+ \item This new list is sorted according to the interpreter's
+ definition of the command given by \meta{csname} (if provided)
+ and the designated \meta{sort} method;
+ \item The field value is reconstructed with the labels in the
+ corresponding order (prefixed with \code{\oargm{tag}} if it was
+ present in the original).
+ \end{enumerate}
+ \end{enumerate}
+\end{enumerate}
+Note that there is no hierarchical structure in the sorting of the field list
+even if any of the referenced entries has a parent.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{bird}
+\strut
+\atentry{index}\marg{waterfowl, \field{parent}=\marg{bird} }
+\strut
+\atentry{index}\marg{duck,
+ \field{parent}=\marg{waterfowl},
+ \field{seealso}=\marg{swan,duckling,parrot,goose}
+}
+\strut
+\atentry{index}\marg{swan,
+ \field{parent}=\marg{waterfowl},
+ \field{seealso}=\marg{goose,duck}
+}
+\strut
+\atentry{index}\marg{goose,
+ \field{parent}=\marg{waterfowl},
+ \field{seealso}=\marg{duck}
+}
+\strut
+\atentry{index}\marg{parrot, \field{parent}=\marg{bird} }
+\strut
+\atentry{index}\marg{duckling,
+ \field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade}
+}
+\strut
+\atentry{index}\marg{fluffy}
+\strut
+\atentry{index}\marg{tardigrade, \field{name}=\marg{water bear} }
+\strut
+\atentry{index}\marg{velociraptor}
+\end{codeenv}
+And suppose the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt[tree]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[en]{sort},
+ \csopt[\marg{seealso,see}:en:glsentryname]{sort-label-list}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{parrot}, \cs{gls}\marg{tardigrade}, \cs{gls}\marg{swan}, \cs{gls}\marg{duck},
+\cs{gls}\marg{goose}, \cs{gls}\marg{fluffy} \cs{gls}\marg{duckling}, \cs{gls}\marg{velociraptor}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Then this reorders the \field{see} and \field{seealso} fields according to
+the referenced entry's name (obtained with \ics{glsentryname}).
+
+For example, the \field{see} field for the \code{duckling} entry was
+originally:
+\begin{codeenv}
+\field{see}=\marg{[related terms]fluffy,velociraptor,duck,tardigrade}
+\end{codeenv}
+but in the \ext{glstex} file it's written as:
+\begin{codeenv}
+\field{see}=\marg{[related terms]duck,fluffy,velociraptor,tardigrade}
+\end{codeenv}
+The reason for \code{tardigrade} being placed after
+\code{velociraptor} is because
+\code{\ics{glsentryname}\marg{tardigrade}} is expanded to \qt{water
+bear} (and \qt{W} comes after \qt{V}). If no encapsulating command
+was specified:
+\begin{codeenv}
+\csopt[\marg{seealso,see}:en]{sort-label-list}
+\end{codeenv}
+then the list would have been sorted according to the labels
+instead (and so \code{tardigrade} would come before
+\code{velociraptor}). Note that the optional tag is kept at the start of the
+list.
+
+The \field{seealso} fields have also been changed. For example,
+the \code{duck} entry originally had:
+\begin{codeenv}
+\field{seealso}=\marg{swan,duckling,parrot,goose}
+\end{codeenv}
+but in the \ext{glstex} file it's written as:
+\begin{codeenv}
+\field{seealso}=\marg{duckling,goose,parrot,swan}
+\end{codeenv}
+Note that the hierarchical structure hasn't been maintained. The glossary
+lists \qt{duckling} (a top-level entry) after \qt{swan} (a level~2 entry)
+but the \field{seealso} field has \code{duckling} first.
+
+If you want to maintain the hierarchy you can use \ics{glsxtrhiername} instead
+of \ics{glsentryname}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[en]{sort},
+ \csopt[\marg{seealso,see}:en:glsxtrhiername]{sort-label-list}
+}
+\end{codeenv}
+The separator between the levels is
+given by \ics{glsxtrhiernamesep} which is defined by
+\sty{glossaries-extra} to produce \qt{\glsxtrhiernamesep}.
+The \bibgls\ interpreter's definition of this command is different
+to assist sorting and simply expands to a \idx{full-stop} to prevent
+it from being replaced by the default word break marker.
+
+In this case \code{\ics{glsxtrhiername}\marg{swan}} would be
+displayed as \qt{bird\glsxtrhiernamesep waterfowl\glsxtrhiernamesep
+swan} if used in the document, but the interpreter converts it to
+\qt{bird.waterfowl.swan}, so with the default \csopt{break-at}
+setting the actual sort value becomes \code{bird.waterfowl.swan|}
+(instead of \code{bird|waterfowl|swan|} which would be the result if
+the interpreter used the same definition as \sty{glossaries-extra}).
+
+Therefore the \field{seealso} field for the \code{duck} entry ends up as:
+\begin{codeenv}
+\field{seealso}=\marg{parrot,goose,swan,duckling}
+\end{codeenv}
+Now \code{swan} comes before \code{duckling} because the actual sort
+value started with a \qt{B} not \qt{S}.
+
+This hierarchical information isn't shown in the cross-reference by
+default, so the \code{duck} cross-reference list appears in the
+document as: parrot, goose, swan \& duckling.
+
+If you want the hierarchical information to appear to help assist
+the reader, you can redefine \ics{glsseeitemformat} in the document
+to use \ics{glsxtrhiername}:
+\begin{codeenv}
+\cmd{renewcommand}*\marg{\cs{glsseeitemformat}}[1]\marg{\cs{glsxtrhiername}\marg{\idx{param}1}}
+\end{codeenv}
+This means that the \code{duck} cross-reference now appears in the
+document as: bird\glsxtrhiernamesep parrot, bird\glsxtrhiernamesep
+waterfowl\glsxtrhiernamesep goose, bird\glsxtrhiernamesep waterfowl
+\glsxtrhiernamesep swan \& duckling.
+
+This next example document has two languages, English and
+Portuguese. The file \filefmt{entries-en.bib} contains the English
+terms, such as:
+\begin{codeenv}
+\atentry{index}\marg{cat, \fieldfmt{translations}=\marg{gato,gatinho} }
+\atentry{index}\marg{kitten, \fieldfmt{translations}=\marg{gatinho} }
+\atentry{index}\marg{staple, \fieldfmt{translations}=\marg{grampo}}
+\atentry{index}\marg{rivet, \fieldfmt{translations}=\marg{rebite}}
+\end{codeenv}
+The file \filefmt{entries-pt.bib} contains the Portuguese
+terms, such as:
+\begin{codeenv}
+\atentry{index}\marg{gato, \fieldfmt{translations}=\marg{cat,staple,rivet} }
+\atentry{index}\marg{gatinho, \fieldfmt{translations}=\marg{kitten} }
+\end{codeenv}
+
+Both files have a custom field called \fieldfmt{translations} that
+will need to be either defined or aliased. This field contains a
+comma-separated list of labels for the corresponding entries in the
+other language file that provide a possible translation. Where a
+word has multiple possible translations, I'd like the list sorted
+alphabetically. (In practice, it would make more sense to sort them
+according to how likely the translation is, but this is for
+illustrative purposes.) For convenience, the
+custom field is simply aliased to the \field{user1} field.
+
+The document has two glossaries for each set of terms. The English
+terms are sorted according to \csopt[en-GB]{sort} in one
+\idx{resourceset} and the Portuguese terms are sorted according to
+\csopt[pt-BR]{sort} in another \idx{resourceset}. This means that there
+are cross-resource references, but since there are no instances of
+\atentry{preamble} it should be possible to resolve the references.
+
+The document code is:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[T1]\marg{fontenc}
+\cmd{usepackage}[utf8]\marg{inputenc}
+\cmd{usepackage}[british,brazilian]\marg{babel}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt{nomain},
+ \styopt{nostyles},
+ \styopt[bookindex]{stylemods},
+ \styopt[bookindex]{style}
+}\marg{glossaries-extra}
+\cmd{usepackage}\marg{glossaries-prefix}
+\strut
+\cs{newglossary*}\marg{en}\marg{English Terms}
+\cs{newglossary*}\marg{pt}\marg{Portuguese Terms}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},
+ \csopt[en]{type},
+ \csopt[entries-en]{src},
+ \csopt[en-GB]{sort},
+ \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases},
+ \csopt[\field{user1}:pt-BR:\encap{glsentryname}]{sort-label-list}
+}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[all]{selection},
+ \csopt[pt]{type},
+ \csopt[entries-pt]{src},
+ \csopt[pt-BR]{sort},
+ \csopt[\fieldfmt{translations}=\field{user1}]{field-aliases},
+ \csopt[\field{user1}:en-GB:\encap{glsentryname}]{sort-label-list}
+}
+\strut
+\cs{apptoglossarypreamble}\oarg{en}\marg{\ics{selectlanguage}\marg{british}}
+\cs{apptoglossarypreamble}\oarg{pt}\marg{\cs{selectlanguage}\marg{brazilian}}
+\strut
+\cmd{begin}\marg{document}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{glsxtrifhasfield}\marg{useri}\marg{\idx{param}1}\marg{: \ics{glsxtrseelist}\cs{glscurrentfieldvalue}}\marg{}\comment{}
+}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+In verbose mode, the transcript file indicates that it's performing
+the label list sorting. For example, when sorting according to
+\csopt[user1:pt-BR:glsentryname]{sort-label-list}, the transcript
+file contains:
+\begin{verbatim}
+Label list sort method 'pt-BR' on field: user1
+\end{verbatim}
+The \code{cat} entry has a list of two elements in this field:
+\code{gato,gatinho}. This is converted into a new list where the
+first element is:
+\begin{codeenv}
+\marg{\cs{glsentryname}\marg{gato}}
+\end{codeenv}
+and the second element is:
+\begin{codeenv}
+\marg{\cs{glsentryname}\marg{gatinho}}
+\end{codeenv}
+Regardless of the level of verbosity, the transcript file will
+contain the conversions obtained by the interpreter:
+\begin{verbatim}
+texparserlib: {\glsentryname{gato}} -> gato
+texparserlib: {\glsentryname{gatinho}} -> gatinho
+\end{verbatim}
+The \code{kitten} entry has the same list, and the same process is
+repeated for that entry. The \longarg{verbose} mode will provide additional
+information. The \longarg{debug} mode will indicate whether the
+referenced label was found in the current \idx{resourceset} or if it had
+to be fetched from another \idx{resourceset}. So if the resulting
+order isn't what you expect, check the transcript file for messages.
+
+\optsection[\subsubsection]{bibtex-contributor-fields}
+
+This option indicates that the listed fields all use \BibTeX's name
+syntax (as used in \BibTeX's \code{author} and \code{editor} fields). The value is required for this key but
+may be empty, which indicates an empty set of fields (that is, the
+setting is switched off).
+
+The values of these fields will be converted into the form:
+\begin{codeenv}
+\gls{bibglscontributorlist}\margm{contributor list}\margm{n}
+\end{codeenv}
+where \meta{n} is the number of names in the list and
+\meta{contributor-list} is a comma-separated list of names in the
+form:
+\begin{codeenv}
+\gls{bibglscontributor}\margm{forenames}\margm{von-part}\margm{surname}\margm{suffix}
+\end{codeenv}
+
+The \gls{bibglscontributorlist} command is initially defined in
+\bibgls's interpreter to just do the first argument and ignore the
+second. This means that if you're sorting on this field, the \qt{and}
+part between the final names doesn't appear in the sort value.
+The actual definition of \gls{bibglscontributorlist} provided in the
+\ext{glstex} file depends on whether or not \ics{DTLformatlist} is defined.
+(Note that \styfmt{glossaries} automatically loads \sty{datatool-base}
+so this command will be defined if you have at least v2.28 of
+\sty{datatool-base}.)
+
+For example, if the \field{name} field is specified as:
+\begin{codeenv}
+\field{name}=\marg{John Smith and Jane Doe and Dickie von Duck}
+\end{codeenv}
+then \csopt[name]{bibtex-contributor-fields} will convert the
+\field{name} field value to:
+\begin{codeenv}
+\gls{bibglscontributorlist}\marg{\comment{}
+ \gls{bibglscontributor}\marg{John}\marg{}\marg{Smith}\marg{},\comment{}
+ \gls{bibglscontributor}\marg{Jane}\marg{}\marg{Doe}\marg{},\comment{}
+ \gls{bibglscontributor}\marg{Dickie}\marg{von}\marg{Duck}\marg{}}\marg{3}
+\end{codeenv}
+With \csopt[von]{contributor-order} the sort value obtained from
+this field will be:
+\begin{verbatim}
+Smith, John,Doe, Jane,von Duck, Dickie
+\end{verbatim}
+With one of the locale sort methods and with the default
+\csopt[word]{break-at}, this will end up as:
+\begin{verbatim}
+Smith|John|Doe|Jane|von|Duck|Dickie
+\end{verbatim}
+
+\optsection[\subsubsection]{contributor-order}
+
+The \gls{bibglscontributor} command is defined in
+\bibgls's interpreter and its definition is dependent on this
+setting. The \meta{value} may be one of (where the parts in square
+brackets are omitted if that argument is empty):
+\begin{itemize}
+\item \optfmt{surname}: \gls{bibglscontributor} expands to
+\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}}\oarg{,
+\meta{von-part}};
+\item \optfmt{von}: \gls{bibglscontributor} expands to
+\oarg{\meta{von-part} }\meta{surname}\oarg{, \meta{suffix}}\oarg{, \meta{forenames}};
+\item \optfmt{forenames}: \gls{bibglscontributor} expands to
+\oarg{\meta{forenames} }\oarg{\meta{von-part} }\meta{surname}\oarg{,
+\meta{suffix}}.
+\end{itemize}
+The default value is \optfmt{von}. Note that if you have multiple
+resource sets, this option governs the way \bibgls's version of
+\gls{bibglscontributor} behaves. The actual definition is written to
+the \ext{glstex} using \cs{providecommand}, which means that \LaTeX\
+will only pick up the first definition.
+
+For example:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglscontributor}}[4]\marg{\comment{}
+ \idx{param}1\ics{ifstrempty}\marg{\idx{param}2}\marg{}\marg{ \idx{param}2} \idx{param}3\cs{ifstrempty}\marg{\idx{param}4}\marg{}\marg{, \idx{param}4}\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[name]{bibtex-contributor-fields}
+}
+\end{codeenv}
+This will display the names in the glossary with the forenames
+first, but \bibgls\ will sort according to surname.
+
+An alternative approach, if you need an initial resource set
+such as with the \exfile{no-interpret-preamble.bib} file:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[no-interpret-preamble]{src},
+ \csopt[false]{interpret-preamble},
+ \csopt[name]{bibtex-contributor-fields},
+ \csopt[forenames]{contributor-order}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[name]{bibtex-contributor-fields}
+}
+\end{codeenv}
+Note the need to use \csopt[name]{bibtex-contributor-fields}
+in the first resource set even though there are no entries in
+the \ext{bib} file. This is because the definition of
+\gls{bibglscontributor} is only written to the \ext{glstex} file if
+\csopt{bibtex-contributor-fields} has been set to a non-empty list.
+The second resource set will use the default
+\csopt[von]{bibtex-contributor-fields} setting when obtaining the
+sort value.
+
+\optsection[\subsubsection]{encapsulate-fields}
+
+This option should take a comma-separated list of
+\optfmt{\meta{field}\dequals\meta{cs-name-1arg}} values, where
+\meta{cs-name-1arg} is the name of a control sequence that takes
+one argument. The value is required for this key but
+may be empty, which indicates an empty set (that is, the
+setting is switched off).
+
+During the processing stage, each field identified in
+the list (if defined) will have its value replaced with:
+\begin{codeenv}
+\cmd{\meta{cs-name-1arg}}\margm{value}
+\end{codeenv}
+where \meta{value} was its previous value. An
+empty list switches off encapsulation (the default).
+
+This action overrides any previous use of \csopt{encapsulate-fields}
+within the same \idx{resourceset} and is always performed before
+\csopt{encapsulate-fields*}, regardless of the order in the
+\idx{resourceset}['s] list of options.
+
+\optsection[\subsubsection]{encapsulate-fields*}
+
+This option should take a comma-separated list of
+\optfmt{\meta{field}\dequals\meta{cs-name-2arg}} values, where
+\meta{cs-name-2arg} is the name of a control sequence that takes two
+arguments. The value is required for this key but
+may be empty, which indicates an empty set (that is, the
+setting is switched off).
+
+During the processing stage, each field identified in the
+list (if defined) will have its value replaced with:
+\begin{codeenv}
+\cmd{\meta{cs-name-2arg}}\margm{value}\margm{label}
+\end{codeenv}
+where \meta{value} was its previous value and \meta{label} is the
+entry's label (including prefix, if appropriate). An
+empty list switches off encapsulation (the default).
+
+This action overrides any previous use of
+\csopt{encapsulate-fields*} within the same \idx{resourceset}, and
+is always performed after \csopt{encapsulate-fields}, regardless of
+the order in the \idx{resourceset}['s] list of options, so if the
+same field is listed in both settings, its value will end up as:
+\begin{codeenv}
+\cmd{\meta{cs-name-2arg}}\marg{\cmd{\meta{cs-name-1arg}}\margm{value}}\margm{label}
+\end{codeenv}
+
+\optsection[\subsubsection]{interpret-fields}
+
+This option indicates that the listed fields should be replaced by
+their interpreted values. The value is required for this key but
+may be empty, which indicates an empty set of fields (that is, the
+setting is switched off). Other fields not listed may still be
+interpreted depending on other settings. As with the \field{sort}
+field, any special characters are replaced with commands like
+\ics{glsbackslash} and \ics{bibglsdollarchar}. This option is
+applied after \csopt{field-case-change} (if set).
+
+For example, suppose I have a file \filefmt{entries.bib} that
+contains definitions like:
+\begin{codeenv}
+\atentry{symbol}\marg{pi,
+ \field{name}=\marg{\cs{ensuremath}\marg{\ics{pi}}},
+ \field{description}=\marg{the ratio of a circle's circumference to its diameter},
+}
+\strut
+\atentry{symbol}\marg{sigma,
+ \field{name} = \marg{\cs{ensuremath}\marg{\ics{sigma}}},
+ \field{description} = \marg{standard deviation}
+}
+\end{codeenv}
+Instead of having a list of terms (glossary), suppose I want to have
+standalone definitions, where the term appears in a section heading.
+I could define a command like this:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
+ \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{section}\oarg{\cs{glsentryname}\marg{\idx{param}}}\marg{\cs{glsadd}\marg{\idx{param}1}\ics{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
+ \ics{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
+ }\comment{}
+ \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}\comment{}
+}
+\end{codeenv}
+which can be used in the document:
+\begin{codeenv}
+\ics{tableofcontents}
+\cmd{definition}\marg{pi}
+\cmd{definition}\marg{sigma}
+\end{codeenv}
+A problem with this definition of my custom command occurs if I add
+\sty{hyperref} to the document, because this tries to write \cs{pi}
+and \cs{sigma} to the PDF bookmarks, which doesn't work because
+those commands can't be automatically converted to characters
+permitted in a PDF string. This leads to a warning from
+\sty{hyperref}:
+\begin{alltt}
+Token not allowed in a PDF string (Unicode)
+\end{alltt}
+Ideally I'd like to be able to convert these symbols to Unicode so
+that they can appear in the bookmarks. Since \bibgls' interpreter
+recognises these commands, I can get it to make the conversion
+instead of trying to implement a method within \TeX:
+\begin{codeenv}
+\cs{glsaddstoragekey}\marg{pdfname}\marg{}\marg{\cmd{pdfname}}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[\field{name}=\fieldfmt{pdfname}]{replicate-fields},
+ \csopt[fallback]{replicate-missing-field-action},
+ \csopt[\fieldfmt{pdfname}]{interpret-fields}
+}
+\end{codeenv}
+This first copies the \field{name} field to the custom
+\fieldfmt{pdfname} and then interprets the copy. This leaves
+the \field{name} field with the \LaTeX\ code to produce the symbol
+in the document, but the \fieldfmt{pdfname} field ends up with all markup
+stripped by the interpreter and the \cs{pi} and \cs{sigma} are
+converted to the Unicode characters \hex{1D70B} (mathematical italic
+small pi) and \hex{1D70E} (mathematical italic small sigma). With
+\XeLaTeX\ or \LuaLaTeX\ these characters can be written to the PDF
+bookmarks by adjusting the definition of the custom command:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{definition}}[1]\marg{\comment{}
+ \cs{ifglsentryexists}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{section}
+ \oarg{\ics{texorpdfstring}\marg{\cs{glsentryname}\marg{\idx{param}1}}\marg{\cmd{pdfname}\marg{\idx{param}1}}}
+ \marg{\cs{glsadd}\marg{\idx{param}1}\cs{glsxtrglossentry}\marg{\idx{param}1}}\comment{}
+ \cs{Glossentrydesc}\marg{\idx{param}1}\cs{glspostdescription}
+ }\comment{}
+ \marg{\cs{section}\oarg{Missing `\idx{param}1'}\marg{\cs{glsadd}\marg{\idx{param}1}}}%
+}
+\end{codeenv}
+
+\optsection[\subsubsection]{date-time-fields}
+
+This option indicates that the listed fields all contain
+date and time information. Primary entries will have these fields
+parsed according to \csopt{date-time-field-format} and
+\csopt{date-time-field-locale} and dual entries will have these
+fields parsed according to \csopt{dual-date-time-field-format} and
+\csopt{dual-date-time-field-locale}. If the field value is missing
+or doesn't match the given pattern it remains unchanged, otherwise
+it's converted into the form:
+\formatdef{bibglsdatetime}
+where \meta{original} is the value of the field before conversion.
+If the interpreter is on, the value will be interpreted before
+being parsed if it contains \idx{escchar}, \idx{mshiftchar},
+\idx{bgroupchar}, \idx{egroupchar} or \idx{nbspchar}. (Remember that
+\idx{nbspchar} is converted to the non-breaking space character
+\hex{A0} unless \longarg{break-space} is used.)
+
+\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
+to:
+\formatdef{bibglsdate}
+The fields are parsed according to
+\csopt{date-field-format} and
+\csopt{date-field-locale} for primary entries and according to
+\csopt{dual-date-field-format} and
+\csopt{dual-date-field-locale} for dual entries.
+
+\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
+to:
+\formatdef{bibglstime}
+The fields are parsed according to
+\csopt{time-field-format} and
+\csopt{time-field-locale} for primary entries and according to
+\csopt{dual-time-field-format} and
+\csopt{dual-time-field-locale} for dual entries.
+
+\optsection[\subsubsection]{date-time-field-format}
+
+This option also sets
+\csopt[\meta{value}]{dual-date-time-field-format}.
+The value is the format pattern used when parsing fields identified
+by \csopt{date-time-fields}. The \meta{value} is as for
+\csopt{date-sort-format}.
+
+\optsection[\subsubsection]{date-field-format}
+
+This option also sets
+\csopt[\meta{value}]{dual-date-field-format}.
+The value is the format pattern used when parsing fields identified
+by \csopt{date-fields}. The \meta{value} is as for
+\csopt{date-sort-format}.
+
+\optsection[\subsubsection]{time-field-format}
+
+This option also sets
+\csopt[\meta{value}]{dual-time-field-format}.
+The value is the format pattern used when parsing fields identified
+by \csopt{time-fields}. The \meta{value} is as for
+\csopt{date-sort-format}.
+
+\optsection[\subsubsection]{date-time-field-locale}
+
+This option also sets
+\csopt[\meta{value}]{dual-date-time-field-locale}.
+The value is the locale used when parsing fields identified
+by \csopt{date-time-fields}. The \meta{value} is as for
+\csopt{date-sort-locale}.
+
+\optsection[\subsubsection]{date-field-locale}
+
+This option also sets
+\csopt[\meta{value}]{dual-date-field-locale}.
+The value is the locale used when parsing fields identified
+by \csopt{date-fields}. The \meta{value} is as for
+\csopt{date-sort-locale}.
+
+\optsection[\subsubsection]{time-field-locale}
+
+This option also sets
+\csopt[\meta{value}]{dual-time-field-locale}.
+The value is the locale used when parsing fields identified
+by \csopt{time-fields}. The \meta{value} is as for
+\csopt{date-sort-locale}.
+
+\subsection{Case-Changing}
+\label{sec:fieldcase}
+
+The \sty{glossaries-extra} package comes with the category
+attributes \catattr{glossdesc} and \catattr{glossname}, which may
+take the values \optfmt{firstuc} or \optfmt{title}. These don't
+change the actual \field{name} or \field{description} fields, but
+instead \ics{glossentryname} and \ics{glossentrydesc} (which are
+used by the default glossary styles) check for the corresponding
+attribute and apply the appropriate \idx{case-change} to the field value.
+
+So \ics{glossentryname} will use \ics{Glsentryname} if the
+\catattr{glossname} attribute for the given entry is set to \optfmt{firstuc}
+and \ics{glossentrydesc} will use \ics{Glsentrydesc} if the
+\catattr{glossdesc} attribute is set to \optfmt{firstuc}.
+The \optfmt{title} setting will instead use \ics{capitalisewords}
+applied to the field value.
+
+The resource options described in this section provide an
+alternative to those attributes that actually modify the relevant
+field (rather than just adjusting the style code used to display it).
+There are two forms of modification: the field is adjusted so that
+the original value is encapsulated by a command or \bibgls\ will
+perform the actual \idx{case-change} according to its own algorithm.
+The results can vary according to the field content.
+
+Only a subset of known fields have a resource option that can be
+used to apply a \idx{case-change}. For example, \csopt{name-case-change}
+can be used to change the case of the \field{name} field, but
+there's no equivalent option for the \field{text} field.
+
+Each of the case-changing resource options may take one of the
+following values:
+\begin{itemize}
+\item \optfmt{none}: don't apply any case-changing (default);
+
+\item \optfmt{lc-cs}: make \bibgls\ behave as though the field
+assignment:
+\begin{codeenv}
+\meta{field} = \margm{text}
+\end{codeenv}
+had actually been specified as:
+\begin{codeenv*}
+\meta{field} = \marg{\gls{bibglslowercase}\margm{text}}
+\end{codeenv*}
+which uses \TeX\ to convert the field to \idx{lowercase};
+
+\item \optfmt{uc-cs}: make \bibgls\ behave as though the field
+assignment:
+\begin{codeenv}
+\meta{field} = \margm{text}
+\end{codeenv}
+had actually been specified as:
+\begin{codeenv*}
+\meta{field} = \marg{\gls{bibglsuppercase}\margm{text}}
+\end{codeenv*}
+which uses \TeX\ to convert the field to \idx{uppercase};
+
+\item \optfmt{firstuc-cs}: make \bibgls\ behave as though the field
+assignment:
+\begin{codeenv}
+\meta{field} = \margm{text}
+\end{codeenv}
+had actually been specified as:
+\begin{codeenv*}
+\meta{field} = \marg{\gls{bibglsfirstuc}\margm{text}}
+\end{codeenv*}
+which uses \TeX\ to convert the field to first-letter \idx{uppercase};
+
+\item \optfmt{title-cs}: make \bibgls\ behave as though the field
+assignment:
+\begin{codeenv}
+\meta{field} = \margm{text}
+\end{codeenv}
+had actually been specified as:
+\begin{codeenv*}
+\meta{field} = \marg{\gls{bibglstitlecase}\margm{text}}
+\end{codeenv*}
+which uses \TeX\ to convert the field to \idx{titlecase};
+
+\item \optfmt{lc}: convert to \idx{lowercase} by making the
+appropriate modifications to tokens in the field value that have
+a known \idx{lowercase} alternative (see below);
+
+\item \optfmt{uc}: convert to \idx{uppercase} by making the
+appropriate modifications to tokens in the field value that have
+a known \idx{uppercase} alternative (see below);
+
+\item \optfmt{firstuc}: convert to first letter \idx{uppercase}
+by making the appropriate modification, if it has
+a known \idx{uppercase} alternative (see below);
+
+\item \optfmt{title}: convert to \idx{titlecase} by making the
+appropriate modifications to the first letter of each identified
+word in the field value that has a known \idx{uppercase}
+alternative (see below).
+
+A word-boundary is identified according to the
+\csopt{word-boundaries} setting. Words to be excluded from the
+case-changing (unless they occur at the start) can be identified
+with \ics{MFUnocap} in the \atentry{preamble} or you can use
+\code{\longarg{packages} mfirstuc-english} for the exclusion list
+provided by the \isty{mfirstuc-english} package. Alternatively, you
+can use \longarg{custom-packages} to load a simple package that
+contains the required \cs{MFUnocap} commands (in a similar style to
+\sty{mfirstuc-english}).
+
+The \bibgls\ word-boundary implementation is slightly different with
+this setting than with the \cs{capitalisewords} command (implemented
+in \TeX\ or by the \TeX\ parser library when interpreting field
+values). Only words in the exclusion list that start with an
+alphabetical character can be matched. Punctuation following a
+word-boundary is not considered part of the next word.
+
+\end{itemize}
+The \optfmt{firstuc-cs} and \optfmt{firstuc} options are essentially
+a \idx{sentencecase} change, but there's no check for
+sentence-breaks within the value, so even if the value contains
+multiple sentences, only the first is changed.
+
+The \optfmt{\meta{option}-cs} settings defer the actual case-changing
+to \TeX, which means that the case-changing has to be applied every
+time the field is typeset (and it introduces non-expandable content
+to the field value). Be aware of the limitations of using any of the
+case-changing commands. See the \isty{textcase} and \isty{mfirstuc}
+package documentation for further details~\cite{textcase,mfirstuc}.
+You may use \code{\ics{NoCaseChange}\margm{content}} (provided by
+\sty{textcase}) to prevent any \idx{case-change} to \meta{content}.
+
+For the settings where \bibgls\ itself performs the \idx{case-change}, then
+\bibgls\ will iterate over each token of the field value and apply
+the following rules:
+\begin{enumerate}
+
+\item If the token is a normal Unicode alphabetic character, it will
+be replaced with the corresponding upper or lower case character, as
+appropriate.
+For \optfmt{title} and \optfmt{firstuc}, the \idx{titlecase} character is
+used as the replacement, for \optfmt{uc} the \idx{uppercase} character is
+used as the replacement, and for \optfmt{lc} the \idx{lowercase} character
+is used as the replacement. Many characters have the same upper and
+title case alternative (for example, \qt{a} will be converted to \qt{A}
+for the \optfmt{title}, \optfmt{firstuc} and \optfmt{uc} settings), but
+some characters have different title and upper versions (for example,
+the digraph \qt{\char"01F3} has the title version \qt{\char"01F2}
+and \idx{uppercase} version \qt{\char"01F1}).
+
+If the option is \optfmt{firstuc} then all the remaining tokens are
+skipped. If the option is \optfmt{title} then the subsequent tokens
+are skipped until a word-boundary is found.
+
+\item If the token is a normal Unicode character that isn't alphabetical,
+then this token will be skipped for all options.
+
+\item If \code{\idx{mshiftchar}\meta{maths}\idx{mshiftchar}} is
+encountered, it will be skipped. If the option is \optfmt{firstuc}
+then all remaining tokens are skipped, so no \idx{case-change} will be
+performed.
+
+\item\label{case-change-group} If a group \code{\margm{content}} is
+found, then the \idx{case-change} is applied to the entire \meta{content}
+(which may be empty). This corresponds to the way \ics{makefirstuc}
+and \ics{capitalisewords} work if a~word starts with a group. Note
+that with \optfmt{firstuc} and \optfmt{title} the group content will
+be converted according to \optfmt{uc}, so the normal \idx{uppercase}
+character is used rather than the title case character (if they are
+different).
+
+If the option is \optfmt{firstuc} then all the remaining tokens are
+skipped. If the option is \optfmt{title} then the subsequent tokens
+are skipped until a word-boundary is found.
+
+\item If a control sequence \csfmt{}\meta{csname} is found, then:
+
+ \begin{enumerate}
+ \item If the control sequence is \cs{protect}, this token is skipped
+ for all options.
+
+ \item If the control sequence is one of: \ics{o}, \ics{O}, \ics{l},
+ \ics{L}, \ics{ae}, \ics{AE}, \ics{oe}, \ics{OE}, \ics{aa}, \ics{AA},
+ \ics{ss}, \ics{SS}, \ics{ng}, \ics{NG}, \ics{th}, \ics{TH},
+ \ics{dh}, \ics{DH}, \ics{dj} or \ics{DJ}, then
+ it's replaced with its \idx{case-change} counterpart (if not already the
+ correct case).
+
+ If the option is \optfmt{firstuc} then all the remaining tokens are
+ skipped. If the option is \optfmt{title} then the subsequent tokens
+ are skipped until a word-boundary is found.
+
+ \item If the control sequence is \ics{NoCaseChange} or is in the
+ \csopt{no-case-change-cs} list, then the
+ control sequence and its argument is ignored. With \optfmt{firstuc}
+ and \optfmt{title}, if \code{\ics{NoCaseChange}\margm{text}}
+ (but not any \csopt{no-case-change-cs} command)
+ occurs at the start of a word, then \bibgls\ will act as though
+ the word hasn't started yet (so the next token will be considered
+ for a \idx{case-change}). This is different to the way \ics{makefirstuc}
+ and \ics{capitalisewords} work.
+
+ \item If the control sequence is \ics{ensuremath}, \ics{si} or if
+ \meta{csname} ends with \qtt{ref} (for example, \ics{ref} or
+ \ics{pageref}) then the control sequence and its argument is ignored.
+ In the case where \meta{csname} ends with \qtt{ref}, a following
+ star (\code{*}) or optional argument before the mandatory argument
+ will also be skipped. This allows for some common cross-referencing
+ commands, such as \sty{hyperref}['s] \ics{autoref}, which may have
+ a starred form, but does not allow for more complicated commands with
+ multiple arguments.
+
+ If the option is \optfmt{firstuc} then all the remaining tokens are
+ skipped (so no \idx{case-change} will be performed). If the option is
+ \optfmt{title} then the subsequent tokens
+ are skipped until a word-boundary is found (so no \idx{case-change} is
+ performed for this word).
+
+ \item If the control sequence is \ics{glsentrytitlecase} then:
+ \begin{description}
+ \item[\optfmt{lc}] the control sequence is converted to
+ \ics{glsxtrusefield};
+ \item[\optfmt{uc}] the control sequence is converted to
+ \ics{GLSxtrusefield};
+ \item[\optfmt{firstuc}] the control sequence is converted to
+ \ics{Glsxtrusefield} and the remaining tokens are skipped;
+ \item[\optfmt{title}] the control sequence is left unchanged
+ and subsequent tokens are skipped until a word-boundary is found.
+ \end{description}
+ The field and entry label arguments are skipped.
+
+ \item If the control sequence is \ics{glshyperlink} then the
+ \idx{case-change} is applied to its optional argument. (If there was no
+ optional argument in the original field value, one will be inserted.)
+ The label argument is skipped.
+
+ If the option is \optfmt{firstuc} then all the remaining tokens are
+ skipped. If the option is \optfmt{title} then the subsequent tokens
+ are skipped until a word-boundary is found.
+
+ \item If the control sequence is \ics{glsdisp}, \ics{glslink},
+ \ics{dglsdisp} or \ics{dglslink} then the \idx{case-change} will be
+ applied to the appropriate argument. The optional argument (if
+ present) and the label are skipped.
+
+ If the option is \optfmt{firstuc} then all the remaining tokens are
+ skipped. If the option is \optfmt{title} then the subsequent tokens
+ are skipped until a word-boundary is found.
+
+ \item If the control sequence has a known case variant, it will be
+ substituted. For example, \ics{gls} will be changed to \ics{Gls}
+ or \ics{GLS}. In some cases there isn't an appropriate variant.
+ For example, \ics{glsentrytext} has a first-letter upper case
+ version \ics{Glsentrytext}, but not an all-caps version.
+
+ If the option is \optfmt{firstuc} then all the remaining tokens are
+ skipped. If the option is \optfmt{title} then the subsequent tokens
+ are skipped until a word-boundary is found.
+
+ \item If the control sequence is followed by a group, then the
+ appropriate \idx{case-change} is applied to the group contents.
+ Unlike step~\ref{case-change-group}, the \idx{case-change} isn't
+ applied to the entire group content with \optfmt{firstuc} and
+ \optfmt{title}. (Again, this follows the way that
+ \ics{makefirstuc} and \ics{capitalisewords} work.)
+
+ If there are subsequent groups, they won't be considered arguments,
+ but will be treated as groups, as per step~\ref{case-change-group}.
+ (This will only affect the \optfmt{title} setting as they will be
+ skipped by the \optfmt{firstuc} setting.) For complex cases,
+ consider using a semantic command that hides non-textual context
+ such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}.
+
+ \item Otherwise the control sequence is skipped.
+ \end{enumerate}
+
+\item Anything else is skipped.
+
+\end{enumerate}
+
+For example, if an entry is defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{HTML},
+ \field{long} = \marg{hypertext markup language},
+ \field{description}=\marg{a markup language for creating web pages}
+}
+\end{codeenv}
+then:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[lc]{short-case-change},
+ \csopt[title]{long-case-change},
+ \csopt[firstuc]{description-case-change}
+}
+\end{codeenv}
+will make the entry behave as if it had been defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{Hypertext Markup Language},
+ \field{description}=\marg{A markup language for creating web pages}
+}
+\end{codeenv}
+whereas:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[lc-cs]{short-case-change},
+ \csopt[title-cs]{long-case-change},
+ \csopt[firstuc-cs]{description-case-change}
+}
+\end{codeenv}
+will make the entry behave as if it had been defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{\gls{bibglslowercase}\marg{HTML}},
+ \field{long} = \marg{\gls{bibglstitlecase}\marg{hypertext markup language}},
+ \field{description}=\marg{\gls{bibglsfirstuc}\marg{a markup language for creating web pages}}
+}
+\end{codeenv}
+If the given field is missing, no change is made, except under
+certain circumstances (see the relevant resource option for details).
+For example, if an abbreviation is simply defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{hypertext markup language}
+}
+\end{codeenv}
+then:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[uc]{name-case-change},
+ \csopt[title]{description-case-change}
+}
+\end{codeenv}
+won't have an effect. Although the default \abbrstyle{long-short} abbreviation
+style sets the \field{name} and \field{description} fields, \bibgls\ doesn't
+have access to this information.
+
+Remember that you can create missing fields by copying the value
+from another field. So if the resource options are changed to:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[uc]{name-case-change},
+ \csopt[title]{description-case-change},
+ \csopt[\field{short}=\field{name},\field{long}=\field{description}]{replicate-fields}
+}
+\end{codeenv}
+then \bibgls\ will act as though the entry had been defined as:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \marg{html},
+ \field{long} = \marg{hypertext markup language},
+ \field{name} = \marg{HTML},
+ \field{description} = \marg{Hypertext Markup Language}
+}
+\end{codeenv}
+If the \abbrstyle{long-short-sc} abbreviation style is set (before
+\gls{GlsXtrLoadResources}) then this will override the default style
+for the \field{name} and \field{description}, so
+\code{\cs{gls}\marg{html}} will display the short form using
+\code{\ics{textsc}\marg{html}} but the \field{name} in the glossary
+will be displayed using just \code{HTML}.
+
+Note that with \atentry{index} the \field{name} and \field{text}
+fields will automatically be created if they are missing and
+\csopt{name-case-change} is used. For example, if an entry is
+defined as:
+\begin{codeenv}
+\atentry{index}\marg{duck}
+\end{codeenv}
+then \csopt[firstuc]{name-case-change} will make this entry behave
+as though it was defined as:
+\begin{codeenv}
+\atentry{index}\marg{duck,
+ \field{name} = \marg{Duck},
+ \field{text} = \marg{duck}
+}
+\end{codeenv}
+
+Suppose I have a slightly eccentric abbreviation definition:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \qtdelim{ht\cs{emph}\marg{ml}},
+ \field{long} = \qtdelim{hypertext markup language}
+}
+\end{codeenv}
+then \csopt[uc]{short-case-change} would convert the value of the
+\field{short} field into:
+\begin{codeenv}
+HT\cs{emph}{ML}
+\end{codeenv}
+Note that \csfmt{emph} isn't modified as it's recognised as a
+command. There's a difference between a group that follows a control
+sequence and one that doesn't. For example:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \qtdelim{\marg{ht}ml},
+ \field{long} = \qtdelim{hypertext markup language}
+}
+\end{codeenv}
+In this case \csopt[firstuc]{short-case-change} will convert the
+\field{short} field value to:
+\begin{codeenv}
+\marg{HT}ml
+\end{codeenv}
+(The entire contents of the group \code{\marg{ht}} has been
+converted.) Whereas with:
+\begin{codeenv}
+\atentry{abbreviation}\marg{html,
+ \field{short} = \qtdelim{\cs{emph}\marg{ht}ml},
+ \field{long} = \qtdelim{hypertext markup language}
+}
+\end{codeenv}
+then \csopt[firstuc]{short-case-change} will convert the
+\field{short} field value to:
+\begin{codeenv}
+\cs{emph}\marg{Ht}ml
+\end{codeenv}
+(Only the first letter of the argument \code{\marg{ht}} has been
+converted.)
+
+There's no attempt at interpreting the field contents at this point (but
+the value may later be interpreted during sorting).
+For example, suppose a \field{name} field is defined using:
+\begin{codeenv}
+\field{name} = \qtdelim{z\ics{ae}\ics{oe}},
+\end{codeenv}
+then with \csopt[uc]{name-case-change}, the value would be converted to
+\begin{codeenv}
+Z\ics{AE}\ics{OE}
+\end{codeenv}
+because \cs{ae} and \cs{oe} have known \idx{uppercase} versions.
+
+With \csopt[uc-cs]{name-case-change}, the \field{name}
+value would be converted to:
+\begin{codeenv}
+\gls{bibglsuppercase}\marg{z\cs{ae}\cs{oe}}
+\end{codeenv}
+If the interpreter is used during sorting, the sort value will be set to
+\code{Z\AE\OE} because the interpreter recognises all three commands.
+
+You can use \code{\ics{NoCaseChange}\margm{text}} to prevent the given
+\meta{text} from having the case changed. For example, if the \field{short}
+field is defined as:
+\begin{codeenv}
+\field{short} = \marg{a\cs{NoCaseChange}\marg{bc}d}
+\end{codeenv}
+then with \csopt[uc]{short-case-change}, this would be converted to
+\begin{codeenv}
+A\cs{NoCaseChange}\marg{bc}D
+\end{codeenv}
+
+Note that with \optfmt{firstuc} and \optfmt{title}, if
+\code{\ics{NoCaseChange}\margm{text}} occurs at the start of a word
+then it's skipped, and the case change is
+applied to the material following its argument. For example,
+suppose the \field{short} field is defined as:
+\begin{codeenv}
+\field{short}=\marg{\cs{NoCaseChange}\marg{h}tml}
+\end{codeenv}
+then the result is:
+\begin{codeenv}
+\cs{NoCaseChange}\marg{h}Tml
+\end{codeenv}
+whereas with:
+\begin{codeenv}
+\field{short}=\marg{\marg{}html}
+\end{codeenv}
+then the result is just \code{\marg{}html} (since the case change is
+applied to the empty group, which has no effect).
+
+If you have a command that takes a label or identifier as an argument then it's
+best to hide the label in a custom command. For example, if the
+\field{short} field in the \ext{bib} definition is defined as:
+\begin{codeenv}
+ \field{short} = \qtdelim{ht\ics{textcolor}\marg{red}\marg{ml}},
+\end{codeenv}
+then with \csopt[uc]{short-case-change} this would end up as:
+\begin{codeenv}
+HT\cs{textcolor}\marg{RED}\marg{ML}
+\end{codeenv}
+which is incorrect. Instead, provide a command that hides the label
+(such as the \csfmt{strong} example described on page~\glsxtrpageref{strong}).
+
+\optsection[\subsubsection]{no-case-change-cs}
+
+Instructs the non-\TeX\ case-changing options (where \bibgls, not
+\TeX, performs the modification) to treat the commands whose control
+sequence names are given in the comma-separated \meta{list} in the
+same way as it treats \cs{ensuremath} etc. That is, the case-change
+is omitted for the argument that follows any of those commands.
+
+For example, this manual defines some semantic commands such as
+\csfmt{fieldfmt} (to format field names), \csfmt{abbrstylefmt}
+(to format abbreviation style names) and \csfmt{glostylefmt} (to format
+glossary style names). These occur in some of the section
+and subsection headings in the \hyperref[sec:topics]{topic summary}
+which are converted to \idx{titlecase} (see \csopt{field-case-change}).
+These formatting commands shouldn't have their argument changed so they
+are identified with:
+\begin{codeenv}
+\csopt[fieldfmt,abbrstylefmt,glostylefmt]{no-case-change-cs}
+\end{codeenv}
+
+\optsection[\subsubsection]{word-boundaries}
+
+Governs how the \optfmt{title} \idx{case-change} option
+determines word boundaries. The \meta{list} must contain one or
+more of the following keywords:
+\begin{description}
+\item[\optfmt{white space}] any white space Unicode character
+that is not a non-breakable space indicates a word-boundary;
+\item[\optfmt{cs space}] the control sequences
+\ics{space} or \ics{cs.space} indicate a word-boundary;
+\item[\optfmt{dash}] a Unicode character that belongs to the
+\idx{punctuationdash} block indicates a word-boundary;
+\item[\optfmt{nbsp}] the \idx{nbspchar} active character or the Unicode
+non-breakable characters \hex{00A0}, \hex{2007} and \hex{202F}
+indicate a word-boundary.
+\end{description}
+Any keyword that is not listed indicates that particular setting is off. This
+option is not cumulative. Any subsequent use of
+\csopt{word-boundaries} within the same set of resource options will
+override previous settings.
+
+The default setting is \csopt[white space,cs
+space]{word-boundaries}, which excludes non-breakable
+spaces and dashes.
+
+\optsection[\subsubsection]{short-case-change}
+
+Applies a case-change to the \field{short} field (if present).
+This option may take one of the values described above.
+
+See \csopt{dual-short-case-change} to adjust the \field{dualshort}
+field.
+
+\optsection[\subsubsection]{long-case-change}
+
+Applies a case-change to the \field{long} field (if present).
+This option may take one of the values described above.
+
+See \csopt{dual-long-case-change} to adjust the \field{duallong}
+field.
+
+\optsection[\subsubsection]{name-case-change}
+
+Applies a case-change to the \field{name} field.
+This option may take one of the values described above.
+
+If the \field{text} field hasn't been set, the \field{name}
+value is first copied to the \field{text} field. If the \field{name}
+field hasn't been set (for example, with the \atentry{index} entry
+type), it's copied from the fallback value (which
+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[\subsubsection]{description-case-change}
+
+Applies a case-change to the \field{description} field (if present).
+This option may take one of the values described above.
+
+\optsection[\subsubsection]{field-case-change}
+
+A general case-change instruction. The value should be a
+comma-separated list of \code{\meta{field}\dequals\meta{setting}} for each
+field that needs a case-change applied. The value is required for this key but
+may be empty, which indicates this option is switched off.
+
+The \meta{setting} should be
+the same as the permitted values for the above options. This
+option is applied after all fields have been parsed but before
+\csopt{interpret-fields}. If the
+specified field is missing, the fallback for that field (if known) is copied
+into the field. For example:
+\begin{codeenv}
+\csopt[\field{user1}=uc,\field{user2}={firstuc}]{field-case-change}
+\end{codeenv}
+This manual provides a custom storage key called
+\fieldfmt{nametitle}:
+\begin{codeenv}
+\cs{glsxtrprovidestoragekey}\marg{\fieldfmt{nametitle}}\marg{}\marg{}
+\end{codeenv}
+The resource options copy the \field{name} value to this custom
+field and convert \fieldfmt{nametitle} to \idx{titlecase}:
+\begin{codeenv}
+\csopt[\field{name}=\fieldfmt{nametitle}]{replicate-fields},
+\csopt[\fieldfmt{nametitle}=title]{field-case-change},
+\end{codeenv}
+This means that the \hyperref[sec:topics]{topic summary}
+(page~\pageref{sec:topics}) can fetch the value of
+\fieldfmt{nametitle} instead of \field{name}, which provides an
+expandable \idx{titlecase} form that's suitable for the PDF
+bookmarks.
+
+This option isn't cumulative. If used multiple times in the same
+\idx{resourceset}, the last instance will be the one used. If
+the \keyvallist\ is missing, no general case-changing is applied
+(the default).
+
+\section{Plurals}
+\label{sec:plurals}
+
+Some languages, such as English, have a general rule that plurals
+are formed from the singular with a suffix appended. This isn't
+an absolute rule. There are plenty of exceptions (for example,
+geese, children, churches, elves, fairies, sheep, mice), so a
+simplistic approach of just doing \code{\ics{gls}\margm{label}[s]}
+will sometimes produce inappropriate results, so the \styfmt{glossaries}
+package provides a \field{plural} key with the corresponding command
+\ics{glspl}.
+
+In some cases a plural may not make any sense (for example, if the
+term is a verb or symbol), so the \field{plural} key is optional, but to
+make life easier for languages where the majority of plurals can
+simply be formed by appending a suffix to the singular, the
+\styfmt{glossaries} package lets the \field{plural} field default
+to the value of the \field{text} field with \ics{glspluralsuffix}
+appended. This command is defined to be just the letter \qt{s}.
+This means that the majority of terms in such languages don't need to have the
+\field{plural} supplied as well, and you only need to use it for the
+exceptions.
+
+For languages that don't have this general rule, the \field{plural}
+field will always need to be supplied for nouns.
+
+There are other plural fields, such as \field{firstplural},
+\field{longplural} and \field{shortplural}. Again, if you are using
+a language that doesn't have a simple suffix rule, you'll have to
+supply the plural forms if you need them (and if a plural makes
+sense in the context).
+
+If these fields are omitted, the \styfmt{glossaries} package follows
+these rules:
+\begin{itemize}
+\item If \field{firstplural} is missing, then \ics{glspluralsuffix}
+is appended to the \field{first} field, if that field has been
+supplied. If the \field{first} field hasn't been supplied but the
+\field{plural} field has been supplied, then the \field{firstplural}
+field defaults to the \field{plural} field. If the \field{plural}
+field hasn't been supplied, then both the \field{plural} and
+\field{firstplural} fields default to the \field{text} field (or
+\field{name}, if no \field{text} field) with \ics{glspluralsuffix}
+appended.
+
+\item If the \field{longplural} field is missing, then
+\ics{glspluralsuffix} is appended to the \field{long} field, if the
+\field{long} field has been supplied.
+
+\item If the \field{shortplural} field is missing then, \emph{with
+the base \styfmt{glossaries} acronym mechanism}, \ics{acrpluralsuffix}
+is appended to the \field{short} field.
+
+\end{itemize}
+
+The last case is different with the \isty{glossaries-extra} extension
+package. The \field{shortplural} field defaults to the \field{short}
+field with \ics{abbrvpluralsuffix} appended \emph{unless overridden
+by category attributes}. This suffix command is set by the
+abbreviation styles. This means that every time an abbreviation
+style is implemented, \ics{abbrvpluralsuffix} is redefined. Most
+styles simply define this command as:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{glsxtrabbrvpluralsuffix}}
+\end{codeenv}
+where \ics{glsxtrabbrvpluralsuffix} expands to \ics{glspluralsuffix}.
+The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different
+definition:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{abbrvpluralsuffix}}\marg{\cs{protect}\ics{glsxtrscsuffix}}
+\end{codeenv}
+This allows the suffix to be reverted back to the upright font,
+counteracting the affect of the small-caps font.
+
+This means that if you want to change or strip the suffix used for
+the plural short form, it's usually not sufficient to redefine
+\ics{abbrvpluralsuffix}, as the change will be undone the next time
+the style is applied. Instead, for a document-wide solution, you
+need to redefine \ics{glsxtrabbrvpluralsuffix}. Alternatively you can
+use the category attributes.
+
+There are two attributes that affect the short plural suffix
+formation. The first is \catattr{aposplural} which uses the suffix
+\begin{codeenv*}
+\idx{aposchar}\cs{abbrvpluralsuffix}
+\end{codeenv*}
+That is, an \idx{apostrophe} followed by \ics{abbrvpluralsuffix} is
+appended. The second attribute is \catattr{noshortplural} which
+suppresses the suffix and simply sets \field{shortplural} to the
+same as \field{short}.
+
+With \bibgls, if you have some abbreviations where the plural should
+have a suffix and some where the plural shouldn't have a suffix
+(for example, the document has both English and French abbreviations)
+then there are two approaches.
+
+The first approach is to use the category attributes. For example:
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{french}\marg{\catattr{noshortplural}}
+\end{codeenv}
+Now just make sure all the French abbreviations are have their
+\field{category} field set to \optfmt{french}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[french]{category}}
+\end{codeenv}
+
+The other approach is to use the options listed below for the given
+\idx{resourceset}. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[fr-abbrvs]{src},\csopt[\empty]{short-plural-suffix}}
+\end{codeenv}
+
+\optsection{short-plural-suffix}
+
+Sets the plural suffix for the default \field{shortplural} to
+\meta{value}. The \meta{value} may be one of:
+\begin{itemize}
+\item \meta{suffix}: add the
+\field{shortplural} field, if missing, with the given \meta{suffix}.
+\item \meta{empty}: add the
+\field{shortplural} field, if missing, with no suffix.
+\item \optfmt{use-default}: leave
+it to \styfmt{glossaries-extra} to determine the appropriate default.
+\end{itemize}
+The default setting is \csopt[use-default]{short-plural-suffix}.
+If the \code{=\meta{value}} part is omitted, then
+\csopt[\empty]{short-plural-suffix} is assumed.
+
+\optsection{dual-short-plural-suffix}
+
+Sets the plural suffix for the default \field{dualshortplural} field to
+\meta{value}. As with \csopt{short-plural-suffix}, the default
+setting is \csopt[use-default]{dual-short-plural-suffix}. If the
+\meta{value} is omitted or empty, the suffix is set to empty.
+
+\section{Location List Options}
+\label{sec:locationopts}
+
+The \styopt{record} package option automatically adds two new keys:
+\field{loclist} and \field{location}. These two fields are set by
+\bibgls\ from the information supplied in the \iext{aux} file (unless
+the option \csopt[false]{save-locations} is used). The
+\field{location} field contains the code to typeset the formatted
+\idx{locationlist}.
+
+The \field{loclist} field has the syntax of an \isty{etoolbox} internal list
+and includes every location (except for the discarded duplicates and
+\idxpl{ignoredrecord}) with no range formations. Any explicit range markup
+is stripped from the \glsopt{format} information to leave just the \idx{encap}
+name, so you just get the start and end locations added as individual
+elements but they are still encapsulated with the associated formatting
+command. Each item in the list is provided in one of the following forms:
+\begin{codeenv}
+\ics{glsseeformat}\oargm{tag}\margm{label list}\marg{}
+\end{codeenv}
+for the cross-reference supplied by the \field{see} field,
+\begin{codeenv}
+\ics{glsxtruseseealsoformat}\margm{xr list}
+\end{codeenv}
+for the cross-reference supplied by the \field{seealso} field,
+\nosecdef{glsnoidxdisplayloc}
+for standard the internal locations,
+\begin{codeenv}
+\format{glsxtrdisplaysupploc}
+\end{codeenv}
+for supplemental (external) locations and
+\begin{codeenv}
+\format{glsxtrdisplaylocnameref}
+\end{codeenv}
+for \code{nameref} records. (See \sectionref{sec:supplementalopts}
+for more information about supplemental locations and
+\longarg{merge-nameref-on} for more information about \code{nameref}
+records.)
+
+You can iterate through the \field{loclist} value
+using one of \sty{etoolbox}'s internal list loops (either
+by first fetching the list using \ics{glsfieldfetch}
+or through \styfmt{glossaries-extra}'s \ics{glsxtrfielddolistloop}
+or \ics{glsxtrfieldforlistloop} shortcuts).
+
+The \meta{format} is that supplied by the \glsopt{format} key
+when using commands like \ics{gls} or \ics{glsadd} (the encapsulator or
+\idx{encap} in \idx!{makeindex} parlance). If omitted, the default
+\glsopt[glsnumberformat]{format} is assumed (unless this
+default value is changed with \ics{GlsXtrSetDefaultNumberFormat}.
+The value of the \glsopt{format} key must be the name of
+a text-block command without the leading backslash that takes
+a single argument (the location). The location
+is encapsulated by that command. For example,
+\begin{codeenv}
+\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}
+\end{codeenv}
+will display the corresponding location in bold, but note that this
+will no longer have a hyperlink if you've used \sty{hyperref}.
+If you want to retain the hyperlink you need the location
+encapsulated with \cs{hyperbf} instead of \cs{textbf}:
+\begin{codeenv}
+\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}
+\end{codeenv}
+The \csfmt{hyper}\meta{xx} set of commands all internally use
+\cs{glshypernumber} which adds the appropriate hyperlink to the
+location. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries}
+user manual for a list of all the \csfmt{hyper}\meta{xx} commands.
+
+Ranges can be explicitly formed using the parenthetical
+syntax \glsopt[\idx{openrange}]{format} and
+\glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and
+\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of
+a text-block command without the initial backslash) in the optional
+argument of commands like \ics{gls} or \ics{glsadd}. These will always
+form a range, regardless of \csopt{min-loc-range}, and will be
+encapsulated by \gls!{bibglsrange}. (This command is not used with
+ranges that are formed by collating consecutive locations.) The
+initial marker is stripped from the \meta{format} argument of the
+location formatting commands, such as \gls{glsnoidxdisplayloc}, to
+allow for easy conversion to the corresponding text-block command.
+
+Explicit ranges don't merge with neighbouring locations, but will
+absorb any single locations within the range that don't conflict.
+(Conflicts will be moved to the start of the explicit range.)
+For example, if \code{\cs{gls}\marg{sample}} is used on page~1,
+\code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} is used on page~2,
+\code{\cs{gls}\marg{sample}} is used on page~3, and
+\code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} is used on page~4, then the location
+list will be 1, 2--4. The entry on page~3 is absorbed into the
+explicit range, but the range can't be expanded to include page~1.
+If the entry on page~3 had a different format to the explicit range,
+for example \code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}}
+then it would cause a warning and be moved before the start of the
+range so that the location list would then be 1, \textbf{3}, 2--4.
+
+An \idx{ignoredrecord} identifies a term that needs to be treated as
+though it has a record for selection purposes, but the record
+should not be included in the location list.
+The special format \glsaddopt[\encap{glsignore}]{format} is provided
+by the \styfmt{glossaries} package for cases where the location
+should be ignored. (The command \ics{glsignore} simply ignores its
+argument.) This works reasonably well if an entry only has the one
+location, but if the entry happens to be indexed again, it can lead
+to an odd empty gap in the location list with a spurious comma. If
+\bibgls\ encounters a record with this special format, the entry
+will be selected but the record will be discarded.
+
+This means that the location list will be empty if the entry was
+only indexed with the special ignored format, but if the entry was also
+indexed with another format then the location list won't include the
+\idxpl{ignoredrecord}. (This format is used by \ics{glsaddallunused} but
+remember that iterative commands like this don't work with \bibgls.
+Instead, just use \csopt[all]{selection} to select all entries.
+Those that don't have records won't have a location list.)
+
+For example, suppose you only want main matter locations in the
+number list, but you want entries that only appear in the back matter
+to still appear in the glossary (without a location list), then you could do:
+\begin{codeenv}
+\ics{backmatter}
+\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+If you also want to drop front matter locations as well:
+\begin{codeenv}
+\ics{frontmatter}
+\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\ldots
+\ics{mainmatter}
+\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsnumberformat}}
+\ldots
+\cs{backmatter}
+\cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+
+Note that explicit range formations aren't discarded, so if
+\encap{glsignore} is used in a range, such as:
+\begin{codeenv}
+\ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample}
+\ldots
+\cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample}
+\end{codeenv}
+then the range will be included in the location list (encapsulated
+with \ics{glsignore}), but this case would be a rather odd use of
+this special format and is not recommended.
+
+The record counting commands, such as \gls{rgls}, use the special
+format \encap{glstriggerrecordformat}, which \bibgls\ also treats
+as an \idx{ignoredrecord} and the same rules as for \encap{glsignore} apply.
+
+The locations are always listed in the order in which they were indexed,
+(except for the cross-reference which may be placed at the start or
+end of the list or omitted).
+This is different to \idx!{xindy} and \idx!{makeindex} where you can
+specify the ordering (such as \idx!{lowercase} Roman first, then digits,
+etc), but unlike those applications, \bibgls\ allows any location,
+although it may not be able to work out an integer representation.
+(With \idx!{xindy}, you can define new location formats, but you need
+to remember to add the appropriate code to the custom module.)
+
+It's possible to define a custom glossary style where
+\ics{glossentry} (and the child form \ics{subglossentry}) ignore the
+final argument (which will be the \field{location} field)
+and instead parse the \field{loclist} field and re-order the
+locations or process them in some other way. Remember that you can
+also use \ics{glsnoidxloclist}
+provided by \styfmt{glossaries}. For example:
+\begin{codeenv}
+\cs{glsfieldfetch}\marg{gls.sample}\marg{loclist}\marg{\cmd{loclist}}\comment{fetch location list}
+\cs{glsnoidxloclist}\marg{\cmd{loclist}}\comment{iterate over locations}
+\end{codeenv}
+This uses \ics{glsnoidxloclisthandler} as the list's \idx{handler}
+macro, which simply displays each location separated by \ics{delimN}.
+(See also
+\href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration
+Tips and Tricks}~\cite{iterationtips}.)
+
+Each regular location is listed in the \iext{aux} file in the form:
+\nosecdef{glsxtr@record}
+(See \longarg{merge-nameref-on} for \code{nameref} records.)
+Exact duplicates are discarded. For example, if \code{cat}
+is indexed twice on page 1:
+\begin{codeenv}
+\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\end{codeenv}
+then the second record is discarded. Only the first record is added
+to the location list.
+
+Partial duplicates, where all arguments match except for
+\meta{format}, may be discarded depending on the value
+of \meta{format}. For example, if page~1 of the document
+uses \code{\cs{gls}\marg{cat}} and
+\code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{cat}}
+then the \ext{aux} file will contain:
+\begin{codeenv}
+\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{cat}\marg{}\marg{\counter{page}}\marg{\encap{hyperbf}}\marg{1}
+\end{codeenv}
+This is a partial record match. In this case, \bibgls\
+makes the following tests:
+\begin{itemize}
+\item If one of the formats includes a range formation, the
+range takes precedence.
+
+\item If one of the formats is \encap{glsnumberformat} (as in the
+above example) or an \idx{ignoredrecord} format such as
+\encap{glsignore}, that format will be skipped. So in the above
+example, the second record will be added to the location list, but
+not the first. (A message will only be written to the transcript if
+the \longarg{debug} switch is used.) The default
+\encap{glsnumberformat} will take precedence over the
+\idx{ignoredrecord} formats (\encap{glsignore} and
+\encap{glstriggerrecordformat}).
+
+\item If a mapping has been set with the \longarg{map-format}
+switch that mapping will be checked.
+\item Otherwise the duplicate record will be discarded with a
+warning.
+\end{itemize}
+
+The \field{location} field is used to store the formatted location
+list. The code for this list is generated by \bibgls\ based on the
+information provided in the \iext{aux} file, the presence of the
+\field{see} or \field{seealso} field and the various settings described in this
+chapter. When you display the glossary using \ics{printunsrtglossary},
+if the \field{location} field is present it will be displayed
+according to the glossary style (and other factors, such as whether the
+\styopt{nonumberlist} option has been used, either as a package
+option or supplied in the optional argument of \ics{printunsrtglossary}).
+For more information on adjusting the formatting see the
+\styfmt{glossaries}~\cite{glossaries} and
+\styfmt{glossaries-extra}~\cite{glossaries-extra} user manuals.
+
+\optsection{save-locations}
+
+By default, the locations will be processed and stored in the
+\field{location} and \field{loclist} fields. However, if you don't
+want the location lists (for example, you are using the
+\styopt{nonumberlist} option or you are using \idx{xindy} with a
+custom location rule), then there's no need for \bibgls\ to process
+the locations. To switch this function off, just use
+\csopt[false]{save-locations}. Note that with this setting, if
+you're not additionally using \idx!{makeindex} or \idx!{xindy}, then
+the locations won't be available even if you don't have the
+\styopt{nonumberlist} option set.
+
+\optsection{save-loclist}
+
+If you want the \field{location} field but don't need
+\field{loclist}, you can use \csopt[false]{save-loclist}.
+This can help to save resources and build time.
+
+\optsection{save-primary-locations}
+
+It's sometimes useful to identify primary locations with a different
+format, such as bold or italic. This helps the reader select which
+location to try first in the event of a long location list. However,
+you may prefer to store the primary location in a different field to
+give it a more prominent position. In order to do this you
+need to specify the format (or formats) used to identify primary
+locations with \csopt{primary-location-formats} and
+use \csopt{save-primary-locations} to determine how to deal with
+these locations.
+
+This option may take one of the following values:
+\begin{itemize}
+\item \optfmt{false}: don't save primary locations (default);
+\item \optfmt{retain}: save primary locations in the
+\field{primarylocations} field but don't remove from the usual
+\idx{locationlist};
+\item \optfmt{default format}: similar to \optfmt{retain} but the
+format for the primary records in the \field{location} field is
+converted to the default \encap{glsnumberformat} \idx{encap} (the records in the
+\field{primarylocations} field retain their given format);
+\item \optfmt{start}: save primary locations in the
+\field{primarylocations} field and also move to the start of the
+usual \idx{locationlist};
+\item \optfmt{remove}: save primary locations in the
+\field{primarylocations} field and remove from the usual
+\idx{locationlist}.
+\end{itemize}
+
+The primary locations are copied to the \field{primarylocations}
+field and encapsulated with \gls!{bibglsprimary}.
+If you use \csopt[remove]{save-primary-locations}, the
+\field{location} field will end up empty if the locations for the
+associated entry were all identified as primary. If you use
+\csopt[start]{save-primary-locations}, all primary locations will be
+moved to the start of the \idx{locationlist} stored in the
+\field{location} field, but there will be no additional markup
+(other than the given format) to identify them. If you need
+additional markup, then use \csopt[remove]{save-primary-locations}
+and adjust the \idx{locationlist} format to insert the primary
+locations at the start. This can be done by modifying the glossary
+style.
+
+For example, the \glostyle{bookindex} style inserts
+\ics{glsxtrbookindexprelocation} before the location, so you could
+redefine this:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{primarylocations}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \ics{glsxtrprelocation}
+ \cs{glscurrentfieldvalue}
+ \cs{glsxtrifhasfield}\marg{location}\marg{\idx{param}1}\marg{;}\marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+ \cs{glsxtrprelocation}
+}
+\end{codeenv}
+(Note that if \csopt{loc-prefix} is used, the prefix will be
+in the \field{location} field and so will come after the primary
+locations in the above example. Similarly for cross-references
+unless they've been omitted.)
+
+You can switch from using the \field{location} field to the
+\field{primarylocations} field by locally changing
+\ics{GlsXtrLocationField}:
+\begin{codeenv}
+\cs{printunsrtglossary*}\marg{\comment{}
+ \cs{renewcommand}\marg{\cs{GlsXtrLocationField}}\marg{primarylocations}\comment{}
+}
+\end{codeenv}
+Remember that the \idx{handler} used by \cs{printunsrtglossary} will
+fallback on the \field{loclist} field if the field identified
+by \cs{GlsXtrLocationField} is missing or empty. You may want to
+consider using \csopt[false]{save-loclist} to prevent this.
+
+\optsection{primary-location-formats}
+
+This option will automatically set
+\csopt[retain]{save-primary-locations} unless it has already been
+changed from the default \csopt[false]{save-primary-locations}
+setting. The argument should be a comma-separated list of
+formats. If a record's format is contained in this list then it will
+be considered a primary location and it will be included in the
+associated entry's \field{primarylocations} field.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{bird,
+ \field{name}=\marg{bird},
+ \field{description}=\marg{feathered animal}
+}
+\atentry{entry}\marg{waterfowl,
+ \field{name}=\marg{waterfowl},
+ \field{description}=\marg{any bird that lives in or about water}
+}
+\atentry{entry}\marg{zebra,
+ \field{name}=\marg{zebra},
+ \field{description}=\marg{striped African horse}
+}
+\atentry{entry}\marg{parrot,
+ \field{name}=\marg{parrot},
+ \field{description}=\marg{mainly tropical bird with bright plumage}
+}
+\end{codeenv}
+and the document \filefmt{test.tex} contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{report}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt[dot]{postpunc},
+ \styopt{nostyles},
+ \styopt[tree,bookindex]{stylemods},
+ \styopt[bookindex]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[hyperbf,hyperemph]{primary-location-formats},
+ \csopt[remove]{save-primary-locations}
+}
+\strut
+\cmd{renewcommand}*\marg{\cs{glsxtrbookindexprelocation}}[1]\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{primarylocations}}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \ics{glsxtrprelocation}
+ \cs{glscurrentfieldvalue}
+ \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\idx{param}1}\marg{;}\marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+ \cs{glsxtrprelocation}
+}
+\strut
+\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
+\strut
+\cmd{begin}\marg{document}
+\cmd{chapter}\marg{Sample}
+\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Another Sample}
+\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Yet Another Sample}
+\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Yet Another Sample Again}
+\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}.
+\strut
+\ics{printunsrtglossary*}\oarg{\printglossopt[\iglostyle{tree}]{style},\printglossopt{nonumberlist}}\marg{\comment{}
+ \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{}
+}
+\strut
+\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+The \csopt[\encap{hyperbf},\encap{hyperemph}]{primary-location-formats} setting
+in the above indicates that locations encapsulated with \ics{hyperbf} and
+\ics{hyperemph} are primary records. In this case, the bold format is used to
+indicate the primary location in the main document text and the emphasized
+format is used to indicate the location in the main glossary.
+
+The primary records are removed from the \field{location} field
+due to the \csopt[remove]{save-primary-locations} setting. This can
+lead to a ragged location list. The option
+\csopt[default format]{save-primary-locations} can allow the primary
+location to be absorbed into a range.
+
+The main glossary records are added through the category-independent post-name
+hook with \cs{glsadd}. This won't be implemented until the entries are actually
+defined as the page number can't be determined until the glossary can be
+displayed. This means that the document build requires an extra \bibgls\ and
+\LaTeX\ run:
+\begin{verbatim}
+pdflatex test
+bib2gls --group test
+pdflatex test
+bib2gls --group test
+pdflatex test
+\end{verbatim}
+
+For consistency, I've used \gls{glsxtrnewglslike} to provide commands
+used to indicate a primary reference in the text. This means that if
+I decide to change the optional arguments used for primary
+references I only need to edit one line. For example, I might want to
+change the default counter:
+\begin{codeenv}
+\gls{glsxtrnewglslike}\oarg{\glsopt[\encap{hyperbf}]{format},\glsopt[\counter{chapter}]{counter}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
+\end{codeenv}
+
+Here's another example that only has one primary format (\encap{hyperrm})
+that's indexed through the use of \ics{GlsXtrAutoAddOnFormat}, which sets
+up a hook that automatically inserts:
+\begin{codeenv*}
+\ics{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\margm{label}
+\end{codeenv*}
+on each instance of \code{\cs{gls}\oarg{\glsopt[primaryfmt]{format}}\margm{label}} (or
+similar). This means that the entry is indexed twice when this particular
+format is used: first with the \encap{hyperrm} format and \counter{chapter}
+counter (from the \cs{glsadd} command in the hook), and then with the
+\code{primaryfmt} format and the default counter (as per normal behaviour):
+\begin{codeenv}
+\cmd{documentclass}\marg{report}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{
+ \styopt[nameref]{record},
+ \styopt[dot]{postpunc},
+ \styopt{nostyles},
+ \styopt[tree,bookindex]{stylemods},
+ \styopt[bookindex]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[topics]{src},
+ \csopt[hyperrm]{primary-location-formats},
+ \csopt[remove]{save-primary-locations},
+ \csopt[false]{save-loclist}
+}
+\strut
+\cmd{newcommand}\marg{\cmd{primaryfmt}}\oarg{1}\marg{\cs{hyperbf}\marg{\idx{param}1}}
+\strut
+\ics{GlsXtrAutoAddOnFormat}\marg{primaryfmt}\marg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}
+\strut
+\gls{glsxtrnewglslike}\oarg{\glsaddopt[primaryfmt]{format}}\marg{}\marg{\cmd{primary}}\marg{\cmd{primarypl}}\marg{\cmd{Primary}}\marg{\cmd{Primarypl}}
+\strut
+\cmd{begin}\marg{document}
+\cmd{chapter}\marg{Sample}
+\cmd{Primary}\marg{waterfowl}, \cs{gls}\marg{bird} and \cs{gls}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Another Sample}
+\cs{Gls}\marg{waterfowl}, \cmd{primary}\marg{bird} and \cs{gls}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Yet Another Sample}
+\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird} and \cmd{primary}\marg{zebra}.
+\strut
+\cmd{chapter}\marg{Yet Another Sample Again}
+\cs{Gls}\marg{waterfowl}, \cs{gls}\marg{bird}, \cmd{primarypl}\marg{parrot} and \cs{gls}\marg{zebra}.
+\strut
+\ics{printunsrtglossary*}\oarg{\printglossopt[\glostyle{tree}]{style},\printglossopt[Summary]{title}}\marg{\comment{}
+ \cmd{renewcommand}*\marg{\ics{glsextrapostnamehook}}[1]\marg{\ics{glsadd}\oarg{\glsaddopt[\encap{hyperemph}]{format}}\marg{\idx{param}1}}\comment{}
+ \cmd{renewcommand}\marg{\ics{GlsXtrLocationField}}\marg{\field{primarylocations}}\comment{}
+}
+\strut
+\cs{printunsrtglossary}\oarg{\printglossopt[Index]{title},\printglossopt[false]{target}}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+Note that in this case, from \bibgls' point of view, the primary format is
+\encap{hyperrm} not \code{primaryfmt}. This picks out the records created with
+the automated \ics{glsadd}, which have the counter set to \counter{chapter}.
+The first glossary (with the title \qt{Summary}) switches the location field to
+\field{primarylocations} so that only the primary records are listed. Since
+\styopt[nameref]{record} has been used this means that the chapter title is
+shown rather than the chapter number.
+
+The second glossary (\qt{Index}) shows the location lists that only
+have the \counter{page} counter (because the automated \cs{glsadd}
+records with the \counter{chapter} counter have been removed because
+they were identified as primary records). These just show the page
+number as that's the default display with \styopt[nameref]{record}
+for records with the \counter{page} counter.
+
+An alternative to \ics{GlsXtrAutoAddOnFormat} would be to simply
+define the custom commands as follows:
+\begin{codeenv}
+\cmd{newcommand}\marg{\cmd{primary}}[2][]\marg{\comment{}
+ \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
+ \cs{gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
+}
+\cmd{newcommand}\marg{\cmd{primarypl}}[2][]\marg{\comment{}
+ \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
+ \cs{glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
+}
+\cmd{newcommand}\marg{\cmd{Primary}}[2][]\marg{\comment{}
+ \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
+ \cs{Gls}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
+}
+\cmd{newcommand}\marg{\cmd{Primarypl}}[2][]\marg{\comment{}
+ \cs{glsadd}\oarg{\glsaddopt[\counter{chapter}]{counter},\glsaddopt[\encap{hyperrm}]{format}}\marg{\idx{param}2}\comment{}
+ \cs{Glspl}\oarg{\glsopt[primaryfmt]{format},\idx{param}1}\marg{\idx{param}2}\comment{}
+}
+\end{codeenv}
+This is more useful if you want to simply omit the
+\code{\glsopt[primaryfmt]{format}} option (just remove it from the above four
+definitions), which makes it easier to merge the locations into
+ranges in the index.
+
+\optsection{min-loc-range}
+
+By default, three or more consecutive locations \meta{loc-1},
+\meta{loc-2}, \ldots, \meta{loc-n} are compressed into
+the range \code{\meta{loc-1}\ics{delimR} \meta{loc-n}}. Otherwise
+the locations are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}.
+As mentioned above, these aren't merged with explicit range formations.
+
+You can change this with the \csopt{min-loc-range} setting where
+\meta{value} is either \optfmt{none} (don't form ranges) or an
+integer greater than one indicating how many consecutive locations should be
+converted into a range.
+
+\bibgls\ determines if one location
+\code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}}
+is one unit more than another location
+\code{\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} }
+according to the following:
+\begin{enumerate}
+\item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or
+\meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1}
+is not equal to \meta{format-2}, then the locations aren't
+considered consecutive.
+\item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty,
+then the locations aren't considered consecutive.
+\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the
+pattern (line break for clarity only)\footnote{The Java class \code{\csfmt{p}\marg{javaDigit}}
+used in the \idx{regex} will match any digits in the
+Unicode \idx{numberdecimaldigit} category not just the digits in the Basic Latin set. Similarly \code{\csfmt{p}\marg{javaAlphabetic}} will also match alphabetic
+characters outside the Basic Latin set.}
+\begin{verbatim}
+(.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit}
+\p{javaAlphabetic}]+)\}
+\end{verbatim}
+then:
+ \begin{itemize}
+ \item if the control sequence matched by group 2 isn't the same for
+ both locations, the locations aren't considered consecutive;
+ \item if the argument of the control sequence (group 3) is the same for
+ both locations, then the test is retried with \meta{location-1}
+set to group 1 of the first pattern match and \meta{location-2}
+set to group 1 of the second pattern match;
+ \item otherwise the test is retried with \meta{location-1} set to
+group 3 of the first pattern match and \meta{location-2} set to
+group 3 of the second pattern match.
+ \end{itemize}
+\item\label{itm:decmatch} If both \meta{location-1} and \meta{location-2} match the
+pattern
+\begin{verbatim}
+(.*?)([^\p{javaDigit}]?)(\p{javaDigit}+)
+\end{verbatim}
+then:
+ \begin{enumerate}
+ \item\label{itm:decgrp3eq} if group 3 of both pattern matches are
+equal then:
+ \begin{enumerate}
+ \item\label{itm:decgrp3nz} if group 3 isn't zero, the locations
+aren't considered consecutive;
+ \item if the separators (group 2) are different the test is
+retried with \meta{location-1} set to the concatenation of the first
+two groups \meta{group-1}\meta{group-2} of the first pattern match
+and \meta{location-2} set to the concatenation of the first two groups
+\meta{group-1}\meta{group-2} of the second pattern
+match;
+ \item\label{itm:decgrp3eqsepeq} if the separators (group 2) are the same the test is
+retried with \meta{location-1} set to the first
+group \meta{group-1} of the first pattern match
+and \meta{location-2} set to the first group
+\meta{group-1} of the second pattern match.
+ \end{enumerate}
+ \item If \meta{group-1} of the first pattern match (of
+\meta{location-1}) doesn't equal
+\meta{group-1} of the second pattern match (of \meta{location-2})
+or \meta{group-2} of the first pattern match (of
+\meta{location-1}) doesn't equal
+\meta{group-2} of the second pattern match (of \meta{location-2})
+then the locations aren't considered consecutive;
+ \item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $
+where $l_2$ is \meta{group 3} of the second pattern match,
+$l_1$ is \meta{group 3} of the first pattern match and
+$d$ is the value of \optfmt{max-loc-diff} then the locations
+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 \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 \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 \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
+consecutive.
+\end{enumerate}
+
+Examples:
+\begin{enumerate}
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2}
+\end{codeenv}
+These records are consecutive. The prefix, counter and format are
+identical (so the test passes step~\ref{itm:pre}), the locations match
+the \hyperref[itm:decmatch]{decimal pattern} and the test in
+step~\ref{itm:decgrp3} passes.
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{textbf}}\marg{2}
+\end{codeenv}
+These records aren't consecutive since the formats are different.
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.i}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{A.ii}
+\end{codeenv}
+These records are consecutive. The prefix, counter and format are
+identical (so it passes step~\ref{itm:pre}). The locations match
+the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where
+\code{A} is considered a prefix and the dot is consider a
+separator. The Roman numerals i and ii are converted to decimal and
+the test is retried with the locations set to 1 and 2, respectively.
+This now passes the decimal pattern test (step~\ref{itm:decgrp3}).
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{i.A}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{ii.A}
+\end{codeenv}
+These records aren't consecutive. They match the
+\hyperref[itm:alphmatch]{alpha pattern}. The first location is
+considered to consist of the prefix \code{i}, the separator
+\code{.}\ (dot) and the number given by the character code of A.
+The second location is considered to consist of the prefix
+\code{ii}, the separator \code{.}\ (dot) and the number
+given by the character code of A.
+
+The test fails because the numbers are equal and the prefixes are
+different.
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.0}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.0}
+\end{codeenv}
+These records are consecutive. They match the \hyperref[itm:decmatch]{decimal
+pattern}, and then step~\ref{itm:decgrp3eq} followed by
+step~\ref{itm:decgrp3eqsepeq}. The \code{.0} part is discarded and
+the test is retried with the first location set to 1 and the second
+location set to 2.
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{1.1}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{2.1}
+\end{codeenv}
+These records aren't consecutive as the test branches off into
+step~\ref{itm:decgrp3nz}.
+
+\item
+\begin{codeenv}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{1}}
+\gls{glsxtr@record}\marg{gls.sample}\marg{}\marg{\counter{page}}\marg{\encap{glsnumberformat}}\marg{\cmd{@alph}\marg{2}}
+\end{codeenv}
+These records are consecutive. The locations match the
+\hyperref[itm.csmatch]{control sequence pattern}. The control
+sequences are the same, so the test is retried with the first
+location set to 1 and the second location set to 2.
+
+In this example, the location has been written to the file as
+\code{\csfmt{@alph}\margm{number}} instead of fully expanding according to the
+normal behaviour of \code{\ics{alph}\margm{counter}}. (Note that
+\gls!{glsxtrresourcefile} changes the category code of \code{@} to allow for
+internal commands in locations.) This unusual case is for illustrative purposes.
+\end{enumerate}
+
+\optsection{max-loc-diff}
+
+This setting is used to determine whether two locations are
+considered consecutive.
+The value must be an integer greater than or equal to 1.
+(The default is \optfmt{1}.)
+
+For two locations, \meta{location-1} and \meta{location-2},
+that have numeric values $n_1$ and $n_2$ (and identical prefix,
+counter and format), then the sequence \meta{location-1},
+\meta{location-2} is considered consecutive if
+\[
+0 < n_2 - n_1 \leq \text{\meta{max-loc-diff}}
+\]
+The default value of 1 means that \meta{location-2} immediately
+follows \meta{location-1} if $n_2 = n_1+1$.
+
+For example, if \meta{location-1} is \qt{B} and \meta{location-2}
+is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1=
+n_1+1$ then \meta{location-2} immediately follows \meta{location-1}.
+
+This is used in the range formations within the location lists (as described
+in the above section).
+So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59,
+61} becomes
+\qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}.
+
+The automatically indexing of commands like \ics{gls} means that
+the location lists can become long and ragged. You could
+deal with this by switching off the automatic indexing and
+only explicitly index pertinent use or you can adjust
+the value of \optfmt{max-loc-diff} so that a range can be formed even
+if there are one or two gaps in it.
+By default, any location ranges that have skipped gaps in this
+manner will be followed by \gls!{bibglspassim}. The default
+definition of this command is obtained from the resource file.
+For English, this is \verb*| passim| (space followed by \qt{passim}).
+
+So with the above set of locations, if \csopt[2]{max-loc-diff} then
+the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that
+there are two blocks within the document related to that
+term.
+
+\optsection{suffixF}
+
+If set, a range consisting of two consecutive locations
+\meta{loc-1} and \meta{loc-2} will be
+displayed in the location list as \meta{loc-1}\meta{value}.
+
+Note that \csopt[\empty]{suffixF} sets the suffix to the
+empty string. To remove the suffix formation use
+\csopt[none]{suffixF}.
+
+The default is \csopt[none]{suffixF}.
+
+\optsection{suffixFF}
+
+If set, a range consisting of three or more consecutive locations
+\meta{loc-1} and \meta{loc-2} will be
+displayed in the location list as \meta{loc-1}\meta{value}.
+
+Note that \csopt[\empty]{suffixFF} sets the suffix to the
+empty string. To remove the suffix formation use
+\csopt[none]{suffixFF}.
+
+The default is \csopt[none]{suffixFF}.
+
+\optsection{compact-ranges}
+
+The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to
+\csopt[0]{compact-ranges}) or \optfmt{true} (equivalent to
+\csopt[3]{compact-ranges}). If no \meta{value} is specified,
+\optfmt{true} is assumed.
+
+This setting allows location ranges such as 184--189 to appear
+more compactly as 184--9. The end location is encapsulated
+in the command \gls{bibglscompact}, so the range would actually
+become:
+\begin{codeenv}
+184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}
+\end{codeenv}
+If the location is in the form \code{\meta{cs}\margm{loc}}
+(where \meta{cs} is a command)
+then \gls{bibglscompact} will be inside the argument.
+For example, if the range would normally be:
+\begin{codeenv}
+\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189}
+\end{codeenv}
+then it would become:
+\begin{codeenv}
+\cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{\gls{bibglscompact}\marg{digit}\marg{18}\marg{9}}
+\end{codeenv}
+The numerical value given in \csopt[\meta{n}]{compact-ranges}
+indicates that compaction should only occur if the actual location
+consists of at least \meta{n} characters, for $\meta{n} \geq 2$.
+Any value of \meta{n} less than 2 will switch off compaction.
+
+For example, \code{189} consists of 3 characters, so it will be
+compacted with \csopt[3]{compact-ranges} but not with
+\csopt[4]{compact-ranges}. Whereas \code{\csfmt{custom}\marg{89}}
+would only be compacted with \csopt[2]{compact-ranges}
+because \code{89} only consists of 2 characters.
+
+The compaction isn't limited to decimal digits but it will only
+occur if both the start and end location have the same number of
+characters. For example, xvi--xviii can't be compacted because
+the start consists of three characters and the end consists
+of five characters, whereas xxv--xxx can be compacted to xxv--x,
+which may look a little strange. In this case, you may want to
+consider changing the definition of \cs{bibglscompact} so that
+it only performs the compaction for digits.
+
+\optsection{see}
+
+If an entry has a \field{see} field, this can be placed before or
+after the location list, or completely omitted (but the value will
+still be available in the \field{see} field for use with
+\ics{glsxtrusesee}). The required \meta{value} must be one of:
+\begin{itemize}
+\item \optfmt{omit}: omit the see reference from the location
+list.
+\item \optfmt{before}: place the see reference before the location
+list.
+\item \optfmt{after}: place the see reference after the location
+list (default).
+\end{itemize}
+
+The separator between the location list and the cross-reference is
+provided by \gls!{bibglsseesep}. This separator is omitted if the
+location list is empty. The cross-reference is written to the
+\field{location} field using \code{\gls{bibglsusesee}\margm{label}}.
+
+\optsection{seealso}
+
+This is like \csopt{see} but governs the location of the cross-references
+provided by the \field{seealso} field. You need at least v1.16
+of \sty{glossaries-extra} for this option. The values are the
+same as for \csopt{see} but the separator is given by
+\gls!{bibglsseealsosep}. The cross-reference is written to the
+\field{location} field using \code{\gls{bibglsuseseealso}\margm{label}}.
+
+\optsection{alias}
+
+This is like \csopt{alias} but governs the location of the cross-references
+provided by the \field{alias} field. The separator is given by
+\gls!{bibglsaliassep}. The cross-reference is written to the
+\field{location} field using \code{\gls{bibglsusealias}\margm{label}}.
+
+\optsection{alias-loc}
+
+If an entry has an \field{alias} field, the location list
+may be retained or omitted or transferred to the target entry.
+The required \meta{value} must be one of:
+\begin{itemize}
+\item\optfmt{keep}: keep the location list;
+\item\optfmt{transfer}: transfer the location list;
+\item\optfmt{omit}: omit the location list.
+\end{itemize}
+The default setting is \csopt[transfer]{alias-loc}.
+In all cases, the target entry will be added to the \field{see}
+field of the entry with the \field{alias} field, unless it
+already has a \field{see} field (in which case the \field{see} value
+is left unchanged).
+
+Note that with \csopt[transfer]{alias-loc}, both the aliased
+entry and the target entry must be in the same resource set.
+(That is, both entries have been selected by the same instance of
+\gls!{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version~1.12,
+you may need to redefine \ics{glsxtrsetaliasnoindex} to do
+nothing if the location lists aren't showing correctly
+with aliased entries. (This was corrected in version~1.13.)
+
+\optsection{loc-prefix}
+
+The \csopt{loc-prefix} setting indicates that the location lists
+should begin with \code{\gls!{bibglslocprefix}\margm{n}}. The \meta{value} may
+be one of the following:
+\begin{itemize}
+\item \optfmt{false}: don't insert \code{\gls{bibglslocprefix}\margm{n}} at the
+start of the location lists (default).
+
+\item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}:
+insert \code{\gls{bibglslocprefix}\margm{n}} (where \meta{n} is the number of
+locations in the list) at the start of each location list and the
+definition of \gls{bibglslocprefix} will be appended to the glossary
+preamble providing an \ics{ifcase} condition:
+\begin{codeenv}
+\cmd{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
+ \ics{ifcase}\idx{param}1
+ \cmd{or} \meta{prefix-1}\gls{bibglspostlocprefix}
+ \cmd{or} \meta{prefix-2}\gls{bibglspostlocprefix}
+ \ldots
+ \cmd{else} \meta{prefix-n}\gls{bibglspostlocprefix}
+ \cmd{fi}
+}
+\end{codeenv}
+
+\item \optfmt{comma}: equivalent to \csopt[\marg{,~}]{loc-prefix}
+but avoids confusion with the list syntax. That is, the prefix is a comma
+followed by a space for non-empty locations.
+
+\item \optfmt{list}: equivalent to \csopt[\ics{pagelistname} ]{loc-prefix}.
+
+\item \optfmt{true}: equivalent to
+\csopt[\gls{bibglspagename},\gls{bibglspagesname}]{loc-prefix},
+where the definitions of \gls{bibglspagename} and
+\gls{bibglspagesname} are obtained from the \idx{tag.page} and
+\idx{tag.pages} entries in \bibgls's \langxml.
+This setting works best if the document's language matches the
+language file. However, you can redefine these commands within
+the document's language hooks or in the glossary preamble.
+
+\end{itemize}
+
+If \meta{value} is omitted, \optfmt{true} is assumed. Take care not
+to mix different values of \csopt{loc-prefix} for entries for the
+same \csopt{type} setting. It's okay to mix \csopt[false]{loc-prefix} with
+another value, but don't mix non-\optfmt{false} values.
+See the description of \gls!{bibglslocprefix} for
+further details.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries1]{src},\csopt[false]{loc-prefix}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[entries2]{src},\csopt{loc-prefix}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[symbols]{type},\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}}
+\end{codeenv}
+This works since the conflicting \csopt[p.,pp.]{loc-prefix} and
+\csopt[true]{loc-prefix} are in different glossaries (assigned through the
+\csopt{type} key). The entries fetched from \filefmt{entries1.bib}
+won't have a location prefix. The entries fetched from
+\filefmt{entries2.bib} will have the location prefix obtained from
+the language resource file. The entries fetched from
+\filefmt{entries3.bib} will have the location prefix \qt{p.}\ or
+\qt{pp.} (Note that using the \csopt{type} option isn't the same as
+setting the \field{type} field for each entry in the \ext{bib}
+file.)
+
+If the \csopt{type} option isn't used:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries1]{src},\csopt[false]{loc-prefix}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries2]{src},\csopt{loc-prefix}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries3]{src},\csopt[p.,pp.]{loc-prefix}}
+\end{codeenv}
+then \csopt[true]{loc-prefix} takes precedence over
+\csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from
+\filefmt{entries1.bib} still won't have a location prefix, but the entries
+fetched from both \filefmt{entries2.bib} and \filefmt{entries3.bib}
+have the location prefixes obtained from the language resource file.
+
+\optsection{loc-suffix}
+
+This is similar to \csopt{loc-prefix} but there are some subtle
+differences. In this case \meta{value} may either be the keyword
+\optfmt{false} (in which case the location suffix is omitted)
+or a comma-separated list
+\optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}}
+where \meta{suffix-0} is the suffix to use when the location list
+only has a cross-reference with no locations, \meta{suffix-1} is the suffix to use
+when the location list has one location (optionally with a
+cross-reference), and so on. The final \meta{suffix-n} in the list
+is the suffix when the location list has \meta{n} or more locations
+(optionally with a cross-reference).
+
+This option will append \code{\gls!{bibglslocsuffix}\margm{n}} to location
+lists that either have a cross-reference or have at least one location.
+Unlike \gls{bibglslocprefix}, this command isn't used when the
+location list is completely empty. Also, unlike
+\gls{bibglslocprefix}, this suffix command doesn't have an equivalent
+to \gls{bibglspostlocprefix}.
+
+If \meta{value} omitted, \csopt[\ics{at}\idx{periodchar}]{loc-suffix}
+is assumed. The default is \csopt[false]{loc-suffix}.
+
+As with \csopt{loc-prefix}, take care not to mix different values
+of \csopt{loc-suffix} for entries in the same glossary type.
+
+\optsection{loc-counters}
+
+Commands like \ics{gls} allow you to select a different
+counter to use for the location for that specific instance
+(overriding the default counter for the entry's glossary type).
+This is done with the \glsopt{counter} option. For example,
+consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt[tree]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src}\comment{data in entries.bib}
+}
+\strut
+\cmd{begin}\marg{document}
+\strut
+\cs{gls}\marg{pi}.
+\cmd{begin}\marg{equation}
+\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
+\cmd{end}\marg{equation}
+\cmd{begin}\marg{equation}
+\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
+\cmd{end}\marg{equation}
+\strut
+\cmd{newpage}
+\cmd{begin}\marg{equation}
+\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
+\cmd{end}\marg{equation}
+\strut
+\cmd{newpage}
+\cs{gls}\marg{pi}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{pi}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{pi}.
+\strut
+\cmd{newpage}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+This results in the location list \qt{1, 1--3, 3--5}. This
+looks a little odd and it may seem as though the range formation
+hasn't worked, but the locations are actually: page~1, equation~1,
+equation~2, equation~3, page~3, page~4 and page~5. Ranges can't
+be formed across different counters.
+
+The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\
+to group the locations according to the counters given in
+the comma-separated \meta{list}. If a location has a counter
+that's not listed in \meta{list}, then the location is discarded.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[\counter{equation},\counter{page}]{loc-counters},\comment{group locations by counter}
+ \csopt[entries]{src}\comment{data in entries.bib}
+}
+\end{codeenv}
+This will first list the locations for the \counter{equation}
+counter and then the locations for the \counter{page} counter.
+Each group of locations is encapsulated within the command
+\gls!{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}.
+The groups are separated by \gls!{bibglslocationgroupsep}.
+
+The \meta{list} value must be non-empty. Use
+\csopt[as-use]{loc-counters} to restore the default behaviour, where
+the locations are listed in the document order of use, or
+\csopt[false]{save-locations} to omit the location lists. Note that
+you can't form counter groups from
+\hyperref[sec:supplementalopts]{supplemental location lists}.
+
+\optsection{save-index-counter}
+
+\emph{This option requires at least version 1.29 of
+\isty{glossaries-extra}.} The \meta{value} may be one of:
+\begin{itemize}
+\item \optfmt{false}: don't create the \field{indexcounter} field
+(default);
+\item \optfmt{true}: create the \field{indexcounter} field with the
+value set to the first \counter{wrglossary} location;
+\item \meta{encap}: create the \field{indexcounter} field with the
+value set to the first \counter{wrglossary} location
+where the \glsopt{format} is \meta{encap}.
+\end{itemize}
+This setting will have no effect if the \styopt{indexcounter} package
+option hasn't been used. In the case where the \meta{value} is
+\meta{encap}, make sure that this format takes priority in the
+location precedence rules (\longarg{map-format}). If the location
+with that \meta{encap} format value is discarded then it can't be
+saved.
+
+The \styopt{indexcounter} package option
+(\sty{glossaries-extra} v1.29+) creates a new counter called
+\counter{wrglossary} that's incremented every time a term is
+indexed (recorded), except for cross-references such as \cs{glssee}.
+The increment is performed using \ics{refstepcounter} and is
+followed by \code{\ics{label}\marg{wrglossary.\meta{n}}} where
+\meta{n} is the value of the \counter{wrglossary} counter.
+This option is intended for use with the \sty{hyperref} package to
+allow locations to link back to the particular part of the page where
+the term was referenced rather than to the top of the page.
+
+The \styopt{indexcounter} package option also automatically
+implements the option \styopt[wrglossary]{counter}, which means that
+each instance of \code{\ics{gls}\margm{id}} writes the label
+information to the \iext{aux} file:
+\begin{codeenv}
+\cmd{newlabel}\marg{wrglossary.\meta{n}}\marg{\margm{n}\margm{page}\marg{}\marg{wrglossary.\meta{n}}\marg{}}
+\end{codeenv}
+(where \meta{page} is the page number) followed by the record:
+\begin{codeenv}
+\gls{glsxtr@record}\margm{id}\marg{}\marg{wrglossary}\marg{\encap{glsnumberformat}}\margm{n}
+\end{codeenv}
+The location here is actually the value of the \counter{wrglossary}
+counter not the page number, but \bibgls\ can pick up the
+corresponding \meta{page} from the \csfmt{newlabel} command. It then
+replaces the record's location \meta{n} with:
+\nosecdef{glsxtr@wrglossarylocation}
+(but it only does this for records that have the \counter{wrglossary}
+counter).
+
+The \sty{glossaries-extra} package (v1.29+) adjusts the definition
+of \ics{glshypernumber} (which is internally used by
+\cs{glsnumberformat}, \cs{hyperbf} etc when \sty{hyperref} has been
+loaded) so that if the counter is \counter{wrglossary} then
+\ics{pageref} is used instead of \ics{hyperlink}. This means that the
+page number is displayed in the location list but it links back to
+the place where the corresponding \cs{label} occurred.
+
+This method works partially with \appfmt{makeindex} and \appfmt{xindy}
+but from their point of view the location is the value of the
+\counter{wrglossary} counter, which interferes with their ability to
+merge duplicate page numbers and form ranges. Since \bibgls\ is
+designed specifically to work with \sty{glossaries-extra}, it's
+aware of this special counter and will merge and collate the
+locations according to the corresponding page number instead.
+
+With the default \longarg{merge-wrglossary-records} switch, if a
+term has multiple \counter{wrglossary} records for a given page they
+will be merged. The reference link will be the dominant record for
+that page.
+
+The \csopt{save-index-counter} option allows you to save the first
+of the \counter{wrglossary} locations for a given entry or the first
+instance of a specific format of the \counter{wrglossary} locations
+for a given entry. This location is stored in the
+\field{indexcounter} internal field using:
+\begin{codeenv}
+\ics{GlsXtrSetField}\margm{id}\marg{\field{indexcounter}}\marg{\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}}
+\end{codeenv}
+Since \gls{glsxtr@wrglossarylocation} simply expands to its first
+argument, the corresponding label can be obtained with:
+\begin{codeenv}
+wrglossary.\gls{glsxtr@wrglossarylocation}\margm{n}\margm{page}
+\end{codeenv}
+For convenience, \sty{glossaries-extra-bib2gls} provides:
+\nosecdef{GlsXtrIndexCounterLink}
+which will do:
+\begin{codeenv*}
+\ics{cs.hyperref.int}\oarg{wrglossary.\meta{value}}\margm{text}
+\end{codeenv*}
+where \meta{value} is the value of the \field{indexcounter} field if
+it has been set. If the \field{indexcounter} field hasn't been set
+(or if \sty{hyperref} hasn't been loaded) then just \meta{text} is
+done.
+
+This provides a convenient way of encapsulating the \field{name} in
+the glossary so that it links back to the first \counter{wrglossary}
+entry or the first \glsopt[\meta{encap}]{format} \counter{wrglossary}
+entry. This encapsulation can be done by providing a new glossary
+style or more simply by redefining \ics{glsnamefont}:
+\begin{codeenv}
+\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{}
+ \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}}
+\end{codeenv}
+Here's a complete example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\marg{lipsum}\comment{dummy filler text}
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt{indexcounter}}\marg{glossaries-extra}
+\strut
+\cmd{newcommand}\marg{\cmd{primary}}[1]\marg{\cs{hyperbf}\marg{\idx{param}1}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{terms defined in entries.bib}
+ \csopt[primary]{save-index-counter}
+}
+\strut
+\cmd{renewcommand}\marg{\cs{glsnamefont}}[1]\marg{\comment{}
+ \gls{GlsXtrIndexCounterLink}\marg{\idx{param}1}\marg{\cs{glscurrententrylabel}}}
+\strut
+\cmd{begin}\marg{document}
+\strut
+A \cs{gls}\marg{sample}. \cmd{lipsum}*[1] A \cs{gls}\marg{duck}.
+\strut
+An equation:
+\cmd{begin}\marg{equation}
+\cs{gls}\oarg{\glsopt[\counter{equation}]{counter}}\marg{pi}
+\cmd{end}\marg{equation}
+\strut
+\cmd{lipsum}[2]
+\strut
+Another \cs{gls}\oarg{\glsopt[primary]{format}}\marg{sample}. \cmd{lipsum}*[3] Another
+\cs{gls}\marg{duck}.
+\strut
+\cs{gls}\marg{pi}. \cmd{lipsum}[4]
+\strut
+A \cs{gls}\marg{sample}. \cmd{lipsum}*[5] A \cs{gls}\marg{duck} and
+\cs{gls}\oarg{\glsopt[primary]{format}}\marg{pi}.
+\strut
+\cmd{lipsum}*[6] A \cs{gls}\oarg{\glsopt[primary]{format}}\marg{duck}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Note that the \glsopt[\counter{equation}]{counter} entry will have its own
+independent location. In this example, it's difficult to tell the
+difference between 1 (the equation reference) and 1 (the page
+reference) in the location list for the \code{pi} entry.
+
+The \glsopt[primary]{format} instances indicate primary references.
+They're displayed in bold (since \csfmt{primary} is defined to use
+\csfmt{hyperbf}) and these are the locations saved in the
+\field{indexcounter} field because that's the \meta{encap}
+identified by the \csopt[primary]{save-index-counter} setting.
+
+\section{Supplemental Locations}
+\label{sec:supplementalopts}
+
+\emph{These options require at least version 1.14 of
+\isty{glossaries-extra}.} If you require locations from multiple
+external sources, then you need at least version 1.36 of
+\isty{glossaries-extra} (or, more specifically,
+\isty{glossaries-extra-bib2gls}, which is automatically loaded
+by the \styopt[only]{record} package option).
+
+The \sty{glossaries-extra} package (from v1.14) provides a way of
+manually adding locations in supplemental documents through the use
+of the \glsaddopt{thevalue} option in the optional argument of
+\ics{glsadd}. Setting values manually is inconvenient and can result
+in errors, so \bibgls\ provides a way of doing this automatically.
+Both the main document and the supplementary document need to use
+the \styopt{record} option. The entries provided in the \csopt{src}
+set must have the same labels as those used in the supplementary
+document. (The simplest way to achieve this is to ensure that both
+documents use the same \ext{bib} files and the same prefixes.)
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{entry}\marg{sample,
+ \field{name}=\marg{sample},
+ \field{description}=\qtdelim{an example entry}
+}
+\strut
+\atentry{abbreviation}\marg{html,
+ \field{short}=\qtdelim{html},
+ \field{long}=\marg{hypertext markup language}
+}
+\strut
+\atentry{abbreviation}\marg{ssi,
+ \field{short}=\qtdelim{ssi},
+ \field{long}=\qtdelim{server-side includes}
+}
+\strut
+\atentry{index}\marg{goose,\field{plural}=\qtdelim{geese}}
+\end{codeenv}
+Now suppose the supplementary document is contained in the file
+\filefmt{suppl.tex}:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record},\styopt[section]{counter}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\cmd{renewcommand}\marg{\cmd{thesection}}\marg{S\cmd{arabic}\marg{section}}
+\cmd{renewcommand}\marg{\cmd{theHsection}}\marg{\cmd{thepart}.\cmd{thesection}}
+\strut
+\cmd{begin}\marg{document}
+\cmd{part}\marg{Sample Part}
+\cmd{section}\marg{Sample Section}
+\cs{gls}\marg{goose}. \cs{gls}\marg{sample}.
+\strut
+\cmd{part}\marg{Another Part}
+\cmd{section}\marg{Another Section}
+\cs{gls}\marg{html}.
+\cs{gls}\marg{ssi}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+This uses the \counter{section} counter for the locations and has a
+prefix (\code{\csfmt{thepart}.})\ for the section hyperlinks.
+
+Now let's suppose I have another document called \filefmt{main.tex}
+that uses the \code{sample} entry, but also needs to include the
+location (S1) from the supplementary document. The manual approached
+offered by \styfmt{glossaries-extra} is quite cumbersome and requires
+setting the \catattr{externallocation} attribute and using
+\ics{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue}
+and \glsaddopt[\encap{glsxtrsupphypernumber}]{format}.
+
+This can be simplified with \bibgls\ by using the
+\optfmt{supplemental-locations} option, described below.
+
+Version 1.36 of \isty{glossaries-extra-bib2gls} introduces some
+special location formatting commands that don't use the
+\catattr{externallocation} attribute, but instead have an extra
+argument that indicates the external reference. The additional
+argument means that it can't be used by the \glsaddopt{format}
+key, but with \bibgls\ you don't use \cs{glsadd} to record
+the external locations. Instead it obtains the records from
+the corresponding supplementary \ext{aux} file, and adjusts the
+location encapsulator as appropriate.
+
+If \bibgls\ detects an older version of \sty{glossaries-extra},
+it will only allow one external supplemental source, and
+will set the \catattr{externallocation} attribute and use
+the \encap{glsxtrsupphypernumber} format. Otherwise \bibgls\
+will allow multiple sources and use the newer method.
+
+\optsection{supplemental-locations}
+
+The value should be the base name (without the extension) of the
+supplementary document (\optfmt{suppl} in the above example).
+If you have at least version 1.36 of \sty{glossaries-extra},
+the value may be a comma-separated list of base names (without the
+extensions) of the supplementary documents. If an older version is
+detected, \bibgls\ will issue a warning and only accept the first
+element of the list.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[suppl]{supplemental-locations},\comment{fetch records from suppl.aux}
+ \csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{sample} document.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+The location list for \code{sample} will now be \qt{1, S1} (page~1
+from the main document and S1 from the supplementary document).
+
+With \sty{glossaries-extra} v1.36+, a regular location from the
+supplementary document will be encapsulated with:
+\nosecdef{glsxtrdisplaysupploc}
+By default, this simply creates an external hyperlink to the
+supplementary document with the location as the hyperlink text.
+The hyperlink is created using \meta{src} as the target path
+with the fragment part (anchor) formed from the prefix and
+location. The \catattr{externallocation} attribute is not set in
+this case. The actual formatting is done via:
+\nosecdef{glsxtrmultisupplocation}
+which ignores the \meta{format} argument by default. Its
+definition is simply:
+\begin{codeenv}
+\cmd{newcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{}
+ \marg{\comment{scope required to localise changes}
+ \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{}
+ \cs{glshypernumber}\marg{\idx{param}1}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+This locally sets the command \ics{glsxtrsupplocationurl}, which is checked
+by \ics{glshypernumber} to establish an external rather than internal link.
+You can redefine the supplemental location command to retain the original
+\idx{encap} used in the target document:
+\begin{codeenv}
+\cmd{renewcommand}*\marg{\gls{glsxtrmultisupplocation}}[3]\marg{\comment{}
+ \marg{\comment{scope required to localise changes}
+ \cmd{def}\cs{glsxtrsupplocationurl}\marg{\idx{param}2}\comment{}
+ \ics{csuse}\marg{\idx{param}3}\marg{\idx{param}1}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+but remember that if a hyperlink is required, the identified
+control sequence name must correspond to a command that
+uses \cs{glshyperlink} (such as \cs{hyperbf}), otherwise you
+will lose the hyperlink.
+
+With older versions of \sty{glossaries-extra},
+the original location format from the supplementary document
+will be replaced by \encap{glsxtrsupphypernumber}, which
+again produces an external hyperlink. The \catattr{externallocation}
+attribute also needs to be set (this can be done automatically with
+\csopt{supplemental-category}) to identify the external document.
+The original format can't be accessed.
+
+In both cases, if the document hasn't loaded the \isty{hyperref} package, the
+location will simply be displayed without a hyperlink. Even if both the main
+and the supplementary documents have loaded \sty{hyperref}, note that not all
+PDF viewers can handle external hyperlinks, and some that can open the external
+PDF file may not recognise the destination within that file.
+
+The special \code{nameref} locations (see
+\longarg{merge-nameref-on}) are still identified with
+\gls!{glsxtrdisplaylocnameref} but the \meta{file} argument will now
+be set.
+
+As from \bibgls\ v1.7, any awkward characters in the file path are
+replaced with \gls{bibglshrefchar} or (for \idx{non-ASCII} characters when
+\sty{fontspec} is loaded) \gls{bibglshrefunicode}. Both commands
+take two arguments: the hexadecimal character code and the actual
+character. In the case of \gls{bibglshrefchar}, the second
+argument is ignored, and the first is preceded by a literal percent
+character, so \filefmt{file name.pdf} will be converted to:
+\begin{codeenv}
+file\gls{bibglshrefchar}\marg{20}\marg{ }name.pdf
+\end{codeenv}
+which will expand to \verb|file%20name.pdf|.
+In the case of \gls{bibglshrefunicode}, the first argument is
+ignored, so \filefmt{skr\'aarnafn.pdf} will be converted to:
+\begin{codeenv}
+skr\gls{bibglshrefunicode}\marg{E1}\marg{\'a}arnafn.pdf
+\end{codeenv}
+which will expand to \code{skr\'aarnafn.pdf}.
+
+
+The supplementary locations lists are encapsulated within
+\gls{bibglssupplemental}. With \sty{glossaries-extra} v1.36+,
+this command will encapsulate the sub-lists with
+\gls{bibglssupplementalsublist}.
+
+So the above example with an old version of \sty{glossaries-extra}
+(pre 1.36) will set the supplemental location list (which only consists
+of one location) to:
+\begin{codeenv}
+\gls{bibglssupplemental}
+\marg{1}\marg{\ics{setentrycounter}\oarg{I}\marg{\counter{section}}\cs{glsxtrsupphypernumber}\marg{S1}}
+\end{codeenv}
+and the external target must be supplied through the
+\catattr{externallocation} attribute, which can be set
+with the \csopt{supplemental-category} option.
+
+Whereas with at least version 1.36, the list will be:
+\begin{codeenv}
+\gls{bibglssupplemental}\marg{1}\marg{\gls{bibglssupplementalsublist}\marg{1}\marg{suppl.pdf}
+\marg{\gls{glsxtrdisplaysupploc}\marg{I}\marg{\counter{section}}\marg{\encap{glsnumberformat}}\marg{suppl.pdf}\marg{S1}}}
+\end{codeenv}
+
+If an entry has both a main location list and a supplementary
+location list (such as the \code{sample} entry above), the lists
+will be separated by \gls!{bibglssupplementalsep}. The sub-lists
+(when supported) are separated by \gls{bibglssupplementalsubsep}.
+
+\optsection{supplemental-selection}
+
+In the above example, only the \code{sample} entry is listed in
+the main document, even though the supplementary document also
+references the \code{goose}, \code{html} and \code{ssi}
+entries. By default, only those entries that are referenced in the
+main document will have supplementary locations added (if found in
+the supplementary document's \iext{aux} file). You can additionally
+include other entries that are referenced in the supplementary
+document but not in the main document using
+\optfmt{supplemental-selection}. The \meta{value} may be one of the
+following:
+\begin{itemize}
+\item \optfmt{all}: add all the entries in the supplementary
+document that have been defined in the \ext{bib} files listed in
+\csopt{src} for this resource set in the main document.
+\item \optfmt{selected}: only add supplemental locations for entries
+that have already been selected by this resource set.
+\item \meta{label-1},\ldots,\meta{label-2}: in addition to all those
+entries that have already been selected by this resource set, also
+add the entries identified in the comma-separated list. If a label
+in this list doesn't have a record in the supplementary document's
+\ext{aux} file, it will be ignored.
+\end{itemize}
+Any records in the supplementary \ext{aux} file that aren't defined
+by the current resource set (through the \ext{bib} files listed in
+\csopt{src}) will be ignored. Entry aliases aren't taken into
+account when including supplementary locations.
+
+For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[suppl]{supplemental-locations},
+ \csopt[html,ssi]{supplemental-selection},
+ \csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{sample} document.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+This will additionally add the \code{html} and \code{ssi} entries
+even though they haven't been used in this document. The
+\code{goose} entry used in the supplementary document won't be
+included.
+
+\optsection{supplemental-category}
+
+The \field{category} field for entries containing supplemental location
+lists may be set using this option. If unset,
+\meta{value} defaults to the same as that given by the
+\csopt{category} option. The \meta{value} may either be a known
+identifier (as per \csopt{category}) or the category label. For example:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{colorlinks}\marg{hyperref}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[suppl]{supplemental-locations},
+ \csopt[html,ssi]{supplemental-selection},
+ \csopt[supplemental]{supplemental-category},
+ \csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{Gls}\marg{sample} document.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+\section{Sorting}
+\label{sec:sortingopts}
+
+Entries are typically displayed in an ordered list, but the
+\styfmt{glossaries-extra} package is versatile enough to be used in
+wider contexts than simple terms, symbols or abbreviations. For
+example, entries could contain theorems or problems where the
+\field{name} supplies the title and the \field{description} provides
+a description of the theorem or problem. Another field might then
+contain the proof or solution. Therefore, somewhat unusually for an
+indexing application, \bibgls\ also provides the option to shuffle
+the entries instead of sorting them.
+
+This section covers the resource options for sorting primary
+entries. See \sectionref{sec:dualoptssort} for sorting dual entries
+and also \csopt{sort-label-list} for sorting field values that
+contain a comma-separated list of entry labels (such as the
+\field{see} or \field{seealso} fields).
+
+The sort methods that use a comparison function (that is, all the
+sort methods except those listed in \tableref{tab:sortoptionsnosort})
+require a sort value for each entry. The function compares these
+values to determine the order. By default, this sort value is
+obtained from the \field{sort} field but for greater flexibility
+it's best to not actually set this field. \bibgls\ has a set of fallbacks
+that it uses if a field it needs to access is missing. These
+fallbacks depend on the entry type and resource settings.
+
+For example, if a term defined with \atentry{index} doesn't have the
+\field{sort} field set then \bibgls\ will use the value given by the
+\field{name} field because \field{name} is the fallback field for
+\field{sort} for \atentry{index} entries. If the \field{name} field
+isn't set either then \bibgls\ will use the fallback for that field.
+In the case of \atentry{index} that's the entry's label. If the
+\field{sort} field is explicitly set then there's no need to use the
+fallback.
+
+If, on the other hand, a term defined with \atentry{symbol} doesn't
+have the \field{sort} field set then \bibgls\ will use the value
+from the field identified by \csopt{symbol-sort-fallback}, which is
+the entry's label by default (not the \field{name} field).
+
+This means that if I don't explicitly set the \field{sort} field for
+any entries then I can, for example, sort terms defined with
+\atentry{index} by \field{name} and those defined with
+\atentry{symbol} by \field{description} with the setting:
+\begin{codeenv}
+\csopt[description]{symbol-sort-fallback}
+\end{codeenv}
+
+If the field used to obtain the sort value is changed
+(with \csopt{sort-field}) then the \field{sort} field won't be
+queried. This reduces the flexibility of selecting the most
+appropriate field for given entry types. For example,
+\csopt[name]{sort-field} will force all entries to be sorted by the
+\field{name} field, which may not be appropriate for symbols.
+
+\begin{important}
+If you choose a field whose value must be a label (such as
+\field{parent} or \field{group}) then the sort value will be that label.
+\end{important}
+
+You can have \atentry{preamble} definitions that
+can be hidden from \bibgls's interpreter. For example,
+\exfile{no-interpret-preamble.bib} might contain:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}1 \idx{param}2}}}
+\end{codeenv}
+which is loaded using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[no-interpret-preamble]{src},
+ \csopt[false]{interpret-preamble}}
+\end{codeenv}
+This provides a custom command:
+\nosecdef{sortop}
+for internal use in the document. (Remember it won't be defined on
+the first \LaTeX\ run before the \iext{glstex} file has been
+created and so is only used within entry fields.)
+
+Another file, say, \filefmt{interpret-preamble.bib} may provide
+a definition for \bibgls:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\gls{sortop}}[2]\marg{\idx{param}2, \idx{param}1}}}
+\end{codeenv}
+which can be processed with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble]{src}}
+\end{codeenv}
+to provide \bibgls\ with this definition.
+The \filefmt{entries.bib} file could contain:
+\begin{codeenv}
+\atentry{entry}\marg{caesar,
+ \field{name}=\marg{\gls{sortop}\marg{Gaius Julius}\marg{Caesar}},
+ \field{first}=\marg{Julius Caesar},
+ \field{text}=\marg{Caesar},
+ \field{description}=\marg{Roman politician and general}
+}
+\end{codeenv}
+and then be processed with:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\end{codeenv}
+
+The definition provided in \filefmt{interpret-preamble.bib}, which
+swaps the two arguments around, is now picked up by \bibgls, so the
+sort value becomes \code{Caesar, Gaius Julius}, but this new
+definition doesn't affect the document since \LaTeX\ has already
+defined \gls{sortop} from the first resource set, so the name will
+appear as \qt{Gaius Julius Caesar} in the glossary. (If you have
+\cs{renewcommand} rather than \cs{providecommand}, you can prevent
+the redefinition occurring in the document with
+\csopt[false]{write-preamble}.)
+
+Alternatively both of these \ext{bib} files can be loaded in one
+\idx{resourceset}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[interpret-preamble,entries]{src}}
+\end{codeenv}
+Another possibility is to provide a custom package that contains the
+command definitions for the \bibgls\ interpreter and load it with
+\longarg{custom-packages} instead of having the
+\filefmt{interpret-preamble.bib} file.
+
+\optsection{sort}
+
+The \csopt{sort} key indicates how primary entries should be sorted.
+If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the
+\csopt{sort} option isn't used then \csopt[doc]{sort} is assumed if the
+document has a language that's been detected by \sty{tracklang},
+otherwise \csopt[locale]{sort} is assumed.
+
+The \optfmt{\meta{method}\dhyphen reverse} options reverse the
+result returned by the corresponding \meta{method} comparator.
+However \optfmt{\meta{method}\dhyphen reverse} may not produce a
+list that's the exact reverse of the underlying non-reversed
+\meta{method} as the hierarchical structure or associated settings
+can affect the order.
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: No Actual Sorting}
+\label{tab:sortoptionsnosort}
+\centering
+\begin{tabular}{ll}
+\optfmt{none} or \optfmt{unsrt} & don't sort\tabularnewline
+\optfmt{random} & shuffle entries\tabularnewline
+\optfmt{use} & order of use\tabularnewline
+\optfmt{use-reverse} & reverse order of use
+\end{tabular}
+\end{table}
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: Alphabet}
+\label{tab:sortoptionsrule}
+\centering
+\begin{tabular}{ll}
+\meta{lang tag} & sort according to this language tag\tabularnewline
+\meta{lang tag}\optfmt{-reverse} & reverse sort according to this language tag\tabularnewline
+\optfmt{doc} & sort according to the document
+language\tabularnewline
+\optfmt{doc-reverse} & reverse sort according to the document
+language\tabularnewline
+\optfmt{locale} & sort according to the default
+locale\tabularnewline
+\optfmt{locale-reverse} & reverse sort according to the default
+locale\tabularnewline
+\optfmt{custom} & sort according to \csopt[\meta{custom
+rule}]{sort-rule}\tabularnewline
+\optfmt{custom-reverse} & reverse sort according to \csopt[\meta{custom rule}]{sort-rule}
+\end{tabular}
+\end{table}
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: Letter (Non-Locale)}
+\label{tab:sortoptionsletter}
+\centering
+\begin{tabular}{ll}
+\optfmt{letter-case} & case-sensitive letter sort\tabularnewline
+\optfmt{letter-case-reverse} & reverse case-sensitive letter
+sort\tabularnewline
+\optfmt{letter-nocase} & case-insensitive letter sort\tabularnewline
+\optfmt{letter-nocase-reverse} & reverse case-insensitive letter
+sort\tabularnewline
+\optfmt{letter-upperlower} & upper-lower letter sort\tabularnewline
+\optfmt{letter-upperlower-reverse} & reverse upper-lower letter
+sort\tabularnewline
+\optfmt{letter-lowerupper} & lower-upper letter sort\tabularnewline
+\optfmt{letter-lowerupper-reverse} & reverse lower-upper letter sort
+\end{tabular}
+\end{table}
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: Letter-Number}
+\label{tab:sortoptionsletternumber}
+\centering
+\begin{tabular}{ll}
+\optfmt{letternumber-case} & case-sensitive letter-number
+sort\tabularnewline
+\optfmt{letternumber-case-reverse} & reverse case-sensitive
+letter-number sort\tabularnewline
+\optfmt{letternumber-nocase} & case-insensitive letter-number
+sort\tabularnewline
+\optfmt{letternumber-nocase-reverse} & reverse case-insensitive
+letter-number sort\tabularnewline
+\optfmt{letternumber-upperlower} & upper-lower letter-number
+sort\tabularnewline
+\optfmt{letternumber-upperlower-reverse} & reverse upper-lower
+letter-number sort\tabularnewline
+\optfmt{letternumber-lowerupper} & lower-upper letter-number
+sort\tabularnewline
+\optfmt{letternumber-lowerupper-reverse} & reverse lower-upper letter-number sort
+\end{tabular}
+\end{table}
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: Numerical}
+\label{tab:sortoptionsnumerical}
+\centering
+\begin{tabular}{ll}
+\optfmt{integer} & integer sort\tabularnewline
+\optfmt{integer-reverse} & reverse integer sort\tabularnewline
+\optfmt{hex} & hexadecimal sort\tabularnewline
+\optfmt{hex-reverse} & reverse hexadecimal sort\tabularnewline
+\optfmt{octal} & octal sort\tabularnewline
+\optfmt{octal-reverse} & reverse octal sort\tabularnewline
+\optfmt{binary} & binary sort\tabularnewline
+\optfmt{binary-reverse} & reverse binary sort\tabularnewline
+\optfmt{float} & float sort\tabularnewline
+\optfmt{float-reverse} & reverse float sort\tabularnewline
+\optfmt{double} & double sort\tabularnewline
+\optfmt{double-reverse} & reverse double sort\tabularnewline
+\optfmt{numeric} & locale-sensitive numeric sort\tabularnewline
+\optfmt{numeric-reverse} & reverse locale-sensitive numeric
+sort\tabularnewline
+\optfmt{currency} & locale-sensitive currency sort\tabularnewline
+\optfmt{currency-reverse} & reverse locale-sensitive currency
+sort\tabularnewline
+\optfmt{percent} & locale-sensitive percent sort\tabularnewline
+\optfmt{percent-reverse} & reverse locale-sensitive percent
+sort\tabularnewline
+\optfmt{numberformat} & locale-sensitive custom numeric
+sort\tabularnewline
+\optfmt{numberformat-reverse} & reverse locale-sensitive custom numeric sort
+\end{tabular}
+\end{table}
+
+\begin{table}[p]
+\caption{Summary of Available Sort Options: Date-Time}
+\label{tab:sortoptionsdatetime}
+\centering
+\begin{tabular}{ll}
+\optfmt{date} & locale-sensitive date sort\tabularnewline
+\optfmt{date-reverse} & reverse locale-sensitive date
+sort\tabularnewline
+\optfmt{datetime} & locale-sensitive date-time sort\tabularnewline
+\optfmt{datetime-reverse} & reverse locale-sensitive date-time
+sort\tabularnewline
+\optfmt{time} & locale-sensitive time sort\tabularnewline
+\optfmt{time-reverse} & reverse locale-sensitive time sort
+\end{tabular}
+\end{table}
+
+\subsubsection{No Sort}
+
+The sort methods listed in \tableref{tab:sortoptionsnosort}
+don't actually perform any sorting. This may cause a problem for
+hierarchical entries. In some cases this can lead to detached child
+entries or an attempt to define a child entry before its parent.
+\begin{itemize}
+
+\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries.
+(The entries will be in the order they were processed when parsing
+the data.)
+
+\item \optfmt{random}: shuffles rather than sorts the entries.
+This won't work if there are hierarchical entries, so it's best
+to use this option with \csopt{flatten}. The seed for the
+random generator can be set using \csopt{shuffle} (which
+also automatically sets \csopt[random]{sort} and \csopt{flatten}).
+
+\item \optfmt{use}: order of use. This order is determined
+by the records written to the \iext{aux} file by the \styopt{record}
+package option. Dependencies and cross-references (including those
+identified with \ics{glssee}) come after entries with records.
+
+Note that this is different from using the analogous option with
+\idx{makeindex} or \idx{xindy}, which does actually sort
+numerically, where each entry has an associated number set on the
+first use of that term that's used as the sort value.
+
+\item \optfmt{use-reverse}: reverses the order that would be
+obtained with \csopt[use]{sort} without reference to hierarchy.
+
+\end{itemize}
+
+\subsubsection{Alphabet}
+
+The sort methods listed in \tableref{tab:sortoptionsrule} are for
+alphabets that are defined by a rule. These usually ignore most
+punctuation and may ignore modifiers (such as accents). Use with
+\csopt{break-at} to determine whether or not to split at word
+boundaries. The collation rules (except for the custom options) are obtained
+from the \idx{localeprovider} (see page~\pageref{locale.provider}).
+
+\begin{itemize}
+\item \meta{lang tag}: sort according to the rules of the locale
+given by the \idx{IETF} language tag \meta{lang tag}.
+
+\item \meta{lang tag}\optfmt{-reverse}: reverse sort according to the rules of the locale
+given by the \idx{IETF} language tag \meta{lang tag}.
+
+\item \optfmt{locale}: equivalent to
+\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained
+from the \idx{JRE} (which usually matches the
+operating system's locale).
+
+\item \optfmt{locale-reverse}: equivalent to
+\csopt[\meta{lang tag}-reverse]{sort} where \meta{lang tag} is obtained
+from the \idx{JRE}.
+
+\item \optfmt{doc}: sort the entries according to the document
+language. This is equivalent to \csopt[\meta{lang tag}]{sort}
+where \meta{lang tag} is the locale associated with the document
+language. In the case of a multi-lingual document, \meta{lang tag}
+is the locale of the last language resource file to be loaded through
+\isty{tracklang}'s interface. It's best to explicitly set the locale
+for multi-lingual documents to avoid confusion. If no languages have been tracked, this
+option is equivalent to \csopt[locale]{sort}.
+
+\item \optfmt{doc-reverse}: as \optfmt{doc} but in reverse order.
+
+\item \optfmt{custom}: sort the entries according to the
+rule provided by \csopt{sort-rule}.
+
+\item \optfmt{custom-reverse}: reverse sort the entries according to the
+rule provided by \csopt{sort-rule}.
+\end{itemize}
+
+Note that \csopt[\meta{locale}]{sort} can provide more detail about the
+given locale than \csopt[doc]{sort}, depending on how the document
+language has been specified. For example, with:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{ngerman}\marg{babel}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
+\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
+\end{codeenv}
+the language tag will be \code{de-1996}, which doesn't have an
+associated region, so this is equivalent to using \csopt[de-1996]{sort}.
+Whereas with:
+\begin{codeenv}
+\cmd{documentclass}\oarg{de-DE-1996}\marg{article}
+\cmd{usepackage}\oarg{ngerman}\marg{babel}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
+\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
+\end{codeenv}
+the language tag will be \code{de-DE-1996} because \isty{tracklang}
+has picked up the locale from the document class options, so this is
+equivalent to using \csopt[de-DE-1996]{sort}. This is
+only likely to cause a difference if a language has different
+sorting rules according to the region or if the language may be
+written in multiple scripts.
+
+If no language package is loaded then the default is \csopt[locale]{sort}
+rather than \csopt[doc]{sort}. For example, with:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\cmd{usepackage}\oarg{\styopt{record}}\marg{glossaries}
+\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src}}
+\end{codeenv}
+the language tag will be whatever is the default locale for the \idx{JVM}.
+For a user in Germany, this could be \code{de-DE-1996} and for a user
+in Austria this could be \code{de-AT-1996}.
+
+A multilingual document will need to have the \csopt{sort} specified
+when loading the \idx{resourceset} to ensure the correct language is chosen.
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[english-terms]{src},\csopt[en-GB]{sort}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[german-terms]{src},\csopt[de-DE-1996]{sort}}
+\end{codeenv}
+
+\subsubsection{Letter (Non Locale)}
+
+The sort methods listed in \tableref{tab:sortoptionsletter}
+use letter comparators. These simply compare the
+character codes. The \optfmt{-nocase} options first convert the
+\field{sort} field to \idx{lowercase} before performing the sort to
+provide a case-insensitive comparison.
+
+Punctuation isn't ignored.
+Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to
+emulate \idx!{xindy}['s] locale letter ordering. The examples below
+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.
+\Idx{uppercase} and \idx{lowercase} are in separate letter groups.
+Example:
+
+\code{Africa} (letter group \idx{uppercase} \qt{A}), \code{Brazil}
+(letter group \idx{uppercase} \qt{B}), \code{aardvark} (letter group
+\idx{lowercase} \qt{a}), \code{antelope} (letter group
+\idx{lowercase} \qt{a}), \code{bee} (letter group \idx{lowercase} \qt{b}).
+
+\item \optfmt{letter-case-reverse}: reverse case-sensitive letter sort.
+Example:
+
+\code{bee} (letter group \idx{lowercase} \qt{b}), \code{antelope}
+(letter group \idx{lowercase} \qt{a}), \code{aardvark} (letter group
+\idx{lowercase} \qt{a}) \code{Brazil} (letter group \idx{uppercase}
+\qt{B}), \code{Africa} (letter group \idx{uppercase} \qt{A}).
+
+\item \optfmt{letter-nocase}: case-insensitive letter sort. (All
+\idx{uppercase} characters will have first been converted to
+\idx{lowercase} in the sort value.)
+Example:
+
+\code{aardvark} (letter group \qt{A}), \code{Africa}
+(letter group \qt{A}), \code{antelope} (letter group \qt{A}),
+\code{bee} (letter group \qt{B}),
+\code{Brazil} (letter group \qt{B}).
+
+\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter sort.
+Example:
+
+\code{Brazil} (letter group \qt{B}), \code{bee} (letter group
+\qt{B}), \code{antelope} (letter group \qt{A}), \code{Africa}
+(letter group \qt{A}), \code{aardvark} (letter group \qt{A}).
+
+\item \optfmt{letter-upperlower}: each character pair is first
+compared according to their \idx{lowercase} values. If these are equal,
+then they are compared according to case. This puts upper and lower
+case in the same letter group but the \idx{uppercase} comes first.
+Example:
+
+\code{Africa} (letter group \qt{A}), \code{aardvark} (letter group
+\qt{A}), \code{antelope} (letter group \qt{A}), \code{Brazil}
+(letter group \qt{B}), \code{bee} (letter group \qt{B}).
+
+\item \optfmt{letter-upperlower-reverse}: reverse upper-lower letter sort.
+This now puts the \idx{lowercase} letters first within the letter group.
+Example:
+
+\code{bee} (letter group \qt{B}), \code{Brazil} (letter group
+\qt{B}), \code{antelope} (letter group \qt{A}), \code{aardvark}
+(letter group \qt{A}), \code{Africa} (letter group \qt{A}).
+
+\item \optfmt{letter-lowerupper}: each character pair is first
+compared according to their \idx{lowercase} values. If these are equal,
+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}),
+\code{Africa} (letter group \qt{A}), \code{bee} (letter group
+\qt{B}), \code{Brazil} (letter group \qt{B}).
+
+\item \optfmt{letter-lowerupper-reverse}: reverse lower-upper letter sort.
+This now puts the \idx{uppercase} letters first within the letter group.
+Example:
+
+\code{Brazil} (letter group \qt{B}), \code{bee} (letter group
+\qt{B}), \code{Africa} (letter group \qt{A}), \code{antelope}
+(letter group \qt{A}), \code{aardvark} (letter group \qt{A}).
+
+\end{itemize}
+
+\subsubsection{Letter-Number}
+\label{sec:letternumber}
+
+The sort methods listed in \tableref{tab:sortoptionsletternumber}
+use a letter-integer hybrid. They behave in a similar way to the
+above letter sort methods, but if an integer number pattern is detected in
+the string then the sub-string containing the number will be compared.
+This only detects base 10 integers (unlike the numeric methods
+such as \csopt[hexadecimal]{sort} or \csopt[float]{sort}) but in
+addition to recognising all the digits in the Unicode \idx{numberdecimaldigit}
+category it also recognises the subscript and
+superscript digits, such as \textsuperscript{1} (\hex{00B9})
+and \textsuperscript{2} (\hex{00B2}).
+
+As with the letter sort methods, letters are compared using a
+character code comparison not by a locale alphabet. The closest
+locale-sensitive equivalent is to use \csopt{sort-number-pad} with a
+locale sort method.
+
+\begin{figure}
+\figcontents
+{%
+\begin{tikzpicture}[every node/.style={minimum size=9mm},
+ ampersand replacement=\&]
+\matrix[font={\Large\ttfamily}]
+{
+ \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}}; \&[20mm]
+ \node[draw]{a\hexsb{61}}; \& \node{$=$}; \& \node[draw]{a\hexsb{61}};
+ \\
+ \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}}; \&
+ \node[draw]{b\hexsb{62}}; \& \node{$=$}; \& \node[draw]{b\hexsb{62}};
+ \\
+ \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}}; \&
+ \node[draw]{c\hexsb{63}}; \& \node{$=$}; \& \node[draw]{c\hexsb{63}};
+ \\
+ \node[draw,ultra thick]{1\hexsb{31}}; \& \node{$<$}; \&
+ \node[draw,ultra thick]{6\hexsb{36}}; \&
+ \node (n1) {1}; \& \node{$>$}; \& \node[draw,ultra thick]{6};
+ \\
+ \node[draw]{2\hexsb{32}}; \& \& \node[draw]{b\hexsb{62}}; \&
+ \node (n2) {2}; \& \& \node[draw]{b\hexsb{62}};
+ \\
+ \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}}; \&
+ \node[draw]{f\hexsb{66}}; \& \& \node[draw]{a\hexsb{61}};
+ \\
+ \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}}; \&
+ \node[draw]{o\hexsb{6f}}; \& \& \node[draw]{r\hexsb{72}};
+ \\
+ \node[draw]{o\hexsb{6f}}; \& \& \&
+ \node[draw]{o\hexsb{6f}}; \& \&
+ \\[10pt]
+ \& \node[font=\rmfamily]{\subfigfmt{a}}; \& \&
+ \& \node[font=\rmfamily]{\subfigfmt{b}}; \&
+ \\
+};
+\draw[ultra thick] (n1.north east) rectangle (n2.south west);
+\end{tikzpicture}%
+}
+{%
+ \caption[Regular letter comparison vs letter-number
+ comparison]{Regular letter comparison vs letter-number comparison.
+ Comparing the strings \code{abc12foo} and \code{abc6bar}:
+ \subfigfmt{a} \optfmt{letter-case}; \subfigfmt{b}
+ \optfmt{letternumber-case}.}%
+}
+{fig:letternumber}
+\end{figure}
+
+For example, suppose the first string is \code{abc12foo}
+and the second string is \code{abc6bar}.
+\Figureref{fig:letternumber}\subfigfmt{a} shows the regular letter
+comparison using \csopt[letter-case]{sort}, where the subscript
+indicates the hexadecimal character code. The first three characters
+from each string are identical (\code{abc}). At this point there's
+no difference detected, so the comparator moves on to the next
+character, \code{1\hexsb{31}} for the first string and
+\code{6\hexsb{36}} for the second string. Since \hex{31} is less than
+\hex{36}, the first string (\code{abc12foo}) is considered less than the second
+(\code{abc6bar}).
+
+With the letter-number comparison using
+\csopt[letternumber-case]{sort}, the comparator starts in much the
+same way. The first three characters from each string are still
+identical, so the comparator moves on to the next character,
+\code{1} for the first string and \code{6} for the second.
+These are now both recognised as digits, so the comparator
+looks ahead and reads in any following digits (if present). For the
+first case, this is the sub-string \code{12} and, for the second
+case, \code{6} (\figureref{fig:letternumber}\subfigfmt{b}). These
+are both compared according to their integer representation $12 >
+6$, so \code{abc12bar} is considered greater than \code{abc6foo}
+(that is, \code{abc12bar} comes after \code{abc6foo}).
+
+The same result occurs for other numbering systems, for example if
+the Basic Latin digits 1, 2 and 6 are replaced with the
+corresponding Devanagari digits \devone, \devtwo\ and
+\devsix. (But note that the letter comparisons will still be
+based on their Unicode values not according to a particular locale.
+This type of sort method is intended primarily for symbolic values,
+such as chemical formulae, rather than for words or phrases.)
+
+Signed integers are also recognised, so \code{abc-12foo} is less
+than \code{abc+6bar}, which is again different from the result
+obtained with a straight letter comparator where the
+character~\code{+} (\hex{2B})
+comes before the character~\code{-} (\hex{2D}). The sign must be followed by at
+least one digit for it to be recognised as a number otherwise it's
+treated as a punctuation character.
+
+If only one sub-string is numeric
+then the \csopt{letter-number-rule} is used to determine the
+result. Where both sub-strings are non-numeric, then the
+\csopt{letter-number-punc-rule} setting is used to determine the result
+according to the category of the characters, which may be one of the
+following:
+\begin{itemize}
+\item white space: belongs to the Unicode \idx{separatorspace}
+category. If both characters are white space, then they are compared
+according to their Unicode values otherwise they are ordered according to
+the \csopt{letter-number-punc-rule} setting.
+
+\item letter: belongs to one of the Unicode categories \idx{letteruppercase},
+\idx{letterlowercase}, \idx{lettertitlecase},
+\idx{lettermodifier} or \idx{letterother}. If both characters
+are letters then, for sort method \optfmt{letternumber-\meta{modifier}},
+the characters are compared in the same way as the
+corresponding \optfmt{letter-\meta{modifier}} sort method otherwise
+they are ordered according to the
+\csopt{letter-number-punc-rule} setting.
+
+\item punctuation: everything else. If both characters are
+punctuation, then they are compared according to their Unicode value
+otherwise they are ordered according to
+the \csopt{letter-number-punc-rule} setting.
+\end{itemize}
+For simplicity, the actual sort value used during sorting isn't a
+simple string but is converted into a list of objects that represent
+one of: letter, integer, space or other (punctuation). This reduces
+the amount of parsing of substrings that needs to be performed.
+
+The examples below show the ordering of the list:
+\code{CH\textsubscript{2}O},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{CO}, \code{Cl},
+\code{Co}, \code{Co\textsubscript{2}O\textsubscript{3}},
+\code{Co\textsubscript{2}}, \code{CO\textsubscript{2}},
+\code{CoMoO\textsubscript{4}} and \code{CoCl\textsubscript{2}},
+for the setting
+\csopt[between]{letter-number-rule}, where the subscripts are
+the Unicode subscript characters.
+
+\begin{itemize}
+\item \optfmt{letternumber-case}: case-sensitive
+letter-number sort. Example:
+
+\code{CH\textsubscript{2}O},
+\code{CO},
+\code{CO\textsubscript{2}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{Cl},
+\code{Co},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}},
+\code{Co\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}}.
+
+(Order determined by: $\mathtt{H} < \mathtt{O} < 5 < 10 < \mathtt{l} < \mathtt{o}$.)
+
+\item \optfmt{letternumber-case-reverse}: reverse case-sensitive
+letter-number sort. Example:
+
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{Co\textsubscript{2}},
+\code{CoMoO\textsubscript{4}},
+\code{CoCl\textsubscript{2}},
+\code{Co},
+\code{Cl},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{CO\textsubscript{2}},
+\code{CO},
+\code{CH\textsubscript{2}O}.
+
+\item \optfmt{letternumber-nocase}: case-insensitive
+letter-number sort. The sort value is first converted to lower
+case. Note that \csopt[between]{letter-number-rule} doesn't make
+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},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{CH\textsubscript{2}O},
+\code{Cl},
+\code{CO},
+\code{Co},
+\code{CO\textsubscript{2}},
+\code{Co\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}}.
+
+(Order determined by: $5 < 10 < \mathtt{h} < \mathtt{l} < \mathtt{o}$.)
+
+\item \optfmt{letternumber-nocase-reverse}: reverse case-insensitive
+letter-number sort, so numbers will now always come after letters. Example:
+
+\code{CoMoO\textsubscript{4}},
+\code{CoCl\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{Co\textsubscript{2}},
+\code{CO\textsubscript{2}},
+\code{Co},
+\code{CO},
+\code{Cl},
+\code{CH\textsubscript{2}O},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
+
+\item \optfmt{letternumber-upperlower}: upper-lower
+letter-number sort. This behaves slightly differently to
+\optfmt{letter-upperlower} when used with \csopt[between]{letter-number-rule}
+and has a more complicated rule that's determined by the character
+following the number and implied numbers inserted between letters.
+(There was a bug in earlier versions that has been corrected in v1.8
+so you may find a slightly different ordering when upgrading.)
+Example:
+
+\code{CH\textsubscript{2}O},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{Cl},
+\code{CO},
+\code{CO\textsubscript{2}},
+\code{Co},
+\code{Co\textsubscript{2}},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}},
+\code{Co\textsubscript{2}O\textsubscript{3}}.
+
+(Order determined by: $\mathtt{H} < 5\mathtt{H} < 10\mathtt{H} <
+\mathtt{l} < \mathtt{O} < \mathtt{o}$, and for the terms starting
+with \code{CO} or \code{Co}: 2 comes after null and $\mathtt{C} <
+\mathtt{M} < 2\mathtt{O}$.)
+
+Compare this with \csopt[before letter]{letter-number-rule} which
+results in the order:
+
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{CH\textsubscript{2}O},
+\code{Cl},
+\code{CO},
+\code{CO\textsubscript{2}},
+\code{Co},
+\code{Co\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}}.
+
+\item \optfmt{letternumber-upperlower-reverse}: reverse upper-lower
+letter-number sort. Example (with \csopt[between]{letter-number-rule}):
+
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CoMoO\textsubscript{4}},
+\code{CoCl\textsubscript{2}},
+\code{Co\textsubscript{2}},
+\code{Co},
+\code{CO\textsubscript{2}},
+\code{CO},
+\code{Cl},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{CH\textsubscript{2}O}.
+
+Compare this with \csopt[before letter]{letter-number-rule} which
+results in the order:
+
+\code{CoMoO\textsubscript{4}},
+\code{CoCl\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{Co\textsubscript{2}},
+\code{Co},
+\code{CO\textsubscript{2}},
+\code{CO},
+\code{Cl},
+\code{CH\textsubscript{2}O},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH}.
+
+Remember that the associated settings are reversed
+well. So \csopt[before letter]{letter-number-rule}
+results in numbers \emph{after} letters.
+
+\item \optfmt{letternumber-lowerupper}: lower-upper letter-number
+sort. As with the upper-lower option, this behaves slightly differently to
+\optfmt{letter-lowerupper} when used with \csopt[between]{letter-number-rule}
+and has a more complicated rule.
+Example:
+
+\code{CH\textsubscript{2}O},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{Cl},
+\code{Co},
+\code{Co\textsubscript{2}},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CO},
+\code{CO\textsubscript{2}}.
+
+Compare this with \csopt[before letter]{letter-number-rule} which
+results in the order:
+
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{CH\textsubscript{2}O},
+\code{Cl},
+\code{Co},
+\code{Co\textsubscript{2}},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CoCl\textsubscript{2}},
+\code{CoMoO\textsubscript{4}},
+\code{CO},
+\code{CO\textsubscript{2}}.
+
+\item \optfmt{letternumber-lowerupper-reverse}: reverse lower-upper
+letter-number sort. Example (with \csopt[between]{letter-number-rule}):
+
+\code{CO\textsubscript{2}},
+\code{CO},
+\code{Co\textsubscript{2}O\textsubscript{3}},
+\code{CoMoO\textsubscript{4}},
+\code{CoCl\textsubscript{2}},
+\code{Co\textsubscript{2}},
+\code{Co},
+\code{Cl},
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}},
+\code{C\textsubscript{5}H\textsubscript{4}NCOOH},
+\code{CH\textsubscript{2}O}.
+
+\end{itemize}
+
+\subsubsection{Numerical}
+\label{sec:numerical}
+
+The sort methods listed in \tableref{tab:sortoptionsnumerical}
+use numeric comparisons. The sort value is expected to
+be a numeric value. If it can't be parsed then it's treated as 0
+(and a warning will be written to the transcript).
+These all recognise the digits in the Unicode \qt{Number,
+Decimal Digit} category but, unlike the hybrid letter-number
+comparators above, they don't recognise the superscript or subscript
+digits. The \qt{non-locale} in some of the descriptions below
+indicates that the method doesn't recognise locale-sensitive
+formatting, such as group separators.
+\begin{itemize}
+\item \optfmt{integer}: integer sort. This is for non-locale integer sort
+values.
+
+\item \optfmt{integer-reverse}: as above but reverses the order.
+
+\item \optfmt{hex}: hexadecimal integer sort. This is for non-locale
+hexadecimal sort values.
+
+\item \optfmt{hex-reverse}: as above but reverses the order.
+
+\item \optfmt{octal}: octal integer sort. This is for non-locale
+octal sort values.
+
+\item \optfmt{octal-reverse}: as above but reverses the order.
+
+\item \optfmt{binary}: binary integer sort. This is for non-locale binary sort
+values.
+
+\item \optfmt{binary-reverse}: as above but reverses the order.
+
+\item \optfmt{float}: single-precision sort. This is for non-locale
+decimal sort values.
+
+\item \optfmt{float-reverse}: as above but reverses the order.
+
+\item \optfmt{double}: double-precision sort. This is for non-locale
+decimal sort values.
+
+\item \optfmt{float-reverse}: as above but reverses the order.
+
+\item \optfmt{numeric}: locale-sensitive numeric sort. Use
+\csopt{numeric-locale} to set the locale.
+
+\item \optfmt{numeric-reverse}: as above but reverses the order.
+
+\item \optfmt{currency}: locale-sensitive currency sort. Use
+\csopt{numeric-locale} to set the locale.
+
+\item \optfmt{currency-reverse}: as above but reverses the order.
+
+\item \optfmt{percent}: locale-sensitive percent sort. Use
+\csopt{numeric-locale} to set the locale.
+
+\item \optfmt{percent-reverse}: as above but reverses the order.
+
+\item \optfmt{numberformat}: locale-sensitive custom numeric sort. Use
+\csopt{numeric-locale} to set the locale and
+\csopt{numeric-sort-pattern} to set the number pattern.
+
+\item \optfmt{numberformat-reverse}: as above but reverses the order.
+
+\end{itemize}
+
+In general, it doesn't make much sense to have hierarchical entries
+that need to be sorted by a number, but it is possible as long as each
+level uses the same type of numbering.
+
+\subsubsection{Date-Time}
+
+The sort methods listed in \tableref{tab:sortoptionsdatetime}
+are for dates and times. Use \csopt{date-sort-format}
+and \csopt{date-sort-locale} to specify the date format and locale.
+\begin{itemize}
+\item \optfmt{date}: sort dates.
+
+\item \optfmt{date-reverse}: as above but reverses the order.
+
+\item \optfmt{datetime}: sort date and time information.
+
+\item \optfmt{datetime-reverse}: as above but reverses the order.
+
+\item \optfmt{time}: sort times.
+
+\item \optfmt{time-reverse}: as above but reverses the order.
+
+\end{itemize}
+
+If the field you want to sort by contains a date then the
+simplest way to sort is to ensure the date is in ISO format
+and then just use a letter sort. However it may be that
+the date is in the format particular to your locale or you have a
+mix of \era{AD} and \era{BC}. In which
+case you can use one of the date/time sort options (such as
+\csopt[date]{sort} or \csopt[date-reverse]{sort}). The locale
+is assumed to be your default locale (as given by the \idx{JVM})
+but if you are using a different locale this can
+be set with \csopt{date-sort-locale}. The pattern is assumed
+to be the default for that locale but you can change this with
+\csopt{date-sort-format}. If you provide your
+own custom pattern you must make sure that it matches the selected
+\optfmt{sort} option.
+
+Take care if you switch from using the \idx{JRE} to the \idx{CLDR}
+ \idx{localeprovider} as you may find the default pattern changes.
+
+The locale and pattern information is used by \bibgls\ to parse the
+field. If the field value can't be parsed then \bibgls\ will issue
+a warning and assume the current date (or time).
+
+The actual sort value that's used by the comparator is numeric. In
+the case of the time-based \csopt[datetime]{sort} and
+\csopt[time]{sort} (or their \optfmt{-reverse} versions), this value
+is the number of milliseconds since 1st~January, 1970. In the case
+of \csopt[date]{sort} (or \csopt[date-reverse]{sort}), this value is
+obtained from $a(y\times10000 + m\times100 + d)$ where $y$ is the
+year, $m$ is the month number, $d$ is the day of month number, and
+$a$ is an integer representation of the era ($-1$ for \era{BC} and
+$+1$ for \era{AD}).
+
+Unlike the numeric sort methods (such as \csopt[integer]{sort})
+the date-time sort methods set the \field{sort} field to a value
+that can be more easily parsed within the document and that should
+mostly achieve the same ordering if a letter comparator were to be used
+with it (except for \era{BC} dates, where the order needs to be
+reversed). This has the by-product of providing a field that
+you can access within the document that can be more easily parsed by
+\LaTeX.
+
+In general, it doesn't make much sense to have hierarchical entries
+that need to be sorted by date, but it is possible as long as each
+level uses the same date format.
+
+For example, suppose my \ext{bib} file contains:
+\begin{codeenv}
+\atentry{entry}\marg{journalentry,
+ \field{name}=\marg{10 Jan 2017},
+ \field{description}=\marg{an interesting journal entry}
+}
+\end{codeenv}
+The \field{name} field uses an abbreviated UK date format.
+If all my other entries also use this format in the \field{name}
+then I can sort them chronologically:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[date]{sort},
+ \csopt[en-GB]{date-sort-locale},
+ \csopt[medium]{date-sort-format}
+}
+\end{codeenv}
+(The medium format is actually the default for this locale,
+and the locale matches my system locale, so I could omit
+both \csopt{date-sort-locale} and \csopt{date-sort-format}.)
+
+If \longarg{verbose} mode is on, the transcript will show
+the label, sort value and numeric value for each entry.
+In this case, the information is:
+\begin{verbatim}
+journalentry -> '+1 2017-01-10' [20170110]
+\end{verbatim}
+The first value is the label (\code{journalentry}), the second
+value is assigned to the \field{sort} field
+(\code{+1 2017-01-10}) and the number in square brackets
+is the actual numeric value used by the comparator. The signed
+number at the start of the sort field \code{+1} is the numeric
+representation of the era as used for the $a$ variable in the
+computation of the numeric value (as described earlier).
+
+If I change the format to \csopt[short]{date-sort-format},
+then the date can't be parsed correctly and \bibgls\ will
+issue the following warning:
+\begin{verbatim}
+Warning: Can't parse sort value '10 Jan 2017' for 'journalentry'
+(pattern: 'dd/MM/yyyy')
+\end{verbatim}
+This shows the value that \bibgls\ is trying to
+parse (\code{10 Jan 2017}) for the entry identified by
+the given label (\code{journalentry}). The pattern \bibgls\
+expects is also given (\code{dd/MM/yyyy}).
+
+\optsection{shuffle}
+
+Automatically sets \csopt[random]{sort} and \csopt{flatten}.
+The value \meta{seed} may be omitted. If present, it should
+be an integer used as a seed for the random number generator.
+
+\optsection{sort-field}
+
+The \csopt{sort-field} key indicates which field provides the sort
+value. The \meta{field} must be a recognised field name or you
+may use \csopt[id]{sort-field} to sort according to the label.
+The default value is the \field{sort} field (which is typically
+inferred rather than explicitly set).
+
+Example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-terms]{src},\comment{data in entries-terms.bib}
+ \csopt[category]{sort-field},\comment{sort by 'category' field}
+ \csopt[letter-case]{sort}\comment{case-sensitive letter sort}
+}
+\end{codeenv}
+This sorts the entries according to the \field{category} field using
+a case-sensitive letter comparison.
+
+If an entry is missing a value for \meta{field}, then the value of
+the fallback field will be used instead. If \csopt{missing-sort-fallback} is
+set, then that's used as the fallback, otherwise it depends on the
+entry type.
+If no fallback field can be found, the entry's label will be used.
+
+For the specific case with the default \csopt[sort]{sort-field}
+setting, the fallback for the \field{sort} field is governed not
+only by the entry type but also by some associated settings:
+
+\begin{itemize}
+\item If the entry is defined using \atentry{entry} (or a dual form
+that acts like \atentry{entry}), then if the \field{sort} field is
+missing the value is obtained from the field identified by
+\csopt{entry-sort-fallback}. If that field is also missing then
+that field's fallback is used.
+
+\item For the index entry types like \atentry{index} or
+\atentry{indexplural}, then if the \field{sort} field is missing the
+value is obtained from the \field{name} field. If that field is also
+missing, then the value is obtained from the particular entry type's
+fallback for the \field{name} field. (For example, the entry's label
+for \atentry{index} or the \field{plural} field for
+\atentry{indexplural}.)
+
+\item If the entry is defined with an abbreviation type (for
+example, \atentry{abbreviation} or \atentry{acronym}) then if the
+\field{sort} field is missing, \bibgls\ will fallback on the field
+given by \csopt{abbreviation-sort-fallback}.
+
+\item The symbol-like entry types fallback on the field given by
+\csopt{symbol-sort-fallback} if the \field{sort} field is missing.
+
+\item Entries defined using \atentry{bibtexentry} fallback on the field
+given by \csopt{bibtexentry-sort-fallback}, which defaults to the
+\field{name} field. Note that this only applies to the main entry.
+The spawned \atentry{contributor} entries behave like
+\atentry{index}.
+
+\end{itemize}
+Use \csopt{dual-sort-field} when sorting dual entries.
+
+\optsection{missing-sort-fallback}
+
+With \csopt[\meta{sort-field}]{sort-field}, if the value of the field
+identified by \meta{sort-field} is missing, then \bibgls\ behaves as
+follows:
+\begin{enumerate}
+\item If \csopt[\meta{fallback-field}]{missing-sort-fallback} is set, then
+\bibgls\ will fallback on the value provided by the field
+\meta{fallback-field}. If \meta{fallback-field} is
+missing, then \bibgls\ will query the entry type's fallback for
+\meta{fallback-field} (not for \meta{sort-field}).
+\item If the entry type has a fallback rule for \meta{sort-field},
+then that rule is used. When \csopt[sort]{sort-field} this means:
+\begin{itemize}
+\item If the entry was defined using one of the index types (such as
+\atentry{index}), then \bibgls\ will fallback on the \field{name}
+field.
+
+\item If the entry was defined using the \atentry{entry} type (or a
+dual form that acts like \atentry{entry}), then \bibgls\ will
+fallback on the field given by \csopt{entry-sort-fallback}.
+
+\item If the entry was defined using
+one of the symbol types (such as \atentry{symbol}), then \bibgls\
+will fallback on the field given by \csopt{symbol-sort-fallback}.
+
+\item If the entry was defined using
+one of the abbreviation types (such as \atentry{abbreviation}), then \bibgls\
+will fallback on the field given by
+\csopt{abbreviation-sort-fallback}.
+
+\item If the entry was defined using \atentry{bibtexentry} (but not
+the spawned \atentry{contributor} entries), then \bibgls\ will
+fallback on the field given by
+\csopt{bibtexentry-sort-fallback}.
+\end{itemize}
+If \meta{sort-field} is not \field{sort}, then there may not be a
+fallback, in which case the next condition applies:
+\item Otherwise the sort value will be set to the entry label and \bibgls\
+will issue a warning.
+\end{enumerate}
+The default setting is \csopt[\empty]{missing-sort-fallback}, which
+means that step~1 above is omitted.
+
+Use \csopt{dual-missing-sort-fallback} when sorting dual entries
+separately from primaries, and use
+\csopt{secondary-missing-sort-fallback} for \csopt{secondary}
+sorting.
+
+\optsection{entry-sort-fallback}
+
+The regular entry types (such as \atentry{entry} and
+\atentry{dualentry}) will, by default, fallback on the \field{name}
+field if the \field{sort} field is missing (assuming
+\csopt[sort]{sort-field}). If you prefer to
+fallback on a different field, then you can use this option to
+specify the field.
+Note that \csopt{missing-sort-fallback} overrides this setting.
+
+This setting doesn't affect the index type of entries, such as
+\atentry{index} or \atentry{indexplural}. This is useful if your
+glossary contains homographs (terms with the same spelling) which
+can't be distinguished by the sort comparators. For example, suppose
+my file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{pagelist,
+ \field{name}=\marg{page list},
+ \field{description}=\marg{a list of individual pages or page ranges}
+}
+\strut
+\atentry{index}\marg{glossary}
+\strut
+\atentry{entry}\marg{glossarylist,
+ \field{parent}=\marg{glossary},
+ \field{description}={list of technical words}
+}
+\strut
+\atentry{entry}\marg{glosscol,
+ \field{parent}=\marg{glossary},
+ \field{description}=\marg{collection of glosses}
+}
+\end{codeenv}
+Now first consider a document that uses the default settings:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}\oarg{\styopt{record},\styopt{subentrycounter},\styopt[\glostyle{treenoname}]{style}}\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+A test document describing \cs{glspl}\marg{pagelist} and
+\cs{gls}\marg{glosscol} (collection) vs \cs{gls}\marg{glossarylist} (list).
+\strut
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+The default behaviour for \atentry{entry} if the \field{sort} field
+is missing is to fallback on the \field{name} field. If the
+\field{name} field is missing (as with \code{glossarylist} and
+\code{glosscol}), then the value is obtained from the
+\field{name} field from the parent entry. The parent entry for these
+homographs is the \code{glossary} entry, which was defined with
+\atentry{index} and doesn't have the \field{name} field. For the
+\atentry{index} entries, if \field{name} is missing the value is
+obtained from the label.
+
+Therefore both \code{glossarylist} and \code{glosscol} end
+up with the same sort value: \code{glossary}. This triggers a
+message in verbose mode (\longarg{verbose}) which can be found
+in the transcript file:
+\begin{verbatim}
+Identical sort values for 'glossarylist' and 'glosscol'
+Falling back on ID
+\end{verbatim}
+So the actual sort values used are \qt{glossarylist} and
+\qt{glosscol}. This puts the \code{glossarylist} entry
+before the \code{glosscol} entry.
+
+Now suppose a minor modification is made to the document:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}
+ \oarg{
+ \csopt[entries]{src},
+ \csopt[description]{entry-sort-fallback}
+ }
+\end{codeenv}
+This means that when the sort function fails to find the
+\field{sort} field for the terms defined with \atentry{entry}, it
+will fallback on the \field{description} field. This doesn't affect
+the terms defined with \atentry{index}, which still fallback on the
+\field{name} field. This time there's no message in the transcript
+file and the \code{glosscol} entry now comes before the
+\code{glossarylist} entry.
+
+\begin{important}
+The \csopt{entry-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a term defined with
+\atentry{entry} and finds that the field hasn't been set. This means
+that this setting has no effect if you explicitly set the \field{sort}
+field or if you change the field used for sorting
+(\csopt{sort-field}).
+\end{important}
+
+\optsection{abbreviation-sort-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{sort} field is
+missing (assuming \csopt[sort]{sort-field}). If you prefer to
+fallback on a different field, then you can use this option to
+specify the field. For example,
+\csopt[long]{abbreviation-sort-fallback}. Note that if you use
+\csopt[name]{sort-field}, then the fallback field will be given by
+\csopt{abbreviation-name-fallback} if the \field{name} field is
+omitted. The \meta{field} value must be a known field label.
+
+Note that \csopt{missing-sort-fallback} overrides this setting.
+
+\begin{important}
+The \csopt{abbreviation-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for an abbreviation and finds
+that the field hasn't been set. This means that this setting has no effect
+if you explicitly set the \field{sort} field or if you change the field used
+for sorting (\csopt{sort-field}).
+\end{important}
+
+\optsection{symbol-sort-fallback}
+
+The entry types that define symbols (such as \atentry{symbol} and
+\atentry{number}) will, by default, fallback on the label if the
+\field{sort} field is missing (assuming the default
+\csopt[sort]{sort-field}). If you prefer to fallback on a different
+field, then you can use this option to specify the field. For
+example, \csopt[name]{symbol-sort-fallback}. The \meta{field} value
+must be a known field label.
+
+Note that \csopt{missing-sort-fallback} overrides this setting.
+
+\begin{important}
+The \csopt{symbol-sort-fallback} setting is only used when \bibgls\
+tries to access the \field{sort} field for a symbol and finds
+that the field hasn't been set. This means that this setting has no effect
+if you explicitly set the \field{sort} field or if you change the field used
+for sorting (\csopt{sort-field}).
+\end{important}
+
+\optsection{bibtexentry-sort-fallback}
+
+The main \atentry{bibtexentry} entry types will, by default,
+fallback on the \field{name} if the
+\field{sort} field is missing (assuming the default
+\csopt[sort]{sort-field}). If you prefer to fallback on a different
+field, then you can use this option to specify the field.
+
+Note that \csopt{missing-sort-fallback} overrides this setting.
+
+\begin{important}
+The \csopt{bibtexentry-sort-fallback} setting is only used when
+\bibgls\ tries to access the \field{sort} field for a main entry
+defined with \atentry{bibtexentry} and finds that the field hasn't
+been set. This means that this setting has no effect if you
+explicitly set the \field{sort} field or if you change the field used for
+sorting (\csopt{sort-field}).
+\end{important}
+
+\optsection{trim-sort}
+
+If the interpreter is used to determine the sort value, this setting
+governs whether or not the interpreter should trim leading and
+trailing spaces. The default setting is \csopt[true]{trim-sort}.
+
+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 \idx{regex} substitutions
+on the sort value and has the same syntax as \csopt{labelify-replace}.
+The value is required for this key but may be empty, which indicates
+that the setting is switched off.
+
+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{codeenv}
+\cs{ensuremath}\marg{\ics{approx} 3.14}
+\end{codeenv}
+then the interpreter will convert this to $\mathtt{\approx}$\texttt{3.14} but:
+\begin{codeenv}
+\csopt[\marg{\cs{glshex}2248}\marg{}]{sort-replace}
+\end{codeenv}
+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
+provided with \optfmt{sort-rule}. If \csopt{sort} is not set to
+\optfmt{custom}, the \optfmt{sort-rule} setting will be ignored.
+This setting uses Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator}
+class~\cite{rulebasedcollator}, and the rule syntax needs to conform
+to that format.
+
+Remember that the options will be expanded as they are written to
+the \iext{aux} file, so be careful of any special characters that
+occur in the rule. For the special characters \idx{param}
+\idx{commentchar} \idx{sbchar} \idx{colsep} \idx{bgroupchar} and
+\idx{egroupchar} you can use \ics{cs.hash}, \ics{cs.percent},
+\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and
+\ics{cs.closebrace}. These will be written to the \ext{aux} file
+with the leading backslash, but \bibgls\ will remove it for this
+resource option. Remember that the \styfmt{glossaries} package
+provides \ics{glsbackslash} and \ics{glstildechar} which can be used
+to produce a literal backslash (\idx{backslashchar}) and tilde
+(\idx{tildechar}).
+
+You can also
+use \stringu\meta{hex} (where \meta{hex} is a hexadecimal
+code) to represent a Unicode character. For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[custom]{sort},
+ \csopt[< a,A < b,B < c,C < ch,Ch,CH < d,D
+ < dd,Dd,DD < e,E < f,F < ff,Ff,FF
+ < g,G < ng,Ng,NG < h,H < ij,Ij,IJ
+ < i,I < j,J < k,K < l,L < ll,Ll,LL < m,M
+ < n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH
+ < s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z
+ < \stringu00E6,\stringu00C6]{sort-rule}
+}
+\end{codeenv}
+It's best to use \ics{cs.string} rather than \ics{protect} to avoid
+unwanted spaces interfering with \meta{hex}. Note that
+\sty{glossaries-extra} v1.21+ provides\footnote{The command
+definition was moved to \isty{glossaries-extra-bib2gls} from version
+1.27 since it's only needed with \bibgls.}\ \ics{glshex}
+which just does \stringu\ so you can do
+\code{\ics{glshex} 00E6} instead of \code{\stringu00E6}.
+This is only one character different, but you can redefine
+\ics{glsxtrresourceinit} to locally set \ics{u} to \ics{glshex} while
+the protected write is performed. For example:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\cmd{let}\cmd{u}\cs{glshex}}
+\end{codeenv}
+Then you can just do \code{\csfmt{u}00E6} instead of \code{\stringu00E6}.
+
+The \isty{glossaries-extra-bib2gls} package (which is automatically loaded by
+the \styopt{record} option) provides some commands for common rule blocks
+that may be used in the construction of custom rules. For example:
+\begin{codeenv}
+\csopt[\ics{glsxtrcontrolrules}
+ ;\ics{glsxtrspacerules}
+ ;\ics{glsxtrnonprintablerules}
+ ;\ics{glsxtrcombiningdiacriticrules}
+ ,\ics{glsxtrhyphenrules}
+ <\ics{glsxtrgeneralpuncrules}
+ <\ics{glsxtrdigitrules}
+ <\ics{glsxtrfractionrules}
+ <\ics{glsxtrMathItalicGreekIrules}
+ <\ics{glsxtrGeneralLatinIVrules}
+ <\ics{glsxtrLatinAA}
+ <\ics{glsxtrLatinOslash}
+]{sort-rule}
+\end{codeenv}
+This places the Greek maths symbols (such as \ics{alpha}) before the
+Latin block. See the \sty{glossaries-extra} documentation for
+further details of these commands.
+
+You might find it convenient to provide similar commands in a
+package for rules you may often need. For example, suppose I have a
+package called, say, \styfmt{mapsymbols} for providing map symbols:
+\begin{codeenv}
+\cmd{NeedsTeXFormat}\marg{LaTeX2e}
+\cmd{ProvidesPackage}\marg{mapsymbols}
+\comment{some package or font loading stuff here to provide}
+\comment{the appropriate symbols}
+\cmd{newcommand}\marg{\cmd{Stadium}}\marg{\ldots}
+\cmd{newcommand}\marg{\cmd{Battlefield}}\marg{\ldots}
+\cmd{newcommand}\marg{\cmd{Harbour}}\marg{\ldots}
+\comment{etc}
+\strut
+\comment{Provide a rule block:}
+\cmd{newcommand}\marg{\cmd{MapSymbolOrder}}\marg{\comment{}
+ \cs{glshex} 2694 \comment{crossed-swords 0x2694}
+ < \cs{glshex} 2693 \comment{anchor 0x2693}
+ < \cs{glshex} 26BD \comment{football 0x26BD}
+}
+\end{codeenv}
+In addition to \filefmt{mapsymbols.sty}, I also need to create
+\filefmt{mapsymbols.bib} to provide the appropriate definitions for
+\bibgls:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\icharhex{2693}}
+\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
+\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}}}
+\end{codeenv}
+The use of \ics{glsxtrprovidecommand} will override any previous
+definitions of these commands in \bibgls's interpreter but will act
+like \ics{providecommand} within the document, and so won't
+interfere with the commands defined in \filefmt{mapsymbols.sty}.
+Now I can just do:
+\begin{codeenv}
+\cmd{usepackage}\marg{mapsymbols}\comment{my custom package}
+\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[mapsymbols,\comment{<--- my custom mapsymbols.bib}
+ entries\comment{data in entries.bib}
+ ]{src},
+ \csopt[custom]{sort},
+ \csopt[\cs{glsxtrcontrolrules}
+ ;\cs{glsxtrspacerules}
+ ;\cs{glsxtrnonprintablerules}
+ ;\cs{glsxtrcombiningdiacriticrules}
+ ,\cs{glsxtrhyphenrules}
+ <\cs{glsxtrgeneralpuncrules}
+ <\cs{glsxtrdigitrules}
+ <\cs{glsxtrfractionrules}
+ <\cmd{MapSymbolOrder} \comment{<--- custom map symbols}
+ <\cs{glsxtrMathItalicGreekIrules}
+ <\ics{glsxtrGeneralLatinIrules}
+ ]{sort-rule}
+}
+\end{codeenv}
+
+An alternative to providing \filefmt{mapsymbols.bib} is to provide a
+custom package just for \bibgls' use. For example,
+\filefmt{mapsymbols-bib2gls.sty}:
+\begin{codeenv}
+\comment{Provided for \bibgls\ only.}
+\comment{Use \cmd{usepackage}\marg{mapsymbols} in the document.}
+\cmd{NeedsTeXFormat}\marg{LaTeX2e}
+\cmd{ProvidesPackage}\marg{mapsymbols-bib2gls}
+\cs{glsxtrprovidecommand}\marg{\cmd{Harbour}}\marg{\charhex{2693}}
+\cs{glsxtrprovidecommand}\marg{\cmd{Battlefield}}\marg{\charhex{2694}}
+\cs{glsxtrprovidecommand}\marg{\cmd{Stadium}}\marg{\charhex{26BD}}
+\cmd{endinput}
+\end{codeenv}
+and instruct \bibgls\ to parse it with
+\code{\longarg{custom-packages} mapsymbols-bib2gls} (and use
+\filefmt{mapsymbols.sty} in the document). Remember that \bibgls\
+isn't a \TeX\ engine so make sure to only use simple commands in
+this file.
+
+\optsection{break-at}
+
+This option automatically implements
+\csopt[\meta{option}]{dual-break-at} and
+\csopt[\meta{option}]{secondary-break-at}.
+
+The alphabet sort options (\tableref{tab:sortoptionsrule}) typically
+list non-letter characters before alphabetical characters and spaces
+are quite often in the ignored set. This means that the alphabet
+sort options are naturally in a letter order, similar to
+\idx{xindy}['s] \code{ord/letorder} module. (This isn't the same as
+\csopt[letter-nocase]{sort}, which just sorts according to the
+Unicode value not according to a particular alphabet.)
+
+In order to replicate \idx!{makeindex} and \idx!{xindy}['s] default word
+order, \bibgls\ splits up the sort value at word boundaries and
+inserts a marker (identified by \csopt{break-marker}).
+For example, if the sort value is \qt{sea lion} then it's actually
+converted to \verb"sea|lion|" whereas \qt{sea} becomes \verb"sea|"
+and \qt{seal} becomes \verb"seal|". The default marker is \verb"|"
+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 comma)
+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}
+\item \optfmt{word}: break at word boundaries (default).
+Note that what constitutes a word varies
+according to the locale but usually anything that's not alphanumeric
+will designate a word-boundary. The characters between words are
+discarded.
+For example, the sort value \qt{Tom, Dick, and Harry} becomes
+\verb"Tom|Dick|and|Harry", which has discarded the comma and space
+characters.
+\item \optfmt{character}: break after each character.
+\item \optfmt{sentence}: break after each sentence.
+\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 \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}.
+\item \optfmt{upper-upper-word}: first applies break-points
+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, 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. You can find the break points in the
+\field{sort} field for the entry's definition in the \ext{glstex}
+file (which is provided for information rather than for use in the
+document). Alternatively, use the \longarg{debug} switch to show
+the break points in the transcript. (This will also show the
+collation rule.)
+
+\optsection{break-marker}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{marker}]{dual-break-marker} and
+\csopt[\meta{marker}]{secondary-break-marker}.
+
+The break marker can be changed using
+\csopt[\meta{marker}]{break-marker}, where \meta{marker} is
+the character to use. For example, \csopt[-]{break-marker} will use a
+hyphen. The marker may be empty, which effectively strips the
+inter-word punctuation. For example, with
+\csopt[\empty]{break-marker}, \qt{Tom, Dick, and Harry} becomes
+\code{TomDickandHarry} and \qt{sea lion} simply becomes
+\code{sealion}. If \meta{marker} is omitted,
+\csopt[\empty]{break-marker} is assumed.
+
+\optsection{sort-number-pad}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{number}]{dual-sort-number-pad},
+\csopt[\meta{number}]{secondary-sort-number-pad}.
+
+If \meta{number} is greater than 1, any integer sub-strings found
+in the sort value will be zero-padded up to this value. Since the
+\code{-} character is often ignored by rule-based sort methods,
+any signs found will be replaced with the markers given by
+\csopt{sort-pad-plus} and \csopt{sort-pad-minus}, which should be
+chosen to ensure that negative numbers are ordered before positive
+numbers (if this is desired). An unsigned number will have the
+\csopt{sort-pad-plus} marker inserted before it. The default value
+is \csopt[0]{sort-number-pad}, which doesn't implement any padding.
+
+If you use this with a locale sort method, it's best to also set
+\csopt[none]{break-at}, as the default word boundary break points
+will likely be confused by a mix of alphanumerics.
+
+\optsection{sort-pad-plus}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{marker}]{dual-sort-pad-plus},
+\csopt[\meta{marker}]{secondary-sort-pad-plus}.
+
+This option only has an effect when used with
+\csopt[\meta{number}]{sort-number-pad} where \meta{number} is
+greater than 1. Positive numbers will have their sign replaced with
+\meta{marker}. The default setting is \csopt[>]{sort-pad-plus}.
+
+\optsection{sort-pad-minus}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{marker}]{dual-sort-pad-minus},
+\csopt[\meta{marker}]{secondary-sort-pad-minus}.
+
+This option only has an effect when used with
+\csopt[\meta{number}]{sort-number-pad} where \meta{number} is
+greater than 1. Negative numbers will have their sign replaced with
+\meta{marker}. The default setting is \csopt[<]{sort-pad-plus}.
+
+\optsection{identical-sort-action}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{value}]{dual-identical-sort-action} and
+\csopt[\meta{value}]{secondary-identical-sort-action}.
+
+This option determines what the comparator should do if
+two entries at the same hierarchical level are considered
+equal. The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{none}: don't take any further action if sort values are
+identical;
+\item\optfmt{id}: if sort values are identical, compare
+the entry labels;
+\item\optfmt{original id}: if sort values are identical, compare the
+original unprefixed entry labels (as given in the \ext{bib} file);
+\item\meta{field}: if sort values are identical, compare
+the values from the given \meta{field}.
+\end{itemize}
+In each case (other than \csopt[none]{identical-sort-action}) a
+simple case-sensitive string comparison is used. If \meta{value}
+isn't a recognised keyword or valid field an error will occur. The
+default setting is \csopt[id]{identical-sort-action}. If you're
+using one of the sort rules listed in \tableref{tab:sortoptionsrule}
+and you also want a locale-sensitive sort used on the fallback, then
+you need to use \csopt{sort-suffix} instead.
+
+\bibgls\ allows duplicate sort values, but this can cause a problem
+for hierarchical entries where parent entries with duplicate sort
+fields are clumped together and their children follow. To prevent
+this from happening, the \csopt[id]{identical-sort-action}
+setting will fallback on comparing the labels. Since all labels
+must be unique, this means comparisons between two different entries
+are all either strictly higher or strictly lower.
+
+This action occurs after any suffixes have been appended through
+\csopt{sort-suffix}.
+
+\optsection{sort-suffix}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{value}]{dual-sort-suffix} and
+\csopt[\meta{value}]{secondary-sort-suffix}.
+The value may be one of:
+\begin{itemize}
+\item\optfmt{none}: don't append a suffix to any \field{sort} value;
+\item\optfmt{non-unique}: append a numeric suffix to non-unique
+ \field{sort} values;
+\item\meta{field}: append the value of the given field (if set) to
+ the \field{sort} field. The given field must be defined (has an
+ associated key for use in \gls{newglossaryentry}) but may be unset.
+ If the interpreter is on, the field contents will be interpreted.
+ If the field is just a label (such as the \field{category} field)
+ you may find it simpler to use
+ \csopt[\meta{field}]{identical-sort-action} instead.
+\end{itemize}
+The default setting is \csopt[none]{sort-suffix}.
+
+This option only affects the alphabetic
+(\tableref{tab:sortoptionsrule}), letter
+(\tableref{tab:sortoptionsletter}) and letter-number
+(\tableref{tab:sortoptionsletternumber}) sort rules. For the other
+types of sort methods (not including the no-sort options listed in
+\tableref{tab:sortoptionsnosort}) you'll need to use
+\csopt{identical-sort-action} to prevent problems occurring with
+duplicate sort values.
+
+In the case of \csopt[non-unique]{sort-suffix}, this will only append a
+suffix to the duplicate sort values (within the same hierarchical
+level). The first sort value to be encountered isn't given a suffix.
+
+The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix
+if that field is set, but (if set) it will apply the suffix to all
+\field{sort} values, even those that are unique.
+
+If you use \longarg{verbose}, then \bibgls\ will write information
+in the transcript when it appends a suffix to the sort value. The
+message:
+\begin{alltt}
+Sort value '\meta{sort}' (entry '\meta{id}') not unique for the entry's
+hierarchical level.
+\end{alltt}
+indicates that an entry with the given \meta{sort} value has already
+been found within the same hierarchical level as the currently
+processed entry (whose label is given by \meta{id}). The same
+hierarchical level in this context means that either both entries
+don't have a parent or both entries have the same parent. (That is,
+the entries are considered siblings.)
+
+This message will then be followed by:
+\begin{alltt}
+Appending suffix '\meta{suffix}' to the sort value '\meta{sort}'
+for entry '\meta{id}'.
+\end{alltt}
+which indicates that the entry (identified by the label \meta{id})
+has been assigned the sort value given by \meta{sort}\meta{suffix}.
+If any break markers are applied, this is done after the suffix has
+been appended.
+
+For example, suppose in my document I want to write about \appfmt{makeglossaries}
+(the application) and \csfmt{makeglossaries} (the command). I might
+decide to define semantic commands:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\ics{texttt}\marg{\idx{param}1}}
+\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}
+\end{codeenv}
+In my \ext{bib} file I might have:
+\begin{codeenv}
+\atentry{entry}\marg{cs.makeglossaries,
+ \field{name}=\marg{\cmd{command}\marg{makeglossaries}},
+ \field{category}=\marg{command},
+ \field{description}=\marg{opens glossary files}
+}
+\strut
+\atentry{entry}\marg{ap.makeglossaries,
+ \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
+ \field{category}=\marg{application},
+ \field{description}=\marg{Perl script}
+}
+\end{codeenv}
+If \bibgls\ is provided with the definitions of \csfmt{application}
+and \csfmt{command} (by interpreting the \atentry{preamble} or a
+package provided with \longarg{custom-packages}) then it will
+determine that the sort value for \code{cs.makeglossaries} is
+\csfmt{makeglossaries} and the sort value for
+\code{ap.makeglossaries} is just \code{makeglossaries}. These are
+two distinct sort values from \bibgls's point of view although the
+sort rule may consider them identical if the rule ignores the
+\idx{escchar} character (such as the locale sort methods), in which case,
+\bibgls\ will then act according to \csopt{identical-sort-action}.
+
+If \bibgls\ isn't provided with these custom definitions, then it
+will ignore those semantic commands and both entries will end up with
+the sort value \code{makeglossaries}. The second instance will be
+recognised as a duplicate and the sort value will be converted to
+\code{makeglossaries1} (where the automated suffix is \code{1} and
+the suffix marker, see below, is the empty string). Whereas with,
+say, \csopt[.]{sort-suffix-marker}\ then the sort value would become
+\code{makeglossaries.1}.
+
+For comparison, consider the following document:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt[indexgroup]{style}]\marg{glossaries}
+\strut
+\ics{cs.makeglossaries}
+\strut
+\cs{newcommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}}
+\cs{newcommand}*\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}
+\strut
+\gls{newglossaryentry}\marg{cs.makeglossaries}\marg{\comment{}
+ \field{name}=\marg{\cmd{command}\marg{makeglossaries}},
+ \field{description}=\marg{opens glossary files}}
+\strut
+\gls{newglossaryentry}\marg{ap.makeglossaries}\marg{\comment{}
+ \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
+ \field{description}=\marg{Perl script}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}.
+\ics{printglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+
+This uses \idx{makeindex}, which puts both entries in the
+\qt{Symbols} group (since they both start with \idx{escchar} from the
+start of \csfmt{command} and \csfmt{application}, respectively).
+The ordering is \appfmt{makeglossaries}, \csfmt{makeglossaries}
+because \qt{a} (second character of \csfmt{application}) comes
+before \qt{c} (second character of \csfmt{command}).
+
+The switch to \idx{xindy} just involves adding the \styopt{xindy}
+package option:
+\begin{codeenv}
+\cs{usepackage}[\styopt{xindy},\styopt[indexgroup]{style}]\marg{glossaries}
+\end{codeenv}
+This results in a glossary that only contains one entry,
+\csfmt{makeglossaries}, because \idx{xindy} merges entries with
+duplicate sort values and the sort values end up as duplicates
+because \idx{xindy} discards the \csfmt{application} and
+\csfmt{command} control sequences. Although \bibgls\ also ignores
+unknown control sequences, it doesn't perform this merger.
+
+If I add:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}*\marg{\cmd{application}}[1]\marg{\cs{texttt}\marg{\idx{param}1}}
+\cs{providecommand}\marg{\cmd{command}}[1]\marg{\cs{texttt}\marg{\cs{glsbackslash} \idx{param}1}}}}
+\end{codeenv}
+to the earlier \ext{bib} file (called, say, \filefmt{entries.bib})
+then the document can be altered to use \bibgls:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},
+ \csopt[non-unique]{sort-suffix},
+ \csopt[none]{identical-sort-action}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{cs.makeglossaries} and \cs{gls}\marg{ap.makeglossaries}.
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+This uses the default \csopt[locale]{sort} which considers \idx{escchar}
+an ignored (punctuation) character, so both \csfmt{makeglossaries} and
+\appfmt{makeglossaries} are listed in the \qt{M} letter group, even
+though the interpreter has determined that the sort value for
+\code{cs.makeglossaries} is the literal string \csfmt{makeglossaries}.
+Note that in this case \bibgls\ doesn't detect duplicate sort values
+since it only uses a simple string comparison to detect duplicates
+rather than using the collator.
+
+If I switch to using a letter-based sort rule instead, for example
+\csopt[letter-nocase]{sort}, then \csfmt{makeglossaries} will be
+listed in the \qt{Symbols} letter group since the leading \idx{escchar}
+from the sort value \csfmt{makeglossaries} isn't ignored with this
+rule.
+
+Now let's suppose I use \csopt[false]{interpret-preamble} to prevent
+\bibgls\ from interpreting the preamble:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries.bib]{src},\csopt[false]{interpret-preamble}}
+\end{codeenv}
+This means that the custom commands won't be recognised and will
+therefore be ignored, so both entries will have their sort values reduced to
+\code{makeglosssaries}.
+
+The first entry to be processed is \code{cs.makeglossaries} because
+it's the first to be selected. This is assigned the sort value
+\code{makeglossaries}. (Note that, unless you use
+\csopt[unsrt]{sort}, the initial selection order is based on the record
+order. In this example, \code{cs.makeglossaries} has the first
+record in the \ext{aux} file.)
+
+The next entry to be processed is \code{ap.makeglossaries}. This
+also ends up with the sort value \code{makeglossaries} so \bibgls\
+converts this to \code{makeglossaries1} and (with verbose mode on)
+the following messages are written to the transcript:
+\begin{verbatim}
+Sort value 'makeglossaries' (entry 'ap.makeglossaries') not unique
+for the entry's hierarchical level.
+Appending suffix '1' to the sort value 'makeglossaries' for entry
+'ap.makeglossaries'.
+\end{verbatim}
+Both entries are listed in the \qt{M} letter group in the order
+\csfmt{makeglossaries}, \appfmt{makeglossaries}.
+
+If the records are reversed:
+\begin{codeenv}
+\cs{gls}\marg{ap.makeglossaries} and \cs{gls}\marg{cs.makeglossaries}.
+\end{codeenv}
+then the sort value for \code{cs.makeglossaries} is now considered
+the duplicate and the order is reversed: \appfmt{makeglossaries},
+\csfmt{makeglossaries}.
+
+Suppose now I modify the \ext{bib} file so that
+\code{ap.makeglossaries} is defined as:
+\begin{codeenv}
+\atentry{entry}\marg{ap.makeglossaries,
+ \field{name}=\marg{\cmd{application}\marg{makeglossaries}},
+ \field{category}=\marg{application},
+ \field{description}=\marg{Perl script (must be used with \cs{gls}\marg{cs.makeglossaries})}
+}
+\end{codeenv}
+and suppose the document only contains an explicit reference to
+\code{ap.makeglossaries}:
+\begin{codeenv}
+\cmd{begin}\marg{document}
+\cs{gls}\marg{ap.makeglossaries}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+Now \code{ap.makeglossaries} is the first entry to be selected
+because entries with records are always selected before any
+(unrecorded) dependencies. In this case \code{cs.makeglossaries} is
+only selected because it's required by \code{ap.makeglossaries}. Now
+\code{ap.makeglossaries} is the first to have its sort value
+assigned, and it's \code{cs.makeglossaries} that has the duplicate.
+This means that the ordering in the glossary is now:
+\appfmt{makeglossaries}, \csfmt{makeglossaries}.
+
+An oddity occurs if the glossary is moved to the start of the
+document:
+\begin{codeenv}
+\cmd{begin}\marg{document}
+\cs{printunsrtglossaries}
+\cs{gls}\marg{ap.makeglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+In this case, the first document build:
+\begin{verbatim}
+pdflatex myDoc
+bibgls --group --verbose myDoc
+pdflatex myDoc
+\end{verbatim}
+leads to the ordering described above:
+\appfmt{makeglossaries}, \csfmt{makeglossaries}.
+However, the next document build has a new record for
+\code{cs.makeglossaries} occurring in the glossary (within the
+description of \code{ap.makeglossaries}) which means it's now the
+first entry to be selected so the ordering switches to:
+\csfmt{makeglossaries}, \appfmt{makeglossaries}.
+In this type of situation you might be better off with the
+\csopt[id]{identical-sort-action} option instead.
+
+Remember that you can temporarily switch off the indexing by locally
+setting:
+\begin{codeenv*}
+\ics{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}
+\end{codeenv*}
+Since the glossary preamble is scoped, you can simply do
+\begin{codeenv}
+\ics{appto}\ics{glossarypreamble}\marg{\cs{GlsXtrSetDefaultGlsOpts}\marg{\glsopt{noindex}}}
+\end{codeenv}
+to switch off the indexing within the glossary (or use
+\ics{apptoglossarypreamble}). Note that this is
+different to using:
+\begin{codeenv}
+\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+which creates an \idx{ignoredrecord}. Even though the record is ignored
+(and so won't show in the location list) the record still influences
+the selection order and the record count.
+
+\optsection{sort-suffix-marker}
+
+This automatically implements the dual and secondary settings
+\csopt[\meta{value}]{dual-sort-suffix-marker} and
+\csopt[\meta{value}]{secondary-sort-suffix-marker}.
+
+If a suffix is appended to the sort value (see above) then it will
+be separated by the suffix marker, which can be set with
+\csopt[\meta{value}]{sort-suffix-marker} where \meta{value} is the
+marker. By default the marker is empty. You can use \stringu\meta{hex}
+or \cs{glshex}\meta{hex} to indicate Unicode characters outside the
+\idx{ASCII} range. If, for some reason, you want to use a special
+character, such as \idx{param}, you will need to precede it with
+\ics{cs.string} (for example \code{\cs{cs.string}\idx{param}}) or
+use the above hexadecimal markup. If you use \ics{cs.hash} it will
+be treated as a literal string containing a backslash followed by a
+hash character.
+
+\optsection{strength}
+
+This option automatically implements
+\csopt[\meta{value}]{dual-strength} and
+\csopt[\meta{value}]{secondary-strength}.
+
+The collation strength used by the alphabet sort methods
+(\tableref{tab:sortoptionsrule}) can be set
+to the following values: \optfmt{primary} (default),
+\optfmt{secondary}, \optfmt{tertiary} or \optfmt{identical}. These
+indicate the difference between two characters, but the exact
+assignment is locale dependent. See the documentation for Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator}
+class}~\cite{collator} for further details.
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{index}\marg{resume}
+\atentry{index}\marg{RESUME}
+\atentry{index}\marg{resumee, \field{name}=\marg{r\ics{acute}esum\cs{acute}e}}
+\atentry{index}\marg{rat}
+\atentry{index}\marg{rot}
+\atentry{index}\marg{aardvark}
+\atentry{index}\marg{zoo}
+\end{codeenv}
+and the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{resumee}, \cs{gls}\marg{resume}, \cs{gls}\marg{RESUME},
+\cs{gls}\marg{aardvark}, \cs{gls}\marg{rat}, \cs{gls}\marg{rot}, \cs{gls}\marg{zoo}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+then this uses the default \csopt[primary]{strength}, so the entries
+are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo.
+
+If the strength is changed to \optfmt{secondary}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[en]{sort},\csopt[entries]{src},\csopt[secondary]{strength}}
+\end{codeenv}
+then the entries are listed as aardvark, rat, resume, RESUME,
+r\'esum\'e, rot, zoo.
+
+If the strength is changed to \optfmt{tertiary} or
+\optfmt{identical}, there's no difference from
+\csopt[secondary]{strength} for this particular example.
+
+This option is ignored by non-alphabet sorts (such as letter or numeric).
+
+\optsection{decomposition}
+
+This option automatically implements the dual and secondary settings
+\csopt[\meta{value}]{dual-decomposition} and
+\csopt[\meta{value}]{secondary-decomposition}.
+
+The collation decomposition used by alphabet sort methods
+(\tableref{tab:sortoptionsrule}) can be set
+to the following values: \optfmt{canonical} (default),
+\optfmt{full} or \optfmt{none}. This determines how Unicode composed
+characters are handled. The fastest mode is \optfmt{none} but is
+only appropriate for languages without accents. The slowest mode is
+\optfmt{full} but is the most complete for languages with \idx{non-ASCII}
+characters. See the documentation for Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\code{Collator}
+class}~\cite{collator} for further details.
+This option is ignored by non-alphabet sorts (such as letter or numeric).
+
+\optsection{letter-number-rule}
+
+This automatically implements the dual and secondary settings
+\csopt[\meta{value}]{dual-letter-number-rule}
+and
+\csopt[\meta{value}]{secondary-letter-number-rule}.
+
+If you use one of the letter-number sort methods
+(\tableref{tab:sortoptionsletternumber}), then you can determine the
+comparison between a number and letter. The \meta{value} may be
+one of:
+\begin{itemize}
+\item\optfmt{before letter}: numbers are considered less than any
+letter.
+
+\item\optfmt{after letter}: numbers are considered greater than any
+letter.
+
+\item\optfmt{between}: (default) numbers come between letter cases.
+With the \optfmt{letternumber\dhyphen case} sort option, this will put
+numbers after \idx{uppercase} and before \idx{lowercase}. This
+setting doesn't make much sense with the
+\optfmt{letternumber\dhyphen nocase} option but, if used, this will put
+numbers before letters. The \optfmt{letternumber\dhyphen upperlower} and
+\optfmt{letternumber\dhyphen lowerupper} options are more complicated. See
+\sectionref{sec:letternumber} for more detail.
+
+\item\optfmt{first}: numbers are considered less than all
+characters (including punctuation and spaces).
+
+\item\optfmt{last}: numbers are considered greater than all
+characters (including punctuation and spaces).
+\end{itemize}
+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 \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
+position of white space and punctuation.
+
+\optsection{letter-number-punc-rule}
+
+This automatically implements the dual and secondary
+\csopt[\meta{value}]{dual-letter-number-punc-rule}
+and
+\csopt[\meta{value}]{secondary-letter-number-punc-rule}.
+
+If you use one of the letter-number sort methods
+(\tableref{tab:sortoptionsletternumber}), then you can determine the
+order of white space and punctuation. In this context, punctuation
+means any character that's not considered a letter, a number
+or white space. This means that characters such as combining marks
+are considered punctuation.
+
+The \meta{value} may be one of the following:
+\begin{itemize}
+\item\optfmt{punc-space-first}: punctuation comes first, followed by
+white space (then letters and optionally numbers according to the letter-number
+rule);
+\item\optfmt{punc-space-last}: punctuation followed by white space
+come last (after letters and optionally numbers according to the letter-number
+rule);
+\item\optfmt{space-punc-first}: white space comes first, followed by
+punctuation (then letters and optionally numbers according to the letter-number
+rule);
+\item\optfmt{space-punc-last}: white space followed by punctuation
+come last (after letters and optionally numbers according to the letter-number
+rule);
+\item\optfmt{space-first-punc-last}: white space comes first
+(followed by letters and optionally numbers according to the letter-number
+rule) and punctuation comes last;
+\item\optfmt{punc-first-space-last}: punctuation comes first
+(followed by letters and optionally numbers according to the letter-number
+rule) and white space comes last;
+\item\optfmt{punc-first-space-zero}: punctuation comes first
+(although numbers may come before)
+and white space is replaced by the digit~\code{0} (\hex{30});
+\item\optfmt{punc-last-space-zero}: punctuation comes last
+(although numbers may come after)
+and white space is replaced by the digit~\code{0} (\hex{30}).
+\item\optfmt{punc-first-space-zero-match-next}: punctuation comes first
+(although numbers may come before)
+and white space is replaced by the appropriate zero character (see below);
+\item\optfmt{punc-last-space-zero-match-next}: punctuation comes last
+(although numbers may come after)
+and white space is replaced by the appropriate zero character (see below).
+\end{itemize}
+Remember that the reverse sort methods will invert order governed by this setting.
+
+For the \optfmt{space-zero-match-next} settings, the sort value will
+have all spaces replaced with a digit that represents zero. If the
+space isn't followed by a digit, the basic Latin \code{0} (\hex{30})
+will be used, otherwise \bibgls\ will try to match the zero with the
+following digit group. For example, if the space is followed by
+\textsuperscript{1} (\hex{B9}) the space will be replaced by
+\textsuperscript{0} (\hex{2070}), resulting in the sub-string
+\code{\textsuperscript{01}} (\hex{B9} \hex{2070}).
+
+If just the \optfmt{space-zero}
+(without the \optfmt{-match-next}) is used then the space will just
+be replaced with \code{0} resulting in the sub-string
+\code{0\textsuperscript{1}} (\hex{30} \hex{2070}). In this case, the
+\code{0} will be distinct from \textsuperscript{1} (rather than
+being considered a leading zero). However, for
+other numbering systems the \code{0} will be treated as a leading
+zero. For example, if the space is followed by the Devanagari digit
+one (\hex{0967}) then the sub-string will be \hex{30} \hex{0967} but here the
+mixture is allowed to form a number (with a leading zero) as both
+characters belong to the Unicode category \idx{numberdecimaldigit}.
+
+This means that the \optfmt{-match-next} settings are only really
+needed if the sort string contains the superscript or subscript
+digits that don't belong to the \qt{Number, Decimal Digit} category.
+The plain \optfmt{space-zero} alternatives are more efficient as
+they just perform a simple substitution.
+
+The \TeX\ parser library used by \bibgls\ recognises the standard
+\LaTeX\ text-mode commands \ics{textsuperscript}\margm{text} and
+\ics{textsubscript}\margm{text}
+and will use the Unicode superscript or subscript characters if they cover every
+character in \meta{text}, otherwise HTML markup is used, but that's
+then stripped by \bibgls. This means that:
+\begin{codeenv}
+C\cs{textsubscript}\marg{10}H\cs{textsubscript}\marg{10}O\cs{textsubscript}\marg{4}
+\end{codeenv}
+will be converted to:
+\code{C\textsubscript{10}H\textsubscript{10}O\textsubscript{4}} but:
+\begin{codeenv}
+X\cs{textsubscript}\marg{1, 2}
+\end{codeenv}
+will be converted to:
+\begin{verbatim}
+X<sub>1, 2</sub>
+\end{verbatim}
+which ends up as \code{X1, 2}.
+
+
+Note that \csopt[first]{letter-number-rule} and
+\csopt[last]{letter-number-rule} overrides this option when
+comparing a number with white space or punctuation.
+
+\optsection{numeric-sort-pattern}
+
+If you use the custom \csopt[numberformat]{sort} or
+\csopt[numberformat-reverse]{sort}, you need to
+specify the format pattern with this option where
+\meta{value} is a pattern recognised by Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html}{\code{java.text.DecimalFormat}}
+class~\cite{decimalformat}. You can use \stringu\meta{hex} or
+\cs{glshex}\meta{hex} to indicate Unicode characters by their
+hexadecimal code. You can also use \ics{cs.hash}, \ics{cs.percent},
+\ics{cs.underscore}, \ics{cs.amp}, \ics{cs.openbrace} and
+\ics{cs.closebrace} to indicate \idx{hashchar}, \idx{percentchar},
+\idx{underscorechar}, \idx{ampchar}, \idx{openbracechar} and
+\idx{closebracechar}.
+
+Where the dual or secondary sort uses \optfmt{numberformat}
+or \optfmt{numberformat-reverse}, use \csopt{dual-numeric-sort-pattern} for
+\csopt{dual-sort} and \csopt{secondary-numeric-sort-pattern}
+for \csopt{secondary}.
+
+\optsection{numeric-locale}
+
+If you use any of the locale-sensitive numeric sort methods
+described in \sectionref{sec:numerical},
+such as \csopt[numeric]{sort}, use this option to set
+the locale. The value may be:
+\begin{itemize}
+\item\optfmt{locale}: use Java's default locale (which is usually
+the operating system's locale);
+\item\optfmt{doc}: use the document's locale or, if not set, assume
+\csopt[locale]{numeric-locale};
+\item\meta{lang-tag}: set to the locale identified by the given
+a valid language tag \meta{lang-tag}.
+\end{itemize}
+Use \csopt{dual-numeric-locale} for
+\csopt{dual-sort} and \csopt{secondary-numeric-locale}
+for \csopt{secondary}.
+
+\optsection{date-sort-locale}
+
+If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
+then you can set the locale used by Java's date-time parser.
+The default setting is \csopt[locale]{date-sort-locale}.
+
+The value may be \optfmt{locale} (use Java's default locale),
+\optfmt{doc} (use the document's locale) or a valid language tag
+\meta{lang-tag} identifying the locale.
+
+Use \csopt{dual-date-sort-locale} and \csopt{secondary-date-sort-locale}
+for the dual and secondary.
+
+\optsection{date-sort-format}
+
+If you use a date/time sort method (\tableref{tab:sortoptionsdatetime}),
+then you can set the format used by Java's date-time parser.
+If omitted, \csopt[default]{date-sort-format} is assumed.
+The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{default}: use the locale's default format.
+\item\optfmt{short}: use the locale's short format.
+\item\optfmt{medium}: use the locale's medium format.
+\item\optfmt{long}: use the locale's long format.
+\item\optfmt{full}: use the locale's full format.
+\item\meta{pattern}: provide a custom pattern.
+This should match the specifications for Java's
+\href{http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html}{\code{SimpleDateFormat}}
+class~\cite{simpledateformat}. You may use \stringu\meta{hex} or
+\code{\cs{glshex} \meta{hex}} to indicate Unicode characters
+or \ics{cs.hash}, \ics{cs.percent}, \ics{cs.underscore}, \ics{cs.amp},
+\ics{cs.openbrace} and \ics{cs.closebrace} to indicate
+\idx{hashchar}, \idx{percentchar}, \idx{underscorechar},
+\idx{ampchar}, \idx{openbracechar} and~\idx{closebracechar}.
+\end{itemize}
+
+With the custom setting, if the pattern only contains date (but not
+time) information, then it must be used with \csopt[date]{sort}
+or \csopt[date-reverse]{sort}. If the pattern only contains time
+(but not date) information, then it must be used with
+\csopt[time]{sort} or \csopt[time\dhyphen reverse]{sort}. If the pattern
+contains date and time information, then it must be used with
+\csopt[datetime]{sort} or \csopt[datetime-reverse]{sort}.
+
+For example, suppose each entry provides information about a person
+and the \field{user1} field is used to store their date of birth:
+\begin{codeenv}
+\atentry{entry}\marg{caesar,
+ \field{name}=\marg{Gaius Julius Caesar},
+ \field{first}=\marg{Julius Caesar},
+ \field{text}=\marg{Caesar},
+ \field{description}=\marg{Roman politician and general},
+ \field{user1}=\marg{13 July 100 BC}
+}
+\strut
+\atentry{entry}\marg{wellington,
+ \field{name}=\marg{Arthur Wellesley, 1st Duke of Wellington},
+ \field{first}=\marg{Arthur Wellesley (Duke of Wellington)},
+ \field{text}=\marg{Wellington},
+ \field{description}=\marg{Anglo-Irish soldier and statesman},
+ \field{user1}=\marg{1 May 1769 AD}
+}
+\end{codeenv}
+Then the entries can be sorted by date of birth using:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{data in entries.bib}
+ \csopt[user1]{sort-field},
+ \csopt[date]{sort},
+ \csopt[d MMM y G]{date-sort-format}
+}
+\end{codeenv}
+
+The \code{G} (era) date pattern specifier expects a string, such as
+\qt{AD}. It will match \idx{lowercase} forms, such as \qt{ad}, so if you
+have \code{\cs{textsc}\marg{ad}} the interpreter will convert this to
+\code{ad} (stripping the text-block command). However, in general
+it's best to supply a semantic command that ensures that the
+interpreted result matches the required format.
+
+For example, if \csfmt{era} is provided with:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{era}}[1]\marg{\cs{textsc}\marg{\cs{MakeLowercase}\marg{\idx{param}1}}}}}
+\end{codeenv}
+If the definition is hidden from the interpreter
+(\csopt[false]{interpret-preamble}) and the field
+value contains \verb|\era{AD}| then the custom command will simply be stripped
+leaving \code{AD} which can be matched by \code{G}.
+
+If the definition is picked up by the interpreter then the field
+value will contain \code{ad} (from \ics{MakeLowercase}) but this can
+be matched by \code{G}, so it isn't a problem.
+However, if the definition of \csfmt{era} is changed so that the era label
+supplied in the argument is converted to something that doesn't
+match \code{G} then the definition should be hidden from the
+interpreter.
+
+Here's a complete document that changes the \field{group} fields to use
+the year and era:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style}]\marg{glossaries-extra}
+\strut
+\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7}
+\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\ics{number}\idx{param}1\cs{cs.space}\idx{param}4}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[user1]{sort-field},
+ \csopt[date]{sort},
+ \csopt[d MMM y G]{date-sort-format},
+ \csopt[all]{selection}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+(The use of \ics{number} strips the leading zero from the year.)
+
+\optsection{group-formation}
+
+If the \field{group} field hasn't been set in
+the \ext{bib} file or through options like \csopt{group}, then it is
+assigned according to this option's setting during sorting if
+\longarg{group} has been used. Permitted values:
+\begin{itemize}
+\item\optfmt{default}: the group is assigned according to
+the sort method's default group formation. This is the default
+setting.
+
+\item\optfmt{codepoint}: the group is set to
+\format{bibglsunicodegroup}, where the first argument is the first
+significant character (converted to \idx{lowercase} and decomposed,
+if applicable) of the sort value.
+
+\item\optfmt{unicode category}: the group is set to
+\format{bibglsunicodegroup}, where the first argument is the label
+identifying the Unicode category of the first significant character
+of the sort value. For example, the label \code{Ll} signifies a
+\idx!{lowercase} letter and \code{Lu} signifies an \idx!{uppercase}
+letter.
+
+\item\optfmt{unicode script}: the group is set to
+\format{bibglsunicodegroup}, where the first argument is the
+label identifying the Unicode script of the first significant
+character of the sort value. For example, the label \code{LATIN}
+indicates Latin, \code{GREEK} indicates Greek and \code{COMMON}
+indicates common characters (such as mathematical Greek characters
+that are often used with non-Greek scripts).
+
+\item\optfmt{unicode category and script}: the group is set to
+\format{bibglsunicodegroup}, where the first argument is the
+label corresponding to the Unicode category and script of the first
+significant character of the sort value. For example, the label
+\code{Ll.LATIN} indicates a \idx!{lowercase} Latin letter.
+\end{itemize}
+This option has no effect with \longarg{no-group} or if no sorting
+is applied. Use \csopt{secondary-group-formation} for secondary
+sorting and \csopt{dual-group-formation} for dual entries.
+Settings other than the default can cause the groups to become
+fragmented, so care is needed if you use this option.
+See also \sectionref{sec:logicaldivisions}.
+
+\section{Secondary Glossary}
+\label{sec:secondaryopts}
+
+The secondary glossary may only be used with \csopt[define]{action}
+(within the same resource set) since it's incompatible with the copy actions.
+You may use \csopt{secondary} in the first resource set and a copy
+action in a subsequent resource set.
+
+\optsection{secondary}
+
+It may be that you want to display a glossary twice but with a
+different order. For example, the first time alphabetically and the
+second time by category. One way to do this is to have two
+\gls{GlsXtrLoadResources} that both load the same \ext{bib} file with
+different \csopt{label-prefix} and \csopt{sort} settings, but this
+is only possible with \csopt[all]{selection} or by ensuring you
+reference each entry with both label prefixes. Another method is
+to use \csopt[copy]{action} but this requires a second resource
+command with the same selection criteria.
+
+A simpler method is to use a single \gls{GlsXtrLoadResources}
+with the \csopt{secondary} option. The value
+(which must be supplied) should be in the format:
+\begin{definition}
+\meta{sort}:\meta{field}:\meta{type}
+\end{definition}
+or
+\begin{definition}
+\meta{sort}:\meta{type}
+\end{definition}
+If the \meta{field} is omitted, the value of \csopt{sort-field} is
+used. Remember that when the primary entries are sorted, the
+\field{sort} field will be set, which means that the fallback field
+(such as \field{name}) won't be used in the secondary sort. In
+general it's best to supply the field unless one type is sorted and the
+other isn't. (The actual sort value obtained by the secondary sort
+will be saved in the \field{secondarysort} field in case you require it.)
+
+The value of \meta{sort} is as for \csopt{sort}, but note
+that in this case the sort value \optfmt{unsrt} or \optfmt{none}
+means to use the same ordering as the primary entries. For
+example, with \csopt[de-CH-1996]{sort},
+\csopt[none:copies]{secondary} the \code{copies} list will be
+ordered according to \code{de-CH-1996} and not according to the
+order in which they were read when the \ext{bib} file or files were
+parsed. If \meta{sort} is \optfmt{custom}, then the rule should be
+provided with \csopt{secondary-sort-rule}.
+
+This option will copy all the selected entries into the glossary labelled
+\meta{type} sorted according to \meta{sort} (using \meta{field} as
+the sort value). Note that this \emph{just copies the entry's label}
+to the second glossary list rather than creating a duplicate entry,
+which saves resources but it means that all the fields will be
+identical. If you want groups in your glossary, the group
+information for the secondary glossary will be stored in the
+internal \field{secondarygroup} field. The \field{group} field will
+contain the group for the primary glossary.
+
+In order to switch fields in \ics{printunsrtglossary}, you need at
+least v1.21 of \sty{glossaries-extra} which provides
+\ics{glsxtrgroupfield} to keep track of the appropriate field label.
+If this command is defined, the preamble for the secondary glossary
+will be adjusted to locally change the field to
+\field{secondarygroup}. With older versions, the group information
+in the secondary glossary will be the same as for the primary
+glossary.
+
+(If the glossary \meta{type} doesn't exist, it will be
+defined with \ics{provideignoredglossary*}\margm{type}.)
+Note that if the glossary already exists and contains entries,
+the existing entries aren't re-ordered. The new entries are
+simply appended to the list.
+
+For example, suppose the \ext{bib} file contains entries like:
+\begin{codeenv}
+\atentry{entry}\marg{quartz,
+ \field{name}=\marg{quartz},
+ \field{description}=\marg{hard mineral consisting of silica},
+ \field{category}=\marg{mineral}
+}
+\strut
+\atentry{entry}\marg{cabbage,
+ \field{name}=\marg{cabbage},
+ \field{description}=\marg{vegetable with thick green or purple leaves},
+ \field{category}=\marg{vegetable}
+}
+\strut
+\atentry{entry}\marg{waterfowl,
+ \field{name}=\marg{waterfowl},
+ \field{description}=\marg{any bird that lives in or about water},
+ \field{category}=\marg{animal}
+}
+\end{codeenv}
+and the document preamble contains:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en-GB]{sort},
+ \csopt[en-GB:category:topic]{secondary}
+}
+\end{codeenv}
+This sorts the primary entries according to the default
+\csopt{sort-field} and then sorts the entries according
+to the \field{category} field and copies this list to
+the \code{topic} glossary (which will be provided if not defined.)
+
+The secondary list can be displayed with the hypertargets switched
+off to prevent duplicates. The cross-references will link to the
+original glossary.
+
+For example:
+\begin{codeenv*}
+\ics{printunsrtglossary}\oarg{\printglossopt[Summary (alphabetical)]{title}}
+\ics{printunsrtglossary}\oarg{\printglossopt[Summary (by topic)]{title},\printglossopt[false]{target}}
+\end{codeenv*}
+
+The alternative (or if more than two lists are required) is to
+reload the same \ext{bib} file with different label prefixes.
+For example, if the entries are stored in \filefmt{entries.bib}:
+\begin{codeenv}
+\cs{newglossary*}\marg{nosort}\marg{Symbols (Unsorted)}
+\cs{newglossary*}\marg{byname}\marg{Symbols (Letter Order)}
+\cs{newglossary*}\marg{bydesc}\marg{Symbols (Ordered by Description)}
+\cs{newglossary*}\marg{byid}\marg{Symbols (Ordered by Label)}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{entries.bib}
+ \csopt[unsrt]{sort},
+ \csopt[nosort]{type}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{entries.bib}
+ \csopt[letter-case]{sort},
+ \csopt[byname]{type},
+ \csopt[byname.]{label-prefix}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{entries.bib}
+ \csopt[locale]{sort},
+ \csopt[description]{sort-field},
+ \csopt[bydesc]{type},
+ \csopt[bydesc.]{label-prefix}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},\comment{entries.bib}
+ \csopt[letter]{sort},
+ \csopt[id]{sort-field},
+ \csopt[byid]{type},
+ \csopt[byid.]{label-prefix}
+}
+\end{codeenv}
+
+\optsection{secondary-missing-sort-fallback}
+
+As \csopt{missing-sort-fallback} but for secondary sorting.
+
+\optsection{secondary-trim-sort}
+
+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.
+
+\optsection{secondary-break-at}
+
+As \csopt{break-at} but for secondary entries.
+
+\optsection{secondary-break-marker}
+
+As \csopt{break-marker} but for secondary entries.
+
+\optsection{secondary-sort-number-pad}
+
+As \csopt{sort-number-pad} but for secondary entries.
+
+\optsection{secondary-sort-pad-plus}
+
+As \csopt{sort-pad-plus} but for secondary entries.
+
+\optsection{secondary-sort-pad-minus}
+
+As \csopt{sort-pad-minus} but for secondary entries.
+
+\optsection{secondary-identical-sort-action}
+
+As \csopt{identical-sort-action} but for secondary entries.
+
+\optsection{secondary-sort-suffix}
+
+As \csopt{sort-suffix} but for secondary entries.
+
+\optsection{secondary-sort-suffix-marker}
+
+As \csopt{sort-suffix-marker} but for secondary entries.
+
+\optsection{secondary-strength}
+
+As \csopt{strength} but for secondary entries.
+
+\optsection{secondary-decomposition}
+
+As \csopt{decomposition} but for secondary entries.
+
+\optsection{secondary-letter-number-rule}
+
+As \csopt{letter-number-rule} but for secondary letter-number sorting.
+
+\optsection{secondary-letter-number-punc-rule}
+
+As \csopt{letter-number-punc-rule} but for secondary letter-number sorting.
+
+\optsection{secondary-numeric-sort-pattern}
+
+As \csopt{numeric-sort-pattern} but for secondary
+locale-sensitive numeric sorting.
+
+\optsection{secondary-numeric-locale}
+
+As \csopt{numeric-locale} but for secondary
+locale-sensitive numeric sorting.
+
+\optsection{secondary-date-sort-locale}
+
+As \csopt{date-sort-locale} but for secondary date-time sorting.
+
+\optsection{secondary-date-sort-format}
+
+As \csopt{date-sort-format} but for secondary date-time sorting.
+
+\optsection{secondary-group-formation}
+
+As \csopt{group-formation} but for secondary sorting.
+
+\section{Dual Entries}
+\label{sec:dualopts}
+
+\subsection{General Dual Settings}
+\label{sec:dualoptsgeneral}
+
+\optsection[\subsubsection]{dual-prefix}
+
+This option indicates the prefix to use for the dual entries. The
+default value is \idprefix{dual} (including the terminating period).
+Any references to dual entries within the \ext{bib} file should use
+the prefix \idprefix{dual} which will be replaced by \meta{value}
+when the \ext{bib} file is parsed.
+
+As from version 1.8, the dual label prefix is identified
+in the \ext{glstex} file with:
+\begin{codeenv}
+\format{bibglsdualprefixlabel}
+\end{codeenv}
+
+\optsection[\subsubsection]{primary-dual-dependency}
+
+This is a boolean setting that determines whether or not primary and
+dual entries should be considered mutual dependencies. The default value is
+\csopt[true]{primary-dual-dependency}, which means that if a primary
+has records then the dual is added as a dependency and vice versa.
+The setting \csopt[false]{primary-dual-dependency} can't be used
+with \csopt[none]{dual-sort} or \csopt[use]{dual-sort} (but may be
+used with \csopt[combine]{dual-sort} and \csopt[none]{sort} or
+\csopt[use]{sort}).
+
+\optsection[\subsubsection]{combine-dual-locations}
+
+This setting allows the location lists for each primary entry
+to be merged with that of the corresponding dual entry.
+The \meta{value} may be one of:
+\begin{itemize}
+\item\optfmt{false} This is the default setting. The location lists
+aren't combined.
+\item\optfmt{both} Both the primary and dual are given the combined
+location list.
+\item\optfmt{dual} Only the dual is given the combined location
+list. The primary's location list is emptied.
+\item\optfmt{primary} Only the primary is given the combined
+location list. The dual's location list is emptied.
+\end{itemize}
+
+For example, suppose the file \filefmt{entries.bib} contains:
+\begin{codeenv}
+\atentry{dualindexentry}\marg{array,
+ \field{description}=\marg{ordered list of values}
+}
+\strut
+\atentry{dualindexentry}\marg{vector,
+ \field{name}=\marg{vector},
+ \field{description}=\marg{column or row of values}
+}
+\strut
+\atentry{dualindexentry}\marg{set,
+ \field{description}=\marg{collection of values}
+}
+\strut
+\atentry{dualindexentry}\marg{matrix,
+ \field{plural}=\marg{matrices},
+ \field{description}=\marg{rectangular array of values}
+}
+\end{codeenv}
+and the document contains:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[colorlinks]\marg{hyperref}
+\cmd{usepackage}[\styopt{record},\styopt{index},\styopt[indexgroup]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries]{src},
+ \csopt[index]{type},
+ \csopt[idx.]{label-prefix},
+ \csopt[gls.]{dual-prefix},
+ \csopt[main]{dual-type}
+}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{gls.array}, \cs{gls}\marg{idx.vector}, \cs{gls}\marg{idx.set}, \cs{gls}\marg{gls.matrix}.
+\strut
+\cmd{newpage}
+\cs{gls}\marg{gls.array}, \cs{gls}\marg{gls.vector}, \cs{gls}\marg{gls.set}, \cs{gls}\marg{gls.matrix}.
+\strut
+\cs{printunsrtglossaries}
+\cmd{end}\marg{document}
+\end{codeenv}
+In this case, the primary entries are placed in the \code{index}
+glossary type and are assigned the prefix \idprefixfmt{idx} but only
+two of the primary entries have been used in the document (both on
+page~2).
+
+The dual entries are assigned the prefix \idprefixfmt{gls} and are
+placed in the \code{main} glossary. The \code{gls.array}
+and \code{gls.matrix} entries have been indexed on pages~1, 2 and~3.
+The \code{gls.vector} and \code{gls.set} entries have been indexed
+on pages~1 and~3.
+
+With the default setting, some of the locations are in the
+\code{main} glossary (corresponding to \code{\cs{gls}\marg{gls.array}},
+\code{\cs{gls}\marg{gls.vector}}, \code{\cs{gls}\marg{gls.set}} and
+\code{\cs{gls}\marg{gls.matrix}}) and some of the locations are in the
+\code{index} glossary (corresponding to \code{\cs{gls}\marg{idx.vector}}
+and \code{\cs{gls}\marg{idx.set}}).
+
+If the option \csopt[primary]{combine-dual-locations} is added to
+the resource set, then all the locations are moved to the
+\code{index} glossary. The entries in the \code{main} glossary no
+longer have locations. This is actually preferable for this type
+of document and it's best not to reference the primary (index)
+entries as the hyperlink created by \ics{gls} will point to the
+index, but these entries don't have descriptions, so it's less
+useful than referencing the dual (main) entries as then the
+hyperlink can point to the definition in the \code{main} glossary.
+
+
+\subsection{Dual Fields}
+\label{sec:dualoptsfields}
+
+\optsection[\subsubsection]{dual-type}
+
+This option sets the \field{type} field for all dual
+entries. (The primary entries obey the \csopt{type} option.) This
+will override any value of \field{type} provided in the \ext{bib}
+file (or created through a mapping). The \meta{value} is required and
+should be one of:
+\begin{itemize}
+\item \optfmt{same as entry}: sets the \field{type} to the entry
+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}.
+If you've used \csopt{entry-type-aliases}, this refers to the target
+entry type not the original entry type provided in the \ext{bib}
+file.
+
+\item \optfmt{same as original entry}: set the \field{type} field
+to the original entry type (\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}: sets the \field{type} to the base name
+of the \ext{bib} file (without the extension) that provided the
+entry definition (new to v1.1);
+
+\item \optfmt{same as primary}: sets the \field{type} to the same as
+the corresponding primary entry's \field{type} (which may have been
+set with \csopt{type}). If the primary entry doesn't have the
+\field{type} field set, the dual's \field{type} will remain
+unchanged.
+
+\item \optfmt{same as parent}: sets the \field{type} to the same as
+the entry's parent (new to v1.9). If the entry doesn't have a parent
+or if the parent doesn't have the \field{type} field set, then
+no change is made.
+
+\item \meta{label}: sets the \field{type} field to \meta{label}.
+\end{itemize}
+
+Remember that the glossary with that label must have already
+been defined (see \sectionref{sec:newglossary}).
+For example:
+\begin{codeenv}
+\cs{newglossary*}\marg{english}\marg{English}
+\cs{newglossary*}\marg{french}\marg{French}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort},
+ \csopt[english]{type},
+ \csopt[french]{dual-type}}
+\end{codeenv}
+Alternatively:
+\begin{codeenv}
+\cs{newglossary*}\marg{dictionary}\marg{Dictionary}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt[en]{sort},\csopt[fr]{dual-sort},
+ \csopt[dictionary]{type},
+ \csopt[same as primary]{dual-type}}
+\end{codeenv}
+
+\optsection[\subsubsection]{dual-category}
+
+This option sets the \field{category} field for all dual
+entries. (The primary entries obey the \csopt{category} option.) This
+will override any value of \field{category} provided in the \ext{bib}
+file (or created through a mapping). The \meta{value} may be empty or
+one of:
+\begin{itemize}
+\item \optfmt{same as entry}: sets the \field{category} to the entry
+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}.
+If you've used \csopt{entry-type-aliases}, this refers to the target
+entry type not the original entry type provided in the \ext{bib}
+file.
+
+\item \optfmt{same as original entry}: set the \field{category} field
+to the original entry type (\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}: sets the \field{category} to the base
+name of the \ext{bib} file (without the extension) that provided the
+entry definition (new to v1.1);
+
+\item \optfmt{same as primary}: sets the \field{category} to the
+same as the corresponding primary entry's \field{category} (which
+may have been set with \csopt{category}). If the primary entry
+doesn't have the \field{category} field set, the dual's
+\field{category} will remain unchanged.
+
+\item \optfmt{same as type}: sets the \field{category} to the same
+as the value of the entry's \field{type} field (which may have been
+set with \csopt{dual-type}). If the entry doesn't have the
+\field{type} field set, the \field{category} will remain unchanged.
+
+\item \meta{label}: sets the \field{category} field to \meta{label}.
+\end{itemize}
+
+\optsection[\subsubsection]{dual-counter}
+
+As \csopt{counter} but for the dual entries. In this case
+\meta{value} may be the name of the counter or
+\optfmt{same as primary} which uses the counter for the primary
+entry.
+
+\optsection[\subsubsection]{dual-short-case-change}
+
+As \csopt{short-case-change} but applies to the \field{dualshort}
+field instead.
+
+\optsection[\subsubsection]{dual-long-case-change}
+
+As \csopt{long-case-change} but applies to the \field{duallong}
+field instead.
+
+\optsection[\subsubsection]{dual-field}
+
+If this option is used, this will add \ics{glsxtrprovidestoragekey}
+to the start of the \iext{glstex} file providing the key given by
+\meta{value}. Any entries defined using a dual entry type, such as
+\atentry{dualentry}, will be written to the \ext{glstex} file with
+an extra field called \meta{value} that is set to the mirror entry.
+If \meta{value} is omitted \csopt[dual]{dual-field} is assumed. If
+you use a different value, you will need to redefine
+\gls{GlsXtrDualField} (either locally or globally).
+
+For example, if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{dualentry}\marg{child,
+ \field{name}=\marg{child},
+ \field{plural}=\marg{children},
+ \field{description}=\marg{enfant}
+}
+\end{codeenv}
+Then with \csopt[dual]{dual-field} (or simply \csopt{dual-field}
+without a value) this will first add the line:
+\begin{codeenv}
+\cs{glsxtrprovidestoragekey}\marg{\field{dual}}\marg{}\marg{}
+\end{codeenv}
+at the start of the file and will include the line:
+\begin{codeenv*}
+\field{dual}=\marg{dual.child},
+\end{codeenv*}
+for the primary entry (\code{child}) and the line:
+\begin{codeenv}
+\field{dual}=\marg{child},
+\end{codeenv}
+for the dual entry (\code{dual.child}). It's then possible to
+reference one entry from the other. For example, the post-description
+hook could contain:
+\begin{codeenv}
+ \cs{ifglshasfield}\marg{\field{dual}}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{}
+ \cs{space}
+ (\cs{glshyperlink}\marg{\cs{glscurrentfieldvalue}})\comment{}
+ }\comment{}
+ \marg{}\comment{}
+\end{codeenv}
+Note that this new field won't be available for use within the
+\iext{bib} file (unless it was previously defined in the document
+before \gls!{glsxtrresourcefile}).
+
+\optsection[\subsubsection]{dual-date-time-field-format}
+
+As \csopt{date-time-field-format} but is used for dual entries.
+
+\optsection[\subsubsection]{dual-date-field-format}
+
+As \csopt{date-field-format} but is used for dual entries.
+
+\optsection[\subsubsection]{dual-time-field-format}
+
+As \csopt{time-field-format} but is used for dual entries.
+
+\optsection[\subsubsection]{dual-date-time-field-locale}
+
+As \csopt{date-time-field-locale} but is used for dual entries.
+
+\optsection[\subsubsection]{dual-date-field-locale}
+
+As \csopt{date-field-locale} but is used for dual entries.
+
+\optsection[\subsubsection]{dual-time-field-locale}
+
+As \csopt{time-field-locale} but is used for dual entries.
+
+\subsection{Dual Sorting}
+\label{sec:dualoptssort}
+
+\optsection[\subsubsection]{dual-sort}
+
+This option indicates how to sort the dual entries. The primary
+entries are sorted with the normal entries according to
+\csopt{sort}, and the dual entries are sorted according to
+\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the dual
+entries will be combined with the primary entries and all the
+entries will sorted together according to the \csopt{sort} option.
+
+If \meta{value} isn't set to \optfmt{combine} then the dual
+entries are sorted separately according to \meta{value} (as per
+\csopt{sort}) and the dual entries will be appended at the end of
+the \iext{glstex} file. The field used by the comparator is given by
+\csopt{dual-sort-field}.
+If \csopt[custom]{dual-sort}, then the dual entries are sorted according to the
+rule provided by \csopt{dual-sort-rule}.
+
+For example:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-dual]{src},
+ \csopt[en]{sort},
+ \csopt[de-CH-1996]{dual-sort}
+}
+\end{codeenv}
+This will sort the primary entries according to \optfmt{en}
+(English) and the secondary entries according to \optfmt{de-CH-1996}
+(Swiss German new orthography) whereas:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[entries-dual]{src},
+ \csopt[en-GB]{sort},
+ \csopt[combine]{dual-sort}
+}
+\end{codeenv}
+will combine the dual entries with the primary entries and sort them
+all according to the \optfmt{en-GB} locale (British English).
+
+If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If
+\meta{value} is omitted, \optfmt{locale} is assumed.
+
+\optsection[\subsubsection]{dual-sort-field}
+
+This option indicates the field to use when sorting dual entries
+(when they haven't been combined with the primary entries). The
+default value is the same as the \csopt{sort-field} value.
+
+\optsection[\subsubsection]{dual-missing-sort-fallback}
+
+As \csopt{missing-sort-fallback} but for dual sorting.
+
+\optsection[\subsubsection]{dual-trim-sort}
+
+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}.
+
+\optsection[\subsubsection]{dual-break-at}
+
+As \csopt{break-at} but for dual entries.
+
+\optsection[\subsubsection]{dual-break-marker}
+
+As \csopt{break-marker} but for dual entries.
+
+\optsection[\subsubsection]{dual-sort-number-pad}
+
+As \csopt{sort-number-pad} but for dual entries.
+
+\optsection[\subsubsection]{dual-sort-pad-plus}
+
+As \csopt{sort-pad-plus} but for dual entries.
+
+\optsection[\subsubsection]{dual-sort-pad-minus}
+
+As \csopt{sort-pad-minus} but for dual entries.
+
+\optsection[\subsubsection]{dual-identical-sort-action}
+
+As \csopt{identical-sort-action} but for dual entries.
+
+\optsection[\subsubsection]{dual-sort-suffix}
+
+As \csopt{sort-suffix} but for dual entries.
+
+\optsection[\subsubsection]{dual-sort-suffix-marker}
+
+As \csopt{sort-suffix-marker} but for dual entries.
+
+\optsection[\subsubsection]{dual-strength}
+
+As \csopt{strength} but for dual entries.
+
+\optsection[\subsubsection]{dual-decomposition}
+
+As \csopt{decomposition} but for dual entries.
+
+\optsection[\subsubsection]{dual-letter-number-rule}
+
+As \csopt{letter-number-rule} but for dual entries that use a
+letter-number sort.
+
+\optsection[\subsubsection]{dual-letter-number-punc-rule}
+
+As \csopt{letter-number-punc-rule} but for dual entries that use a
+letter-number sort.
+
+\optsection[\subsubsection]{dual-numeric-sort-pattern}
+
+As \csopt{numeric-sort-pattern} but for dual entries that use a
+locale-sensitive numeric sort.
+
+\optsection[\subsubsection]{dual-numeric-locale}
+
+As \csopt{numeric-locale} but for dual entries that use a
+locale-sensitive numeric sort.
+
+\optsection[\subsubsection]{dual-date-sort-locale}
+
+As \csopt{date-sort-locale} but for dual entries that
+use a date/time sort.
+
+\optsection[\subsubsection]{dual-date-sort-format}
+
+As \csopt{date-sort-format} but for dual entries that
+use a date/time sort.
+
+\optsection[\subsubsection]{dual-group-formation}
+
+As \csopt{group-formation} but for dual sorting.
+
+
+\subsection{Dual Mappings}
+\label{sec:dualoptsmap}
+
+\optsection[\subsubsection]{dual-entry-map}
+
+This setting governs the behaviour of \atentry{dualentry}
+definitions. The value consists of two comma-separated lists of
+equal length identifying the field mapping used to create the dual
+entry from the primary one. Note that the \field{alias} field
+can't be mapped.
+
+The default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}},
+ \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}}
+]{dual-entry-map}
+\end{codeenv}
+The dual entry is created by copying the value of the field in the
+first list \meta{list1} to the field in the corresponding place in the second
+list \meta{list2}. Any additional fields are copied over to the same
+field.
+For example:
+\begin{codeenv}
+\atentry{dualentry}\marg{cat,
+ \field{name}=\marg{cat},
+ \field{description}=\marg{chat},
+ \field{see}=\marg{dog}
+}
+\end{codeenv}
+defines two entries. The primary entry is essentially like:
+\begin{codeenv}
+\atentry{entry}\marg{cat,
+ \field{name}=\marg{cat},
+ \field{plural}=\marg{cat\cs{glspluralsuffix} },
+ \field{description}=\marg{chat},
+ \field{descriptionplural}=\marg{chat\cs{glspluralsuffix} },
+ \field{see}=\marg{dog}
+}
+\end{codeenv}
+and the dual entry is essentially like:
+\begin{codeenv}
+\atentry{entry}\marg{dual.cat,
+ \field{description}=\marg{cat},
+ \field{descriptionplural}=\marg{cat\cs{glspluralsuffix} },
+ \field{name}=\marg{chat},
+ \field{plural}=\marg{chat\cs{glspluralsuffix} },
+ \field{see}=\marg{dog}
+}
+\end{codeenv}
+(except they're defined using \gls{bibglsnewdualentry} instead of
+\gls{bibglsnewentry}, and each is considered dependent on the other.)
+
+The \field{see} field isn't listed in \csopt{dual-entry-map} so its
+value is simply copied directly over to the \field{see} field in the
+dual entry. Note that the missing \field{plural} and
+\field{descriptionplural} fields have been filled in using their
+fallback values.
+
+In general \bibgls\ doesn't try to supply missing fields, but in the
+dual entry cases it needs to do this for the mapped fields. This is
+because the shuffled fields might have different default values from
+the \styfmt{glossaries-extra} package's point of view. For example,
+\gls{longnewglossaryentry} doesn't provide a default for
+\field{descriptionplural} if it hasn't been set.
+
+\optsection[\subsubsection]{dual-abbrv-map}
+
+This is like \csopt{dual-entry-map} but applies to
+\atentry{dualabbreviation} rather than \atentry{dualentry}.
+Note that the \field{alias} field can't be mapped. The
+default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{short},\field{shortplural},\field{long},\field{longplural},\field{dualshort},\field{dualshortplural},
+ \field{duallong},\field{duallongplural}},
+ \marg{\field{dualshort},\field{dualshortplural},\field{duallong},\field{duallongplural},\field{short},\field{shortplural},
+ \field{long},\field{longplural}}
+]{dual-abbrv-map}
+\end{codeenv}
+
+This essentially flips the \field{short} field with the
+\field{dualshort} field and the \field{long} field with the
+\field{duallong} field. See \atentry{dualabbreviation}
+for further details.
+
+\optsection[\subsubsection]{dual-abbrventry-map}
+
+This is like \csopt{dual-entry-map} but applies to
+\atentry{dualabbreviationentry} rather than \atentry{dualentry}.
+Note that the \field{alias} field can't be mapped. The
+default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{long},\field{short},\field{shortplural}},
+ \marg{\field{name},\field{text},\field{plural}}
+]{dual-abbrventry-map}
+\end{codeenv}
+See \atentry{dualabbreviationentry} for further details.
+
+
+\optsection[\subsubsection]{dual-symbol-map}
+
+This is like \csopt{dual-entry-map} but applies to
+\atentry{dualsymbol} rather than \atentry{dualentry}.
+Note that the \field{alias} field can't be mapped. The
+default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{name},\field{plural},\field{symbol},\field{symbolplural}},
+ \marg{\field{symbol},\field{symbolplural},\field{name},\field{plural}}
+]{dual-symbol-map}
+\end{codeenv}
+This essentially flips the \field{name} field with the
+\field{symbol} field.
+
+\optsection[\subsubsection]{dual-indexentry-map}
+
+This is like \csopt{dual-entry-map} but applies to
+\atentry{dualindexentry} rather than \atentry{dualentry}.
+The default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{name}},
+ \marg{\field{name}}
+]{dual-indexentry-map}
+\end{codeenv}
+Note that there must always be at least one pair, even if it's the
+same field, since this identifies the field to use for the backlink,
+if set.
+
+\optsection[\subsubsection]{dual-indexsymbol-map}
+
+This is like \csopt{dual-entry-map} but applies to both
+\atentry{dualindexsymbol} and \atentry{dualindexnumber}.
+The default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{symbol},\field{name},\field{symbolplural},\field{plural}},
+ \marg{\field{name},\field{symbol},\field{plural},\field{symbolplural}}
+]{dual-indexsymbol-map}
+\end{codeenv}
+
+\optsection[\subsubsection]{dual-indexabbrv-map}
+
+This is like \csopt{dual-entry-map} but applies to both the dual
+\atentry{dualindexabbreviation} and tertiary
+\atentry{tertiaryindexabbreviationentry} entry types.
+The default setting is:
+\begin{codeenv}
+\csopt[
+ \marg{\field{name}},
+ \marg{\field{name}}
+]{dual-indexabbrv-map}
+\end{codeenv}
+
+\subsection{Dual Back-Links}
+\label{sec:dualoptsbacklinks}
+
+\optsection[\subsubsection]{dual-entry-backlink}
+
+This is a boolean setting. If \meta{boolean} is missing \optfmt{true}
+is assumed.
+
+When used with \atentry{dualentry}, if \meta{boolean} is
+\optfmt{true}, this will wrap the contents of the first mapped field
+with \gls{bibglshyperlink}. The field is obtained from the first
+mapping listed in \csopt{dual-entry-map}.
+
+For example, if the document contains:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt{dual-entry-backlink},
+ \csopt[
+ \marg{\field{name},\field{plural},\field{description},\field{descriptionplural}},
+ \marg{\field{description},\field{descriptionplural},\field{name},\field{plural}}
+ ]{dual-entry-map},
+ \csopt[entries-dual]{src}}
+\end{codeenv}
+and if the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{dualentry}\marg{child,
+ \field{name}=\marg{child},
+ \field{plural}=\marg{children},
+ \field{description}=\marg{enfant}
+}
+\end{codeenv}
+Then the definition of the primary entry (\code{child}) in the
+\ext{glstex} file will set the \field{description} field to:
+\begin{codeenv}
+\gls{bibglshyperlink}\marg{enfant}\marg{dual.child}
+\end{codeenv}
+and the dual entry (\code{dual.child}) will have the
+\field{description} field set to:
+\begin{codeenv}
+\gls{bibglshyperlink}\marg{child}\marg{child}
+\end{codeenv}
+This use of the wrapper \gls{bibglshyperlink} (rather than explicitly
+using \ics{glshyperlink}) and inserting the actual field value
+(rather than using commands like \ics{glsentryname}) allows it
+to work with \ics{makefirstuc} if the field requires a case-change.
+
+The reason the \field{description} field is chosen for the modification is
+because the first field listed in \meta{list1} of \csopt{dual-entry-map}
+is the \field{name} field which maps to \field{description} (the
+first field in the second list \meta{list2}). This means that the hyperlink for
+the dual entry should be put in the \field{description} field.
+
+For the primary entry, the \field{name} field is looked up in the
+second list from the \csopt{dual-entry-map} setting. This is the
+third item in this second list, so the third item in the first list
+is selected, which also happens to be the \field{description} field,
+so the hyperlink for the primary entry is put in the
+\field{description} field.
+
+\optsection[\subsubsection]{dual-abbrv-backlink}
+
+This is analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualabbreviation} instead of
+\atentry{dualentry}.
+
+\optsection[\subsubsection]{dual-symbol-backlink}
+
+This is analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualsymbol} instead of \atentry{dualentry}.
+
+\optsection[\subsubsection]{dual-abbrventry-backlink}
+
+Analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualabbreviationentry} instead of
+\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{codeenv}
+\cs{renewcommand}*\marg{\ics{glsuserdescription}}[2]\marg{\comment{}
+ \gls{GlsXtrDualBackLink}\marg{\ics{glslonguserfont}\marg{\idx{param}1}}\marg{\idx{param}2}\comment{}
+}
+\cs{setabbreviationstyle}\marg{\abbrstyle{long-short-user}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{dual-field}}
+\end{codeenv}
+
+\optsection[\subsubsection]{dual-entryabbrv-backlink}
+
+As \csopt{dual-abbrventry-backlink} but for entries
+defined with \atentry{dualentryabbreviation} instead of
+\atentry{dualabbreviationentry}.
+
+\optsection[\subsubsection]{dual-indexentry-backlink}
+
+This is analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualindexentry} instead of
+\atentry{dualentry}.
+
+\optsection[\subsubsection]{dual-indexsymbol-backlink}
+
+This is analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualindexsymbol} and
+\atentry{dualindexnumber}.
+
+\optsection[\subsubsection]{dual-indexabbrv-backlink}
+
+This is analogous to \csopt{dual-entry-backlink} but for entries
+defined with \atentry{dualindexabbreviation} and
+\atentry{tertiaryindexabbreviationentry}.
+
+\optsection[\subsubsection]{dual-backlink}
+
+Shortcut for:
+\begin{flushleft}\obeylines
+\csopt[\meta{boolean}]{dual-entry-backlink},
+\csopt[\meta{boolean}]{dual-abbrventry-backlink},
+\csopt[\meta{boolean}]{dual-abbrv-backlink},
+\csopt[\meta{boolean}]{dual-symbol-backlink},
+\csopt[\meta{boolean}]{dual-indexentry-backlink},
+\csopt[\meta{boolean}]{dual-indexsymbol-backlink},
+\csopt[\meta{boolean}]{dual-indexabbrv-backlink}
+\end{flushleft}
+
+\section{Tertiary Entries}
+
+\optsection{tertiary-prefix}
+
+This option indicates the prefix to use for the tertiary entries. The
+default value is \idprefix{tertiary} (including the terminating period).
+
+As from version 1.8, the tertiary label prefix is identified
+in the \ext{glstex} file with:
+\begin{codeenv}
+\format{bibglstertiaryprefixlabel}
+\end{codeenv}
+
+\optsection{tertiary-type}
+
+This option indicates that the tertiary entries should have
+their \field{type} field set to \meta{value}. If \meta{value} is
+empty the \field{type} is left unchanged. Unlike
+the \csopt{type} and \csopt{dual-type} options, there are no
+recognised keywords.
+
+\optsection{tertiary-category}
+
+This option indicates that the tertiary entries should have
+their \field{category} field set to \meta{value}. If \meta{value} is
+empty the \field{category} is left unchanged. Unlike
+the \csopt{category} and \csopt{dual-category} options, there are no
+recognised keywords.
+
+\chapter{Provided Commands}
+\label{sec:bibglscs}
+
+When \bibgls\ creates the \iext{glstex} file, it writes some
+definitions for custom commands in the form \csfmt{bibgls\ldots} which
+may be changed as required. The command definitions all use
+\ics{providecommand} which means that you can define the command with
+\ics{newcommand} before the resource file is loaded.
+
+Note that if you try to redefine any of these commands after the
+resource file has been loaded with \ics{renewcommand}, you will get
+an error on the first \LaTeX\ run when the \ext{glstex} file doesn't
+exist. You may prefer to use \ics{glsrenewcommand} instead, which
+will generate a warning instead of an error.
+
+Since many of the commands are actually used within the \ext{glstex}
+file, it's best to use \cs{newcommand} before the first
+\idx{resourceset} and \cs{renewcommand} between \idxpl{resourceset}
+if adjustments are necessary.
+
+
+\section{Entry Definitions}
+\label{sec:newentrydefs}
+
+This section lists the commands (\csfmt{bibglsnew\ldots}) used to
+define entries. Note that the entry definition commands are
+actually used when \TeX\ inputs the resource file, so redefining
+them after the resource file is loaded won't have an effect on the
+entries defined in that resource file (but will affect entries defined
+in subsequent resource files). Each provided command is defined in
+the \ext{glstex} file immediately before the first entry that
+requires it, so only the commands that are actually needed are
+provided.
+
+The \field{sort} key may be set within the \ext{glstex} entry
+definition, but its value is usually not required in the document
+unless you are using a hybrid method with \styopt[alsoindex]{record}.
+
+After each entry is defined, if it has any associated locations and
+the default \csopt[true]{save-loclist} is set, then the
+locations are added using:
+\nosecformatdef{glsxtrfieldlistadd}
+Any additional fields that don't have associated keys are then set (if
+required) with \ics{GlsXtrSetField}.
+
+\cssection{bibglsnewentry}
+
+\formatdef{bibglsnewentry}
+This command is used to define terms identified with the
+\atentry{entry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+This uses the starred form \ics{longnewglossaryentry*} that
+doesn't automatically append \ics{nopostdesc} (which interferes with
+the post-description hooks provided by category attributes).
+
+\cssection{bibglsnewsymbol}
+
+\formatdef{bibglsnewsymbol}
+This command is used to define terms identified with the
+\atentry{symbol} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+Note that this sets the \field{sort} field to the label, but this
+may be overridden by the \meta{options} if the \field{sort} field
+was supplied or if \bibgls\ has determined the value whilst sorting
+the entries.
+
+This also sets the \field{category} to \optfmt{symbol}, but again this may
+be overridden by \meta{options} if the entry had the \field{category}
+field set in the \ext{bib} file or if the \field{category} was
+overridden with \csopt[\meta{value}]{category}.
+
+\cssection{bibglsnewnumber}
+
+\formatdef{bibglsnewnumber}
+This command is used to define terms identified with the
+\atentry{number} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewnumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{number},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+This is much the same as \gls{bibglsnewsymbol} above but sets the
+\field{category} to \optfmt{number}. Again the \field{sort} and
+\field{category} keys may be overridden by \meta{options}.
+
+\cssection{bibglsnewindex}
+
+\formatdef{bibglsnewindex}
+This command is used to define terms identified with the
+\atentry{index} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglsnewindex}}[2]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}=\marg{index},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+This makes the \field{name} default to the \meta{label}, assigns
+the \field{category} to \code{index} and sets an empty
+\field{description}. These settings may be overridden by
+\meta{options}.
+
+Note that the \field{description} doesn't include
+\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{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewindexplural}}[3]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+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}
+This command is used to define terms identified with the
+\atentry{abbreviation} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+Since this uses \gls{newabbreviation}, it obeys the
+abbreviation style for its given \field{category} (which may have
+been set in \meta{options}, either from the \field{category} field
+in the \ext{bib} file or through the \csopt{category} option).
+Similarly the \field{type} will obey \ics{glsxtrabbrvtype} unless
+the value is supplied in the \ext{bib} file or through the
+\csopt{type} option.
+
+\cssection{bibglsnewacronym}
+
+\formatdef{bibglsnewacronym}
+This command is used to define terms identified with the
+\atentry{acronym} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+This works in much the same way as \gls{bibglsnewabbreviation}.
+Remember that with the \styfmt{glossaries-extra} package \gls{newacronym}
+is redefined to just use \gls{newabbreviation} with the default \field{type}
+set to \ics{acronymtype} and the default \field{category} set to
+\code{acronym}.
+
+\cssection{bibglsnewdualentry}
+
+\formatdef{bibglsnewdualentry}
+This command is used to define terms identified with the
+\atentry{dualentry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewdualindexentry}
+
+\formatdef{bibglsnewdualindexentry}
+This command is used to define primary terms identified with the
+\atentry{dualindexentry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}\marg{}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{description} argument.
+
+\cssection{bibglsnewdualindexentrysecondary}
+
+\formatdef{bibglsnewdualindexentrysecondary}
+This command is used to define secondary terms identified with the
+\atentry{dualindexentry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexentrysecondary}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewdualindexsymbol}
+
+\formatdef{bibglsnewdualindexsymbol}
+This command is used to define primary terms identified with the
+\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbol}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{description} argument.
+
+\cssection{bibglsnewdualindexsymbolsecondary}
+
+\formatdef{bibglsnewdualindexsymbolsecondary}
+This command is used to define secondary terms identified with the
+\atentry{dualindexsymbol} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexsymbolsecondary}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{symbol},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewdualindexnumber}
+
+\formatdef{bibglsnewdualindexnumber}
+This command is used to define primary terms identified with the
+\atentry{dualindexnumber} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexnumber}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{description} argument.
+
+\cssection{bibglsnewdualindexnumbersecondary}
+
+\formatdef{bibglsnewdualindexnumbersecondary}
+This command is used to define secondary terms identified with the
+\atentry{dualindexnumber} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\cs{bibglsnewdualindexnumbersecondary}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{number},\field{symbol}=\marg{\idx{param}4},\idx{param}2}\marg{\idx{param}5}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewdualindexabbreviation}
+
+\formatdef{bibglsnewdualindexabbreviation}
+This command is used to define primary terms identified with the
+\atentry{dualindexabbreviation} type. The default definition provided in
+the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
+ \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
+ \field{category}=\marg{index},\idx{param}3}\marg{}\comment{}
+}
+\end{codeenv}
+In this case \meta{dual-label} is the dual entry's label, which is used
+to fetch the category label in \gls{bibglsuseabbrvfont}. (The
+\field{category} field for the dual isn't used since a custom
+definition of
+\gls!{bibglsnewdualindexabbreviationsecondary} may override the
+value known to \bibgls.)
+
+Note that (as shown above) with the default
+\csopt[short]{abbreviation-name-fallback} the \field{name} uses:
+\nosecformatdef{bibglsuseabbrvfont}
+to format the name, which ensures that it uses the same font as the
+short form for the dual abbreviation. This will use
+\ics{glsuseabbrvfont} if it's defined otherwise it will be defined
+to replicate that command. If \csopt{abbreviation-name-fallback} is
+set to some other field then the \field{name} uses:
+\nosecformatdef{bibglsuselongfont}
+instead, which ensures that it uses the same font as the
+long form for the dual abbreviation.
+
+\cssection{bibglsnewdualindexabbreviationsecondary}
+
+\formatdef{bibglsnewdualindexabbreviationsecondary}
+This command is used to define secondary terms identified with the
+\atentry{dualindexabbreviation} entry type.
+The definition provided in the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualindexabbreviationsecondary}}[6]\marg{\comment{}
+ \cs{ifstrempty}\marg{\idx{param}6}\comment{}
+ \marg{\gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{}
+ \marg{\gls{newabbreviation}\oarg{\idx{param}2,\field{description}=\marg{\idx{param}6}}\marg{\idx{param}1}\marg{\idx{param}4}\marg{\idx{param}5}}\comment{}
+}
+\end{codeenv}
+This ensures that a missing or empty \field{description} doesn't
+interfere with the abbreviation style.
+
+\cssection{bibglsnewdualabbreviationentry}
+
+\formatdef{bibglsnewdualabbreviationentry}
+This command is used to define primary terms identified with the
+\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentry}}[5]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{description} argument.
+
+\cssection{bibglsnewdualabbreviationentrysecondary}
+
+\formatdef{bibglsnewdualabbreviationentrysecondary}
+This command is used to define secondary terms identified with the
+\atentry{dualabbreviationentry} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualabbreviationentrysecondary}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{short} and \meta{long}
+arguments (which will typically be empty unless the default mappings
+are changed).
+
+\cssection{bibglsnewdualentryabbreviation}
+
+\formatdef{bibglsnewdualentryabbreviation}
+This command is used to define primary terms identified with the
+(now deprecated) entry type
+\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviation}}[5]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{description} argument.
+
+\cssection{bibglsnewdualentryabbreviationsecondary}
+
+\formatdef{bibglsnewdualentryabbreviationsecondary}
+This command is used to define secondary terms identified with the
+(now deprecated) entry type
+\atentry{dualentryabbreviation}. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualentryabbreviationsecondary}}[5]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}5}\comment{}
+}
+\end{codeenv}
+Note that this definition ignores the \meta{short} and \meta{long}
+arguments (which will typically be empty unless the default mappings
+are changed).
+
+\cssection{bibglsnewdualsymbol}
+
+\formatdef{bibglsnewdualsymbol}
+This command is used to define terms identified with the
+\atentry{dualsymbol} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewdualnumber}
+
+\formatdef{bibglsnewdualnumber}
+This command is used to define terms identified with the
+\atentry{dualnumber} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualnumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{symbol},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewdualabbreviation}
+
+\formatdef{bibglsnewdualabbreviation}
+This command is used to define terms identified with the
+\atentry{dualabbreviation} type where the \field{duallong} field
+is swapped with the \field{long} field and the \field{dualshort}
+field is swapped with the \field{short} field. The definition provided in the
+\ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewdualacronym}
+
+\formatdef{bibglsnewdualacronym}
+This command is used to define terms identified with the
+\atentry{dualacronym} type. The definition provided in the \ext{glstex}
+file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewdualacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+This works in much the same way as \gls{bibglsnewdualabbreviation}.
+Remember that with the \styfmt{glossaries-extra} package \gls{newacronym}
+is redefined to just use \gls{newabbreviation} with the default \field{type}
+set to \ics{acronymtype} and the default \field{category} set to
+\code{acronym}.
+
+\cssection{bibglsnewtertiaryindexabbreviationentry}
+
+\formatdef{bibglsnewtertiaryindexabbreviationentry}
+This is used to define primary terms identified with the
+\atentry{tertiaryindexabbreviationentry} type. It's essentially
+the same as \gls!{bibglsnewdualindexabbreviation}.
+The definition provided in the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentry}}[7]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
+ \field{name}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
+ \field{category}=\marg{index},\idx{param}3}{}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewtertiaryindexabbreviationentrysecondary}
+
+\formatdef{bibglsnewtertiaryindexabbreviationentrysecondary}
+This command is used to define both the secondary and tertiary terms identified with the
+\atentry{tertiaryindexabbreviationentry} type. The secondary
+term is an abbreviation and the tertiary term is a regular entry.
+The definition written to the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewtertiaryindexabbreviationentrysecondary}}[8]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}3}\marg{\idx{param}1}\marg{\idx{param}6}\marg{\idx{param}7}\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}2}\comment{}
+ \marg{\field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}7}\marg{\cs{glscategory}\marg{\idx{param}1}}},\idx{param}4}\comment{}
+ \marg{\idx{param}8}\comment{}
+}
+\end{codeenv}
+The \meta{label} is the label for the secondary (abbreviation) entry
+and \meta{tertiary-label} is the label for the tertiary (regular)
+entry. The fifth argument (\meta{primary name}) isn't used but is
+provided if required for a custom redefinition.
+The \field{name} field for the tertiary is obtained from
+the \meta{long} argument encapsulated by \gls{bibglsuselongfont}
+to format the name, which ensures that it uses the same font as the
+long form for the dual abbreviation. This will use
+\ics{glsuselongfont} if it's defined otherwise it will be defined to
+replicate that command.
+
+\cssection{bibglsnewbibtexentry}
+
+\formatdef{bibglsnewbibtexentry}
+This command is used to define the main term identified with
+\atentry{bibtexentry}.
+The definition written to the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewcontributor}
+
+\formatdef{bibglsnewcontributor}
+This command is used to define terms identified with
+\atentry{contributor} (typically implicitly created through
+\atentry{bibtexentry}).
+The definition written to the \ext{glstex} file is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewcontributor}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewprogenitor}
+
+\formatdef{bibglsnewprogenitor}
+This command is used to define the main terms created by
+\atentry{progenitor}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewprogenitor}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnindex}
+
+\formatdef{bibglsnewspawnindex}
+This command is used to define the main terms created by
+\atentry{spawnindex}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnindex}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedindex}
+
+\formatdef{bibglsnewspawnedindex}
+This command is used to define the terms spawned by
+\atentry{progenitor} or \atentry{spawnindex}. The definition is written
+to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedindex}}[2]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}1},\field{category}={index},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnindexplural}
+
+\formatdef{bibglsnewspawnindexplural}
+This command is used to define the main terms created by
+\atentry{spawnindexplural}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnindexplural}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedindexplural}
+
+\formatdef{bibglsnewspawnedindexplural}
+This command is used to define the terms spawned by
+\atentry{spawnindexplural}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedindexplural}}[3]\marg{\comment{}
+ \gls{newglossaryentry}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{indexplural},\field{description}=\marg{},\idx{param}2}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnentry}
+
+\formatdef{bibglsnewspawnentry}
+This command is used to define the main terms created by
+\atentry{spawnentry}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedentry}
+
+\formatdef{bibglsnewspawnedentry}
+This command is used to define the terms spawned by \atentry{spawnentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnabbreviation}
+
+\formatdef{bibglsnewspawnabbreviation}
+This command is used to define the main terms created by
+\atentry{spawnabbreviation}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedabbreviation}
+
+\formatdef{bibglsnewspawnedabbreviation}
+This command is used to define the terms spawned by \atentry{spawnabbreviation}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedabbreviation}}[4]\marg{\comment{}
+ \gls{newabbreviation}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnacronym}
+
+\formatdef{bibglsnewspawnacronym}
+This command is used to define the main terms created by
+\atentry{spawnacronym}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedacronym}
+
+\formatdef{bibglsnewspawnedacronym}
+This command is used to define the terms spawned by \atentry{spawnacronym}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedacronym}}[4]\marg{\comment{}
+ \gls{newacronym}\oarg{\idx{param}2}\marg{\idx{param}1}\marg{\idx{param}3}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnsymbol}
+
+\formatdef{bibglsnewspawnsymbol}
+This command is used to define the main terms created by
+\atentry{spawnsymbol}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnedsymbol}
+
+\formatdef{bibglsnewspawnedsymbol}
+This command is used to define the terms spawned by \atentry{spawnsymbol}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnedsymbol}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnedsymbol},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewspawnnumber}
+
+\formatdef{bibglsnewspawnnumber}
+This command is used to define the main terms created by
+\atentry{spawnnumber}. The definition is written to the \ext{glstex}
+file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnnumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsnewspawnednumber}
+
+\formatdef{bibglsnewspawnednumber}
+This command is used to define the terms spawned by \atentry{spawnnumber}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawnednumber}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{sort}=\marg{\idx{param}1},\field{category}=\marg{spawnednumber},\idx{param}2}\marg{\idx{param}4}}
+\end{codeenv}
+
+\cssection{bibglsnewspawndualindexentry}
+
+\formatdef{bibglsnewspawndualindexentry}
+This command is used to define the \idx{progenitor}['s] primary term created by
+\atentry{spawndualindexentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentry}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\field{category}=\marg{index},\idx{param}2}{}\comment{}
+}
+\end{codeenv}
+The \meta{description} argument is ignored.
+
+\cssection{bibglsnewspawndualindexentrysecondary}
+
+\formatdef{bibglsnewspawndualindexentrysecondary}
+This command is used to define the \idx{progenitor}['s] secondary
+(dual) term created by
+\atentry{spawndualindexentry}.
+The definition is written to the \ext{glstex} file as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsnewspawndualindexentrysecondary}}[4]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+
+\section{Location Lists and Cross-References}
+\label{sec:loclistdefs}
+
+These commands deal with the way the location lists and cross
+references are formatted. The commands typically aren't used until
+the entry information is displayed in the glossary, so you may
+redefine these commands after the resource file has been loaded.
+
+\cssection{bibglsseesep}
+
+\formatdef{bibglsseesep}
+Any entries that provide a \field{see} field (and that field hasn't
+be omitted from the location list with \csopt[omit]{see}) will
+have \gls{bibglsseesep} inserted between the \field{see} part and the
+location list (unless there are no locations, in which case just
+the \field{see} part is displayed without \gls{bibglsseesep}).
+
+This command is provided with:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsseesep}}\marg{, }
+\end{codeenv}
+You can define this before you load the \ext{bib} file:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsseesep}}\marg{; }
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\end{codeenv}
+Or you can redefine it afterwards:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\cs{glsrenewcommand}\marg{\gls{bibglsseesep}}\marg{; }
+\end{codeenv}
+
+\cssection{bibglsseealsosep}
+
+\formatdef{bibglsseealsosep}
+This is like \gls{bibglsseesep} but is used with cross-reference
+lists provided with the \field{seealso} field, if supported.
+
+\cssection{bibglsaliassep}
+
+\formatdef{bibglsaliassep}
+This is like \gls{bibglsseesep} but is used with cross-reference
+lists provided with the \field{alias} field.
+
+\cssection{bibglsusesee}
+
+\formatdef{bibglsusesee}
+Displays the formatted cross-reference list stored in the
+\field{see} field for the given entry. This just defaults to
+\ics{glsxtrusesee}\margm{label}.
+
+\cssection{bibglsuseseealso}
+
+\formatdef{bibglsuseseealso}
+Displays the formatted cross-reference list stored in the
+\field{seealso} field for the given entry. This just defaults to
+\ics{glsxtruseseealso}\margm{label}.
+
+\cssection{bibglsusealias}
+
+\formatdef{bibglsusealias}
+Displays the formatted cross-reference stored in the
+\field{alias} field for the given entry. This is defined to use
+\ics{glsseeformat}.
+
+\cssection{bibglsdelimN}
+
+\formatdef{bibglsdelimN}
+Separator between individual locations, except for the last.
+This defaults to \ics{delimN}.
+
+\cssection{bibglslastDelimN}
+
+\formatdef{bibglslastDelimN}
+Separator between penultimate and final individual locations.
+This defaults to \code{,\idx{nbspchar}} to discourage lonely locations.
+
+\cssection{bibglscompact}
+
+\formatdef{bibglscompact}
+The first argument \meta{pattern} indicates the location pattern:
+\code{digit} for digits, \code{roman} for \idx!{lowercase}
+Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman
+numerals and \code{alpha} for alphabetical locations. The actual
+location is split into two parts, \meta{part1} and \meta{part2}.
+The string concatenation \meta{part1}\meta{part2} forms the
+actual location.
+
+This just does \meta{part2} by default.
+
+\cssection{bibglspassim}
+
+\formatdef{bibglspassim}
+If \csopt{max-loc-diff} is greater than~1, then any ranges that have
+skipped over gaps will be followed by \gls{bibglspassim}, which is
+defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}}
+\end{codeenv}
+You can define this before you load the \ext{bib} file:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglspassim}}\marg{}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\end{codeenv}
+Or you can redefine it afterwards:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\cs{glsrenewcommand}\marg{\gls{bibglspassim}}\marg{}
+\end{codeenv}
+
+\cssection{bibglspassimname}
+
+\formatdef{bibglspassimname}
+The default definition is obtained from the \langxml. For example, with
+\file{bib2gls-en.xml} the provided definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglspassimname}}\marg{passim}
+\end{codeenv}
+
+\cssection{bibglsrange}
+
+\formatdef{bibglsrange}
+Explicit ranges formed using \glsopt[\idx{openrange}]{format} and
+\glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and
+\glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a
+text-block command without the initial backslash) in the optional
+argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within
+the argument of \gls{bibglsrange}. By default this simply does its
+argument. This command is not used with ranges that are formed by collating
+consecutive locations.
+
+\cssection{bibglsinterloper}
+
+\formatdef{bibglsinterloper}
+If an explicit range conflicts with a record, a warning will be
+issued and the conflicting record will be shifted to the front
+of the range inside the argument of \gls{bibglsinterloper}.
+The default definition just does \meta{location}\gls!{bibglsdelimN}
+so that it fits neatly into the list.
+
+For example, suppose on page~4 of my document I start a range with:
+\begin{codeenv*}
+\cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample}
+\end{codeenv*}
+and end it on page~9 with:
+\begin{codeenv*}
+\cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample}
+\end{codeenv*}
+This forms an explicit range, but let's suppose on page~6 I
+have:
+\begin{codeenv}
+\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}
+\end{codeenv}
+This record conflicts with the explicit range (which doesn't include
+\encap{hyperbf} in the format). This causes a warning and
+the conflicting entry will be moved before the start of the
+explicit range resulting in \textbf{6}, 4--9.
+
+Note that implicit ranges can't be formed from interlopers (nor can
+implicit ranges be merged with explicit ones),
+so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}}
+also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7},
+\textbf{8}, 4--9. Either remove the explicit range or
+remove the conflicting entries. (Alternatively, redefine
+\gls{bibglsinterloper} to ignore its argument, which will
+discard the conflicting entries.)
+
+\cssection{bibglspostlocprefix}
+
+\formatdef{bibglspostlocprefix}
+If the \csopt{loc-prefix} option is on, \gls!{bibglslocprefix} will
+be inserted at the start of location lists, and its default
+definition includes \gls{bibglspostlocprefix}
+placed after the prefix text. This command is provided with:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglspostlocprefix}}\marg{\cs{cs.space}}
+\end{codeenv}
+which puts a space between the prefix text and the location list.
+You can define this before you load the \ext{bib} file:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglspostlocprefix}}\marg{: }
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}}
+\end{codeenv}
+Or you can redefine it afterwards:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\csopt{loc-prefix}}
+\cs{glsrenewcommand}\marg{\gls{bibglspostlocprefix}}\marg{: }
+\end{codeenv}
+
+\cssection{bibglslocprefix}
+
+\formatdef{bibglslocprefix}
+If the \csopt{loc-prefix} option is on, this command will be
+provided. If the glossary type has been provided by \csopt{type}
+(and \csopt{dual-type} if there are any dual entries) then the
+definition of \gls{bibglslocprefix} will be appended to the glossary
+preamble for the given type (or types if there are dual entries).
+For example, if the document has:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[main]{type},\csopt[p.,pp.]{loc-prefix},\csopt[entries]{src}}
+\end{codeenv}
+and there are no dual entries, then the following will be added to
+the \ext{glstex} file:
+\begin{codeenv}
+\cs{apptoglossarypreamble}\oarg{main}\marg{\comment{}
+ \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
+ \cs{ifcase}\idx{param}\idx{param}1
+ \cmd{or} p.\gls{bibglspostlocprefix}
+ \cmd{else} pp.\gls{bibglspostlocprefix}
+ \cmd{fi}
+ }\comment{}
+}
+\end{codeenv}
+However, if the \csopt{type} key is missing, then the following will
+be added instead:
+\begin{codeenv}
+\cs{appto}\cs{glossarypreamble}\marg{\comment{}
+ \cs{providecommand}\marg{\gls{bibglslocprefix}}[1]\marg{\comment{}
+ \cs{ifcase}\idx{param}1
+ \cmd{or} p.\gls{bibglspostlocprefix}
+ \cmd{else} pp.\gls{bibglspostlocprefix}
+ \cmd{fi}
+ }\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglspagename}
+
+\formatdef{bibglspagename}
+If \csopt[true]{loc-prefix} is used, then this command is provided
+using the value of \idx{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglspagename}}\marg{Page}
+\end{codeenv}
+
+\cssection{bibglspagesname}
+
+\formatdef{bibglspagesname}
+If \csopt[true]{loc-prefix} is used, then this command is provided
+using the value of \idx{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglspagesname}}\marg{Pages}
+\end{codeenv}
+
+\cssection{bibglslocsuffix}
+
+\formatdef{bibglslocsuffix}
+If the \csopt{loc-suffix} option is on, this command will be
+provided. If the glossary type has been provided by \csopt{type}
+(and \csopt{dual-type} if there are any dual entries) then the
+definition of \gls{bibglslocsuffix} will be appended to the glossary
+preamble for the given type (or types if there are dual entries).
+
+This commands definition depends on the value provided by
+\csopt{loc-suffix}. For example, with
+\csopt[\ics{at}{\idx{periodchar}}]{loc-suffix}
+the command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\ics{at}.}
+\end{codeenv}
+(which ignores the argument).
+
+Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix}
+the command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglslocsuffix}}[1]\marg{\cs{ifcase}\idx{param}1 \meta{A}\cmd{or} \meta{B}\cmd{else} \meta{C}\cmd{fi}}
+\end{codeenv}
+
+Note that this is slightly different from \gls{bibglslocprefix} as
+it includes the 0 case, which in this instance means that there were
+no locations but there was a cross-reference. This command isn't
+added when the location list is empty.
+
+\cssection{bibglsprimary}
+
+\formatdef{bibglsprimary}
+When the \csopt{save-primary-locations} option is used, the primary
+locations are stored in the \field{primarylocations} field
+encapsulated with this command. The first argument is the number of
+locations in the list. The second argument is the list of locations
+formatted in the usual way. The default definition is to ignore the
+first argument and simply do the second.
+
+\cssection{bibglslocationgroup}
+
+\formatdef{bibglslocationgroup}
+When the \csopt{loc-counters} option is used, the locations
+for each entry are grouped together according to the counter
+(in the order specified in the value of \csopt{loc-counters}).
+Each group of locations is encapsulated within
+\gls{bibglslocationgroup}, where \meta{n} is the number
+of locations within the group, \meta{counter} is the
+counter name and \meta{list} is the formatted location sub-list.
+By default, this simply does \meta{list}, but may be
+defined (before the resources are loaded) or redefined
+(after the resources are loaded) as required.
+
+For example:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{}
+ \cs{ifnum}\idx{param}1=1
+ \idx{param}2:
+ \cmd{else}
+ \idx{param}2s:
+ \cmd{fi}
+ \idx{param}3\comment{}
+}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[equation,page]{loc-counters},\comment{group locations by counter}
+ \csopt[entries]{src}\comment{data in entries.bib}
+}
+\end{codeenv}
+This will prefix each group with the counter name, if there's
+only one location, or the counter name followed by \qt{s},
+if there are multiple locations within the group.
+
+There are various ways to adapt this to translate the counter
+name to a different textual label, such as:
+\begin{codeenv}
+\cs{providecommand}\marg{\cmd{pagename}}\marg{Page}
+\cs{providecommand}\marg{\cmd{pagesname}}\marg{Pages}
+\cs{providecommand}\marg{\cmd{equationname}}\marg{Equation}
+\cs{providecommand}\marg{\cmd{equationsname}}\marg{Equations}
+\strut
+\cs{newcommand}*\marg{\gls{bibglslocationgroup}}[3]\marg{\comment{}
+ \ics{ifnum}\idx{param}1=1
+ \ics{ifcsdef}\marg{\idx{param}2name}\marg{\cs{csuse}\marg{\idx{param}2name}}\marg{\idx{param}2}:
+ \cmd{else}
+ \cs{ifcsdef}\marg{\idx{param}2sname}\marg{\cs{csuse}\marg{\idx{param}2sname}}\marg{\idx{param}2s}:
+ \cmd{fi}
+ \idx{param}3\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglslocationgroupsep}
+
+\formatdef{bibglslocationgroupsep}
+When the \csopt{loc-counters} option is set, this command
+is used to separate each location sub-group. It may be defined
+before the resources are loaded:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; }
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[equation,page]{loc-counters},\comment{group locations by counter}
+ \csopt[entries]{src}\comment{data in entries.bib}
+}
+\end{codeenv}
+or redefined after the resources are loaded:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[equation,page]{loc-counters},\comment{group locations by counter}
+ \csopt[entries]{src}\comment{data in entries.bib}
+}
+\strut
+\cs{glsrenewcommand}*\marg{\gls{bibglslocationgroupsep}}\marg{; }
+\end{codeenv}
+
+\cssection{bibglssupplemental}
+
+\formatdef{bibglssupplemental}
+When the \csopt{supplemental-locations} option is used, the locations
+from a supplementary document are encapsulated within the \meta{list}
+part of \gls{bibglssupplemental}. The first argument \meta{n}
+(ignored by default) is the number of supplementary locations.
+
+If multiple supplemental sources are permitted (that is,
+\bibgls\ has detected that the document is using at least
+version 1.36 of \sty{glossaries-extra}), then the \meta{list}
+part will consist of sub-lists for each external source. In this
+case, \meta{n} will be the total number of elements across
+all the sub-lists.
+
+\cssection{bibglssupplementalsublist}
+
+\formatdef{bibglssupplementalsublist}
+If multiple supplemental sources are permitted, this will be used
+to format each sub-list, where \meta{n} (ignored by default)
+is the number of elements in the sub-list, \meta{external document}
+(ignored by default) is the external source and \meta{list}
+is the list of supplementary locations in \meta{external document}.
+
+\cssection{bibglssupplementalsep}
+
+\formatdef{bibglssupplementalsep}
+The separator between the main location list and the supplementary
+location list. By default this is just \gls!{bibglsdelimN}. This may be
+defined before the resources are loaded:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglssupplementalsep}}\marg{; }
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[supplDoc]{supplemental-locations},
+ \csopt[entries]{src}}
+\end{codeenv}
+or redefined after the resources are loaded:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[supplDoc]{supplemental-locations},
+ \csopt[entries]{src}}
+\strut
+\cs{glsrenewcommand}\marg{\gls{bibglssupplementalsep}}\marg{; }
+\end{codeenv}
+
+\cssection{bibglssupplementalsubsep}
+
+\formatdef{bibglssupplementalsubsep}
+The separator between the supplementary
+location sub-lists. By default this is just \gls!{bibglsdelimN}.
+
+\cssection{bibglshrefchar}
+
+\formatdef{bibglshrefchar}
+Expands to a literal percent character followed by \meta{hex}. The
+second argument is ignored.
+
+\cssection{bibglshrefunicode}
+
+\formatdef{bibglshrefunicode}
+Expands to the second argument. The first argument is ignored.
+
+\section{Letter Groups}
+\label{sec:lettergroupdefs}
+
+The commands listed in this section are provided for use with the
+\longarg{group} switch and glossary styles that display the letter
+group title. If these need their definitions altered, they should
+be defined before the resource file is loaded if field expansion
+is on (\longarg{expand-fields}) otherwise they may be redefined
+afterwards.
+
+The base \isty{glossaries} package determines group titles through a fairly
+simplistic rule. Both \idx!{makeindex} and \idx!{xindy} write the
+line:
+\nosecformatdef{glsgroupheading}
+to the associated glossary file at the start of each new letter group.
+For example, the \qt{A} letter group will be written as:
+\begin{codeenv}
+\gls{glsgroupheading}\marg{A}
+\end{codeenv}
+This is quite straightforward and the heading title can just be
+\qt{A}. The \qt{Symbols} group is written as:
+\begin{codeenv}
+\gls{glsgroupheading}\marg{glssymbols}
+\end{codeenv}
+To allow for easy translation, the base \sty{glossaries} package has
+the simple rule:
+\begin{itemize}
+\item if \csfmt{\meta{heading}groupname} exists use that;
+\item otherwise just use \meta{heading}.
+\end{itemize}
+There's no \csfmt{Agroupname} provided, but \ics{glssymbolsgroupname}
+is provided and is supported by the associated language modules,
+such as \styfmt{glossaries-french}. (Similarly for the \qt{Numbers}
+group.)
+
+The glossary styles that provide hyperlinks to the groups (such as
+\glostyle{indexhypergroup}) use \meta{heading} to form the target
+name. A problem arises when active characters occur in
+\meta{heading}, which happens with extended characters and
+\isty{inputenc}.
+
+The \sty{glossaries-extra} package (as from version 1.14) provides:
+\nosecformatdef{glsxtrsetgrouptitle}
+to set the title for a group with the given label. The internal
+workings of \gls{glsgroupheading} are modified to use a slightly
+altered rule:
+\begin{itemize}
+\item if a title has been set using
+\gls{glsxtrsetgrouptitle}\margm{heading}\margm{title} for the given
+\meta{heading}, use that;
+\item if \csfmt{\meta{heading}groupname} exists, use that;
+\item just use \meta{heading} for the title.
+\end{itemize}
+So if \gls{glsxtrsetgrouptitle} hasn't been used, it falls back on
+the original rule.
+
+The problem is now how to make the indexing application use the
+desired label in the argument of \gls{glsgroupheading} instead of selecting
+the heading based on the first character of each sort value for each
+top-level entry in that group. This can't be done with
+\idx!{makeindex}, and with \idx!{xindy} it requires a custom language
+module, which isn't a trivial task.
+
+With \bibgls, a different approach is used. The \iext{glstex} file
+created isn't comparable to the \iext{gls} file created by
+\idx!{makeindex} or \idx!{xindy}. There's nowhere for \bibgls\ to
+write the \gls{glsgroupheading} line as it isn't creating the code
+that typesets the glossary list. Instead it's creating the code that
+defines the entries. The actual group heading is inserted by
+\ics{printunsrtglossary} and it's only able to do this by checking if
+the entry has a \field{group} field and comparing it to the previous
+entry's \field{group} field.
+
+The behaviour of the group formation implemented by the sort
+methods may be changed with \csopt{group-formation}. With any
+setting other than \csopt[default]{group-formation}, the group label
+is set to \format{bibglsunicodegroup} and the title is set to
+\format{bibglsunicodegrouptitle} (see below) otherwise the label and
+title are determined by the sort method.
+
+The collators used by the locale and letter-based rules save the
+following information for each entry based on the first significant letter of
+the \field{sort} field (if the letter is recognised as alphabetical,
+according to the rule):
+\begin{itemize}
+\item \meta{title} The group's title. This is typically title-cased.
+For example, if the rule recognises the digraph \qt{dz}, then the
+title is \qt{Dz}. Exceptions to this are included in the \langxml.
+If the key \idx{grouptitle.case.lc} exists, where
+\meta{lc} is the \idx!{lowercase} version of \meta{title}, then the value
+of that key is used instead. For example, the Dutch digraph \qt{ij}
+should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes:
+\begin{verbatim}
+<entry key="grouptitle.case.ij">IJ</entry>
+\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 \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
+method.
+\item \meta{type} The entry's glossary type. If not known, this will
+be empty. (\bibgls\ won't know if you've modified the associated
+\csfmt{bibglsnew\ldots} command to set the \field{type}. It can only
+know the type if it's in the original \ext{bib} definition or is set
+using resource options such as \csopt{type}.)
+\end{itemize}
+
+The \field{group} field is then set using:
+\begin{codeenv}
+\field{group}=\marg{\gls{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}}
+\end{codeenv}
+This field needs to expand to a simple label, which \gls!{bibglslettergroup}
+is designed to do. Note that non-letter groups are dealt with
+separately (see below).
+
+\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{codeenv}
+\gls{bibglssetlastgrouptitle}\marg{\gls{bibglslettergroup}}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}
+\end{codeenv}
+In this case \meta{cs} is \gls{bibglslettergroup} and \meta{specs}
+are the arguments for that command. If you want \gls{bibglssetlastgrouptitle}
+to change the group title then you need to define it before the
+\idx{resourceset}. For example:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglssetlastgrouptitle}}[2]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\idx{param}1\idx{param}2}\marg{Foreign Words}}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\end{codeenv}
+If you need to change a particular group title, then it has to be
+done after the \idx{resourceset}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\cs{glsxtrsetgrouptitle}
+ \marg{\gls{bibglslettergroup}\marg{\marg{Ø}\marg{Ø}\marg{2147418112}\marg{}}}\comment{label}
+ \marg{Foreign Words}\comment{title}
+\end{codeenv}
+
+\cssection{bibglssetlettergrouptitle}
+
+For each \idx{lettergroup} that's detected, \bibgls\ will write the line:
+\formatdef{bibglssetlettergrouptitle}
+in the \ext{glstex} file, which sets the group's title using:
+\begin{codeenv}
+\format{glsxtrsetgrouptitle}
+\end{codeenv}
+where the \meta{group label} part matches the corresponding \field{group}
+value.
+
+Note that \gls{bibglssetlettergrouptitle} only has a single
+argument, but that argument contains the four arguments needed by
+\gls!{bibglslettergroup} and \gls!{bibglslettergrouptitle}.
+These arguments are as described above.
+
+If \gls{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra}
+version 1.14 onwards), then \gls{bibglssetlettergrouptitle} will be
+defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssetlettergrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\gls{bibglslettergroup}\idx{param}1}\marg{\gls{bibglslettergrouptitle}\idx{param}1}}
+\end{codeenv}
+If an earlier version of \sty{glossaries-extra} is used, then this
+function can't be supported and the command will be defined to
+simply ignore its argument. This will fall back on the original
+method of just using \meta{title} as the label.
+
+Since \gls{bibglssetlettergrouptitle} is used in the \ext{glstex} file to
+set the group titles, the associated commands need to be defined
+before the resource file is loaded if their definitions require
+modification. After the resource file has been loaded, you can
+adjust the title of a specific group, but you'll need to check the
+\ext{glstex} file for the appropriate arguments. For example, if the
+\ext{glstex} file contains:
+\begin{codeenv}
+\gls{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}
+\end{codeenv}
+but you actually want the group title to appear as \qt{\AE\ (AE)}
+instead of just \qt{\AE}, then after the resource file has been
+loaded you can do:
+\begin{codeenv}
+\gls{glsxtrsetgrouptitle}
+ \marg{\gls{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\comment{label}
+ \marg{\AE\ (AE)}\comment{title}
+\end{codeenv}
+
+\cssection{bibglslettergroup}
+
+\formatdef{bibglslettergroup}
+This command is used to determine the \idx{lettergroup} label. The
+default definition is \meta{type}\meta{id}, which ensures that no
+problematic characters occur in the label since \meta{type} can't
+contains special characters and \meta{id} is numeric. The
+\meta{type} is included in case there are multiple glossaries, since
+the hyperlink name must be unique.
+
+\cssection{bibglslettergrouptitle}
+
+\formatdef{bibglslettergrouptitle}
+This command is used to determine the \idx{lettergroup} title.
+The default definition is \ics{unexpanded}\margm{title}, which guards
+against any expansion issues that may arise with characters outside
+the basic Latin set.
+
+For example:
+\begin{codeenv}
+\atentry{entry}\marg{angstrom,
+ \field{name}=\marg{\cs{AA} ngstr\cs{umlaut}om}
+ \field{description}=\marg{a unit of length equal to one hundred-millionth
+of a centimetre}
+}
+\end{codeenv}
+The \field{sort} value is \qtt{\AA ngstr\"om}. With \csopt[en]{sort}
+the \meta{title} part will be \code{A} but with \csopt[sv]{sort}
+the \meta{title} part will be \code{\AA}. In both cases the
+\meta{letter} argument will be \code{\AA}.
+
+Take care if you are using a script that needs encapsulating. For
+example, with the \isty{CJKutf8} package the \idx{CJK} characters need to
+be placed within the \env{CJK} environment, so any letter group
+titles that contain \idx{CJK} characters will need special attention.
+
+For example, suppose the \ext{bib} file contains entries in the
+form:
+\begin{codeenv}
+\atentry{dualentry}\marg{\meta{label},
+ \field{name} = \marg{\gls{cjkname}\margm{\idx{CJK} characters}},
+ \field{description} = \margm{English translation}
+}
+\end{codeenv}
+and the document contains:
+\begin{codeenv}
+\cmd{usepackage}\marg{CJKutf8}
+\cmd{usepackage}[\styopt{record},\styopt[indexgroup]{style},\styopt{nomain}]\marg{glossaries-extra}
+\strut
+\cs{newglossary*}\marg{japanese}\marg{Japanese to English}
+\cs{newglossary*}\marg{english}\marg{English to Japanese}
+\strut
+\ics{newrobustcmd}\marg{\gls{cjkname}}[1]\marg{\cmd{begin}\marg{CJK}\marg{UTF8}\marg{min}\idx{param}1\cmd{end}\marg{CJK}}
+\strut
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[testcjk]{src},\comment{bib file}
+ \csopt[ja-JP]{sort},\comment{locale used to sort primary entries}
+ \csopt[en-GB]{dual-sort},\comment{locale used to sort secondary entries}
+ \csopt[japanese]{type},\comment{put the primary entries in the 'japanese' glossary}
+ \csopt[english]{dual-type},\comment{put the dual entries in the 'english' glossary}
+ \csopt[en.]{dual-prefix}
+}
+\end{codeenv}
+then \idx{CJK} characters will appear in the \meta{title} argument of
+\gls{bibglslettergrouptitle} which causes a problem because they need
+to be encapsulated within the \env{CJK} environment. This can be more
+conveniently done with the user supplied \inlinedef{cjkname}, but the \idx{CJK}
+characters need to be protected from expansion so \ics{unexpanded} is
+also needed. The new definition of \gls{bibglslettergrouptitle} needs
+to be defined before \gls{GlsXtrLoadResources}. For example:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\cs{unexpanded}\marg{\gls{cjkname}\marg{\idx{param}1}}}
+\end{codeenv}
+There's a slight problem here in that the English letter group titles
+also end up encapsulated. An alternative approach is to use the
+\meta{type} part to provide different forms. For example:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{englishlettergroup}}[1]\marg{\idx{param}1}
+\cs{newcommand}*\marg{\cmd{japaneselettergroup}}[1]\marg{\gls{cjkname}\marg{\idx{param}1}}
+\cs{newcommand}\marg{\gls{bibglslettergrouptitle}}[4]\marg{\comment{}
+ \cs{unexpanded}\marg{\cs{csuse}\marg{\idx{param}4lettergroup}\marg{\idx{param}1}}}
+\end{codeenv}
+
+\cssection{bibglssetothergrouptitle}
+
+The label and title for \idxpl{symbolgroup}
+are dealt with in a similar way to the \idxpl!{lettergroup}, but in this
+case the title is set using:
+\formatdef{bibglssetothergrouptitle}
+This is defined in an analogous manner:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssetothergrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsothergroup}\idx{param}1}\marg{\gls{bibglsothergrouptitle}\idx{param}1}}
+\end{codeenv}
+where the group label is obtained using \gls!{bibglsothergroup} and
+the group title is obtained from \gls!{bibglsothergrouptitle}.
+Note that since non-alphabetic characters don't have upper or lower
+case versions, there are only three arguments. The other difference
+between this and the letter group version is that the \meta{id} is
+given in hexadecimal format (corresponding to the character code).
+
+For example, suppose my \ext{bib} file contains:
+\begin{codeenv}
+\atentry{entry}\marg{sauthor,
+ \field{name}=\marg{/Author},
+ \field{description} = \marg{author string}
+}
+\end{codeenv}
+If a locale sort is used, the leading slash \code{/} will be
+ignored and this entry will belong to the \qt{A} letter group using
+the letter commands described above. If, instead, one of the
+character code sort methods are used, such as
+\csopt[letter-case]{sort}, then this entry will be identified as
+belonging to a symbol (or \qt{other}) group and the title will be
+set using:
+\begin{codeenv}
+\gls{bibglssetothergrouptitle}\marg{\marg{/}\marg{2F}\marg{}}
+\end{codeenv}
+
+\cssection{bibglsothergroup}
+
+\formatdef{bibglsothergroup}
+This expands to the label for \idxpl{symbolgroup}. This just
+defaults to \code{glssymbols} (ignoring all arguments), which
+replicates the label used when \idx!{makeindex} or \idx!{xindy}
+generate the glossary files.
+
+\cssection{bibglsothergrouptitle}
+
+\formatdef{bibglsothergrouptitle}
+This expands to the title for \idxpl{symbolgroup}. This just
+expands to \ics{glssymbolsgroupname} by default.
+
+\cssection{bibglssetemptygrouptitle}
+
+Used when the sort value degenerates to an empty string. This command
+sets the label and title.
+\formatdef{bibglssetemptygrouptitle}
+(Note the inner group, as with the other similar
+\csfmt{bibglsset\ldots grouptitle} commands.)
+
+\cssection{bibglsemptygroup}
+
+\formatdef{bibglsemptygroup}
+This expands to the label for \idxpl{emptygroup}. This
+defaults to \code{glssymbols} to make it consistent with
+\idxpl{nonlettergroup} (since the sort value likely contained
+unknown symbol commands).
+
+\cssection{bibglsemptygrouptitle}
+
+\formatdef{bibglsemptygrouptitle}
+This expands to the group title for \idx{emptygroup}. This just
+expands to \ics{glssymbolsgroupname} by default.
+
+\cssection{bibglssetnumbergrouptitle}
+
+The numeric sort methods (\tableref{tab:sortoptionsnumerical})
+all create \idxpl{numbergroup} instead of letter
+or symbol groups. These behave in an analogous way to the above.
+\formatdef{bibglssetnumbergrouptitle}
+In this case \meta{value} is the actual numeric sort value, and
+\meta{id} is a decimal number obtained from converting \meta{value}
+to an integer. This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssetnumbergrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsnumbergroup}\idx{param}1}\marg{\gls{bibglsnumbergrouptitle}\idx{param}1}}
+\end{codeenv}
+
+\cssection{bibglsnumbergroup}
+
+The \idx{numbergroup} label is obtained from:
+\formatdef{bibglsnumbergroup}
+This just defaults to \code{glsnumbers}.
+
+\cssection{bibglsnumbergrouptitle}
+
+The \idx{numbergroup} title is obtained from:
+\formatdef{bibglsnumbergrouptitle}
+This just defaults to \ics{glsnumbersgroupname}.
+
+\cssection{bibglssetdatetimegrouptitle}
+
+The date-time sort methods (\tableref{tab:sortoptionsdatetime})
+create \idxpl{datetimegroup}. These behave in an analogous way to the above.
+\formatdef{bibglssetdatetimegrouptitle}
+This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssetdatetimegrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}
+ \marg{\gls{bibglsdatetimegroup}\idx{param}1}\comment{}
+ \marg{\gls{bibglsdatetimegrouptitle}\idx{param}1}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglsdatetimegroup}
+
+\formatdef{bibglsdatetimegroup}
+
+This command is used for \idx{datetimegroup} labels with \optfmt{datetime} sorting
+(\tableref{tab:sortoptionsdatetime}). This has ten arguments, which means a
+little trickery is needed to deal with the tenth argument.
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdatetimegroup}}[9]\marg{\idx{param}1\idx{param}2\idx{param}3\ics{@firstofone}}
+\end{codeenv}
+This forms the group label from the year \meta{YYYY}, month \meta{MM},
+day \meta{DD} and \meta{type}.
+
+\cssection{bibglsdatetimegrouptitle}
+
+\formatdef{bibglsdatetimegrouptitle}
+
+This command is used for \idx{datetimegroup} titles with \optfmt{datetime} sorting
+(\tableref{tab:sortoptionsdatetime}).
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdatetimegrouptitle}}[9]\marg{\idx{param}1-\idx{param}2-\idx{param}3\ics{@gobble}}
+\end{codeenv}
+This sets the title to the numeric
+\code{\meta{YYYY}-\meta{MM}-\meta{DD}}
+but may be redefined as appropriate.
+
+\cssection{bibglssetdategrouptitle}
+
+The date sort methods (\tableref{tab:sortoptionsdatetime})
+create \idxpl{dategroup} (the time isn't included). These behave in an
+analogous way to the above.
+\formatdef{bibglssetdategrouptitle}
+This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssetdategrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\gls{bibglsdategroup}\idx{param}1}\marg{\gls{bibglsdategrouptitle}\idx{param}1}}
+\end{codeenv}
+
+\cssection{bibglsdategroup}
+
+\formatdef{bibglsdategroup}
+
+This command is used for \idx{dategroup} labels with \optfmt{date} (no time) sorting
+(\tableref{tab:sortoptionsdatetime}). The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}4\idx{param}7}
+\end{codeenv}
+This forms the group label from the year, month, era and type.
+In this case, the era is a textual representation not the numeric
+value used in calculating the sort value.
+
+\cssection{bibglsdategrouptitle}
+
+\formatdef{bibglsdategrouptitle}
+This command is used for \idx{dategroup} titles with \optfmt{date} (no time) sorting
+(\tableref{tab:sortoptionsdatetime}). The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\idx{param}1-\idx{param}2}
+\end{codeenv}
+This just sets the title to the numeric year-month form
+\code{\meta{YYYY}-\meta{MM}}.
+
+\cssection{bibglssettimegrouptitle}
+
+The time sort methods (\tableref{tab:sortoptionsdatetime})
+create \idxpl{timegroup} (the date isn't included). These behave in an
+analogous way to the above.
+\formatdef{bibglssettimegrouptitle}
+This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglssettimegrouptitle}}[1]\marg{\comment{}
+ \cs{glsxtrsetgrouptitle}\marg{\gls{bibglstimegroup}\idx{param}1}\marg{\gls{bibglstimegrouptitle}\idx{param}1}}
+\end{codeenv}
+
+\cssection{bibglstimegroup}
+
+\formatdef{bibglstimegroup}
+This command is used for \idx{timegroup} labels with \optfmt{time} (no date) sorting
+(\tableref{tab:sortoptionsdatetime}).
+This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglstimegroup}}[7]\marg{\idx{param}1\idx{param}2\idx{param}7}
+\end{codeenv}
+
+\cssection{bibglstimegrouptitle}
+
+\formatdef{bibglstimegrouptitle}
+
+This command is used for \idx{timegroup} titles with \optfmt{time} (no date) sorting
+(\tableref{tab:sortoptionsdatetime}).
+This command is defined as:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglstimegrouptitle}}[7]\marg{\idx{param}1}
+\end{codeenv}
+
+\cssection{bibglssetunicodegrouptitle}
+
+\formatdef{bibglssetunicodegrouptitle}
+This command is used to assign the group titles when the group
+formation is set to any value other than the default. For example,
+this command will be used with \csopt[codepoint]{group-formation}.
+The label is obtained from \gls{bibglsunicodegroup} and the title is
+obtained from \gls{bibglsunicodegrouptitle}.
+
+\cssection{bibglsunicodegroup}
+
+\formatdef{bibglsunicodegroup}
+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 \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 \idx!{uppercase} letter);
+\item\csopt[unicode script]{group-formation}: the \meta{label} is the
+Unicode script associated with \meta{character} (for example,
+\code{LATIN});
+\item\csopt[unicode category and script]{group-formation}: the \meta{label}
+identifies both the Unicode category and script associated with
+\meta{character} (for example, \code{Lu.LATIN}).
+\end{itemize}
+(Similarly for \csopt{secondary-group-formation} and
+\csopt{dual-group-formation}.) By default this command expands to
+\meta{type}\meta{label}.
+
+The \meta{character} is the first significant character of the sort
+value. The \meta{id} is the hexadecimal code of (possibly decomposed)
+\meta{character}. The case of codepoint \meta{id} may or may not correspond
+to the case of \meta{character}.
+
+For example, with \csopt[codepoint]{group-formation}, an unset
+\field{type} and a sort value of \qt{\AA ngstr\"om} with \qt{\AA} as a
+significant character distinct from \qt{A} then the \field{group}
+field will be assigned using:
+\begin{codeenv}
+\field{group}=\marg{\gls{bibglsunicodegroup}\marg{å}\marg{Å}\marg{C5}\marg{}}
+\end{codeenv}
+whereas with \csopt[unicode category and script]{group-formation} it will be:
+\begin{codeenv}
+\field{group}=\marg{\gls{bibglsunicodegroup}\marg{Lu.LATIN}\marg{Å}\marg{C5}\marg{}}
+\end{codeenv}
+(\idx!{uppercase} Latin letter).
+
+If instead \qt{\AA} is considered equivalent to \qt{A} according to the
+collator, then with \csopt[codepoint]{group-formation}, the value will be:
+\begin{codeenv}
+\field{group}=\marg{\gls{bibglsunicodegroup}\marg{a}\marg{Å}\marg{61}\marg{}}
+\end{codeenv}
+Note that the \meta{id} is now \hex{61} (the decomposed \qt{A}
+converted to \idx{lowercase}) not \hex{C5}.
+
+\cssection{bibglsunicodegrouptitle}
+
+\formatdef{bibglsunicodegrouptitle}
+The title for Unicode group formations is simply defined as
+\code{\cs{unexpanded}\margm{label}} so you will need to change it to
+something more appropriate. For example (before the \idx{resourceset}):
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}[4]\marg{\comment{}
+ \ifnumhex{\idx{param}3}>64
+ \ifnumhex{\idx{param}3} < 91
+ A-{}-Z\comment{}
+ \cmd{else}
+ \ifnumhex{\idx{param}3} > 96
+ \ifnumhex{\idx{param}3} < 123
+ A-{}-Z\comment{}
+ \cmd{fi}
+ \cmd{fi}
+ \cmd{fi}
+ \cmd{fi}
+}
+\end{codeenv}
+This will make the title \qt{A--Z} if \meta{id} is greater
+than 64 and less than 91 or greater than 96 and less than 123
+(and will be empty otherwise).
+
+Note that this setting can create an odd effect if the sorting
+causes the groups to be split up. For example, if some of the sort values
+start with extended or non-Latin characters this can break up the
+groups. First check how the group labels are assigned using:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsunicodegrouptitle}}\marg{\gls{bibglsunicodegroup}}
+\end{codeenv}
+then adjust the definition of \gls{bibglsunicodegroup} until the
+grouping is correct, and then change the definition of
+\gls{bibglsunicodegrouptitle} so that the title is correct.
+
+\cssection{bibglshypergroup}
+
+\formatdef{bibglshypergroup}
+
+If the \iext{log} file indicates that \isty{hyperref} has been loaded
+and the \longarg{group} switch is used, then this command will be
+used to create the navigation information for glossary styles such
+as \glostyle{indexhypergroup}.
+
+\section{Flattened Entries}
+\label{sec:flattendefs}
+
+These commands relate to the way the \field{name} field is altered
+when flattening lonely child entries with the \csopt{flatten-lonely}
+option.
+
+\cssection{bibglsflattenedhomograph}
+
+\formatdef{bibglsflattenedhomograph}
+The default definition simply does \meta{name}.
+
+This command is used if the child and parent name's are identical.
+For example, suppose the \ext{bib} file contains:
+\begin{codeenv}
+\atentry{index}\marg{super.glossary, \field{name}=\marg{glossary}}
+\strut
+\atentry{entry}\marg{glossarycol,
+ \field{parent}=\marg{super.glossary},
+ \field{description}=\marg{collection of glosses}
+}
+\strut
+\atentry{entry}\marg{glossarylist,
+ \field{parent}=\marg{super.glossary},
+ \field{description}=\marg{list of technical words}
+}
+\end{codeenv}
+The child entries don't have a \field{name} field, so the value is assumed
+to be the same as the parent's \field{name} field. Here's an example
+document where both child entries are used:
+\begin{codeenv}
+\cmd{documentclass}\marg{article}
+\strut
+\cmd{usepackage}[\styopt{record},\istyopt{subentrycounter},\styopt[treenoname]{style}]\marg{glossaries-extra}
+\strut
+\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}
+\strut
+\cmd{begin}\marg{document}
+\cs{gls}\marg{glossarycol} (collection) vs \cs{gls}\marg{glossarylist} (list).
+\strut
+\cs{printunsrtglossary}
+\cmd{end}\marg{document}
+\end{codeenv}
+This uses one of the glossary styles designed for homographs and the
+glossary has the structure:
+\begin{flushleft}
+\textbf{glossary}\par
+\quad 1) collection of glosses 1\par
+\quad 2) list of technical words 1
+\end{flushleft}
+If only one child entry is selected, then the result looks a little
+odd. For example:
+\begin{flushleft}
+\textbf{glossary}\par
+\quad 1) collection of glosses 1
+\end{flushleft}
+With the \csopt{flatten-lonely} option, the parent is removed and
+the child is moved up a hierarchical level. With
+\csopt[postsort]{flatten-lonely} this would normally adjust the
+name so that it appears as \meta{parent name}, \meta{child name}
+but in this case it would look a little odd for the name to
+appear as \qt{glossary, glossary} so instead the name is
+set to:
+\begin{codeenv}
+\gls{bibglsflattenedhomograph}\marg{glossary}\marg{super.glossary}
+\end{codeenv}
+(where the first argument is the original name and the second argument is the
+label of the parent entry).
+
+This means that the name simply appears as \qt{glossary}, even if
+the \csopt[postsort]{flatten-lonely} option is used. Note that if
+the parent entry is removed, the parent label won't be of much use.
+You can test for existence using \ics{ifglsentryexists} in case you
+want to vary the way the name is displayed according to whether or
+not the parent is still present.
+
+\cssection{bibglsflattenedchildpresort}
+
+\formatdef{bibglsflattenedchildpresort}
+
+Used by the \csopt[presort]{flatten-lonely} option. This defaults
+to just \meta{child name}. If you want to change this, remember that
+you can let the interpreter know by adding the definition to
+\atentry{preamble}. For example:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\gls{bibglsflattenedchildpresort}}[2]\marg{\idx{param}1 (\idx{param}2)}}}
+\end{codeenv}
+
+\cssection{bibglsflattenedchildpostsort}
+
+\formatdef{bibglsflattenedchildpostsort}
+
+Used by the \csopt[postsort]{flatten-lonely} option. This defaults
+to \code{\meta{parent name}, \meta{child name}}.
+
+Note that the arguments are in the reverse order to those of the
+previous command. This is done to assist the automated first letter
+upper-casing. If either command is redefined to alter the ordering,
+then this can confuse the case-changing mechanism, in which case you
+may want to consider switching on the expansion of the \field{name}
+field using:
+\begin{codeenv}
+\gls{glssetexpandfield}\marg{name}
+\end{codeenv}
+(before \gls{GlsXtrLoadResources}).
+
+\section{Other}
+
+\cssection{bibglshyperlink}
+
+\formatdef{bibglshyperlink}
+Used by the \hyperref[sec:dualoptsbacklinks]{back link options},
+this just defaults to:
+\begin{codeenv}
+\ics{glshyperlink}\oargm{text}\margm{label}
+\end{codeenv}
+
+\cssection{bibglssetwidest}
+
+\formatdef{bibglssetwidest}
+This is used by \csopt{set-widest} to set the widest name for the
+given hierarchical level where the glossary type can't be determined.
+This is defined as:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsxtrSetWidest}\marg{}\marg{\idx{param}1}\marg{\idx{param}2}}
+\end{codeenv}
+if \ics{glsxtrSetWidest} has been defined, or:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glsupdatewidest}\oarg{\idx{param}1}\marg{\idx{param}2}}
+\end{codeenv}
+if \ics{glsupdatewidest} is defined, otherwise it will be
+defined to use \ics{glssetwidest}:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidest}}[2]\marg{\cs{glssetwidest}\oarg{\idx{param}1}\marg{\idx{param}2}}
+\end{codeenv}
+Since this isn't scoped, this will affect other glossaries.
+In general, if you have more than one glossary it's best to
+set the \field{type} using options like \csopt{type}.
+
+\cssection{bibglssetwidestfortype}
+
+\formatdef{bibglssetwidestfortype}
+This is used by \csopt{set-widest} to set the widest name for the
+given hierarchical level where the glossary type is known. This
+is defined as:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
+ \cs{glsxtrSetWidest}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\comment{}
+}
+\end{codeenv}
+if \ics{glsxtrSetWidest} has been defined, or:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
+ \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glsupdatewidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{}
+}
+\end{codeenv}
+if \ics{glsupdatewidest} is defined, otherwise it will be
+defined to use \ics{glssetwidest}:
+\begin{codeenv}
+\cs{providecommand}*\marg{\gls{bibglssetwidestfortype}}[3]\marg{\comment{}
+ \cs{apptoglossarypreamble}\oarg{\idx{param}1}\marg{\cs{glssetwidest}\oarg{\idx{param}2}\marg{\idx{param}3}}\comment{}
+}
+\end{codeenv}
+Since the glossary preamble is scoped, this won't affect other
+glossaries.
+
+\cssection{bibglssetwidestfallback}
+
+\formatdef{bibglssetwidestfallback}
+This is used by \csopt{set-widest} instead of \gls{bibglssetwidest}
+when all \field{name} fields end up as an empty string when
+interpreted by \bibgls. This typically means that all the
+\field{name} fields contain unknown commands. This fallback command
+will use:
+\begin{codeenv}
+\ics{glsxtrSetWidestFallback}\marg{2}\margm{glossary list}
+\end{codeenv}
+if defined otherwise it will use \ics{glsFindWidestLevelTwo}, which
+sets the widest name for the top-level and first two sub-levels
+across all the listed glossaries.
+
+\cssection{bibglssetwidestfortypefallback}
+
+\formatdef{bibglssetwidestfortypefallback}
+This is used by \csopt{set-widest} instead of
+\gls{bibglssetwidestfortype}
+when all \field{name} fields end up as an empty string when
+interpreted by \bibgls. This typically means that all the
+\field{name} fields contain unknown commands. This fallback command
+will append \gls{bibglssetwidestfallback} to the glossary preamble
+for the given type.
+
+\cssection{bibglssetwidesttoplevelfallback}
+
+\formatdef{bibglssetwidesttoplevelfallback}
+This is used by \csopt{set-widest} instead of \gls{bibglssetwidest}
+when all \field{name} fields end up as an empty string when
+interpreted by \bibgls. This typically means that all the
+\field{name} fields contain unknown commands. This fallback command
+will use:
+\begin{codeenv}
+\ics{glsxtrSetWidestFallback}\marg{0}\margm{glossary list}
+\end{codeenv}
+if defined otherwise it will use \ics{glsFindWidestTopLevelName},
+which sets the widest name for the top-level.
+
+\cssection{bibglssetwidesttoplevelfortypefallback}
+
+\formatdef{bibglssetwidesttoplevelfortypefallback}
+This is used by \csopt{set-widest} instead of
+\gls{bibglssetwidestfortype}
+when all \field{name} fields end up as an empty string when
+interpreted by \bibgls. This typically means that all the
+\field{name} fields contain unknown commands. This fallback command
+will append \gls{bibglssetwidesttoplevelfallback} to the glossary
+preamble of the given type.
+
+\cssection{bibglscontributorlist}
+
+\formatdef{bibglscontributorlist}
+This is used when \csopt{bibtex-contributor-fields} is set. The
+definition depends on whether or not \ics{DTLformatlist} has been
+defined:
+\begin{codeenv}
+\ics{ifdef}\cs{DTLformatlist}
+\marg{\comment{datatool v2.28+}
+ \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\cs{DTLformatlist}\marg{\idx{param}1}}
+}
+\marg{\comment{datatool v2.27 or earlier}
+ \cs{providecommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{}
+ \ics{def}\cmd{bibgls@sep}\marg{}\comment{}
+ \ics{@for}\cmd{bibgls@item}:=\idx{param}1\cmd{do}\marg{\cmd{bibgls@sep}\cmd{bibgls@item}\cs{def}\cmd{bibgls@sep}\marg{, }}\comment{}
+ }
+}
+\end{codeenv}
+The second argument allows you to provide definitions like:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglscontributorlist}}[2]\marg{\comment{}
+ \cs{ifcase}\idx{param}2
+ \cmd{or}
+ name:
+ \cmd{else}
+ names:
+ \cmd{fi}
+ \cs{DTLformatlist}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+
+\cssection{bibglscontributor}
+
+\formatdef{bibglscontributor}
+This is used when \csopt{bibtex-contributor-fields} is set. The
+definition depends on the value of \csopt{contributor-order}. Note that if you
+have multiple resource sets, that option governs the way \bibgls's version of
+\gls{bibglscontributor} behaves. The definition is written to the \ext{glstex}
+using \cs{providecommand}, so \LaTeX\ will only pick up the first definition.
+
+\cssection{bibglsdatetime}
+
+\formatdef{bibglsdatetime}
+Used to encapsulate date-time fields identified with
+\csopt{date-time-fields}.
+Since \gls{bibglsdatetime} requires more than nine arguments, the
+remaining four arguments are picked up with:
+\nosecdef{bibglsdatetimeremainder}
+The default definitions are:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdatetime}}[9]\marg{\gls{bibglsdatetimeremainder}}
+\cs{providecommand}\marg{\gls{bibglsdatetimeremainder}}[4]\marg{\idx{param}4}
+\end{codeenv}
+
+\cssection{bibglsdate}
+
+\formatdef{bibglsdate}
+Used to encapsulate date fields identified with
+\csopt{date-fields}.
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglsdate}}[7]\marg{\idx{param}7}
+\end{codeenv}
+
+\cssection{bibglstime}
+
+\formatdef{bibglstime}
+Used to encapsulate date fields identified with
+\csopt{time-fields}.
+The default definition is:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{bibglstime}}[7]\marg{\idx{param}7}
+\end{codeenv}
+
+\cssection{bibglsprimaryprefixlabel}
+
+\formatdef{bibglsprimaryprefixlabel}
+A hook to pick up the primary prefix label (identified with
+\csopt{label-prefix}) if required. This does nothing by default. If
+required, this command should be defined before the
+\idx{resourceset} is loaded.
+
+\cssection{bibglsdualprefixlabel}
+
+\formatdef{bibglsdualprefixlabel}
+A hook to pick up the dual prefix label (identified with
+\csopt{dual-prefix}) if required. This does nothing by default. If
+required, this command should be defined before the
+\idx{resourceset} is loaded.
+
+\cssection{bibglstertiaryprefixlabel}
+
+\formatdef{bibglstertiaryprefixlabel}
+A hook to pick up the tertiary prefix label (identified with
+\csopt{tertiary-prefix}) if required. This does nothing by default. If
+required, this command should be defined before the
+\idx{resourceset} is loaded.
+
+\cssection{bibglsexternalprefixlabel}
+
+\formatdef{bibglsexternalprefixlabel}
+A hook to pick up the \meta{n}th external prefix label (identified with
+\csopt{ext-prefixes}) if required. This does nothing by default and
+won't be used if the list of external prefixes is empty. If required,
+this command should be defined before the \idx{resourceset} is
+loaded.
+
+\cssection{bibglshashchar}
+
+\formatdef{bibglshashchar}
+Expands to a literal hash character (\,\idx{hashchar}\,).
+
+\cssection{bibglsunderscorechar}
+
+\formatdef{bibglsunderscorechar}
+Expands to a literal underscore character (\,\idx{underscorechar}\,).
+
+\cssection{bibglsdollarchar}
+
+\formatdef{bibglsdollarchar}
+Expands to a literal dollar character (\,\idx{dollarchar}\,).
+
+\cssection{bibglsampersandchar}
+
+\formatdef{bibglsampersandchar}
+Expands to a literal ampersand character (\,\idx{ampchar}\,).
+
+\cssection{bibglscircumchar}
+
+\formatdef{bibglscircumchar}
+Expands to a literal circumflex character (\,\idx{circumchar}\,).
+
+\cssection{bibglsuppercase}
+
+\formatdef{bibglsuppercase}
+Converts \meta{text} to \idx{uppercase}. This just uses
+\ics{MakeTextUppercase} by default.
+
+\cssection{bibglslowercase}
+
+\formatdef{bibglslowercase}
+Converts \meta{text} to \idx{lowercase}. This just uses
+\ics{MakeTextLowercase} by default.
+
+\cssection{bibglstitlecase}
+
+\formatdef{bibglstitlecase}
+Converts \meta{text} to \idx{titlecase}. This just uses
+\ics{capitalisewords} by default.
+
+\cssection{bibglsfirstuc}
+
+\formatdef{bibglsfirstuc}
+Converts the first letter of \meta{text} to \idx{uppercase}. This just uses
+\ics{makefirstuc} by default.
+
+\chapter{Converting Existing \iext{tex} to \iext{bib}}
+\label{sec:gls2bib}
+\setsecdepth{0}
+
+If you have already been using the \styfmt{glossaries} or
+\styfmt{glossaries-extra} package with a large file containing all your
+definitions using commands like \gls{newglossaryentry}, then you can
+use the supplementary tool \idx{convertgls2bib} to convert the definitions
+to the \ext{bib} format required by \bibgls. The syntax is:
+\begin{alltt}
+convertgls2bib \oargm{options} \meta{tex file} \meta{bib file}
+\end{alltt}
+where \meta{tex file} is the \ext{tex} file and \meta{bib file} is
+the \ext{bib} file. This application is less secure than \bibgls\ as
+it doesn't use \idx{kpsewhich} to check \texmfcnf{openinany} and
+\texmfcnf{openoutany}. Take care not to accidentally overwrite
+existing \ext{bib} files as there's no check to determine if
+\meta{bib file} already exists.
+
+The \meta{options} are:
+\begin{description}
+\item[\longargfmt{texenc} \meta{encoding}] The character encoding of the
+\ext{tex} file. If omitted, the operating system's default encoding
+is assumed (or the \idx{JVM}['s]).
+
+\item[\longargfmt{bibenc} \meta{encoding}] The character encoding of the
+\ext{bib} file. If omitted, the same encoding as the
+\ext{tex} file is assumed.
+
+\item[\longargfmt{space-sub} \meta{replacement}] The \ext{bib}
+format doesn't allow spaces in labels. If your original
+definitions in your \ext{tex} file have spaces, use this option to
+replace spaces in labels. Each space will be substituted with
+\meta{replacement}. The cross-referencing fields, \field{see},
+\field{seealso} and \field{alias}, will also be adjusted, but any
+references using \ics{gls} etc will have to be substituted manually
+(or use a global search and replace in your text editor).
+If you want to strip the spaces, use an empty string for
+\meta{replacement}. You'll need to delimit this according to your
+operating system. For example:
+\begin{verbatim}
+convertgls2bib --space-sub '' entries.tex entries.bib
+\end{verbatim}
+
+\item[\longargfmt{ignore-sort}] Ignore the \field{sort} field.
+This is the default since \bibgls\ can work out a more intuitive
+sort value than either \idx!{makeindex} or \idx!{xindy}.
+
+\item[\longargfmt{no-ignore-sort}] Don't ignore the \field{sort} field.
+
+\item[\longargfmt{locale} \meta{lang tag}] Identifies the \langxml\
+to use for \idx{convertgls2bib}['s] messages.
+
+\item[\longargfmt{silent}] Suppress all messages except for errors.
+
+\item[\longargfmt{verbose}] Display messages and warnings (default).
+
+\item[\longargfmt{debug}] Display debugging messages (stack
+traces and other information in addition to \longargfmt{verbose}).
+
+\item[\longargfmt{help} or \shortargfmt{h}] Display help message and
+quit.
+\item[\longargfmt{version} or \shortargfmt{v}] Display version
+information and quit.
+\end{description}
+
+This application recognises the commands listed below. Avoid any overly
+complicated code within the \ext{tex} file. The
+\hyperref[sec:texparserlib]{\TeX\ parser library} isn't a \TeX\ engine! The
+\ext{tex} file doesn't need to be a complete document, but if you want certain
+commands recognised from packages that the \TeX\ parser library supports,
+you'll need to include \ics{usepackage} in the \ext{tex} file.
+In all cases below, if \meta{\keyvallist} contains:
+\begin{codeenv*}
+\field{see}=\marg{[\ics{seealsoname}]\meta{label(s)}}
+\end{codeenv*}
+this will be substituted with:
+\begin{codeenv*}
+\field{seealso}=\margm{label(s)}
+\end{codeenv*}
+For example:
+\begin{codeenv}
+\gls{newterm}\oarg{\field{see}=\marg{[\cs{seealsoname}]goose}}\marg{duck}
+\end{codeenv}
+will be written as:
+\begin{codeenv}
+\atentry{index}\marg{duck,
+ \field{seealso} = \marg{goose}
+}
+\end{codeenv}
+
+Additionally, if \meta{\keyvallist} contains:
+\begin{codeenv}
+\field{type}=\marg{\ics{glsdefaulttype}}
+\end{codeenv}
+then this field will be ignored. (This \field{type} value is
+recommended in \meta{\keyvallist} when loading files with
+\ics{loadglsentries}\oargm{type}\margm{file} to allow the optional
+argument to set the \field{type}. With \bibgls\ you can use the
+\csopt{type} option instead.)
+
+\cssection[\section]{glsexpandfields}
+The base \styfmt{glossaries} package provides:
+\formatdef{glsexpandfields}
+If present, this instructs \idx{convertgls2bib} to expand all fields
+except for those explicitly identified by \gls{glssetnoexpandfield}.
+Remember that there are many commands that aren't recognised by
+\idx{convertgls2bib} so it may not be possible to correctly expand
+field values. Conversely, there are some commands that will be
+expanded by \idx{convertgls2bib} that aren't expandable in \TeX\
+(such as \ics{MakeUppercase} and \ics{char}).
+
+\cssection[\section]{glsnoexpandfields}
+The base \styfmt{glossaries} package provides:
+\formatdef{glsnoexpandfields}
+If present, this instructs \idx{convertgls2bib} to not expand fields
+unless explicitly identified by \gls{glssetexpandfield}.
+
+\cssection[\section]{glssetexpandfield}
+The base \styfmt{glossaries} package provides:
+\formatdef{glssetexpandfield}
+If present, this instructs \idx{convertgls2bib} to expand the
+given field, even if \gls{glsnoexpandfields} has been used.
+
+\cssection[\section]{glssetnoexpandfield}
+The base \styfmt{glossaries} package provides:
+\formatdef{glssetnoexpandfield}
+If present, this instructs \idx{convertgls2bib} to not expand the
+given field, even if \gls{glsexpandfields} has been used.
+Unlike the default behaviour with the \sty{glossaries} package, there are no
+fields switched explicitly switched off by default with
+\idx{convertgls2bib}.
+
+\cssection[\section]{newglossaryentry}
+The base \styfmt{glossaries} package provides:
+\formatdef{newglossaryentry}
+This is converted to:
+\begin{codeenv}
+\atentry{entry}\marg{\meta{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+\ics{newentry} is recognised as a synonym of \gls{newglossaryentry}.
+
+\cssection[\section]{provideglossaryentry}
+The base \styfmt{glossaries} package provides:
+\formatdef{provideglossaryentry}
+This is converted to:
+\begin{codeenv}
+\atentry{entry}\marg{\meta{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+but only if \meta{label} hasn't already been defined.
+
+\cssection[\section]{longnewglossaryentry}
+The base \styfmt{glossaries} package provides:
+\formatdef{longnewglossaryentry}
+This is converted to:
+\begin{codeenv}
+\atentry{entry}\marg{\meta{label},
+ \meta{\keyvallist},
+ \field{description} = \margm{description}
+}
+\end{codeenv}
+The starred version provided by the \styfmt{glossaries-extra} package
+is also recognised. The unstarred version strips trailing spaces
+from \meta{description}. (This doesn't add \ics{nopostdesc}, but
+\styfmt{glossaries-extra} defaults to \styopt{nopostdot}.)
+
+\cssection[\section]{longprovideglossaryentry}
+
+The base \styfmt{glossaries} package provides:
+\formatdef{longprovideglossaryentry}
+As above, but only if \meta{label} hasn't already been defined.
+
+\cssection[\section]{newterm}
+
+The base \styfmt{glossaries} package provides:
+\formatdef{newterm}
+(when the \styopt{index} option is used).
+This is converted to:
+\begin{codeenv}
+\atentry{index}\marg{\meta{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+if the optional argument is present, otherwise it's just converted
+to:
+\begin{codeenv}
+\atentry{index}\marg{\meta{label}}
+\end{codeenv}
+
+If \longargfmt{space-sub} is used and \meta{label} contains one or
+more spaces, then \field{name} will be set if not included in
+\meta{\keyvallist}. For example, if \filefmt{entries.bib}
+contains:
+\begin{codeenv}
+\gls{newterm}\marg{sea lion}
+\gls{newterm}\oarg{\field{seealso}=\marg{sea lion}}\marg{seal}
+\end{codeenv}
+then:
+\begin{verbatim}
+convertgls2bib --space-sub '-' entries.bib entries.tex
+\end{verbatim}
+will write the terms to \filefmt{entries.tex} as:
+\begin{codeenv}
+\atentry{index}\marg{sea-lion,
+ \field{name} = \marg{sea lion}
+}
+\strut
+\atentry{index}\marg{seal,
+ \field{seealso} = \marg{sea-lion}
+}
+\end{codeenv}
+whereas just:
+\begin{verbatim}
+convertgls2bib entries.bib entries.tex
+\end{verbatim}
+will write the terms to \filefmt{entries.tex} as:
+\begin{codeenv}
+\atentry{index}\marg{sea lion}
+\strut
+\atentry{index}\marg{seal,
+ \field{seealso} = \marg{sea lion}
+}
+\end{codeenv}
+which will cause a problem when the \ext{bib} file is parsed
+by \bibgls\ (and will probably also cause a problem for
+bibliographic management systems).
+
+\cssection[\section]{newabbreviation}
+The \styfmt{glossaries-extra} package provides:
+\formatdef{newabbreviation}
+This is converted to:
+\begin{codeenv}
+\atentry{abbreviation}\marg{\meta{label},
+ \field{short} = \margm{short},
+ \field{long} = \margm{long},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+if the optional argument is present, otherwise it's converted to:
+\begin{codeenv}
+\atentry{abbreviation}\marg{\meta{label},
+ \field{short} = \margm{short},
+ \field{long} = \margm{long}
+}
+\end{codeenv}
+
+\cssection[\section]{newacronym}
+The base \styfmt{glossaries} package provides:
+\formatdef{newacronym}
+(which is redefined by \styfmt{glossaries-extra} to use
+\gls{newabbreviation}).
+
+As above but uses \atentry{acronym} instead.
+
+\cssection[\section]{glsxtrnewsymbol}
+The \styfmt{glossaries-extra} package provides:
+\formatdef{glsxtrnewsymbol}
+(when the \styopt{symbols} option is used).
+This is converted to:
+\begin{codeenv}
+\atentry{symbol}\marg{\meta{label},
+ \field{name} = \margm{symbol}
+}
+\end{codeenv}
+if the optional argument is missing, otherwise it's converted to:
+\begin{codeenv}
+\atentry{symbol}\marg{\meta{label},
+ \field{name} = \margm{symbol},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+unless \meta{\keyvallist} contains the \field{name} field,
+in which case it's converted to:
+\begin{codeenv}
+\atentry{symbol}\marg{\meta{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+\ics{newsym} is recognised as a synonym for \gls{glsxtrnewsymbol}.
+
+\cssection[\section]{glsxtrnewnumber}
+
+The \styfmt{glossaries-extra} package provides:
+\formatdef{glsxtrnewnumber}
+(when the \styopt{numbers} option is used).
+This is converted to:
+\begin{codeenv}
+\atentry{number}\marg{\meta{label},
+ \field{name} = \margm{label}
+}
+\end{codeenv}
+if the optional argument is missing, otherwise it's converted to:
+\begin{codeenv}
+\atentry{number}\marg{\meta{label},
+ \field{name} = \margm{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+if \field{name} isn't listed in \meta{\keyvallist},
+otherwise it's converted to:
+\begin{codeenv}
+\atentry{number}\marg{\meta{label},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+\ics{newnum} is recognised as a synonym for \gls{glsxtrnewnumber}.
+
+\cssection[\section]{newdualentry}
+
+\formatdef{newdualentry}
+This command isn't provided by either \styfmt{glossaries} or
+\styfmt{glossaries-extra} but is used as an example in the
+\sty{glossaries} user manual~\cite{glossaries} and in the sample file
+\file{sample-dual.tex} that accompanies the \sty{glossaries}
+package. Since this command seems to be used quite a bit (given the
+number of times it crops up on sites like
+\href{https://tex.stackexchange.com/}{\TeX\ on StackExchange}),
+\idx{convertgls2bib} also supports it unless this command is
+defined using \ics{newcommand} or \ics{renewcommand} in the
+input file. In which case the default definition will be overridden.
+
+If the command definition isn't overridden, then it's converted to:
+\begin{codeenv}
+\atentry{dualabbreviationentry}\marg{\meta{label},
+ \field{short} = \margm{short},
+ \field{long} = \margm{long},
+ \field{description} = \margm{description},
+ \meta{\keyvallist}
+}
+\end{codeenv}
+if \meta{\keyvallist} is supplied, otherwise it's converted to:
+\begin{codeenv}
+\atentry{dualabbreviationentry}\marg{\meta{label},
+ \field{short} = \margm{short},
+ \field{long} = \margm{long},
+ \field{description} = \margm{description}
+}
+\end{codeenv}
+
+For example, if the original \ext{tex} file contains:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{newdualentry}}[5][]\marg{\comment{}
+ \gls{newglossaryentry}\marg{main-\idx{param}2}\marg{\field{name}=\marg{\idx{param}4},\comment{}
+ \field{text}=\marg{\idx{param}3\cs{glsadd}\marg{\idx{param}2}},\comment{}
+ \field{description}=\marg{\idx{param}5},\comment{}
+ \idx{param}1
+ }\comment{}
+ \gls{newacronym}\marg{\idx{param}2}\marg{\idx{param}3\cs{glsadd}\marg{main-\idx{param}2}}\marg{\idx{param}4}\comment{}
+}
+\strut
+\gls{newdualentry}\marg{svm}\comment{label}
+ \marg{SVM}\comment{abbreviation}
+ \marg{support vector machine}\comment{long form}
+ \marg{Statistical pattern recognition technique}\comment{description}
+\end{codeenv}
+then the \ext{bib} file will contain:
+\begin{codeenv}
+\atentry{entry}\marg{main-svm,
+ \field{name} = \marg{support vector machine},
+ \field{description} = \marg{Statistical pattern recognition technique},
+ \field{text} = \marg{SVM\cs{glsadd}\marg{svm}}
+}
+\strut
+\atentry{acronym}\marg{svm,
+ \field{short} = \marg{SVM\cs{glsadd}\marg{main-svm}},
+ \field{long} = \marg{support vector machine}
+}
+\end{codeenv}
+since \gls{newdualentry} was defined with \ics{newcommand}. However,
+if the original file uses \ics{providecommand} or omits the
+definition of \gls{newdualentry}, then the \ext{bib} file will
+contain:
+\begin{codeenv}
+\atentry{dualabbreviationentry}\marg{svm,
+ \field{short} = \marg{SVM},
+ \field{description} = \marg{Statistical pattern recognition technique},
+ \field{long} = \marg{support vector machine}
+}
+\end{codeenv}
+
+\chapter{Examples}
+\label{sec:examples}
+\setsecdepth*{0}
+
+The example files described here can be found in the
+\filefmt{examples} sub-directory. The \ext{bib} files are listed
+first and then sample files that use the \ext{bib} data.
+Make sure you have the latest versions of \styfmt{glossaries},
+\styfmt{mfirstuc}, \styfmt{glossaries-extra} and \bibgls\ if you
+want to try these out. (The \exfile{sample-media.tex} file requires
+at least \styfmt{datatool} v2.28.) If you get any undefined control
+sequence or undefined style errors then you need to update your
+\TeX\ distribution. Use the \longarg{group} switch when invoking
+\bibgls\ for all these examples if you want the glossaries divided
+into groups. The set of system calls for the document build in the
+examples below may require an extra \LaTeX\ run to ensure the PDF
+bookmarks are up-to-date when \sty{hyperref} is used.
+
+These files are just examples of how to use \bibgls. There are other
+ways of defining similar entries and sometimes alternatives are
+suggested. Use the code here as a starting point if you need data
+like this and adapt it to a format appropriate for your
+requirements.
+
+\filesection{no-interpret-preamble.bib}
+
+The \exfile{no-interpret-preamble.bib} file contains command
+definitions used in some of the \field{name} fields. Although these
+commands aren't used explicitly in the document, they need to be
+defined when the names are displayed in the document (typically in
+the glossary). These commands are much like the \gls{sortop} command
+described on \glsxtrpageref{sortop} and need to be hidden
+from \bibgls's interpreter. This file doesn't contain any entry
+definitions and must be loaded first with
+\csopt[false]{interpret-preamble}. The
+\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib}
+file can then be loaded to provide alternative definitions for
+\bibgls's interpreter.
+
+The first command is:
+\nosecdef{sortname}
+This is used in the \field{name} fields for entries containing
+information about a person. The aim here is for \bibgls\ to sort
+according to \meta{surname}, \meta{first name(s)} but for the
+glossary to display \meta{first name(s)} \meta{surname}. For names
+with a \qt{von} part, there's another command:
+\nosecdef{sortvonname}
+which has a similar purpose.
+The third command is:
+\nosecdef{sortart}
+This is the same as \gls{sortname} but is designed for titles,
+phrases or sentences that start with an article (such as \qt{a} or
+\qt{the}). Although it has the same definition as \gls{sortname}
+in this file, in the interpreted files the article part is omitted
+to completely ignore them in the sorting.
+The fourth command is:
+\nosecdef{sortmediacreator}
+which again is functionally the same as \gls{sortname}.
+
+The names could be specified using \BibTeX's
+syntax instead with \csopt{bibtex-contributor-fields} to convert it,
+but the aim here is to show a variety of ways to use \bibgls. For an
+example of \csopt{bibtex-contributor-fields}, see the way the
+\fieldfmt{cast} field in \exfile{films.bib} is dealt with.
+
+Although the file only contains ASCII characters, it starts with
+an encoding line to prevent \bibgls\ from searching the entire file
+for it. (That's not so much of an issue with a short file, but may
+cause an unnecessary delay for much longer files.)
+
+The contents of \filefmt{no-interpret-preamble.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/no-interpret-preamble.bib}
+
+\filesection{interpret-preamble.bib}
+
+This provides definitions of \gls{sortname}, \gls{sortvonname},
+\gls{sortart} and \gls{sortmediacreator} in \atentry{preamble}
+that can be picked up by the interpreter and used during sorting.
+Note that in this case \gls{sortart} is defined to ignore the
+article to completely ignore it from sorting. If you happen to have
+\qt{a \meta{something}} and \qt{the \meta{something}} where the
+\meta{something}s are identical, you may want to append the article
+to disambiguate them.
+
+The contents of \filefmt{interpret-preamble.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/interpret-preamble.bib}
+
+\filesection{interpret-preamble2.bib}
+
+An alternative to \exfile{interpret-preamble.bib} with a different
+definition of \gls{sortmediacreator}. This uses \cs{renewcommand}
+instead of \cs{providecommand} so \csopt[false]{write-preamble}
+is required to prevent \LaTeX\ from picking up the definitions.
+
+The contents of \filefmt{interpret-preamble2.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/interpret-preamble2.bib}
+
+\filesection{constants.bib}
+
+The \exfile{constants.bib} file contains mathematical constants.
+These all use a custom entry type \atentryfmt{constant}, which must
+be aliased otherwise the entries will all be ignored. The entries
+all have custom fields, which also need to be aliased.
+For example:
+\begin{codeenv}
+\csopt[constant=entry]{entry-type-aliases},
+\csopt[
+ \fieldfmt{constantname}=\field{name},
+ \fieldfmt{constantsymbol}=\field{symbol},
+ \fieldfmt{definition}=\field{description},
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{value}=\field{user1}
+]{field-aliases}
+\end{codeenv}
+This setting means that, for example,
+\begin{codeenv}
+\atentryfmt{constant}\marg{root2,
+ \fieldfmt{constantname}=\marg{Pythagoras' constant},
+ \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\ics{surd}2}},
+ \fieldfmt{definition}=\marg{the square root of 2},
+ \fieldfmt{value}=\marg{1.41421},
+ \fieldfmt{identifier}=\marg{constant}
+}
+\end{codeenv}
+is treated as though it was defined as:
+\begin{codeenv}
+\atentry{entry}\marg{root2,
+ \field{name}=\marg{Pythagoras' constant},
+ \field{symbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}},
+ \field{description}=\marg{the square root of 2},
+ \field{user1}=\marg{1.41421},
+ \field{category}=\marg{constant}
+}
+\end{codeenv}
+This use of custom fields and entry types allows more flexibility.
+For example, I may have another document that uses the same
+\ext{bib} file but requires a different definition:
+\begin{codeenv}
+\atentry{number}\marg{root2,
+ \field{description}=\marg{Pythagoras' constant},
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{surd}2}}
+}
+\end{codeenv}
+which can be obtained with:
+\begin{codeenv}
+\csopt[constant=number]{entry-type-aliases},
+\csopt[
+ \fieldfmt{constantname}=\field{description},
+ \fieldfmt{constantsymbol}=\field{name}
+]{field-aliases}
+\end{codeenv}
+Since the other custom fields haven't be aliased, they're ignored.
+
+The custom fields are: \fieldfmt{identifier} (set to \code{constant}
+for all the entries), \fieldfmt{constantname} (the constant's name),
+\fieldfmt{definition} (a definition of the constant),
+\fieldfmt{value} (the approximate numeric value of the constant),
+\fieldfmt{constantsymbol} (the symbolic representation of the
+constant) and \fieldfmt{alternative} (alternative symbol).
+There are three entries that don't have the custom
+\fieldfmt{value} field: \code{zero} and \code{one} (the exact value
+is in the \fieldfmt{constantsymbol} field in both cases) and \code{imaginary}
+(where there's no real number value).
+
+I've provided some commands in the \atentry{preamble} for
+constants that are represented by Latin and Greek letters.
+These can be defined in the document before the \idx{resourceset}
+if different notation is required. The upright Greek commands require
+the \isty{upgreek} package.
+
+If it's likely that there may be a need to sort according to
+\fieldfmt{definition}, then it would be better to use \gls!{sortart}
+describe above:
+\begin{codeenv}
+\atentryfmt{constant}\marg{root2,
+ \fieldfmt{constantname}=\marg{Pythagoras' constant},
+ \fieldfmt{constantsymbol}=\marg{\cs{ensuremath}\marg{\cs{surd}2}},
+ \fieldfmt{definition}=\marg{\gls{sortart}\marg{the}\marg{square root of 2}},
+ \fieldfmt{value}=\marg{1.41421},
+ \fieldfmt{identifier}=\marg{constant}
+}
+\end{codeenv}
+Remember that this would need \exfile{no-interpret-preamble.bib} to
+ensure the command is recognised in the document.
+
+The contents of \filefmt{constants.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/constants.bib}
+
+\filesection{chemicalformula.bib}
+
+The \exfile{chemicalformula.bib} file contains chemical formulae.
+Each entry has a field that uses \ics{ce} provided by \sty{mhchem}
+so the document will need to load that package. Since all resource
+files must be loaded in the preamble, it's possible to ensure that
+the package is loaded using:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{usepackage}\marg{mhchem}}}
+\end{codeenv}
+However, it's best just to load it in the document otherwise it
+won't be available before the \ext{glstex} file has been loaded.
+Also, \sty{glossaries} (and therefore \sty{glossaries-extra}) must be
+loaded after \sty{hyperref}, which usually needs to be loaded last
+so most packages should be loaded before \sty{glossaries-extra}.
+Instead, I've just put a comment in the \ext{bib} file as a
+reminder.
+
+All entries are defined using a custom entry type
+\atentryfmt{chemical}. This must be aliased using
+\csopt{entry-type-aliases} or the entries will be ignored. For
+example, to make \atentryfmt{chemical} behave like \atentry{symbol}:
+\begin{codeenv}
+\csopt[\fieldfmt{chemical}=\field{symbol}]{entry-type-aliases}
+\end{codeenv}
+Remember that with the \atentry{symbol} type, if the \field{sort}
+field is omitted \bibgls\ will fallback on the label by default. It
+can be changed to fallback on the \field{name} field instead using
+\csopt[name]{symbol-sort-fallback}. This will require the use of
+the interpreter if the name contains a command but \bibgls\
+recognises the \sty{mhchem} package and has a limited ability to
+interpret \cs{ce}. If \atentryfmt{chemical} is changed to
+\atentry{entry} instead then the fallback for the \field{sort} will be the
+entry's \field{name}.
+
+All entries only contain custom fields, which will all be ignored by
+\bibgls\ unless defined or aliased: \fieldfmt{identifier}, which is set to
+\code{chemical} for all entries, \fieldfmt{formula}, which is set to the
+chemical formula, and \fieldfmt{chemicalname}, which is set to the chemical
+name. This allows the flexibility of determining whether the
+\field{name} or \field{symbol} field should contain the chemical
+formula on a per-resource basis. For example:
+\begin{codeenv}
+\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases}
+\end{codeenv}
+or
+\begin{codeenv}
+\csopt[\fieldfmt{chemicalname}=\field{name},\fieldfmt{formula}=\field{symbol}]{field-aliases}
+\end{codeenv}
+
+The contents of \filefmt{chemicalformula.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/chemicalformula.bib}
+
+\filesection{bacteria.bib}
+
+The \exfile{bacteria.bib} file contains bacteria abbreviations.
+These all use the \atentry{abbreviation} entry type with a
+\field{short} and \field{long} field.
+
+The entries all have a custom field \fieldfmt{identifier} set to
+\code{bacteria}. This will be ignored by \bibgls\ unless it's
+defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
+aliased with \csopt{field-aliases}.
+
+The contents of \filefmt{bacteria.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/bacteria.bib}
+
+\filesection{baseunits.bib}
+
+The \exfile{baseunits.bib} file contains base \idxpl{SIunit}. The entries
+are all defined using the custom \atentryfmt{unit} entry
+type. This must be aliased with \csopt{entry-type-aliases} otherwise
+\bibgls\ will ignore all the entries. For example:
+\begin{codeenv}
+\csopt[\fieldfmt{unit}=\field{symbol}]{entry-type-aliases}
+\end{codeenv}
+will make \bibgls\ treat the entries as though they were defined
+using \atentry{symbol}. (Remember that \atentry{symbol} entry types use the label
+as the fallback field for \field{sort}.)
+
+The entries all have custom fields \fieldfmt{unitname},
+\fieldfmt{unitsymbol} and \fieldfmt{measurement}, one of which must
+be aliased or copied to \field{name} if \atentryfmt{unit} is aliased
+to an entry type that requires it. The other custom fields may be aliased or
+copied to \field{symbol} and \field{description} as required. The
+\fieldfmt{unitsymbol} fields all use \ics{si} provided by the
+\isty{siunitx} package, so that package must be loaded in the
+document. This is one of the small number of packages recognised by
+\bibgls, so it's possible to sort according to the symbol if
+required.
+
+The entries also all have a custom field \fieldfmt{identifier} set to
+\code{baseunit}. This will be ignored by \bibgls\ unless it's
+defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
+aliased with \csopt{field-aliases}.
+
+The contents of \filefmt{baseunits.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/baseunits.bib}
+
+\filesection{derivedunits.bib}
+
+The \exfile{derivedunits.bib} file is much like \exfile{baseunits.bib}
+but contains derived units and in this case the custom entry type
+is \atentryfmt{measurement}, which must be aliased
+otherwise the entries will all be ignored.
+The entries all have a custom field \fieldfmt{identifier} set to
+\code{derivedunit}. This will be ignored by \bibgls\ unless it's
+defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if it's
+aliased with \csopt{field-aliases}.
+
+The contents of \filefmt{derivedunits.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/derivedunits.bib}
+
+\filesection{people.bib}
+
+The \exfile{people.bib} file contains details about people.
+The \field{name} fields contain custom commands provided in
+\exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib}.
+Remember that if \exfile{no-interpret-preamble.bib} is
+loaded first, the definitions provided in that file will be the one
+in use in the document. The \exfile{interpret-preamble.bib} file
+then needs to be loaded to provide the definitions for \bibgls's
+interpreter.
+
+The information for each person is supplied in an \atentry{entry}
+type. There are some non-standard fields: \fieldfmt{born},
+\fieldfmt{died} and \fieldfmt{othername}. These fields will be ignored
+unless keys are provided (using \cs{glsaddkey} or
+\cs{glsaddstoragekey}) or the fields are aliased (using
+\csopt{field-aliases}). The \fieldfmt{born} and \fieldfmt{died}
+fields have dates that are \emph{almost} in the default \code{en-GB}
+locale format with the \idx{JRE} \idx{localeprovider}, but they include a
+tilde \idx{nbspchar} to prevent awkward line breaks. By default \bibgls's
+interpreter converts \idx{nbspchar} to the non-breaking space character
+\hex{A0} which isn't recognised by the date format. This can easily
+be fixed with the \longarg{break-space} switch which will interpret
+\idx{nbspchar} as a normal breakable space (\hex{20}), so with that switch
+\csopt[date]{sort} or \csopt[date-reverse]{sort} can be used on
+either of those fields. However, the \idx{CLDR} has a slightly
+different default format than the \idx{JRE} for dates with
+\code{en-GB}, so it's probably simplest to actually specify the
+required format.
+
+An alternative approach would be to provide a command that can be
+modified in the document to adjust the date style. For example, the
+\fieldfmt{born} field could be specified as:
+\begin{codeenv}
+\fieldfmt{born}=\marg{\cmd{formatdate}\marg{13}\marg{7}\marg{100}\marg{BC}}
+\end{codeenv}
+The definition provided for the document could then be, for example:
+\begin{codeenv}
+\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\ics{DTMdisplaydate}\marg{\idx{param}3}\marg{\idx{param}2}\marg{\idx{param}1}\marg{-1} \idx{param}4}
+\end{codeenv}
+(where \ics{DTMdisplaydate} is provided by the \isty{datetime2}
+package) and a definition could be provided for \bibgls's
+interpreter, for example:
+\begin{codeenv}
+\cs{providecommand}\marg{\cmd{formatdate}}[4]\marg{\idx{param}1/\idx{param}2/\idx{param}3 \idx{param}4}
+\end{codeenv}
+This would need the date format set. For example,
+\csopt[d/M/y G]{date-sort-format}.
+
+Some of the entries, such as \code{caesar}, have a \field{first}
+field. In those cases the \field{first} field is slightly different
+from the \field{name} field (for example, \qt{Gaius} is omitted in
+\code{caesar}'s \field{first} field). The other entries don't have a
+\field{first} field. They can simply have the \field{name} copied to
+\field{first} with the \csopt{replicate-fields} option (so that the
+full name is shown on first use) or the \field{first} field can be
+ignored with \csopt{ignore-fields} (so all entries will use the
+\field{text} field on first use). The \csopt{replicate-override}
+option can be used to force the \field{name} field to be copied to
+the \field{first} field, even if the \field{first} field is already
+set. Alternatively, with \csopt[true]{replicate-override} and
+\csopt[\field{first}=\field{name}]{replicate-fields}, the \field{first} field be
+copied to the \field{name} field. For consistency, the \field{first}
+fields use the same custom commands as used in the \field{name}
+field.
+
+There's one name with a \qt{von} part. In this case the \field{name}
+field is set to:
+\begin{codeenv}
+\gls{sortvonname}\marg{Manfred}\marg{von}\marg{Richthofen}
+\end{codeenv}
+which will come under the \qt{V} letter group since \gls{sortvonname}
+is defined as \meta{von} \meta{surname}, \meta{first name(s)}
+
+If you prefer that this name should come under \qt{R} instead, then
+you need to adjust the definition of \gls{sortvonname}:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{sortname}}[2]\marg{\idx{param}2, \idx{param}1}
+\cs{providecommand}\marg{\cmd{sortvonname}}[3]\marg{\idx{param}3, \idx{param}1 \idx{param}2}}}
+\end{codeenv}
+An alternative approach would be to format the names using
+\BibTeX's contributor syntax and use
+\csopt[name]{bibtex-contributor-fields} to convert them.
+
+There are also some synonyms provided with \atentry{index} entry
+types that have the \field{alias} field to redirect to the main
+entry. These don't include a \field{description} or any of the other
+fields as that would be redundant. All the information can be found
+in the main entry.
+
+Except for the aliases, the entries have a custom field
+\fieldfmt{identifier} set to \code{person}. This will be ignored by
+\bibgls\ unless it's defined using \cs{glsaddkey} or
+\cs{glsaddstoragekey} or if it's aliased with \csopt{field-aliases}.
+
+The contents of \filefmt{people.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/people.bib}
+
+\filesection{books.bib}
+
+The \exfile{books.bib} file contains details about books.
+As above, the entries use custom commands provided in
+\exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib} or
+\exfile{interpret-preamble2.bib}.
+The entries all have a custom field \fieldfmt{identifier} set to
+\code{book} and other custom fields \fieldfmt{author} and
+\fieldfmt{year}.
+These will be ignored by \bibgls\ unless they're
+defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're
+aliased with \csopt{field-aliases}.
+
+There are other ways in which this data could be specified. For
+example, the \field{description} field could contain a brief summary
+(or \qt{log line}). The \fieldfmt{author} field could use \BibTeX's
+syntax instead with \csopt{bibtex-contributor-fields} to convert it.
+Alternatively, the entries could be defined using standard \BibTeX\
+entry types that are all aliased to \atentry{bibtexentry}.
+
+The contents of \filefmt{books.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/books.bib}
+
+\filesection{films.bib}
+
+The \exfile{films.bib} file contains details about films.
+As above, the entries use custom commands provided in
+\exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib}.
+The entries all have a custom field \fieldfmt{identifier} set to
+\code{film} and other custom fields \fieldfmt{cast}, \fieldfmt{director} and
+\fieldfmt{year}. These will be ignored by \bibgls\ unless they're
+defined using \cs{glsaddkey} or \cs{glsaddstoragekey} or if they're
+aliased with \csopt{field-aliases}.
+
+This example file references entries defined in \exfile{books.bib}
+through the use of the special
+\glsdisp{idx.idprefix.extn}{\idprefixfmt{ext1}} prefix.
+To avoid a label conflict \exfile{films.bib} prefixes all labels
+with \idprefixfmt{film} rather than relying on \csopt{label-prefix}.
+This ensures that both \exfile{books.bib} and \exfile{films.bib}
+can be loaded in the same resource set (otherwise they'd have to be
+loaded in separate resource sets with different prefixes). Remember
+that you can use \gls{glsxtrnewgls}. For example:
+\begin{codeenv}
+\gls{glsxtrnewgls}\marg{film.}\marg{\cmd{film}}
+\end{codeenv}
+This means you can do, for example, just \verb|\film{bladerunner}|
+if you want to reference a film without worrying about the prefix.
+
+As with all the example files, there are other ways in which
+to specify the data, depending on your requirements. For example,
+the \fieldfmt{director} field could use \BibTeX's contributor syntax
+(as the \fieldfmt{cast} field does). Some of
+the films actually had more than one director but only one is listed
+per film in this sample file for simplicity. Similarly, the
+\fieldfmt{cast} field only contains the principle actors rather than the
+complete list. The book on which the film is based
+could be contained in a cross-reference field or a custom
+\fieldfmt{basedon} field.
+
+The book \qt{Do Androids Dream of Electric Sheep?}\ referenced at the end
+of the \qt{Blade Runner} film's \field{description} ends with
+a question mark. (Similarly for \qt{Why Didn't They Ask Evans?})
+If the \field{description} field is simply set as:
+\begin{codeenv}
+\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
+ and Sean Young loosely based on the novel
+ \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}},
+\end{codeenv}
+then the \styopt{postdot} package option will produce an odd
+result as the inserted \idx{full-stop} immediately follows the question
+mark. This is an awkward situation. One possibility is to explicitly
+put the \idx{full-stop} at the end of the \field{description} field for all the
+other entries and omit it for the problematic entries, but this
+interferes with the possibility of a category-dependent
+\idx{postdescriptionhook}.
+
+Another option is to put \ics{nopostdesc} in the
+problematic entries. For example:
+\begin{codeenv}
+\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
+ and Sean Young loosely based on the novel
+ \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{nopostdesc}},
+\end{codeenv}
+Be careful with this as it will completely suppress the
+\idx{postdescriptionhook}.
+A third possibility is to use \ics{glsxtrnopostpunc} instead:
+\begin{codeenv}
+\field{description}=\marg{a film starring Harrison Ford, Rutger Hauer
+ and Sean Young loosely based on the novel
+ \cs{gls}\marg{ext1.doandroidsdreamofelectricsheep}\cs{glsxtrnopostpunc}},
+\end{codeenv}
+This doesn't interfere with the \idx{postdescriptionhook} but if a hook
+is provided the post-punctuation may then be required. In both of
+the above two cases, \csopt{strip-trailing-nopost} could be used
+to remove the suppression commands from the \field{description}
+fields if a hook is defined. However this doesn't deal with hooks
+that only conditionally append text.
+
+The best solution is with \styfmt{glossaries-extra} v1.23+ which
+provides \ics{glsxtrrestorepostpunc} for use in the category
+\idxpl{postdescriptionhook} that counteracts \cs{glsxtrnopostpunc}.
+This can be placed inside a conditional, as used in
+\exfile{sample-media.tex}, and does nothing if \cs{glsxtrnopostpunc}
+doesn't occur in the \field{description} field. (Note that
+\cs{glsxtrrestorepostpunc} can't be used to counteract
+\cs{nopostdesc}, since that completely suppresses the hook.)
+
+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}
+\csopt[\ics{GlsXtrBibTeXEntryAliases}]{entry-type-aliases}
+\end{codeenv}
+The field names will also need to be defined or aliased. For
+example:
+\begin{codeenv}
+\csopt[\fieldfmt{title}=\field{name}]{field-aliases}
+\end{codeenv}
+If \bibgls\ is then run with \longarg{cite-as-record} any
+\ics{citation} commands found in the \ext{aux} file will be treated
+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
+maths mode. These are all defined with \atentry{symbol}, which means
+that by default the \field{sort} field will be obtained from the
+label not from the \field{name} field. However, if you want to sort
+by the \field{name} field (for example, with \csopt[name]{sort-field})
+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 \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}).
+
+The \ext{bib} file could just use \code{o}:
+\begin{codeenv}
+\atentry{symbol}\marg{omicron,
+ \field{name}=\marg{\cs{ensuremath}\marg{o}},
+ \field{description}=\marg{omicron},
+ \fieldfmt{identifier}=\marg{mathgreek}
+}
+\end{codeenv}
+but this means that if \bibgls\ sorts according to the \field{name}
+field using a letter sort, this entry will come before all the other
+Greek letters since the character \qt{o} has Unicode value \hex{6F}
+whereas, for example, mathematical italic small alpha ($\alpha$)
+has Unicode value \hex{1D6FC}. This means that for sorting purposes
+it's better to use \ics{omicron}:
+\begin{codeenv}
+\atentry{symbol}\marg{omicron,
+ \field{name}=\marg{\cs{ensuremath}\marg{\cs{omicron}}},
+ \field{description}=\marg{omicron},
+ \fieldfmt{identifier}=\marg{mathgreek}
+}
+\end{codeenv}
+but \LaTeX\ needs a definition for this, so it's provided in the
+\atentry{preamble}:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cs{omicron}}\marg{o}}}
+\end{codeenv}
+(With \sty{glossaries-extra} v1.27+, this is no longer needed.)
+The \TeX\ parser library and \sty{glossaries-extra-bib2gls}
+similarly provide the missing \idx!{uppercase}
+Greek letters, and these can be dealt with in the same way.
+
+The contents of \filefmt{mathgreek.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/mathgreek.bib}
+
+\filesection{bigmathsymbols.bib}
+
+The \exfile{bigmathsymbols.bib} file contains mathematical symbols
+that have a large version in display mode. As with
+\exfile{mathgreek.bib} the entries are defined using
+\atentry{symbol}. This example file requires the \isty{stix} package
+as not all of the commands are provided by the \LaTeX\ kernel.
+This file also has a preamble:
+\begin{codeenv}
+\atentry{preamble}\marg{\qtdelim{\cmd{providecommand}\marg{\cmd{bigoperatornamefmt}}[1]\marg{\comment{}
+ \idx{mshiftchar}\ics{displaystyle}\idx{param}1\ics{textstyle}\idx{param}1\idx{mshiftchar}}
+\cmd{providecommand}\marg{\cmd{nary}}[1]\marg{\idx{mshiftchar}\idx{param}1\idx{mshiftchar}-ary}}}
+\end{codeenv}
+The first command \inlinedef{bigoperatornamefmt}
+is used in the \field{name} field to display both the in-line and display
+versions of the symbol. The \TeX\ parser library only has a limited ability to
+interpret this as not all the symbols have Unicode in-line and large versions.
+In some cases, such as the integral symbol $\int$, there is only a small
+version. (A large version would require construction from \hex{2320},
+\hex{23AE} and \hex{2321}, which is too complicated in this context.)
+However, the interpreter works well enough to guess at the widest
+name if \csopt{set-widest} is used. There's no advantage in sorting
+according to the \field{name} field here, unless a custom rule is
+provided, as the Unicode symbols are scattered about different
+blocks. Better approaches are to sort according to document use
+(\csopt[use]{sort}) or to sort according to the \field{description}
+field.
+
+The other custom command is \inlinedef{nary} to provide semantic markup for
+\qt{$n$-ary}. This could be defined without an argument:
+\begin{codeenv}
+\cmd{providecommand}\marg{\cmd{nary}}\marg{\idx{mshiftchar}n\idx{mshiftchar}-ary}
+\end{codeenv}
+but providing an argument will allow \code{\csfmt{nary}\marg{n}} to work
+with first letter upper-casing in the event that the
+\field{description} field has a case-change applied (otherwise
+it would end up as \qt{$N$-ARY}). Of course, it may be that no case-change
+should be applied, but this example is just for illustrative purposes.
+
+As with the other sample \ext{bib} files, each entry is given a
+custom \fieldfmt{identifier} field, which by default will be
+ignored. In this case, \fieldfmt{identifier} is either set to
+\code{naryoperator} (for $n$-ary operators) or \code{integral}
+for integrals.
+
+The contents of \filefmt{bigmathsymbols.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/bigmathsymbols.bib}
+
+\filesection{mathsrelations.bib}
+
+The \exfile{mathsrelations.bib} file contains mathematical
+relational symbols. These use the maths shift character
+\idx{mshiftchar} in the \field{name} field and just the symbol in
+the \field{text} field. This just illustrates an alternative way of
+defining symbols. Since \ics{ensuremath} isn't used, commands like
+\cs{gls} must be explicitly placed in maths mode. For example,
+\code{\idx{mshiftchar}\cs{gls}\marg{leq}\idx{mshiftchar}} rather than simply
+\code{\cs{gls}\marg{leq}}. The custom \fieldfmt{identifier} field is
+set to \code{relation}.
+
+The contents of \filefmt{mathsrelations.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/mathsrelations.bib}
+
+\filesection{binaryoperators.bib}
+
+The \exfile{binaryoperators.bib} file contains mathematical binary
+operators. The format is much like the above
+\exfile{mathsrelations.bib} file. The custom \fieldfmt{identifier}
+field is set to \code{binaryoperator}.
+
+The contents of \filefmt{binaryoperators.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/binaryoperators.bib}
+
+\filesection{unaryoperators.bib}
+
+The \exfile{unaryoperators.bib} file contains mathematical unary
+operators. As above, this again uses \atentry{symbol} to define the symbols,
+but in this case \ics{ensuremath} is used in the \field{name}
+field and there's no \field{text} field. I've also used \ics{mathord}
+to ensure the symbol is treated as a unary (rather than binary)
+operator, except for the \ics{forall} entry which is already defined as an
+ordinary maths symbol.
+
+The contents of \filefmt{unaryoperators.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/unaryoperators.bib}
+
+\filesection{mathsobjects.bib}
+
+The \exfile{mathsobjects.bib} file contains entries related to
+mathematical objects (sets, spaces, vectors and matrices). This
+provides some custom formatting commands in the preamble:
+\nosecdef{setfmt}
+which is used to format \meta{symbol} as a set,
+\nosecdef{setcontentsfmt}
+which is used to format the set contents,
+\nosecdef{setmembershipfmt}
+which is used to format the set membership criteria,
+\nosecdef{setcardfmt}
+which is used to format the cardinality of a set,
+(Note this uses \ics{vert} not \textbar\ as in some of the earlier
+examples.)
+\nosecdef{numspacefmt}
+which is used to format \meta{symbol} as a number space,
+\nosecdef{transposefmt}
+which is used to format matrix and vector transposes,
+\nosecdef{invfmt}
+which is used to format inverses,
+\nosecdef{vecfmt}
+which is used to format \meta{symbol} as a vector, and
+\nosecdef{mtxfmt}
+which is used to format \meta{symbol} as a matrix.
+These commands are intended for use with \gls{glsxtrfmt},
+but \gls!{setmembershipfmt} causes a problem as it has two
+arguments and \gls{glsxtrfmt} requires the control sequence to
+have exactly one argument. This means employing a little trick.
+A command with just one argument is provided:
+\nosecdef{setmembershiponeargfmt}
+that requires the actual two arguments to be supplied inside
+\code{\idx!{param}1}. The outer grouping is removed and the two-argument
+\gls!{setmembershipfmt} command is applied:
+\begin{codeenv}
+\cs{providecommand}\marg{\gls{setmembershiponeargfmt}}[1]\marg{\gls{setmembershipfmt}\idx{param}1}
+\end{codeenv}
+This means that the entry needs to be referenced in the document
+using:
+\begin{codeenv}
+\gls{glsxtrfmt}\marg{setmembership}\marg{\margm{variable(s)}\margm{condition}}
+\end{codeenv}
+The simplest thing to do here is to provide a wrapper command in the
+document, for example:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{setmembership}}[2]\marg{\gls{glsxtrfmt}\marg{setmembership}\marg{\marg{\idx{param}1}\marg{\idx{param}2}}}
+\end{codeenv}
+Now this can be used as:
+\begin{codeenv}
+\cmd{setmembership}\margm{variable(s)}\margm{condition}
+\end{codeenv}
+
+There are essentially two types of entry defined in this file:
+entries that demonstrate the formatting for the objects
+and entries that represent specific objects. In the first case
+there's a custom \fieldfmt{format} field
+that's set to the control sequence name of the relevant semantic
+command. If this field is defined or aliased then it can be used
+with \gls!{glsxtrfmt} (as in the example above).
+
+In both cases there's a custom \fieldfmt{identifier} field that
+reflects the type of object: \code{set} for sets,
+\code{numberspace} for number spaces,
+\code{matrix} for matrices or vectors.
+
+Be careful with the set cardinality example. Remember that nested
+links cause problems and the \sty{glossaries-extra} manual advises
+against using commands like \cs{gls} or \gls!{glsxtrfmt} within
+link text and that includes within the \meta{text} argument of
+\gls!{glsxtrfmt}. See \exfile{sample-maths.tex} for suggested
+usage.
+
+Some of the \field{description} fields use \gls!{sortart}, so
+\exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib} are also needed.
+
+The contents of \filefmt{mathsobjects.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/mathsobjects.bib}
+
+\filesection{miscsymbols.bib}
+
+The \exfile{miscsymbols.bib} file contains text symbols provided
+by the \isty{marvosym} and \isty{ifsym} packages. The \sty{ifsym}
+package needs to be loaded with the \styoptfmt{weather} option
+to provide the weather commands. Unfortunately both packages define
+\csfmt{Sun} and \csfmt{Lightning}, which causes a conflict. See
+\exfile{sample-textsymbols.tex} for a workaround. Alternatively,
+you can load \sty{ifsym} without the \styoptfmt{weather} option
+and use the internal definition of \sty{ifsym}'s \csfmt{Sun}
+and \csfmt{Lightning} commands:
+\begin{codeenv}
+\atentryfmt{icon}\marg{sun,
+ \fieldfmt{icon}=\marg{\ics{textweathersymbol}\marg{16}},
+ \fieldfmt{description}=\marg{sunny},
+ \fieldfmt{identifier}=\marg{weather}
+}
+\strut
+\atentryfmt{icon}\marg{lightning,
+ \fieldfmt{icon}=\marg{\cs{textweathersymbol}\marg{26}},
+ \field{description}=\marg{thunderstorm},
+ \fieldfmt{identifier}=\marg{weather}
+}
+\end{codeenv}
+This removes the conflict, and \csfmt{Sun} and \csfmt{Lightning}
+are as defined by \sty{marvosym}.
+
+This file uses a custom entry type \atentryfmt{icon}, which must be
+aliased to a recognised entry identifier otherwise the entries will
+all be ignored. For example:
+\begin{codeenv}
+\csopt[\fieldfmt{icon}=\field{symbol}]{entry-type-aliases}
+\end{codeenv}
+
+There are three types of symbols defined: media controls, information
+and weather. They have the custom \fieldfmt{identifier}
+field set to \code{mediacontrol}, \code{information} and
+\code{weather}, respectively. There are two other custom fields:
+\fieldfmt{icon} and \fieldfmt{icondescription}. These will need to
+be aliased to \field{name} and \field{description}.
+
+Neither of these packages are recognised by \bibgls, which means
+that \csopt{set-widest} won't be able to determine the widest name
+nor is this data suitable for sorting according to the
+\fieldfmt{icon} field (or its alias). Instead, either sort by label
+(which is the default for \atentry{symbol}) or by the
+\field{description}. If you want to use one of the
+\glostyle{alttree} styles you can still use \csopt{set-widest}, but
+it will have to use the fallback command. Alternatively, you can
+omit \csopt{set-widest} and explicitly use
+\cs{glsFindWidestTopLevelName}.
+
+The contents of \filefmt{miscsymbols.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/miscsymbols.bib}
+
+\filesection{markuplanguages.bib}
+
+The \exfile{markuplanguages.bib} file includes a mixture of
+\atentry{entry} and \atentry{abbreviation} definitions. A~custom
+command is provided in \atentry{preamble} to tag the letters
+in the \field{long} field that are used to form the abbreviation.
+This simply does its argument and is provided in case it's not set
+up in the document. If you do want to enable tagging using
+\ics{GlsXtrEnableInitialTagging}, remember that this command must be
+used before the abbreviations are defined, which means before
+the resource file is input with \gls{GlsXtrLoadResources}.
+Similarly, the abbreviation style must be set before the
+abbreviations are defined.
+
+For convenience \atentry{string} is also used to define a \ext{bib}
+variable, which may be appended to fields using the \ext{bib}
+concatenation character \idx{stringconcat}. As with the other sample
+\ext{bib} files, there's a custom field \fieldfmt{identifier}
+which will be ignored unless defined or aliased.
+
+The empty braces at the start some of the fields are there to
+protect against first letter uppercasing within \TeX, where it might cause a
+problem. (For example, with the \catattr{glossname} attribute.)
+
+The contents of \filefmt{markuplanguages.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/markuplanguages.bib}
+
+\filesection{usergroups.bib}
+
+The \exfile{usergroups.bib} file requires either \XeLaTeX\ or
+\LuaLaTeX\ as some of the entry labels use \idx{non-ASCII} characters.
+This file has a mixture of \atentry{abbreviation} and
+\atentry{index} entries. It also uses \atentry{string} for
+convenience and provides a custom command \csfmt{dash} in
+\atentry{preamble}. Each entry is the name of a \TeX\ user group:
+the international \idx{TUG} and all the local groups.
+Most of them have an abbreviated name, so they're defined with
+\atentry{abbreviation}. There are a few without an abbreviation, so
+they're defined with \atentry{index} instead. There's one alias.
+(The information was obtained from \idx{TUG}['s]
+\href{http://tug.org/usergroups.html}{user groups
+page}~\cite{tugusergroups}.)
+
+As with the other examples, there are some custom fields which will
+be ignored if they aren't defined or aliased: \fieldfmt{identifier}
+(set to \code{texusergroup}), \fieldfmt{language} (a comma-separated
+list of language tags) and \fieldfmt{translation} (provides a
+translation if the user group name isn't in English).
+
+Not all entries have a \fieldfmt{translation} field. It it's
+omitted, then the user group name is in English, otherwise it's
+in the first language listed in the \fieldfmt{language} field.
+Most of the language tags are just the ISO 639-1 language code, but
+a few of them include the ISO 3166-1 region code as well.
+
+The contents of \filefmt{usergroups.bib} are as follows:
+\begin{lstlisting}[escapechar=|]
+% Encoding: UTF-8
+
+% Requires XeLaTeX/LuaLaTeX for non-ASCII labels
+
+@string{tug={\TeX\ Users Group}}
+
+@preamble{"\providecommand{\dash}{\,---\,}"}
+
+@abbreviation{TUG,
+ short={TUG},
+ long=tug,
+ language={en},
+ identifier={texusergroup}
+}
+
+@abbreviation{bgTeX,
+ short={bgTeX},
+ long={Bulgarian \LaTeX\ Users Group},
+ language={bg},
+ identifier={texusergroup}
+}
+
+@abbreviation{latex-br,
+ short={latex-br},
+ long={Grupo de Usuários},
+ language={pt-BR},
+ identifier={texusergroup},
+ translation={Brazilian }#tug
+}
+
+@abbreviation{CTeX,
+ short={CTeX},
+ long={Chinese \TeX\ Society},
+ identifier={texusergroup},
+ language={zh}
+}
+
+@abbreviation{CSTUG,
+ short={CSTUG},
+ long={|Československé sdružení uživatelů TeXu|, z.~s.},
+ language={cs},
+ identifier={texusergroup},
+ translation={Czech Republic }#tug
+}
+
+@abbreviation{DANTE,
+ short={DANTE e.V.},
+ long={Deutschsprachige Anwendervereinigung \TeX\ e.V.},
+ language={de},
+ identifier={texusergroup},
+ translation={German Speaking }#tug
+}
+
+@abbreviation{DKTUG,
+ short={DK-TUG},
+ long={Danish }#tug,
+ language={da},
+ identifier={texusergroup}
+}
+
+@index{EUG,
+ name={Estonian User Group},
+ language={et},
+ identifier={texusergroup}
+}
+
+@abbreviation{CervanTeX,
+ short={CervanTeX},
+ long={Grupo de Usuarios de \TeX\ Hispanohablantes},
+ language={es},
+ identifier={texusergroup},
+ translation={Spanish Speaking }#tug
+}
+
+@abbreviation{TirantloTeX,
+ short={Tirant lo \TeX},
+ long={Catalan }#tug,
+ language={ca},
+ identifier={texusergroup}
+}
+
+@abbreviation{GUTenberg,
+ short={GUTenberg},
+ long={Groupe francophone des utilisateurs de \TeX},
+ language={fr},
+ identifier={texusergroup},
+ translation={French Speaking }#tug
+}
+
+@abbreviation{UKTUG,
+ short={UK-TUG},
+ long={UK }#tug,
+ language={en-GB},
+ identifier={texusergroup}
+}
+
+@abbreviation{|\greekmono ɛϕτ|,
+ short={|\greekmono ɛϕτ|},
+ long={|\greekmono Σύλλογος Ελλήνων Φίλων του| \TeX},
+ language={el},
+ identifier={texusergroup},
+ translation={Greek \TeX\ Friends}
+}
+
+@abbreviation{MaTeX,
+ short={MaTeX},
+ long={Magyar \TeX\ Egyesület},
+ language={hu},
+ identifier={texusergroup},
+ translation={Hungarian }#tug
+}
+
+@abbreviation{ITALIC,
+ short={ITALIC},
+ long={Irish \TeX\ and \LaTeX\ In-print Community},
+ language={en-IE,en-GB},
+ identifier={texusergroup}
+}
+
+@abbreviation{ÍsTeX,
+ short={ÍsTeX},
+ long={Vefur íslenskra \TeX\ notenda},
+ language={is},
+ identifier={texusergroup},
+ translation={Icelandic }#tug
+}
+
+@abbreviation{GuIT,
+ short={GuIT},
+ long={Gruppo Utilizzatori Italiani di \TeX},
+ language={it},
+ identifier={texusergroup},
+ translation={Italian }#tug
+}
+
+@abbreviation{KTS,
+ short={KTS},
+ identifier={texusergroup},
+ long={Korean \TeX\ Society},
+ language={ko}
+}
+
+@index{KTUG,
+ alias={KTS},
+ identifier={texusergroup}
+}
+
+@index{LTVG,
+ name={Lietuvos \TeX'o |Vartotojų Grupė|},
+ language={lt},
+ identifier={texusergroup},
+ translation={Lithuanian }#tug
+}
+
+@index{mxTeX,
+ name={\TeX\ México},
+ language={es-MX},
+ identifier={texusergroup},
+ translation={Mexican }#tug
+}
+
+@abbreviation{NTG,
+ short={NTG},
+ long={Nederlandstalige \TeX\ Gebruikersgroep},
+ language={nl},
+ identifier={texusergroup},
+ translation={Netherlands }#tug
+}
+
+@index{NTUG,
+ name={Nordic \TeX\ Users Group},
+ language={da,et,fi,fo,is,nb,nn,sv},
+ identifier={texusergroup}
+}
+
+@abbreviation{GUST,
+ short={GUST},
+ long={Polska Grupa |Użytkowników| Systemu \TeX},
+ language={pl},
+ identifier={texusergroup},
+ translation={Polish }#tug
+}
+
+@abbreviation{GUTpt,
+ short={GUTpt},
+ long={Grupo de Utilizadores de \TeX},
+ language={pt},
+ identifier={texusergroup},
+ translation={Portuguese }#tug
+}
+
+@abbreviation{VietTUG,
+ short={VietTUG},
+ long={Vietnamese }#tug,
+ language={vi},
+ identifier={texusergroup}
+}
+
+@abbreviation{LUGSA,
+ short={LUGSA},
+ long={\LaTeX\ User Group\dash South Africa},
+ language={en-ZA},
+ identifier={texusergroup}
+}
+
+
+\end{lstlisting}
+
+\filesection{animals.bib}
+
+The \exfile{animals.bib} file contains entries defined using
+\atentry{entry}. As with the above example \ext{bib} files, there's
+a custom \fieldfmt{identifier} field that will be ignored unless
+defined or aliased.
+
+The contents of \filefmt{animals.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/animals.bib}
+
+\filesection{minerals.bib}
+
+The \exfile{minerals.bib} file contains entries defined using
+\atentry{entry}. As with the above example \ext{bib} files, there's
+a custom \fieldfmt{identifier} field that will be ignored unless
+defined or aliased.
+
+The contents of \filefmt{minerals.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/minerals.bib}
+
+\filesection{vegetables.bib}
+
+The \exfile{vegetables.bib} file contains entries defined using
+\atentry{entry} and an entry defined with \atentry{index} with just
+the \field{alias} field. As with the above example \ext{bib} files, there's
+a custom \fieldfmt{identifier} field that will be ignored unless
+defined or aliased.
+
+The contents of \filefmt{vegetables.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/vegetables.bib}
+
+\filesection{terms.bib}
+
+The \exfile{terms.bib} file contains entries defined using
+\atentry{index}. Unlike the above sample \ext{bib} files, there
+are no custom fields here.
+
+The contents of \filefmt{terms.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/terms.bib}
+
+\filesection{topics.bib}
+
+The \exfile{topics.bib} file contains entries defined using
+\atentry{index}. Again there are no custom fields here.
+
+The contents of \filefmt{topics.bib} are as follows:
+\lstinputlisting[firstline=5]{../examples/topics.bib}
+
+\filesection{sample-constants.tex}
+
+This example uses the \exfile{constants.bib} file. The aim here
+is to just have a list of all the constants defined in the \ext{bib}
+file. (There are no references in the document.) This means I need
+to use:
+\begin{codeenv}
+\csopt[all]{selection}
+\end{codeenv}
+in order to select all entries. I also need to alias the custom
+\atentryfmt{constant} entry type otherwise all the entries will be
+ignored. I decided to make \atentryfmt{constant} behave like
+\atentry{number} for semantic reasons:
+\begin{codeenv}
+\csopt[constant=number]{entry-type-aliases}
+\end{codeenv}
+The custom fields also need aliasing:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{constantsymbol}=\field{name},
+ \fieldfmt{constantname}=\field{description},
+ \fieldfmt{value}=\field{user1},
+ \fieldfmt{definition}=\field{user2},
+ \fieldfmt{alternative}=\field{user3},
+]{field-aliases}
+\end{codeenv}
+I decided to use the \glostyle{altlist} style, so I've instructed
+\bibgls\ to determine the widest name:
+\begin{codeenv}
+\csopt{set-widest}
+\end{codeenv}
+It's always a good idea to specify the glossary type when using
+\csopt{set-widest}, although in this example there's only one
+glossary so it doesn't make much difference.
+\begin{codeenv}
+\csopt[main]{type}
+\end{codeenv}
+I decided to order the constants according to their (approximate)
+numerical value. I've aliased the custom \fieldfmt{value} field to
+\field{user1}, so I can sort by that field using a numerical
+comparison:
+\begin{codeenv}
+\csopt[\field{user1}]{sort-field},
+\csopt[double]{sort}
+\end{codeenv}
+There are three entries without the \fieldfmt{user1} field (as the
+custom \fieldfmt{value} field is missing in the \ext{bib} file):
+\code{zero}, \code{one} and \code{imaginary}. In the case of
+\code{zero} and \code{one} the exact value can be obtained from the
+\field{name} field. Since I've change the default \csopt{sort-field}, I
+can't use \csopt{symbol-sort-fallback}. Instead I need to use:
+\begin{codeenv}
+\csopt[\field{name}]{missing-sort-fallback}
+\end{codeenv}
+
+What happens with the \code{imaginary} entry? It has no real
+representation. The transcript (\ext{glg}) file shows the message:
+\begin{verbatim}
+Warning: Can't parse sort value 'i' for: imaginary
+\end{verbatim}
+With the numerical sort methods, if the field can't be parsed the
+value defaults to 0. This means that both \code{zero} and
+\code{imaginary} have 0 as the sort value, so the
+\csopt{identical-sort-action} is implemented. The default setting
+means that \bibgls\ will fallback on comparing the entry labels, so
+\code{imaginary} comes before \code{zero}.
+
+Since I'm just using the \glostyle{alttree} style, I only need
+\sty{glossary-tree}. I can improve efficiency in the document build
+by preventing the other glossary style packages from being loaded
+using the \styopt{nostyles} package option. This also prevents
+\sty{glossary-tree} from being loaded, but I can both load it and
+patch the styles with \sty{glossaries-extra-stylemods} through the
+option \styopt[tree]{stylemods}. Since the default \glostyle{list}
+style is no longer available, I need to set a new default with
+\styopt[alttree]{style}. I also want to automatically insert a
+\idx{full-stop} after the description, which can be done with
+\styopt{postdot}. Don't forget that the \styopt{record} option is
+always needed when using \bibgls. This means that the
+\sty{glossaries-extra} package needs to be loaded as follows:
+\begin{codeenv}
+\cs{usepackage}\oarg{\styopt{record},\styopt{nostyles},\styopt{postdot},\styopt[tree]{stylemods},\styopt[alttree]{style}}
+ \marg{glossaries-extra}
+\end{codeenv}
+I've assigned the custom \fieldfmt{constantname} field to the
+\field{description} field and the custom \fieldfmt{constantsymbol} field to the
+\field{name} field. This means that by default the glossary list
+will just show the symbolic representation and the constant's name.
+I'd like to append the value and definition after the description.
+With the base \sty{glossaries} package this would require defining a
+new glossary style but with \sty{glossaries-extra} it can easily be
+achieved through the \idx{postdescriptionhook}.
+
+I've aliased the custom \fieldfmt{identifier} field to
+\field{category}, which means that all the entries will have the
+\field{category} set to \code{constant}. The
+\idx{postdescriptionhook} is obtained from
+\idx{glsxtrpostdesccategory}, so I need to define
+the command \csfmt{glsxtrpostdescconstant}. A simple definition is:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{}
+ \cs{space} (approximately \cs{glsentryuseri}\marg{\cs{glscurrententrylabel}})\comment{}
+ : \cs{glsentryuserii}\marg{\cs{glscurrententrylabel}}\comment{}
+}
+\end{codeenv}
+This is fine if all entries have the \field{user1} and \field{user2}
+fields set. A more generic approach tests for the existence of these
+fields. This can either be done with \ics{ifglshasfield}:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{: \cs{glscurrentfieldvalue}}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+or with \ics{glsxtrifhasfield}:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{: \cs{glscurrentfieldvalue}}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+(Note the need to use the internal field label \field{useri} and
+\field{userii} with \ics{glsxtrifhasfield}.)
+
+A modification can be made to also show the alternative
+representation (obtained from the custom \fieldfmt{alternative}
+field which has been aliased to \field{user3}):
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{useriii}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (also denoted \cs{glscurrentfieldvalue}
+ \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{, approximately \cs{glscurrentfieldvalue}}\comment{}
+ \marg{}\comment{}
+ )\comment{}
+ }\comment{}
+ \marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{useri}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{ (approximately \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{userii}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{: \cs{glscurrentfieldvalue}}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+If you have at least \styfmt{glossaries-extra} v1.31, it's better to use:
+\begin{codeenv}
+\ics{glsdefpostdesc}\marg{constant}
+\end{codeenv}
+instead of:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{glsxtrpostdescconstant}}
+\end{codeenv}
+as it can guard against accidental misspelling of the \code{glsxtrpostdesc}
+part of the command name.
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-constants
+bib2gls sample-constants
+pdflatex sample-constants
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-constants.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-constants.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-constants.pdf}}%
+}
+{\caption{\filefmt{sample-constants.pdf}}}
+{fig:sample-constants.pdf}
+\end{figure}
+
+\filesection{sample-chemical.tex}
+
+This example just uses the \exfile{chemicalformula.bib} file. The aim here
+is to have a list of chemical formulae referenced in the document
+but not have a number list. I could use the \styopt{nonumberlist}
+package option to suppress the number list display, but it's more
+efficient to instruct \bibgls\ to not save the number list with:
+\begin{codeenv}
+\csopt[false]{save-locations}
+\end{codeenv}
+All entries are defined in \exfile{chemicalformula.bib} using
+a custom entry type \atentryfmt{chemical} which needs to be aliased
+in order for the entries to be recognised:
+\begin{codeenv}
+\csopt[chemical=symbol]{entry-type-aliases}
+\end{codeenv}
+Additionally, the entries only have custom fields, so these also
+need to be aliased. In this case I want the formula in the \field{name} field
+and the chemical name in the \field{description} field:
+\begin{codeenv}
+\csopt[\fieldfmt{formula}=\field{name},\fieldfmt{chemicalname}=\field{description}]{field-aliases}
+\end{codeenv}
+The \atentry{symbol} entry type falls back on the label for the
+\field{sort} value by default, but I've decided
+to fallback on the \field{name} field for sorting:
+\begin{codeenv}
+\csopt[\field{name}]{symbol-sort-fallback}
+\end{codeenv}
+An alternative approach would simply be to alias
+\atentryfmt{chemical} to \atentry{entry} instead.
+
+Since the \field{name} field contains chemical formulae rather than
+words, it makes more sense to use one of the letter sort methods
+rather than a locale collator. In this case the names contain
+mixtures of letters and numbers, so one of the letter-number sort
+methods (listed in \tableref{tab:sortoptionsletternumber}) would be
+appropriate.
+
+I want to use the \glostyle{alttreegroup} style (provided by
+\sty{glossary-tree}). Since I don't require the other style
+packages, I've used \styopt{nostyles} to suppress the automatic
+loading and \styopt[tree]{stylemods} to both load
+\sty{glossary-tree} and patch it. The \glostyle{alttreegroup} style
+needs to know the widest name, so I've use \csopt{set-widest} for
+convenience. The default behaviour of the tree styles is to
+format the name in bold. This is done through the command
+\ics{glstreenamefmt} which is defined as:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
+\end{codeenv}
+The group headings use \ics{glstreegroupheaderfmt} which defaults to
+\cs{glstreenamefmt}. Since I want to keep bold headings, I need to
+redefine this as well:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}
+\cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}
+\end{codeenv}
+(For a more compact layout, you could use \glostyle{mcolalttreegroup}
+instead.)
+I also need the \longarg{group} switch to make the sort method
+automatically assign letter groups.
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-chemical
+bib2gls --group sample-chemical
+pdflatex sample-chemical
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-chemical.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-chemical.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-chemical.pdf}}%
+}
+{\caption{\filefmt{sample-chemical.pdf}}}
+{fig:sample-chemical.pdf}
+\end{figure}
+
+\filesection{sample-bacteria.tex}
+
+This example just uses the \exfile{bacteria.bib} file. The aim here
+is to have a simple list of the bacteria referenced in the document.
+Bacteria names are often shown in the long form on first use
+(without the short form) and then the short form on subsequent use.
+This can easily be done with the \abbrstyle{long-only-short-only}
+style. Bacteria are usually typeset in italic. It's best to create a
+semantic command for this:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\end{codeenv}
+There are two methods to apply this to the bacteria entries. The
+first is to redefine the formatting commands used by the
+\abbrstyle{long-only-short-only} style:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\ics{glsabbrvonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}}
+\cs{renewcommand}*\marg{\ics{glslongonlyfont}}[1]\marg{\cmd{bacteriafont}\marg{\idx{param}1}}
+\end{codeenv}
+This is fine if I don't intend to use this style for other types of
+abbreviations. However, I may decide to extend the document at a
+later date to include other abbreviations that need
+\abbrstyle{long-only-short-only} but shouldn't be emphasized.
+This can be done through the use of \idxpl{categoryattribute}.
+The font used for the \field{name} in the glossary is governed by
+the \catattr{glossnamefont} attribute, the font used for the
+\field{description} in the glossary is governed by the
+\catattr{glossdescfont} attribute and the font used by commands like
+\cs{gls} in the document is governed by the \catattr{textformat}
+attribute (\styfmt{glossaries-extra} v1.21+). So if I set
+the \field{category} to \code{bacteria} then I can do:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
+\end{codeenv}
+and (if the \field{description} field is displayed in the glossary):
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
+\end{codeenv}
+(Note that the attribute value is the control sequence name without
+the initial backslash.)
+
+I'd like to use the \glostyle{bookindex} style, which is
+provided by the \sty{glossary-bookindex}
+package.\footnote{\styfmt{glossary-bookindex}
+is distributed with \styfmt{glossaries-extra} v1.21+.} This isn't loaded
+automatically, but it can be loaded through the
+\styopt{stylemods} package option:
+\begin{codeenv}
+\cmd{usepackage}[\styopt{record},\comment{use bib2gls}
+ \styopt{nostyles},\comment{don't load default style packages}
+ \styopt[bookindex]{stylemods},\comment{load glossary-bookindex.sty and patch styles}
+ \styopt[bookindex]{style}]\marg{glossaries-extra}
+\end{codeenv}
+I've used the \styopt{nostyles} package option to suppress loading
+the default style packages, since I'm not using them. If you inspect
+the \ext{log} file, you may notice that \sty{glossary-tree} is still
+loaded. This is because it's required by \sty{glossary-bookindex}
+as the \glostyle{bookindex} style is based on the \glostyle{index}
+style provided by \sty{glossary-tree}.
+With this style I need to use the \longarg{group} switch to instruct
+the sort method to automatically create the letter groups.
+
+The \glostyle{bookindex} style doesn't show the \field{description}
+field (which means I don't need the \catattr{glossdescfont}
+attribute) and, since the \abbrstyle{long-only-short-only} style sets
+the \field{name} to the short form by default, only the short form
+will show in the glossary. I'd rather it was just the long form.
+This could simply be done using \csopt{replicate-fields} to copy the
+\field{long} field to the \field{name} field:
+\begin{codeenv}
+\csopt[\field{long}=\field{name}]{replicate-fields}
+\end{codeenv}
+Again, I want to consider the possibility of adding other types of
+abbreviations and this might not be appropriate for them (for
+example, I might want some abbreviations with the long form followed
+by the short form in parentheses). Another
+approach is to redefine \ics{glsxtrbookindexname} which is used by
+the \glostyle{bookindex} style to display the name. This takes the
+entry's label as the argument. The default definition is:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\cs{glossentryname}\marg{\idx{param}1}}
+\end{codeenv}
+This can be changed to test for the entry's category:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \ics{glsifcategory}\marg{\idx{param}1}\marg{bacteria}
+ \marg{\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{long}}}\comment{}
+ \marg{\cs{glossentryname}\marg{\idx{param}1}}\comment{}
+}
+\end{codeenv}
+Note that I've used \ics{glossentrynameother} here rather than
+\ics{glsentrylong}. This ensures that it follows the same formatting
+as \ics{glossentryname} (so it will use \ics{glsnamefont} or the
+\catattr{glossnamefont} attribute, the \catattr{glossname}
+attribute, and the \idx{postnamehook}, if set). In this case it
+picks up the \catattr{glossnamefont} attribute, which is used
+instead of \cs{glsnamefont}.
+
+If the \field{sort} field is missing for abbreviation styles, the
+fallback value is the \field{short} field (not the \field{name}
+field). In this case it would be better to fallback on the
+\field{long} field instead, which can be done with the
+\csopt{abbreviation-sort-fallback} option:
+\begin{codeenv}
+\csopt[\field{long}]{abbreviation-sort-fallback}
+\end{codeenv}
+If I do add other types of abbreviations, they will all be sorted
+according to the \field{long} form, but at least this way I can have
+some \meta{long} (\meta{short}) names as well.
+
+The complete code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-bacteria
+bib2gls --group sample-bacteria
+pdflatex sample-bacteria
+\end{verbatim}
+This simple example only references entries on the first page so all
+entries just have~1 in the number list. The complete document is
+shown in \figureref{fig:sample-bacteria.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-bacteria.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-bacteria.pdf}}%
+}
+{\caption{\filefmt{sample-bacteria.pdf}}}
+{fig:sample-bacteria.pdf}
+\end{figure}
+
+\filesection{sample-units1.tex}
+
+This example uses the \exfile{baseunits.bib} and
+\exfile{derivedunits.bib} files. The aim here is to have a glossary
+in two blocks: base units and derived units. This can be achieved by
+first loading \exfile{baseunits.bib} with \csopt{group} set to the
+desired group title (\qt{Base Units} in this case) and then load
+\exfile{derivedunits.bib} with the \csopt{group} set to the desired
+title (\qt{Derived Units} in this case). Remember that the
+\field{group} field needs to be used as a label. If the group title
+contains any problematic characters or commands, then it's better to
+use labels:
+\begin{codeenv}
+\csopt[baseunits]{group}
+\end{codeenv}
+for the first \idx{resourceset} and
+\begin{codeenv}
+\csopt[derivedunits]{group}
+\end{codeenv}
+for the second, and then set the group titles:
+\begin{codeenv}
+\gls{glsxtrsetgrouptitle}\marg{baseunits}\marg{Base Units}
+\gls{glsxtrsetgrouptitle}\marg{derivedunits}\marg{Derived Units}
+\end{codeenv}
+I've used this method to make it easier to adapt to other languages
+that may need extended characters in the group titles.
+The \csopt{group} option requires the \longarg{group} switch to
+ensure that the \field{group} field is correctly assigned.
+
+The \exfile{baseunits.bib} file use a custom entry type
+\atentryfmt{unit}, which must be aliased otherwise \bibgls\
+will ignore the entries. I decided to use \atentry{symbol} for
+semantic reasons:
+\begin{codeenv}
+\csopt[unit=symbol]{entry-type-aliases}
+\end{codeenv}
+Similarly for the custom \atentryfmt{measurement} entry type in
+\exfile{derivedunits.bib}:
+\begin{codeenv}
+\csopt[measurement=symbol]{entry-type-aliases}
+\end{codeenv}
+Remember that \atentry{symbol} uses the label as the default sort fallback,
+so I've changed it to use \field{name} instead:
+\begin{codeenv}
+\csopt[\field{name}]{symbol-sort-fallback}
+\end{codeenv}
+An alternative approach would be to alias \atentryfmt{unit}
+and \atentryfmt{measurement} to \atentry{entry} instead.
+
+Since there's no \csopt{type} set, all entries end up in the main
+glossary, but since there are two resource commands the glossary
+ends up with sorted blocks.
+
+The document doesn't include any commands like \cs{gls}, so
+I've use \csopt[all]{selection} to select all entries in the \ext{bib}
+files. There won't be any number lists since there are no records.
+I need a glossary style that shows the \field{symbol} field so I've
+used \glostyle{mcolindexgroup}. Again I've suppressed the automatic
+loading of the default styles with \styopt{nostyles} and used
+\styopt[mcols]{stylemods} to load \sty{glossary-mcols} and patch the
+styles. Note that although I've used \styopt{nostyles}, the
+\sty{glossary-tree} style is loaded as it's required by
+\sty{glossary-mcols}.
+
+As with the previous example, the custom fields need to be aliased:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{unitname}=\field{name},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{description}
+]{field-aliases}
+\end{codeenv}
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-units1
+bib2gls --group sample-units1
+pdflatex sample-units1
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-units1.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-units1.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-units1.pdf}}%
+}
+{\caption{\filefmt{sample-units1.pdf}}}
+{fig:sample-units1.pdf}
+\end{figure}
+
+\filesection{sample-units2.tex}
+
+This example is provided for comparison with
+\exfile{sample-units1.tex}. Instead of having a single glossary with
+sorted blocks this example has two glossaries:
+\begin{codeenv}
+\ics{newglossary*}\marg{baseunits}\marg{Base Units}
+\cs{newglossary*}\marg{derivedunits}\marg{Derived Units}
+\end{codeenv}
+I've used the \styopt{section} package option to use \ics{section*} for the
+glossary titles. This overrides the default \ics{chapter*} which is
+used with book or report type of classes. I've also used the
+\styopt{nomain} option to suppress the creation of the main glossary
+as I want to define my own glossary types instead.
+
+As before the custom entry types need to be aliased:
+\begin{codeenv}
+\csopt[unit=symbol]{entry-type-aliases}
+\end{codeenv}
+for the first \idx{resourceset} and
+\begin{codeenv}
+\csopt[measurement=symbol]{entry-type-aliases}
+\end{codeenv}
+for the second. Similarly for the custom entry fields:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{unitname}=\field{name},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{description}
+]{field-aliases}
+\end{codeenv}
+The \longarg{group} switch is needed to ensure that the
+\field{group} field is automatically assigned by the sort method.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-units2
+bib2gls --group sample-units2
+pdflatex sample-units2
+\end{verbatim}
+The complete document is shown in \figureref{fig:sample-units2.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-units2.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-units2.pdf}}%
+}
+{\caption{\filefmt{sample-units2.pdf}}}
+{fig:sample-units2.pdf}
+\end{figure}
+
+\filesection{sample-units3.tex}
+
+This is another example that uses the \exfile{baseunits.bib} and
+\exfile{derivedunits.bib} files. As before the custom fields need to be aliased:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{unitname}=\field{name},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{description}
+]{field-aliases}
+\end{codeenv}
+This time I want two glossaries containing all the units (base and
+derived) where the first glossary is ordered by name and the second
+is ordered by symbol. This can be done with a single resource
+command that instructs \bibgls\ to make the custom \atentryfmt{unit}
+and \atentryfmt{measurement} entry types behave like
+\atentry{dualsymbol}:
+\begin{codeenv}
+\csopt[
+ unit=dualsymbol,
+ measurement=dualsymbol
+]{entry-type-aliases}
+\end{codeenv}
+This causes the \field{name} and \field{symbol} fields to be swapped in the
+dual list. Remember that the fallback for the \field{sort} field is the label
+for the symbol entry types so I need \csopt[\field{name}]{symbol-sort-fallback}
+to fallback on \field{name} field instead. (Alternative, I could just sort by
+the \field{name} field instead using \csopt[\field{name}]{sort-field}.)
+
+The primary entries can still be sorted according to the default
+locale collator, but the dual entries need a sort method that's
+better suited to symbols. Fortunately, \bibgls\ has some (very
+limited) support for \isty{siunitx} and is able to interpret
+the \ics{si} commands in the sample \ext{bib} files. Since
+\idxpl{SIunit} are a mix of letters and numbers I've used one of the
+letter-number methods listed in
+\tableref{tab:sortoptionsletternumber}.
+
+I've decided to define a custom style for the first glossary. Since
+it's based on the \glostyle{long3col-booktabs} style I need to
+load \sty{glossary-longbooktabs}, which can conveniently be done with
+the \styopt{stylemods} option. This uses \env{longtable} (provided
+by \sty{longtable}, which is automatically loaded) which means
+an extra \LaTeX\ call is required in the build process to ensure the
+column widths are correct. Again I'm using \styopt{nostyles} to
+suppress the automatic loading of the default styles, however
+\sty{glossary-tree} will be loaded as it's listed in the value of
+\styopt{stylemods} and \sty{glossary-long} will be loaded as it's
+required by \sty{glossary-longbooktabs}. I can't use my custom style
+in the \styopt{style} package option as it hasn't been defined at
+that point. The default \glostyle{list} style is now unavailable
+since \styopt{nostyles} has prevented it from being defined, so
+I've used \styopt[alttree]{style} to ensure there's a valid default
+style.
+
+Since my custom style is based on one of the long styles, I need to
+set the length register \ics{glsdescwidth} to adjust the width of
+the description column:
+\begin{codeenv}
+\cmd{setlength}\marg{\cs{glsdescwidth}}\marg{.4\cmd{hsize}}
+\end{codeenv}
+The \glostyle{long3col-booktabs} style sets up a three column
+\env{longtable} so I just need to adjust the table header (to rename
+the column headers) and the way each row is formatted:
+\begin{codeenv}
+\ics{newglossarystyle}\marg{units}\comment{style name}
+\marg{\comment{base it on \glostyle{long3col-booktabs}}
+ \ics{setglossarystyle}\marg{long3col-booktabs}\comment{}
+ \cs{renewcommand}*\marg{\ics{glossaryheader}}\marg{\comment{}
+ \ics{toprule}
+ \ics{bfseries} Name \idx{colsep}
+ \cs{bfseries} Measurement \idx{colsep}
+ \cs{bfseries} Symbol
+ \ics{tabularnewline}\ics{midrule}\ics{endhead}
+ \ics{bottomrule}\ics{endfoot}}\comment{}
+\comment{main entries:}
+ \cs{renewcommand}\marg{\ics{glossentry}}[2]\marg{\comment{}
+ \ics{glsentryitem}\marg{\idx{param}\idx{param}1}\ics{glstarget}\marg{\idx{param}\idx{param}1}\marg{\cs{glossentryname}\marg{\idx{param}\idx{param}1}} \idx{colsep}
+ \cs{glossentrydesc}\marg{\idx{param}\idx{param}1}\ics{glspostdescription} \idx{colsep}
+ \cs{glossentrysymbol}\marg{\idx{param}\idx{param}1}\cs{tabularnewline}
+ }\comment{}
+}
+\end{codeenv}
+There are no sub-entries in this document so I haven't bothered to
+redefine \ics{subglossentry}. (The tabular styles aren't appropriate
+for hierarchical glossaries.) This puts the symbol into the third
+column (rather than the location list, which is ignored).
+This style supports the letter group separator (although it doesn't
+title the groups), so if I want this I need to use the
+\longarg{group} switch.
+
+I also need to make sure I've defined a glossary for the dual
+entries:
+\begin{codeenv}
+\cs{newglossary*}\marg{units}\marg{Units of Measurement (by SI unit)}
+\end{codeenv}
+and specify the glossary types for the primary and dual entries:
+\begin{codeenv}
+\csopt[main]{type},
+\csopt[units]{dual-type}
+\end{codeenv}
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-units3
+bib2gls --group sample-units3
+pdflatex sample-units3
+pdflatex sample-units3
+\end{verbatim}
+The two pages of the document are shown in
+\figureref{fig:sample-units3.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-units3.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-units3.pdf}{2}}
+{\caption{\filefmt{sample-units3.pdf}}}
+{fig:sample-units3.pdf}
+\end{figure}
+
+\filesection{sample-media.tex}
+
+This example uses the sample files \exfile{books.bib},
+\exfile{films.bib}, \exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib}. The aim is to produce a combined
+list of books and films in a single glossary. The films are based on
+some of the books so some of the entries have the same name. The
+default setting for identical sort values is
+\csopt[id]{identical-sort-action}, which means that the ordering for
+the duplicate names is based on the entry labels. This can lead to
+the odd effect of sometimes having the film listed first
+(\code{film.thebigsleep} comes before \code{thebigsleep}) and
+sometimes having the book listed first (\code{brightonrock} comes
+before \code{film.brightonrock}).
+
+One possible solution would be to also assign prefixes for the book
+labels, but \csopt{label-prefix} is applied to all primary entries
+for the given resource set and can't be applied selectively, so this
+would require editing the \exfile{books.bib} file.
+
+A more consistent approach would be to fallback on the category.
+This means that the \field{category} field needs to be set. There
+are two simple ways to achieve this: use \csopt[same as base]{category}
+(which sets the \field{category} to \code{books} for entries in
+\exfile{books.bib} and to \code{films} for entries in
+\exfile{films.bib}) or alias the custom \fieldfmt{identifier} field to
+\field{category}. I've chosen the latter method and also provided
+aliases for the custom \fieldfmt{year} and \fieldfmt{cast} fields:
+\begin{codeenv}
+\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{year}=\field{user1},\fieldfmt{cast}=\field{user2}]{field-aliases},
+\csopt[\field{category}]{identical-sort-action}
+\end{codeenv}
+This ensures that books always come before films with the same
+title. An oddity is the film \qt{Whisky Galore!}\ which is one
+character different from the book \qt{Whisky Galore} but the default
+locale collator ignores punctuation so the two titles are considered
+identical by the collator (but not by \csopt[non-unique]{sort-suffix}).
+If a letter comparison was used instead, they would no longer be
+considered identical, but in this case the film would
+still be placed after the book since the film title is longer.
+
+Since I've set the \field{category} I can provide semantic
+formatting commands (as for \exfile{sample-bacteria.tex}):
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{newcommand}*\marg{\cmd{filmfont}}[1]\marg{\ics{textsf}\marg{\ics{em} \idx{param}1}}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
+\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont}
+\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont}
+\end{codeenv}
+I've given films a slightly different format to make them easier to
+distinguish from books of the same name.
+
+Both \exfile{books.bib} and \exfile{films.bib} had the custom
+\fieldfmt{year} field, indicating the year of first publication
+or release, which I've assigned to the \field{user1} field.
+I can define \idxpl{postnamehook} for each category
+to append the year in brackets after the name is displayed in the
+glossary:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postnamehook{book}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{space}(published \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\strut
+\cs{newcommand}*\marg{\postnamehook{film}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{space}(released \cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+As with the post-description hook, if you have at least
+\styfmt{glossaries-extra} v1.31, it's better to use:
+\begin{codeenv}
+\ics{glsdefpostname}\margm{category}
+\end{codeenv}
+instead of:
+\begin{codeenv}
+\cs{newcommand}\marg{\cs{glsxtrpostnamecategory}}
+\end{codeenv}
+as it can guard against accidental misspelling of the \code{glsxtrpostname}
+part of the command name.
+
+I've assigned the \fieldfmt{cast} field to the \field{user2} field,
+and since this field uses \BibTeX's contributor markup I need to
+convert this to a form that's easier to customize:
+\begin{codeenv}
+\csopt[\field{user2}]{bibtex-contributor-fields}
+\end{codeenv}
+I'm not sorting by this field and it would look better in the
+document to list the forenames before the surname so I've also done:
+\begin{codeenv}
+\csopt[forenames]{contributor-order}
+\end{codeenv}
+Since I have at least version 2.28 of \sty{datatool-base} installed,
+the list will be formatted using \ics{DTLformatlist}. If I want an
+Oxford comma, I need to redefine \ics{DTLlistformatoxford} in the document:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{DTLlistformatoxford}}\marg{,}
+\end{codeenv}
+If I want to change \qt{\&} to \qt{and} I also need to redefine
+\ics{DTLandname}:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{DTLandname}}\marg{and}
+\end{codeenv}
+If \ics{DTLformatlist} isn't defined (\sty{datatool-base} v2.27 or
+earlier), the cast list will look a little odd as it uses a comma
+separator between all elements of this list, including the final
+pair (so there's no final \& or \qt{and}).
+
+I've provided a \idx{postdescriptionhook}
+\ics{glsxtrpostdesccategory} to append the cast list:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postdeschook{film}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrrestorepostpunc} \comment{requires glossaries-extra v1.23+}
+ \cs{cs.space}featuring \cs{glscurrentfieldvalue}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+This uses \ics{glsxtrrestorepostpunc} to restore the
+post-description punctuation if it was suppressed with
+\ics{glsxtrnopostpunc}. This means that if I decide not to include
+the \field{user2} field then the post-description punctuation will
+be revert back to being suppressed for entries containing
+\cs{glsxtrnopostpunc} in the \field{description} field.
+
+I haven't referenced any of the entries in the main body of the
+document, so I've used \csopt[all]{selection} to select all entries.
+This means that there are no number lists on the first document
+build (\LaTeX+\bibgls+\LaTeX) but the next build would show locations for
+the books that have been referenced by the film entries. Since this
+looks a bit odd, I've added \csopt[false]{save-locations} to
+prevent \bibgls\ from saving the locations.
+
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-media
+bib2gls --group sample-media
+pdflatex sample-media
+\end{verbatim}
+The four pages of the document are shown in
+\figureref{fig:sample-media.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-media.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-media.pdf}{4}}
+{\caption{\filefmt{sample-media.pdf}}}
+{fig:sample-media.pdf}
+\end{figure}
+
+\filesection{sample-people.tex}
+
+This example uses the files \exfile{people.bib},
+ \exfile{no-interpret-preamble.bib} and \exfile{interpret-preamble.bib}. The
+aim here is to have a list of people ordered alphabetically by
+surname with a brief description, the same list ordered by date of
+birth and an index of all the people without their details but with
+a number list indicating where that person was mentioned in the
+document. The first two lists shouldn't include aliases but the
+index should. Not all the entries defined in \exfile{people.bib}
+are included in the document. Those that aren't either explicitly
+referenced or aliased are filtered by the \csopt{selection} criteria.
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
+
+Since this is just an example document all the \cs{gls} commands
+only occur on page~1, which means that each number list is just
+\qt{1}. A real document would have the references scattered about.
+The aliases haven't actually been referenced anywhere in the
+document.
+
+The \fieldfmt{born}, \fieldfmt{died} and \fieldfmt{othername} fields will be
+ignored by default since they don't correspond to recognised keys,
+so the keys either need to be defined or the fields need to be
+mapped to existing keys. In this case I've decided to map them to
+the \field{user1}, \field{user2} and \field{user3} fields using
+\csopt{field-aliases}:
+\begin{codeenv}
+\csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
+\end{codeenv}
+Although the aliases haven't been referenced in the document, I've
+taken into account the possibility that they might later be added.
+To prevent them from showing in the first two lists I've filtered
+them out. This is easy to do since the aliases are all defined using
+\atentry{index} whereas the remaining (non-aliased) entries are
+defined using \atentry{entry} so \csopt{match} can be used to only
+select entries defined with \atentry{entry}:
+\begin{codeenv}
+\csopt[entrytype=entry]{match}
+\end{codeenv}
+
+I'd like the first use of \ics{gls} to display the full name, except
+for the entry that has the \field{first} field set. The remaining
+entries only have \field{text} set to a shortened version of the
+name so they need to have the \field{name} field copied to the
+\field{first} field using \csopt{replicate-fields}:
+\begin{codeenv}
+\csopt[\field{name}=\marg{\field{first}}]{replicate-fields}
+\end{codeenv}
+
+I'd like the first use to show the other name in parentheses where
+provided. The simplest way to achieve this is by defining the
+\idx{postlinkhook} \ics{glsxtrpostlinkcategory}. If the
+\field{category} field isn't specified it will default to
+\code{general} (for entries defined with \atentry{entry}), so I
+could just define \csfmt{glsxtrpostlinkgeneral} but to allow for
+the possibility of extending the document to incorporate other types
+of entries I decided to set the \field{category} to \code{people}
+through the use of the \csopt{category} option:
+\begin{codeenv}
+\csopt[people]{category}
+\end{codeenv}
+
+This means that I now need to define a command called
+\csfmt{glsxtrpostlinkpeople} that will be used after instances of
+\cs{gls} etc where the entry has the \field{category} set to
+\code{people}. This first tests if that was the first use of the
+entry with \ics{glsxtrifwasfirstuse} and then tests if the
+\field{user3} field is set. If so, it does a space followed by that
+field's value in parentheses. The entry's label can be obtained from
+\ics{glslabel}:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postlinkhook{people}}\marg{\comment{}
+ \cs{glsxtrifwasfirstuse}
+ \marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{}
+ \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+
+I'd also like to do something similar after the name when the entry
+is displayed in the glossary. This means defining the \idx{postnamehook}
+\ics{glsxtrpostnamecategory}, in this case
+\csfmt{glsxtrpostnamepeople}. The entry's label is referenced
+with \ics{glscurrententrylabel}:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postnamehook{people}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+(A different command is used since \cs{gls} may occur in the
+description, which would interfere with the current entry label if
+they shared the same command to reference the label.)
+
+The \idx{postdescriptionhook} can be used to append the birth and
+death dates. Although all the entries that have been selected from \exfile{people.bib} have a
+\fieldfmt{died} field, I've added a check for the corresponding
+\field{user3} field in case new references are added for people who are
+still alive:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postdeschook{people}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{born}
+ \cs{space}(\cs{glscurrentfieldvalue}\ics{comma}-{}-\cs{comma}\comment{}
+ \cs{ifglshasfield}\marg{user2}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{died}
+ \cs{glscurrentfieldvalue}
+ }\comment{}
+ \marg{}\comment{}
+ )\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+
+The first list is quite straight-forward and can be created with:
+\begin{codeenv}
+\gls!{GlsXtrLoadResources}\oarg{
+ \csopt[people]{src},
+ \csopt[entrytype=entry]{match},
+ \csopt[people]{category},
+ \csopt[\field{name}=\marg{\field{first}}]{replicate-fields},
+ \csopt[\fieldfmt{born}=\field{user1},\fieldfmt{died}=\field{user2},\fieldfmt{othername}=\field{user3}]{field-aliases}
+}
+\end{codeenv}
+I have used the \csopt{sort} option and there's no document language,
+so \bibgls\ will sort according to my locale. The custom
+commands \gls{sortname} and \gls{sortvonname} ensure that the
+entries are all sorted alphabetically according to the surnames.
+
+The second list can easily be created by adding the \csopt{secondary}
+option:
+\begin{codeenv}
+\csopt[date:\field{user1}:bybirth]{secondary}
+\end{codeenv}
+This sorts according to the \field{user1} field (which was
+originally the \fieldfmt{birth} field).
+Note that different locales have different default date formats.
+There may also be a difference in the default date format depending
+on the Java \idx{localeprovider}. For example, if you switch from
+using the \idx{JRE} to using the \idx{CLDR} you may find a change in
+the default format. In case the format provided in the \ext{bib}
+file isn't recognised, the required format can be set with:
+\begin{codeenv}
+ \csopt[d MMM YYYY G]{secondary-date-sort-format}
+\end{codeenv}
+
+I've changed the date group headings by redefining \gls{bibglsdategroup} and
+\gls{bibglsdategrouptitle}, which means that the grouping in the
+\code{bybirth} glossary will be in the form \meta{year} \meta{era}:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsdategroup}}[7]\marg{\idx{param}1\idx{param}4\idx{param}7}
+\cs{newcommand}\marg{\gls{bibglsdategrouptitle}}[7]\marg{\cs{number}\idx{param}1\ \idx{param}4}
+\end{codeenv}
+I've also defined the \code{bybirth} glossary and supplied a title:
+\begin{codeenv}
+\cs{newglossary*}\marg{bybirth}\marg{People (Ordered by Birth)}
+\end{codeenv}
+
+The first two glossaries have entries with fairly long names (especially those
+with the \idx{postnamehook}), so the best style is the
+\glostyle{altlistgroup}. The \sty{glossaries-extra-stylemods}
+package patches this style to discourage page breaks occurring after
+group headings, so I've also used the \styopt{stylemods}
+option to automatically load that package. I'd like to use the
+\glostyle{bookindex} style for the index, which is provided by
+\sty{glossary-bookindex}, so I need:
+\begin{codeenv}
+\styopt[list,bookindex]{stylemods}
+\end{codeenv}
+This ensures that \sty{glossary-list} and \sty{glossary-bookindex}
+are loaded and patches the list styles.
+
+The first two glossaries would look better with a terminating
+\idx{full-stop}, so I've used the \styopt{postdot} package option.
+(The \glostyle{bookindex} style doesn't use the \field{description}
+field and therefore doesn't use the \idx{postdescriptionhook}.)
+The index glossary type can be defined with the \styopt{index}
+package option. I've set the default style to \glostyle{altlistgroup}
+but this can locally be changed to \glostyle{bookindex} when I
+display the index. The \styopt{record} option is needed to use
+\bibgls, so the \styfmt{glossaries-extra} package is loaded with:
+\begin{codeenv}
+\cmd{usepackage}[\styopt{record},\comment{using bib2gls}
+ \styopt{index},\comment{create index glossary}
+ \styopt{postdot},\comment{dot after descriptions}
+\comment{load glossary-list.sty and glossary-bookindex.sty and patch:}
+ \styopt[list,bookindex]{stylemods},
+ \styopt[altlistgroup]{style}]\marg{glossaries-extra}
+\end{codeenv}
+
+The index needs to include all the entries that have already been
+defined but also needs to include the aliased entries. This means
+that existing entries simply need their label copied to the
+\code{index} glossary but the other entries need to be defined
+so this requires setting the \csopt{action} option:
+\begin{codeenv}
+\csopt[define or copy]{action}
+\end{codeenv}
+I would also like to have groups in the index (which the
+\glostyle{bookindex} style supports) so I need to specify a field
+in which to save the group information using
+\csopt{copy-action-group-field}:
+\begin{codeenv}
+\csopt[indexgroup]{copy-action-group-field}
+\end{codeenv}
+I need to remember to redefine \ics{glsxtrgroupfield} to this value before
+displaying the index:
+\begin{codeenv}
+\cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}
+\end{codeenv}
+
+The aliased entries won't be selected by default since they haven't
+been used in the document, so I need to change the selection
+criteria with \csopt{selection}:
+\begin{codeenv}
+\csopt[recorded and deps and see]{selection}
+\end{codeenv}
+
+In the index, I'd like the surnames first. This can be done by
+redefining the custom commands used in the \field{name} fields.
+There's a slight complication here. These commands aren't defined on
+the first \LaTeX\ run as their definitions are written to the
+\ext{glstex} file by \bibgls, so I can't use \cs{renewcommand} (although
+I could use \cs{glsrenewcommand}).
+Instead I've provided some custom commands:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1}
+\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1}
+\end{codeenv}
+Now I just need to make an assignment using \ics{let}:
+\begin{codeenv}
+\cs{let}\gls{sortname}\cmd{swaptwo}
+\cs{let}\gls{sortart}\cmd{swaptwo}
+\cs{let}\gls{sortvonname}\cmd{swapthree}
+\end{codeenv}
+This doesn't perform any check to determine if the commands are
+already defined so there won't be a problem on the first run.
+
+The first two glossaries shouldn't have number lists:
+\begin{codeenv*}
+\cs{printunsrtglossary}\oarg{\printglossopt[People (Alphabetical)]{title},\printglossopt{nonumberlist}}
+\cs{printunsrtglossary}\oarg{\printglossopt[bybirth]{type},\printglossopt[false]{target},\printglossopt{nonumberlist}}
+\end{codeenv*}
+I'd like to use \sty{hyperref} but I have to switch off the
+hypertargets for the second glossary otherwise I'll end up with
+duplicate targets. This is done with \code{\printglossopt[false]{target}}.
+All references using \cs{gls} etc will link to the first glossary.
+
+I could also do this for the index but the cross-references in the
+aliased entries will link to the first glossary rather than the
+relevant entry in the index. The simplest way to fix this is to
+redefine \ics{glolinkprefix} to provide a different target:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}
+\end{codeenv}
+These redefinitions need to be done before the index. I've decided
+to use the starred \ics{printunsrtglossary*} to localise these
+changes, although that's not needed for this document since the
+index comes right at the end:
+\begin{codeenv*}
+\cs{printunsrtglossary*}
+ \oarg{\printglossopt[index]{type},\printglossopt[\glostyle{bookindex}]{style}}
+ \marg{\comment{}
+ \cs{let}\gls!{sortname}\cmd{swaptwo}
+ \cs{let}\gls!{sortart}\cmd{swaptwo}
+ \cs{let}\gls!{sortvonname}\cmd{swapthree}
+ \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{indexgroup}\comment{}
+ \cs{renewcommand}*\marg{\cs{glolinkprefix}}\marg{idx:}\comment{}
+ }
+\end{codeenv*}
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-people
+bib2gls --group --break-space sample-people
+pdflatex sample-people
+\end{verbatim}
+The four pages of the document are shown in \figureref{fig:sample-people.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-people.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-people.pdf}{4}}
+{\caption{\filefmt{sample-people.pdf}}}
+{fig:sample-people.pdf}
+\end{figure}
+
+\filesection{sample-authors.tex}
+
+This example uses the files \exfile{people.bib},
+\exfile{books.bib}, \exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble2.bib}. The aim is to reference the books
+in \exfile{books.bib} and have them listed by author. This means
+finding a way of assigning each book entry a \field{parent} field that
+contains the label identifying the relevant author in \exfile{people.bib}.
+I've used a style that shows letter group headings so I need to use
+the \longarg{group} switch.
+
+To recap, each author is defined in \exfile{people.bib} in the form:
+\begin{codeenv}
+\atentry{entry}\marg{dickens,
+ \field{name}=\marg{\gls{sortname}\marg{Charles}\marg{Dickens}},
+ \field{text}=\marg{Dickens},
+ \field{description}=\marg{English writer and social critic},
+ \fieldfmt{born}=\marg{7\idx{nbspchar}February 1812 AD},
+ \fieldfmt{died}=\marg{9\idx{nbspchar}June 1870 AD},
+ \fieldfmt{identifier}=\marg{person}
+}
+\end{codeenv}
+and each book is defined in \exfile{books.bib} in the form:
+\begin{codeenv}
+\atentry{entry}\marg{bleakhouse,
+ \field{name}=\marg{Bleak House},
+ \field{description}=\marg{novel by Charles Dickens},
+ \fieldfmt{identifier}=\marg{book},
+ \fieldfmt{author}=\marg{\gls{sortmediacreator}\marg{Charles}\marg{Dickens}},
+ \fieldfmt{year}=\marg{1852}
+}
+\end{codeenv}
+There's a field here (the custom \fieldfmt{author} field) that contains
+the author's name, and this can be aliased to the \field{parent}
+field with \csopt{field-aliases}:
+\begin{codeenv}
+\csopt[\fieldfmt{author}=\field{parent}]{field-aliases}
+\end{codeenv}
+but the author's label in the \exfile{people.bib}
+file is just the \idx!{lowercase} surname.
+
+Remember from \sectionref{sec:texparserlib} that the interpreter
+will be used on the \field{parent} field if the value contains
+\idx{escchar} or \idx{bgroupchar} or \idx{egroupchar} and
+\csopt[true]{interpret-label-fields}. This means that with this
+field alias and the interpreter on, \bibgls\ will attempt to
+interpret the field contents. So all that's needed is to ensure that
+\bibgls\ is given a definition of \gls{sortmediacreator} that
+ignores the first argument and converts the second argument to lower
+case. This definition is available in
+\exfile{interpret-preamble2.bib} but, since this file uses
+\cs{renewcommand} rather than \cs{providecommand},
+\csopt[false]{write-preamble} is required to prevent \LaTeX\ from
+picking up this definition.
+
+As with the \exfile{sample-people.tex} example, I need to copy
+the \field{name} field to the \field{first} field if that field is
+missing using \csopt{replicate-fields}:
+\begin{codeenv}
+\csopt[\field{name}=\marg{\field{first}}]{replicate-fields}
+\end{codeenv}
+and I also want to provide a semantic command to format the book
+title, so the field aliases also need to convert the custom
+\fieldfmt{identifier} field to \field{category}:
+\begin{codeenv}
+\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{author}=\field{parent}]{field-aliases}
+\end{codeenv}
+so that the document can set the \catattr{textformat} and
+\catattr{glossnamefont} attributes:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
+\end{codeenv}
+As with \exfile{sample-media.tex}, the terminating question mark at
+the end of some of the \field{name} fields can cause an awkward
+situation if \cs{gls} is used at the end of a sentence. This can be
+dealt with by getting \bibgls\ to make a note of the fields that
+end with sentence-terminating punctuation through the use of
+the \csopt{check-end-punctuation} option. In this example, the
+\field{name}, \field{text} and \field{first} fields are the same for
+all the books, so it's sufficient just to check the \field{name}
+field:
+\begin{codeenv}
+\csopt[\field{name}]{check-end-punctuation}
+\end{codeenv}
+With \sty{glossaries-extra} v1.23+ it's easy to hook into the
+\idx{postlinkhook} to check if
+\fielddisp{fieldendpunc}{nameendpunc} exists:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
+ \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+This will now cause the full stops following:
+\begin{codeenv}
+\cs{gls}\marg{whydidnttheyaskevans}.
+\end{codeenv}
+and
+\begin{codeenv}
+\cs{gls}\marg{doandroidsdreamofelectricsheep}.
+\end{codeenv}
+to be discarded.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-authors
+bib2gls --group sample-authors
+pdflatex sample-authors
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-authors.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-authors.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-authors.pdf}}%
+}
+{\caption{\filefmt{sample-authors.pdf}}}
+{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{codeenv}
+\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls}
+\styopt{nomain},\comment{don't define main glossary}
+\styopt{postdot},\comment{full stop after descriptions}
+\styopt{nostyles},\comment{don't load default styles}
+\comment{load glossary-tree and glossary-list and patch styles:}
+\styopt[tree,list]{stylemods}
+}\marg{glossaries-extra}
+\end{codeenv}
+Next I need to create the glossaries for the list of authors and
+list of titles:
+\begin{codeenv}
+\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 \gls{bibglsnewbibtexentry} that assigns
+\field{type} after the options:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsnewbibtexentry}}[4]\marg{\comment{}
+ \gls{longnewglossaryentry}*\marg{\idx{param}1}\marg{\field{name}=\marg{\idx{param}3},\idx{param}2,\field{type}=\marg{titles}}\marg{\idx{param}4}\comment{}
+}
+\end{codeenv}
+The standard \BibTeX\ entry types need aliasing to
+\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[\fieldfmt{title}=\field{name}]{field-aliases}
+\end{codeenv}
+(The other fields aren't required for the glossary lists.)
+The \field{category} is set to the original entry type:
+\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[\field{category}]{sort-field}
+\end{codeenv}
+and setting the sort suffix to the \field{name} field sub-sorts
+the \atentry{bibtexentry} types according to the title
+(which was aliased to the \field{name}) and the
+\atentry{contributor} types according to the author:
+\begin{codeenv}
+\csopt[\field{name}]{sort-suffix}
+\end{codeenv}
+
+Next the groups identified by the labels \code{article} and \code{book}
+are assigned titles.
+\begin{codeenv}
+\gls{glsxtrsetgrouptitle}\marg{article}\marg{Articles}
+\gls{glsxtrsetgrouptitle}\marg{book}\marg{Books}
+\end{codeenv}
+The \field{group} field is actually set to the associated letter by the default
+\csopt{sort} method. The desired labels are stored in the \field{category}
+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*}[\printglossopt[titles]{type},\printglossopt[indexgroup]{style}]
+\marg{\comment{}
+ \cs{renewcommand}\marg{\cs{glsxtrgroupfield}}\marg{\field{category}}\comment{}
+ \cs{renewcommand}\marg{\cs{glstreenamefmt}}[1]\marg{\cs{emph}\marg{\idx{param}1}}\comment{}
+ \cs{renewcommand}\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\ics{textbf}\marg{\idx{param}1}}\comment{}
+}
+\end{codeenv}
+This again contradicts the advice given in
+\sectionref{sec:logicaldivisions} as I'm sorting by the
+\field{group} label. (Technically it's sorting by the
+\field{category} label but this is being used as the group.) In this
+case it's not a problem as the labels closely match the titles and
+the sorting options ensure that the groups aren't broken up.
+
+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}[\printglossopt[contributors]{type},\printglossopt[altlist]{style}]
+\end{codeenv}
+This will only list the names as there's no description, but again
+the \idx{postdescriptionhook} can be used, in this case for the \code{contributor}
+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{\comment{}
+ \ics{glsxtrifhasfield}\marg{\field{bibtexentry}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrfieldforlistloop}
+ \marg{\cs{glscurrententrylabel}}\marg{\field{bibtexentry}}\comment{}
+ \marg{\csfmt{contributorhandler}}\comment{}
+ }\comment{}
+ \marg{\ics{par} No titles.}\comment{}
+}
+\end{codeenv}
+The \idx{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 --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},
+\exfile{mathsrelations.bib}, \exfile{binaryoperators.bib},
+\exfile{unaryoperators.bib} and \exfile{mathgreek.bib}. The \isty{stix}
+package is required for some of the commands used in
+\exfile{bigmathsymbols.bib}, so that must be loaded in the document.
+
+I'm using the \glostyle{mcolalttree} style for this document,
+which means that the \sty{glossary-mcols} package is required and
+the styles need patching, which can be done with
+the \styopt{stylemods} package option:
+\begin{codeenv}
+\cs{usepackage}\oarg{\styopt{record},\comment{using bib2gls}
+ \styopt{nostyles},\comment{don't load default styles}
+ \styopt{postdot},\comment{append a dot after descriptions}
+ \styopt[mcols]{stylemods},\comment{load glossary-mcols.sty and patch}
+ \styopt[mcolalttree]{style}}\marg{glossaries-extra}
+\end{codeenv}
+
+I'm not referencing any of the entries in the document as I'm just
+generating a complete list of all the defined symbols. This means I
+need to tell \bibgls\ to select all entries and don't bother saving
+the \field{location} field:
+\begin{codeenv}
+\csopt[false]{save-locations},
+\csopt[all]{selection}
+\end{codeenv}
+Since I'm using a style that's based on \glostyle{alttree} I need to
+find the widest \field{name}, which can be done with \csopt{set-widest}.
+
+The simplest way of dividing the glossary into logical blocks is to
+sort according to the category, but first I need to use \csopt{field-aliases}
+to convert the custom \fieldfmt{identifier} field to \field{category}:
+\begin{codeenv}
+\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases}
+\end{codeenv}
+and sort by the \field{category} field:
+\begin{codeenv}
+\csopt[\field{category}]{sort-field}
+\end{codeenv}
+Since this will cause identical sort values, I need to provide a
+a way of ordering these identical values. Here I've decided
+to fallback on the \field{description} field:
+\begin{codeenv}
+\csopt[\field{description}]{identical-sort-action}
+\end{codeenv}
+This means that entries will be ordered by \field{category} and
+then \field{description}, which naturally creates blocks of symbol
+types in the glossary. This only uses a simple case-sensitive string
+comparison which is fine for English, but for another language it
+would be better to use \csopt{sort-suffix} as in the
+\exfile{sample-textsymbols.tex} file.
+
+Remember that I want a small vertical gap between each logical
+block. These need the \field{group} field which, with the default
+locale sort, is obtained from the first letter of the sort value.
+In this case the sort value is obtained from the \field{category}
+field, and as each category happens to start with a different
+letter, this means I get the desired effect. However, in the event
+that I add more entries with a new category that happens to start
+with the same letter as an existing category, it's better to provide
+a more future-proof method, so I've set the \field{group} field to
+fetch its value from the \field{category} field:
+\begin{codeenv}
+\csopt[\field{category}=\field{group}]{replicate-fields}
+\end{codeenv}
+(Since the \csopt{field-aliases} option is always performed before
+\csopt{replicate-fields}, the \field{category} field will already
+have been set and is available for replicating.)
+
+This means that I'm essentially sorting by the \field{group} labels,
+which this manual has warned against doing. In this case, it's an
+acceptable break from that rule as I've used options that ensure the
+groups aren't broken up during sorting and I'm not concerned with the group
+titles. A method such as that used in \exfile{sample-textsymbols2.tex}
+would end up with titled blocks, which I don't want here. By using
+resource options such as \csopt{field-aliases} and
+\csopt{replicate-fields} I can avoid the warning that's triggered
+with the default \longarg{warn-non-bib-fields}.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-msymbols
+bib2gls sample-msymbols
+pdflatex sample-msymbols
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-msymbols.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-msymbols.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-msymbols.pdf}}%
+}
+{\caption{\filefmt{sample-msymbols.pdf}}}
+{fig:sample-msymbols.pdf}
+\end{figure}
+
+\filesection{sample-maths.tex}
+
+This example uses \exfile{bigmathsymbols.bib} and \exfile{mathsobjects.bib}.
+It has a fairly similar preamble to \exfile{sample-msymbols.tex},
+but \exfile{no-interpret-preamble.bib} and
+\exfile{interpret-preamble.bib} are now needed to provide
+the \gls!{sortart} command:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[no-interpret-preamble]{src},
+ \csopt[false]{interpret-preamble}
+}
+\end{codeenv}
+There's also an extra custom field to alias:
+\begin{codeenv}
+\csopt[\fieldfmt{identifier}=\field{category},\fieldfmt{format}=\field{user1}]{field-aliases}
+\end{codeenv}
+I've aliased \fieldfmt{format} to \field{user1} since \gls!{glsxtrfmt}
+defaults to that field. If I decided to use a different field I also
+need to remember to redefine \ics{GlsXtrFmtField} to match.
+
+As with \exfile{sample-msymbols.tex} I'm sorting by the
+\field{category} label and this value is copied to the \field{group}
+field, but again I don't have a hierarchical glossary as the logical
+blocks don't have titles.
+
+In this document I only want to select entries that have been
+indexed, so I've omitted the \csopt{selection} option I used in the
+\exfile{sample-msymbols.tex} example, however
+I still don't want any number lists so I still have
+\csopt[false]{save-locations}.
+
+I want \gls!{glsxtrfmt} to index the term (which it doesn't by default) so
+that means I need to redefine \ics{GlsXtrFmtDefaultOptions}
+to prevent it from using \code{noindex}:
+\begin{codeenv}
+\cs{renewcommand}\marg{\cs{GlsXtrFmtDefaultOptions}}\marg{}
+\end{codeenv}
+I've provided some convenient wrapper commands that use
+\gls!{glsxtrfmt*} or the non-linking \gls!{glsxtrentryfmt} that
+are in the form:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{set}}[2][]\marg{\gls{glsxtrfmt*}\oarg{\idx{param}1}\marg{set}\marg{\idx{param}2}}
+\cs{newcommand}\marg{\cmd{nlset}}[1]\marg{\gls{glsxtrentryfmt}\marg{set}\marg{\idx{param}1}}
+\end{codeenv}
+The use of the starred form allows:
+\begin{codeenv}
+\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}[\idx{sbchar}\marg{i=1}\idx{spchar}n] \cmd{set}\marg{B}[\idx{sbchar}i] \cmd{]}
+\end{codeenv}
+which produces:
+\[ \mathcal{A} = \bigcup_{i=1}^n \mathcal{B}_i \]
+Note the difference if the optional arguments aren't used:
+\begin{codeenv}
+\cmd{[}\cmd{set}\marg{A} = \cs{gls}\marg{bigcup}\idx{sbchar}\marg{i=1}\idx{spchar}n \cmd{set}\marg{B}\idx{sbchar}i \cmd{]}
+\end{codeenv}
+This produces:
+\[ \mathcal{A} = \bigcup{}_{i=1}^n \mathcal{B}{}_i \]
+
+Be careful with the set cardinality example. You might be tempted to
+nest \csfmt{set} within the argument of \csfmt{setcard} but this
+results in nested hyperlinks. These are unpredictable and there's no
+consistent handling of them between different PDF viewers. It can
+also be confusing to the reader. If
+$\lvert\mathcal{B}_1\cup\mathcal{B}_2\rvert$
+shows up as what appears to be a single hyperlink, where would the
+reader expect the target? This is the reason for providing the
+non-linking commands like \csfmt{nlset} and \csfmt{nlsetcard}.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-maths
+bib2gls sample-maths
+pdflatex sample-maths
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-maths.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-maths.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-maths.pdf}}%
+}
+{\caption{\filefmt{sample-maths.pdf}}}
+{fig:sample-maths.pdf}
+\end{figure}
+
+\filesection{sample-textsymbols.tex}
+
+This example uses \exfile{miscsymbols.bib}.
+This requires both \isty{marvosym} and (with the \styoptfmt{weather} option)
+\isty{ifsym}. Unfortunately both define the commands \csfmt{Sun}
+and \csfmt{Lightning}, so these commands need to be undefined after
+the first package is loaded and before the second.
+Since I want the definitions provide by \sty{ifsym} I have to first
+load \sty{marvosym}, then undefine the conflicting commands and then
+load \sty{ifsym}:
+\begin{codeenv}
+\cs{usepackage}\marg{etoolbox}
+\cs{usepackage}\marg{marvosym}
+\cs{undef}\cmd{Sun}
+\cs{undef}\cmd{Lightning}
+\cs{usepackage}\oarg{\styoptfmt{weather}}\marg{ifsym}
+\end{codeenv}
+The \sty{etoolbox} package is also loaded as it provides
+\ics{undef}. (An alternative is to modify the
+\exfile{miscsymbols.bib} file so that it uses \sty{ifsym}'s more
+generic \cs{textweathersymbol} command and omit the \styoptfmt{weather}
+option when loading the package, but the method used here
+demonstrates how to deal with such conflicts.)
+
+The custom entry type \atentryfmt{icon} must be aliased for the
+entries to be recognised:
+\begin{codeenv}
+\csopt[icon=symbol]{entry-type-aliases}
+\end{codeenv}
+
+Since none of the entries have a \field{name} or \field{description}
+field, the custom fields \fieldfmt{icon} and
+\fieldfmt{icondescription} need to be aliased to them.
+The document uses the \glostyle{alttreegroup} style where the groups
+are obtained from the \field{category}, which again I obtain from
+the custom \fieldfmt{identifier} field using:
+\begin{codeenv}
+\csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{icon}=\field{name},
+ \fieldfmt{icondescription}=\field{description}]{field-aliases},
+\csopt[\field{category}=\field{group}]{replicate-fields}
+\end{codeenv}
+The \field{group} field is just a label and an appropriate title needs to be
+supplied for each group label:
+\begin{codeenv}
+\cs{glsxtrsetgrouptitle}\marg{information}\marg{Information}
+\cs{glsxtrsetgrouptitle}\marg{mediacontrol}\marg{Media Controls}
+\cs{glsxtrsetgrouptitle}\marg{weather}\marg{Weather Symbols}
+\end{codeenv}
+This also requires sorting first by \field{category} and then
+fallback on another field. The most appropriate here is the
+\field{description} field, but instead of using
+\csopt{identical-sort-action}, I'm using \csopt{sort-suffix},
+which works better with the default locale sort when the fallback
+field consists of words or phrases.
+\begin{codeenv}
+\csopt[\field{category}]{sort-field},
+\csopt[\field{description}]{sort-suffix},
+\csopt[|]{sort-suffix-marker}
+\end{codeenv}
+Since I'm using one of the \glostyle{alttree} styles, I need to set
+the widest name:
+\begin{codeenv}
+\csopt{set-widest}
+\end{codeenv}
+In this case, \bibgls\ won't be able to determine the widest name
+since it doesn't recognise any of the commands, so it will have to
+use the fallback command, which will use one of the commands
+provided by the \sty{glossaries-extra-stylemods} package.
+
+This is actually not the best method as \bibgls\ can't see the group
+titles as they're in the document, so it's only able to sort by the
+label. While this might work for English, it can become a problem
+for other languages that use extended Latin or non-Latin characters
+in their alphabet. A much better method is to treat this as a
+hierarchical glossary with topic titles as the top-level entries.
+This is covered in the next example \exfile{sample-textsymbols2.tex}.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-textsymbols
+bib2gls sample-textsymbols
+pdflatex sample-textsymbols
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-textsymbols.pdf}.
+
+\lstinputlisting[firstline=6]{../examples/sample-textsymbols.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols.pdf}}%
+}
+{\caption{\filefmt{sample-textsymbols.pdf}}}
+{fig:sample-textsymbols.pdf}
+\end{figure}
+
+\filesection{sample-textsymbols2.tex}
+
+This example is a better approach than the
+\exfile{sample-textsymbols.tex} example above. As with the previous
+example, this requires both \isty{marvosym} and \isty{ifsym} so the
+same patch is applied to avoid conflict.
+
+As before, the custom entry type \atentryfmt{icon} must be aliased for the
+entries to be recognised:
+\begin{codeenv}
+\csopt[icon=symbol]{entry-type-aliases}
+\end{codeenv}
+
+The \exfile{topics.bib} file contains terms with
+labels that match the custom \fieldfmt{identifier} fields used in
+the \exfile{miscsymbols.bib} file. So both files are loaded and the
+\fieldfmt{identifier} field is now aliased to \field{parent}. These
+parent entries represent the topics and unlike the previous example
+it's now possible to sort by the topic title (obtained from the
+\field{name} field) instead of by the label.
+\begin{codeenv}
+\csopt[topics,miscsymbols]{src},
+\csopt[
+ \fieldfmt{identifier}=\field{parent},
+ \fieldfmt{icon}=\field{name},
+ \fieldfmt{icondescription}=\field{description}]{field-aliases},
+\end{codeenv}
+There's no \csopt{sort-field} option in this example. The default
+\field{sort} field is used. Since it's not set for any of the
+entries, the fallback value will be used. In the case of the topic
+titles (\atentry{index} and \atentry{indexplural}), I want to sort
+by the \field{name}, which is the default fallback if the
+\field{sort} field is missing for the index entry types.
+
+The default fallback for the \field{sort} field for \atentry{symbol}
+entries is the label, but in this case I want to use the
+\field{description} field:
+\begin{codeenv}
+ \csopt[description]{symbol-sort-fallback}
+\end{codeenv}
+The best styles for this kind of glossary are the topic styles
+provided by \isty{glossary-topic}. This package was only added to
+\sty{glossaries-extra} v1.40, so you need to make sure you have at
+least that version installed.
+
+In this case I've decided to use the \glostyle{topic} style. I can
+use it with or without the \csopt{set-widest} option.
+As with the previous example, \bibgls\ won't be able to determine
+the widest name since it doesn't recognise any of the commands
+contained in the \field{name} fields, so it will have to use the
+fallback method, which will use one of the commands provided by the
+\sty{glossaries-extra-stylemods} package. The \code{tree} option is
+needed to enable the appropriate commands:
+\begin{codeenv}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt{nostyles},
+ \styopt{postdot},
+ \styopt[tree,topic]{stylemods},
+ \styopt[topic]{style}}\marg{glossaries-extra}
+\end{codeenv}
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-textsymbols2
+bib2gls --group sample-textsymbols2
+pdflatex sample-textsymbols2
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-textsymbols2.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-textsymbols2.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-textsymbols2.pdf}}%
+}
+{\caption{\filefmt{sample-textsymbols2.pdf}}}
+{fig:sample-textsymbols2.pdf}
+\end{figure}
+
+\filesection{sample-markuplanguages.tex}
+
+This example uses \exfile{markuplanguages.bib}. Since the file
+includes abbreviations, any commands that must be used before
+abbreviations are defined need to go before
+\gls!{GlsXtrLoadResources}. This includes the abbreviation style,
+which I've set to \abbrstyle{long-short-desc}:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
+\end{codeenv}
+This style sets the \field{name} field using
+\ics{glsxtrlongshortdescname}, which defaults to the long form
+followed by the short form in parentheses. I decided to switch this
+round so that the short form is shown first, which conveniently
+matches the default \csopt{abbreviation-sort-fallback}.
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
+ \cs{protect}\ics{glsabbrvfont}\marg{\ics{the}\ics{glsshorttok}}\cs{space}
+ \ics{glsxtrparen}\marg{\ics{glslongfont}\marg{\cs{the}\ics{glslongtok}}}\comment{}
+}
+\end{codeenv}
+(The long form is still shown before the short form on the first use
+of \cs{gls} in the document. The switch in the above code only
+affects how the term is displayed in the glossary.)
+
+This redefinition must be done before the abbreviations are defined
+as it's expanded when the \field{name} field is set. (Note the need
+to protect commands that shouldn't be expanded.) If I decide not to change
+the \field{name} format in this way, I would then need to use
+\csopt[long]{abbreviation-sort-fallback}.
+
+I also decided to make use of the custom command \csfmt{abbrvtag}
+that marks up the letters in the \field{long} field used to obtain
+the abbreviation. As with the abbreviation style, this must be
+done before the abbreviations are defined:
+\begin{codeenv}
+\cs{GlsXtrEnableInitialTagging}\marg{markuplanguage}\marg{\cmd{abbrvtag}}
+\end{codeenv}
+If you accidentally place it after \gls{GlsXtrLoadResources}, you'll
+encounter an error on the second \LaTeX\ run (but not the first).
+This is because \ics{GlsXtrEnableInitialTagging} requires that the
+supplied command (\csfmt{abbrvtag} in this case) be undefined. On
+the first \LaTeX\ it's undefined, but on the second it picks up
+the \atentry{preamble} definition, which is now in the resource file.
+
+The tagging format is governed by \ics{glsxtrtagfont} which
+underlines its argument by default. I've redefined it to also
+convert the letter to \idx{uppercase}:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{MakeTextUppercase}\marg{\idx{param}1}}}
+\end{codeenv}
+Note that in the \code{mathml} case, the first tag consists of more
+than one letter:
+\begin{codeenv}
+\field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang
+\end{codeenv}
+Here \ics{NoCaseChange} prevents \ics{MakeTextUppercase}
+from applying the case change.
+
+The default \csopt{selection} criteria includes entries that have
+been indexed and any cross-references. Some of the
+\field{description} fields include \ics{glsxtrshort}, which \bibgls\ picks
+up and the referenced entry is included in the dependency list.
+However, I don't want any indexing
+performed by commands occurring in the glossary. This can be dealt
+with in one of two ways: either switch the format to \encap{glsignore}
+or suppress the indexing by changing the default options with
+\ics{GlsXtrSetDefaultGlsOpts}. In this case I decided to turn the
+records into ignored records:
+\begin{codeenv}
+\ics{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}}
+\end{codeenv}
+This means that some of the entries won't have location lists, so
+I've defined a \idx{postdescriptionhook} that inserts a \idx{full-stop} after the
+\field{description} if there's no location otherwise it inserts a
+comma:
+\begin{codeenv}
+\cs{newcommand}\marg{\postdeschook{markuplanguage}}\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{location}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{,}\comment{}
+ \marg{.}\comment{}
+}
+\end{codeenv}
+I've used \csopt{loc-suffix} to append a \idx{full-stop} after the
+location lists. This doesn't affect the entries that haven't been
+indexed.
+
+I decided to convert the first letter of the \field{name} field to
+\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}:
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossname}}\marg{firstuc}
+\end{codeenv}
+If this line causes an error when the glossary is displayed that goes
+away if it's commented out, make sure you have at least version 2.06
+of \sty{mfirstuc}. For most of the entries, this doesn't make a
+difference as they already start with a capital. It's only the
+\code{markdown} entry that's actually affected.
+
+The description case change is dealt with by \bibgls\ instead:
+\begin{codeenv}
+\csopt[firstuc]{description-case-change}
+\end{codeenv}
+This works better than the \catattr{glossdesc} attribute as \bibgls\ can
+convert commands like \ics{glstext} into \ics{Glstext} which
+\ics{makefirstuc} can't do. (Although in this particular example,
+there's no difference as both instances of \cs{glstext} already
+produce \idx{uppercase} text.)
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-markuplanguages
+bib2gls --group sample-markuplanguages
+pdflatex sample-markuplanguages
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-markuplanguages.pdf}.
+
+\lstinputlisting[firstline=5]{../examples/sample-markuplanguages.tex}
+
+\begin{figure}
+\figcontents
+{%
+ \frame{\includegraphics[height=.9\textheight]{../examples/sample-markuplanguages.pdf}}%
+}
+{\caption{\filefmt{sample-markuplanguages.pdf}}}
+{fig:sample-markuplanguages.pdf}
+\end{figure}
+
+
+\filesection{sample-usergroups.tex}
+
+This example uses \exfile{usergroups.bib}. This requires \XeLaTeX\
+or \LuaLaTeX\ as the \ext{bib} file includes \idx{non-ASCII} labels.
+The entries include fields in different languages, the main one
+being English. If an entry has a non-English \field{name} or
+\field{long} field, it also includes the custom field
+\fieldfmt{translation} that provides an (approximate) translation.
+If this field is present, the language is given by the first element
+of the custom \fieldfmt{language} field.
+
+In this case, I'm providing keys for the custom
+\fieldfmt{language} and \fieldfmt{translation} fields, and, for a bit
+of variety from the other examples, I'm ignoring the custom
+\fieldfmt{identifier} field. The custom keys are provided with
+\ics{glsaddstoragekey}:
+\begin{codeenv}
+\cs{glsaddstoragekey}\marg{language}\marg{}\marg{\cmd{glsentrylanguage}}
+\cs{glsaddstoragekey}\marg{translation}\marg{}\marg{\cmd{glsentrytranslation}}
+\end{codeenv}
+The \ext{bib} file includes abbreviations. Remember that the
+abbreviation style must be set before the resource file is loaded:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{tug}\marg{\abbrstyle{long-short-user}}
+\end{codeenv}
+For this example, I'm explicitly setting the \field{category} field
+to \code{tug}:
+\begin{codeenv}
+\csopt[tug]{category}
+\end{codeenv}
+Some of the fields end with a \idx{full-stop}. This isn't a problem with
+the \field{long} field as the first use follows the long form with
+the short form in parentheses, but it will be a problem on
+subsequent use if the \field{short} field ends with a \idx{full-stop}.
+This means I need to check for end-of-sentence punctuation
+for the \field{short} field. It's also a good idea to do this for
+the \field{name} field for the non-abbreviations.
+\begin{codeenv}
+\csopt[\field{name},\field{short}]{check-end-punctuation}
+\end{codeenv}
+It's now possible to discard a \idx{full-stop} that follows
+\ics{gls}:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrifcustomdiscardperiod}}[2]\marg{\comment{}
+ \ics{ifglshasshort}\marg{\cs{glslabel}}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrifwasfirstuse}\marg{}\comment{}
+ \marg{\comment{}
+ \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{shortendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
+ }\comment{}
+ }\comment{}
+ \marg{\comment{}
+ \cs{GlsXtrIfFieldUndef}\marg{\fielddisp{fieldendpunc}{nameendpunc}}\marg{\cs{glslabel}}\marg{\idx{param}2}\marg{\idx{param}1}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+This first tests if the entry that's just been referenced has a
+\field{short} field. If it has, then the next test is to check if
+that was the first use for that entry. If it was, nothing is done.
+If it wasn't, then \cs{GlsXtrIfFieldUndef} is used to determine
+if \fielddisp{fieldendpunc}{shortendpunc} has been set. If it has
+been set then the period discard function is performed. If the
+entry doesn't have a \field{short} field, then the
+\fielddisp{fieldendpunc}{nameendpunc} field needs checking instead.
+
+Since the document requires \XeLaTeX\ or \LuaLaTeX\ and has some
+\idx{non-ASCII} characters, it needs \sty{fontspec} and an
+appropriate font. In this case I've chosen \qt{Linux Libertine O}.
+If you don't have it installed, you'll need to change it.
+\begin{verbatim}
+\usepackage{fontspec}
+\setmainfont{Linux Libertine O}
+\end{verbatim}
+Since it's a multilingual document I also need \sty{polyglossia}
+with the main language set to \code{english}:
+\begin{codeenv}
+\cmd{usepackage}\marg{polyglossia}
+\ics{setmainlanguage}\oarg{variant=uk}\marg{english}
+\end{codeenv}
+Now comes the difficult bit. The document needs to determine what
+other languages need to be loaded. The \sty{tracklang} package
+provides a convenient interface when dealing with language tags.
+This is automatically loaded by \styfmt{glossaries} but I've loaded
+it here explicitly as a reminder:
+\begin{verbatim}
+\usepackage{tracklang}
+\end{verbatim}
+Once the \hyperref[sec:resourcesets]{resource file} has been loaded, I need to
+iterate over all the defined entries and check if the \fieldfmt{translation}
+field has been set. If it has, then the first language tag in the
+\fieldfmt{language} field will supply the language, but this needs to be
+converted from the \idx{IETF} language tag to a language name recognised by
+\sty{polyglossia}.
+
+Iterating over all entries can be done with \ics{forglsentries}
+but remember that no entries will be defined before \bibgls\ has
+been run, so this does nothing on the first \LaTeX\ run.
+\begin{codeenv}
+\cs{forglsentries}\marg{\cmd{thislabel}}\marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{translation}\marg{\cmd{thislabel}}\comment{}
+ \marg{\comment{}
+ \comment{requires glossaries-extra v1.24}
+ \cs{glsxtrforcsvfield}\marg{\cmd{thislabel}}\marg{language}\marg{\cmd{addfirstlang}}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+Within the outer (\cs{forglsentries}) loop, there's a check
+for the \fieldfmt{translation} field using \ics{glsxtrifhasfield}.
+If it's present, then the first element of the \fieldfmt{language}
+field is required. The simplest way to get this is to use
+\ics{glsxtrforcsvfield} which iterates over all elements of the
+given field (\fieldfmt{language} in this case) and break out of the
+loop (with \ics{glsxtrendfor}) once the language has been found.
+
+The \idx{handler} function (\csfmt{addfirstlang}) is defined so that it
+adds the given language tag as a tracked language using
+\ics{TrackLocale}. This command sets
+\ics{TrackLangLastTrackedDialect} to the associated
+(\sty{tracklang}) dialect label for convenience. This dialect label
+can then be converted to the root language label using
+\ics{TrackedLanguageFromDialect}. If this language is supported
+by \sty{polyglossia}, then there should be a file called
+\metafilefmt{gloss-}{language}{.ldf}.
+
+Some of the entries use the same language, so it's necessary to
+check if the language has already been defined before loading it.
+There's also a problem in that the language file should not be
+loaded in a scoped context, but both \ics{glsxtrforcsvfield}
+and the unstarred \ics{glsxtrifhasfield} add implicit grouping.
+To solve both problems, an internal \sty{etoolbox} list is
+defined:
+\begin{verbatim}
+\newcommand{\langlist}{}%
+\end{verbatim}
+and \ics{xifinlist} is used to first check if the language label is
+already in the list before adding it. Since this part of the code is
+scoped, the global \ics{listxadd} is used to add the language label
+to the list.
+
+Next the \field{useri} field is set to
+\encapdisp{textlanguage}{text\meta{language}}
+which is the name of the control sequence used with
+\sty{polyglossia} to switch language for a short block of text. This means that
+\gls{glsxtrentryfmt}\margm{text} can be used to format \meta{text}
+in the relevant language. Finally, \ics{glsxtrendfor} is used to
+break out of the loop.
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{addfirstlang}}[1]\marg{\comment{}
+ \cs{TrackLocale}\marg{\idx{param}1}\comment{}
+ \ics{edef}\cmd{thislanguage}\marg{\comment{}
+ \cs{TrackedLanguageFromDialect}\cs{TrackLangLastTrackedDialect}}\comment{}
+ \ics{IfFileExists}\marg{gloss-\cmd{thislanguage}.ldf}\comment{}
+ \marg{\comment{}
+ \ics{xifinlist}\marg{\cmd{thislanguage}}\marg{\cmd{langlist}}\marg{}\comment{}
+ \marg{\ics{listxadd}\marg{\cmd{langlist}}\marg{\cmd{thislanguage}}}\comment{}
+ \ics{xGlsXtrSetField}\marg{\cmd{thislabel}}\marg{\field{useri}}\marg{\encapdisp{textlanguage}{text\cmd{thislanguage}}}\comment{}
+ \ics{glsxtrendfor}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+Once the \ics{forglsentries} loop has found the appropriate
+languages, it's now necessary to iterate over the internal list
+\csfmt{langlist} and set the language:
+\begin{codeenv}
+\ics{forlistloop}\marg{\ics{setotherlanguage}}\marg{\cmd{langlist}}
+\end{codeenv}
+The \abbrstyle{long-short-user} style now needs to be adjusted
+to ensure that it picks up the appropriate language change.
+By default this style checks the \field{useri} field, so this needs
+to be changed to \fieldfmt{translation} by redefining
+\ics{glsxtruserfield}:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtruserfield}}\marg{translation}
+\end{codeenv}
+The command that governs the format of the parenthetical material
+(\ics{glsxtruserparen}) also needs adjusting. I've changed the
+space before the parenthesis to \ics{cs.space} because some of the
+long fields end with a \idx{full-stop} and this corrects the
+spacing. The \fieldfmt{translation} field is in English,
+so this needs to be encapsulated with \icsdisp{textlanguage}{textenglish}
+in case the surrounding text is in a different language.
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtruserparen}}[2]\marg{\comment{}
+ \cs{cs.space}
+ \cs{glsxtrparen}\marg{\idx{param}1\comment{}
+ \cs{ifglshasfield}\marg{\cs{glsxtruserfield}}\marg{\idx{param}2}\marg{,
+ \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\marg{}}\comment{}
+}
+\end{codeenv}
+Next I've defined a convenient command for use in the \catattr{textformat}
+attributes for the custom \code{tug} category:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{tugtextformat}}[1]\marg{\comment{}
+ \cs{glsxtrentryfmt}\marg{\cs{glslabel}}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+This uses \gls{glsxtrentryfmt} to encapsulate the given text
+in the appropriate language command (if provided). When this is set
+as the \catattr{textformat} attribute, it will be used instead of
+\ics{glstextformat}, which means that the entry label can be
+referenced with \cs{glslabel}.
+
+There's a similar command for use in the \catattr{glossnamefont}
+attribute. This is used in the glossary, so the label is referenced
+with \cs{glscurrententrylabel}:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{tugnameformat}}[1]\marg{\comment{}
+ \cs{glsxtrentryfmt}\marg{\cs{glscurrententrylabel}}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+The attributes can now be set to the relevant control sequence name:
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{textformat}}\marg{tugtextformat}
+\cs{glssetcategoryattribute}\marg{tug}\marg{\catattr{glossnamefont}}\marg{tugnameformat}
+\end{codeenv}
+
+The document uses the \glostyle{bookindex} style, which is set in
+the package options:
+\begin{codeenv}
+\cmd{usepackage}\oarg{\styopt{record},
+ \styopt{nostyles},
+ \styopt[bookindex]{stylemods},
+ \styopt[bookindex]{style}
+}\marg{glossaries-extra}
+\end{codeenv}
+The \glostyle{bookindex} style ignores the \field{description} field, so I've
+provided a \idx{postnamehook} to append it in parentheses (with the
+translation, if provided):
+\begin{codeenv}
+\cs{newcommand}\marg{\postnamehook{tug}}\marg{\comment{}
+ \ics{ifglshasdesc}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{cs.space}(\cs{glossentrydesc}\marg{\cs{glscurrententrylabel}}\comment{}
+ \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{, \csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}}}\comment{}
+ \marg{}\comment{}
+ )}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{translation}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{cs.space}(\csdisp{textlanguage}{textenglish}\marg{\cs{glscurrentfieldvalue}})}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+Remember that this hook is included within the \field{name} font
+(provided by the \catattr{glossnamefont} attribute in this case)
+so \csdisp{textlanguage}{textenglish} is again used to switch the language to
+English for the translation.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+xelatex sample-usergroups
+bib2gls --group sample-usergroups
+xelatex sample-usergroups
+xelatex sample-usergroups
+\end{verbatim}
+The two pages of the document are shown in
+\figureref{fig:sample-usergroups.pdf}. Since the entries have all
+been referenced on page~1, the location lists are all simply~\qt{1}.
+
+%\lstinputlisting[firstline=5]{../examples/sample-usergroups.tex}
+\begin{lstlisting}[escapechar=|]
+\documentclass{scrreprt}
+
+\usepackage{fontspec}
+\setmainfont{Linux Libertine O}
+
+\usepackage{polyglossia}
+\setmainlanguage[variant=uk]{english}
+\usepackage{tracklang}
+\usepackage{etoolbox}
+
+\usepackage[record,% use bib2gls
+ nostyles,% don't load default styles
+ stylemods={bookindex},
+ style={bookindex}
+]{glossaries-extra}
+
+\glsaddstoragekey{language}{}{\glsentrylanguage}
+\glsaddstoragekey{translation}{}{\glsentrytranslation}
+
+\setabbreviationstyle[tug]{long-short-user}
+
+\GlsXtrLoadResources[
+ src={usergroups}, % data in usergroups.bib
+ check-end-punctuation={name,short},
+ category=tug
+]
+
+\renewcommand*{\glsxtrifcustomdiscardperiod}[2]{%
+ \ifglshasshort{\glslabel}%
+ {%
+ \glsxtrifwasfirstuse{}%
+ {%
+ \GlsXtrIfFieldUndef{shortendpunc}{\glslabel}{#2}{#1}%
+ }%
+ }%
+ {%
+ \GlsXtrIfFieldUndef{nameendpunc}{\glslabel}{#2}{#1}%
+ }%
+}
+
+\newcommand{\langlist}{}%
+
+\newcommand*{\addfirstlang}[1]{%
+ \TrackLocale{#1}%
+ \edef\thislanguage{%
+ \TrackedLanguageFromDialect\TrackLangLastTrackedDialect}%
+ \IfFileExists{gloss-\thislanguage.ldf}%
+ {%
+ \xifinlist{\thislanguage}{\langlist}{}%
+ {\listxadd{\langlist}{\thislanguage}}%
+ \xGlsXtrSetField{\thislabel}{useri}{text\thislanguage}%
+ \glsxtrendfor
+ }%
+ {}%
+}
+
+\forglsentries{\thislabel}{%
+ \glsxtrifhasfield{translation}{\thislabel}%
+ {%
+ % requires glossaries-extra v1.24
+ \glsxtrforcsvfield{\thislabel}{language}{\addfirstlang}%
+ }%
+ {}%
+}
+
+\forlistloop{\setotherlanguage}{\langlist}
+
+\renewcommand*{\glsxtruserfield}{translation}
+
+\renewcommand*{\glsxtruserparen}[2]{%
+ \
+ \glsxtrparen{#1%
+ \ifglshasfield{\glsxtruserfield}{#2}{,
+ \textenglish{\glscurrentfieldvalue}}{}}%
+}
+
+\newcommand*{\tugtextformat}[1]{%
+ \glsxtrentryfmt{\glslabel}{#1}%
+}
+
+\newcommand*{\tugnameformat}[1]{%
+ \glsxtrentryfmt{\glscurrententrylabel}{#1}%
+}
+
+\glssetcategoryattribute{tug}{textformat}{tugtextformat}
+\glssetcategoryattribute{tug}{glossnamefont}{tugnameformat}
+
+\newcommand{\glsxtrpostnametug}{%
+ \ifglshasdesc{\glscurrententrylabel}%
+ {\ (\glossentrydesc{\glscurrententrylabel}%
+ \glsxtrifhasfield{translation}{\glscurrententrylabel}%
+ {, \textenglish{\glscurrentfieldvalue}}%
+ {}%
+ )}%
+ {%
+ \glsxtrifhasfield{translation}{\glscurrententrylabel}%
+ {\ (\textenglish{\glscurrentfieldvalue})}%
+ {}%
+ }%
+}
+
+\begin{document}
+\chapter{Sample}
+\section{First Use}
+\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}.
+\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}.
+\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}.
+\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}.
+\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}.
+\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}.
+\gls{VietTUG}. \gls{LUGSA}.
+
+\section{Next Use}
+
+\gls{TUG}. \gls{bgTeX}. \gls{latex-br}. \gls{CTeX}.
+\gls{CSTUG}. \gls{DANTE}. \gls{DKTUG}. \gls{EUG}.
+\gls{CervanTeX}. \gls{TirantloTeX}. \gls{GUTenberg}.
+\gls{UKTUG}. \gls{|\greekmono ɛϕτ|}. \gls{MaTeX}. \gls{ITALIC}.
+\gls{ÍsTeX}. \gls{GuIT}. \gls{KTS}. \gls{LTVG}.
+\gls{mxTeX}. \gls{NTG}. \gls{NTUG}. \gls{GUST}. \gls{GUTpt}.
+\gls{VietTUG}. \gls{LUGSA}.
+
+\printunsrtglossaries
+\end{document}
+\end{lstlisting}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-usergroups.pdf}{2}}
+{\caption{\filefmt{sample-usergroups.pdf}}}
+{fig:sample-usergroups.pdf}
+\end{figure}
+
+\filesection{sample-multi1.tex}
+
+This example uses \exfile{bacteria.bib},
+\exfile{markuplanguages.bib}, \exfile{vegetables.bib}, \exfile{minerals.bib},
+\exfile{animals.bib}, \exfile{chemicalformula.bib},
+\exfile{baseunits.bib} and \exfile{derivedunits.bib}.
+Since there's one or more UTF-8 character, the document requires
+UTF-8 support:
+\begin{verbatim}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\end{verbatim}
+
+The aim of this example document is to have a separate glossary
+(without number lists) for each type of data (bacteria, markup
+languages, vegetables, minerals, animals, chemical formula, base
+units and derived units) and also an
+index listing all referenced entries with number lists as well as
+aliased entries that haven't explicitly been used but the
+cross-reference term as been indexed. This requires:
+\begin{codeenv}
+\csopt[recorded and deps and see]{selection}
+\end{codeenv}
+to ensure the aliased entries are selected.
+
+Since I don't need the default \code{main} glossary (I'm providing
+my own custom glossaries) I've used the \styopt{nomain} option to
+suppress its automatic creation, but I do want the \code{index}
+glossary so I've used the \styopt{index} package option. As with the
+other examples, I've used \styopt{nostyles} to suppress the creation
+of the default styles and used \styopt{stylemods} to load the
+particular style packages that I need and use
+\sty{glossaries-extra-stylemods} to patch them. The index needs to
+be in an unnumbered chapter, which is the default for book-like
+styles, but I want the other glossaries in unnumbered sections so
+I've used the \styopt{section} option. I just need to remember to
+switch this before displaying the index:
+\begin{codeenv}
+\cmd{usepackage}\oarg{\styopt{record},\comment{use bib2gls}
+ \styopt{section},\comment{use \ics{section*} for glossary headings}
+ \styopt{postdot},\comment{insert dot after descriptions in glossaries}
+ \styopt{nomain},\comment{don't create 'main' glossary}
+ \styopt{index},\comment{create 'index' glossary}
+ \styopt{nostyles},\comment{don't load default styles}
+\comment{load and patch required style packages:}
+ \styopt[list,mcols,tree,bookindex]{stylemods}
+}\marg{glossaries-extra}
+\end{codeenv}
+The remaining glossaries need defining:
+\begin{codeenv}
+\cs{newglossary*}\marg{bacteria}\marg{Bacteria}
+\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages}
+\cs{newglossary*}\marg{vegetable}\marg{Vegetables}
+\cs{newglossary*}\marg{mineral}\marg{Minerals}
+\cs{newglossary*}\marg{animal}\marg{Animals}
+\cs{newglossary*}\marg{chemical}\marg{Chemical Formula}
+\cs{newglossary*}\marg{baseunit}\marg{SI Units}
+\cs{newglossary*}\marg{derivedunit}\marg{Derived Units}
+\end{codeenv}
+As with \exfile{sample-bacteria.tex} and \exfile{sample-markuplanguages.tex}
+I need to set the abbreviation styles before the abbreviations are
+defined:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
+\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
+\end{codeenv}
+Unlike the \exfile{sample-markuplanguages.tex} example, I'm not interested
+in tagging the initials in this case, but I still want to change the
+way the \field{name} field is set with the
+\abbrstyle{long-short-desc} abbreviation style:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
+ \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space}
+ \cs{glsxtrparen}\marg{\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}}\comment{}
+}
+\end{codeenv}
+Remember that this also needs to be set before the abbreviations are
+defined. The \catattr{textformat} and \catattr{glossnamefont}
+attributes may be set after definition:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
+\end{codeenv}
+The description font also needs to be set since this will contain
+the long form:
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
+\end{codeenv}
+
+The \code{markuplanguage} glossary contains descriptions and some
+long names, so it's better suited to the \glostyle{altlist} style,
+in which case the descriptions would look better if they started
+with a capital letter:
+\begin{codeenv}
+\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc}
+\end{codeenv}
+Remember that the \glostyle{altlist} style uses the
+\env{description} environment, which is governed by the document
+class (and may be modified by list-related packages). In this case,
+one of the KOMA-Script classes is used, so the list items are
+typeset in sans-serif.
+
+There are various ways of dealing with the duplicated data in the
+index, such as using the \csopt{secondary} option or having a
+separate resource set with a copy \csopt{action}. In this case, I've
+decided to use a dual entry system. Since the entries aren't defined
+using any dual types, I've used \csopt{entry-type-aliases} to
+make \bibgls\ treat them as though they were, and I also need to
+alias the custom \atentryfmt{chemical}, \atentryfmt{unit} and
+\atentryfmt{measurement} entry types:
+\begin{codeenv}
+\csopt[
+ abbreviation=dualindexabbreviation,
+ entry=dualindexentry,
+ symbol=dualindexsymbol,
+ unit=dualindexsymbol,
+ measurement=dualindexsymbol,
+ chemical=dualindexsymbol
+ ]{entry-type-aliases}
+\end{codeenv}
+Note that I haven't aliased the \atentry{index} types as I only want
+these in the index and not replicated in a separate glossary.
+
+The primary entries for the \atentry{dualindexabbreviation} type
+ignore the short form. It would be useful to store it. This could be
+done by copying the \field{short} field with
+\csopt{replicate-fields}. For example,
+\csopt[\field{short}=\field{symbol}]{replicate-fields}. However, this will cause the
+\field{symbol} field to be set for both the primary and dual
+entries, which will cause an unwanted duplication if the dual
+entries are displayed using a glossary style that shows the
+\field{symbol} field. Another field (such as \field{user1}) could be
+used instead or \gls{bibglsnewdualindexabbreviation} could be
+defined before \gls{GlsXtrLoadResources}:
+\begin{codeenv}
+\cs{newcommand}\marg{\gls{bibglsnewdualindexabbreviation}}[7]\marg{\comment{}
+ \cs{longnewglossaryentry*}\marg{\idx{param}1}\marg{\comment{}
+ \field{name}=\marg{\cs{protect}\gls{bibglsuselongfont}\marg{\idx{param}4}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
+ \field{symbol}=\marg{\cs{protect}\gls{bibglsuseabbrvfont}\marg{\idx{param}5}\marg{\cs{glscategory}\marg{\idx{param}2}}},\comment{}
+ \field{category}=\marg{index},\idx{param}3}\marg{}\comment{}
+}
+\end{codeenv}
+However, this will affect all \atentry{dualindexabbreviation} entry
+types, but it's not necessary for the bacteria abbreviations.
+Instead it's simpler to just keep a record of the dual label so that
+the short form can be obtained from the dual entry:
+\begin{codeenv}
+\csopt{dual-field}
+\end{codeenv}
+
+By default, the \atentry{dualindexabbreviation} entry type falls back on the
+\field{short} field if the \field{name} is omitted. In this case I
+want it to fall back on the \field{long} field instead.
+\begin{codeenv}
+\csopt[long]{abbreviation-name-fallback}
+\end{codeenv}
+Remember that the sort fallback for abbreviations is still \field{short} (but can be
+changed with \csopt{abbreviation-sort-fallback}), but I've changed
+the sort fallback for symbols:
+\begin{codeenv}
+\csopt[name]{symbol-sort-fallback}
+\end{codeenv}
+I also need to alias the custom fields (especially for those in the
+\exfile{chemicalformula.bib}, \exfile{baseunits.bib} and
+\exfile{derivedunits.bib} files):
+\begin{codeenv}
+\csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{formula}=\field{symbol},
+ \fieldfmt{chemicalname}=\field{name},
+ \fieldfmt{unitname}=\field{name},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{description}
+]{field-aliases}
+\end{codeenv}
+There's a slight problem here. This ensures that the entries defined
+in \exfile{chemicalformula.bib} have a \field{name} and
+\field{symbol} field, which are swapped round for the dual
+(according to the default \csopt{dual-indexsymbol-map}) but these
+entries don't have a \field{description} field. Since I'd like to
+use the \glostyle{mcolalttreegroup} style, this will end up with
+the odd appearance of the formula (stored in the \field{name} field for the
+dual) followed by the chemical name (stored in the \field{symbol}
+field for the dual) in parenthesis. This is the default \meta{name}
+(\meta{symbol}) \meta{description} format for the style. I've fixed
+this by locally redefining \ics{glsxtralttreeSymbolDescLocation} for
+just that glossary:
+\begin{codeenv}
+\cs{printunsrtglossary*}\oarg{\printglossopt[chemical]{type},\printglossopt[mcolalttreegroup]{style}}
+\marg{\comment{}
+ \cs{renewcommand}\cs{glsxtralttreeSymbolDescLocation}[2]\marg{\comment{}
+ \ics{glossentrysymbol}\marg{\idx{param}1}\cs{glspostdescription}\ics{glsxtrAltTreePar}
+ }\comment{}
+ \cs{renewcommand}*\marg{\cs{glstreenamefmt}}[1]\marg{\idx{param}1}\comment{}
+ \cs{renewcommand}*\marg{\cs{glstreegroupheaderfmt}}[1]\marg{\cs{textbf}\marg{\idx{param}1}}\comment{}
+}
+\end{codeenv}
+I've also redefined \cs{glstreenamefmt} to prevent the names
+appearing in bold, which means I also need to redefine
+\cs{glstreegroupheaderfmt} to keep the headers bold.
+
+All the \atentryfmt{dualindex\meta{type}} entry types provide a primary
+entry that behaves like \atentry{index}. The secondary behaves like
+\atentryfmt{\meta{type}}. This means that the primaries are
+conveniently gathered together with all the unaliased \atentry{index}
+entries, so the primary entry type needs to be set to \code{index}:
+\begin{codeenv}
+\csopt[index]{type}
+\end{codeenv}
+The dual entry type depends on the entry's category. Since I've
+defined my custom glossaries with a label that matches the
+custom \fieldfmt{identifier} field, I can both alias this custom field
+to the \field{category} field and also set \csopt{dual-type} so that
+it matches the category:
+\begin{codeenv}
+\csopt[\fieldfmt{identifier}=\field{category}]{field-aliases},
+\csopt[same as category]{dual-type}
+\end{codeenv}
+The primary entries (in the \code{index} glossary) need to be sorted
+alphabetically, and since the document is in English I'm sorting
+according to that language (identified by the language code
+\code{en}), but I also want to make sure that all the primary
+entries are sorted by the \field{name} field to avoid discrepancies
+in the fallback value for the \field{sort} field:
+\begin{codeenv}
+\csopt[en]{sort},
+\csopt[name]{sort-field}
+\end{codeenv}
+With \csopt[long]{abbreviation-name-fallback} now set,
+this means that \emph{Coxiella burnetii} comes after
+\emph{Clostridium tetani} in the index. I haven't changed the sort
+field for the dual entries, so in that case the
+\csopt{abbreviation-sort-fallback} and \csopt{symbol-sort-fallback}
+settings will be used with the duals. This means that
+\emph{C.\ burnetii} is between \emph{C.\ botulinum} and \emph{C.\
+perfringens} rather than after \emph{C.\ tetani}.
+
+I'd like to sort the dual entries according to a letter-number rule
+(as for the above \exfile{sample-chemical.tex} and \exfile{sample-units3.tex}
+examples)
+but this would order \qt{b\'ilinite} after \qt{biotite} in the
+\code{minerals} glossary, so instead I'm also using the English sort
+rule for the duals, but with the numbers padded:
+\begin{codeenv}
+\csopt[en]{dual-sort},
+\csopt[2]{dual-sort-number-pad},
+\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 \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}
+glossary, so instead I've used:
+\begin{codeenv}
+\csopt[upper-upper-word]{dual-break-at}
+\end{codeenv}
+This now puts \qt{sea lion} before \qt{seal}. Unfortunately the word
+break points will cause a break at the markers used to indicate
+positive and negative numbers that are inserted with
+\csopt{dual-sort-number-pad}, so these need to be changed to
+something that won't cause them to be discarded:
+\begin{codeenv}
+\csopt[0]{dual-sort-pad-minus},
+\csopt[1]{dual-sort-pad-plus}
+\end{codeenv}
+
+The document loads \sty{hyperref} which means that all the \cs{gls}
+references will create hyperlinks. Since the primaries are in the
+index, the default prefixes mean that, for example,
+\code{\cs{gls}\marg{svg}} links to the \qt{scalable vector graphics} item in
+the index rather than to the abbreviation \qt{SVG} in the
+\code{markuplanguage} glossary. There are two alternatives: change
+\code{\cs{gls}\marg{svg}} to \code{\cs{gls}\marg{dual.svg}} or change the
+default prefixes, which is the more convenient approach and is the one used
+here:
+\begin{codeenv}
+\csopt[idx.]{label-prefix},
+\csopt[\empty]{dual-prefix}
+\end{codeenv}
+Now \code{\cs{gls}\marg{svg}} refers to the dual abbreviation \qt{SVG} and
+\code{\cs{gls}\marg{idx.svg}} refers to the primary entry \qt{scalable vector
+graphics}. Unfortunately this means that the records created with
+\code{\cs{gls}\marg{svg}} now refer to the dual abbreviation and will end up
+being displayed in the glossary instead of the index. This can be
+fixed with:
+\begin{codeenv}
+\csopt[primary]{combine-dual-locations}
+\end{codeenv}
+Which transfers the dual entry locations to the corresponding
+primary.
+
+The other problem is the cross-references in the \field{description}
+fields. Since the labels don't start with \qt{\idprefix{dual}} \bibgls\
+will assume they refer to the primary entries, which means that
+\qt{\idprefixfmt{idx}} (the value of \csopt{label-prefix}) will be
+inserted. This means that they'll link to the index rather than the
+glossary entry. It also means that the cross-references where the
+dual is an abbreviation won't behave like an abbreviation as the
+reference is to the primary (non-abbreviation) entry. This can be
+fixed by setting \csopt{cs-label-prefix} to the same value as
+\csopt{dual-prefix}:
+\begin{codeenv}
+\csopt[\empty]{cs-label-prefix}
+\end{codeenv}
+The index is displayed using the \glostyle{bookindex} style. This
+doesn't show the description or symbol by default, but it would be
+useful to include the symbol in parentheses after the name. This can
+be done by redefining \ics{glsxtrbookindexname}:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{}
+}
+\end{codeenv}
+However the chemical forumlae look a little odd in parentheses
+(especially those that contain parenthetical parts) but this can be
+fixed by adding a category check:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
+ \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
+ \marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+Unfortunately \ics{glossentrysymbol} doesn't pick up the
+\catattr{glossnamefont} attribute, so if the short form of the
+abbreviations is saved in the \field{symbol} field, using one of the
+methods discussed above, then the custom \csfmt{bacteriafont} won't
+be applied. A simple solution is to use \ics{glossentrynameother}
+instead:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
+ \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
+ \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+However, since I decided not to store the short form in the
+\field{symbol} field and just saved the dual entry label instead, I
+need to lookup the short form from the dual entry:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
+ \marg{, \ics{glossentrysymbol}\marg{\idx{param}1}}\comment{}
+ \marg{\cs{space}(\ics{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
+ }\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{markuplanguage}\comment{}
+ \marg{\comment{}
+ \cs{glsxtrifhasfield}\marg{\field{short}}\marg{\cs{glsxtrusefield}\marg{\idx{param}1}\marg{\field{dual}}}\comment{}
+ \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+Not all of the markup languages are abbreviations so this uses
+\ics{glsxtrifhasfield} to check if the \field{short} field is set.
+The dual entry's label is easily obtained because \csopt{dual-field}
+has provided the \fieldfmt{dual} internal field and set it to the
+corresponding label.
+
+It's sometimes useful for the index to include a reference to the
+term's definition. This can be done by making use of
+\idx{glsextrapostnamehook}, which can be redefined before the
+glossaries to automatically record each entry:
+\begin{codeenv}
+\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{\cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}}
+\end{codeenv}
+This needs to be redefined to ignore its argument before the index,
+to avoid the redundant index record:
+\begin{codeenv}
+\cs{renewcommand}\marg{\cs{glsextrapostnamehook}}[1]\marg{}
+\end{codeenv}
+Remember that if any records are added within a glossary, an extra
+\LaTeX\ and \bibgls\ call are required to ensure that the location list
+is correct, so the document build is:
+\begin{verbatim}
+pdflatex sample-multi1
+bib2gls --group sample-multi1
+pdflatex sample-multi1
+bib2gls --group sample-multi1
+pdflatex sample-multi1
+\end{verbatim}
+The complete document code is listed below.
+The resulting document is shown in \figureref{fig:sample-multi1.pdf}
+and \figureref{fig:sample-multi1.pdf2}.
+
+\lstinputlisting[firstline=5]{../examples/sample-multi1.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-multi1.pdf}{4}}
+{\caption{\filefmt{sample-multi1.pdf} (pages~1 to~4)}}
+{fig:sample-multi1.pdf}
+\end{figure}
+
+\begin{figure}
+\figcontents
+{\pdftwocol[5]{../examples/sample-multi1.pdf}{8}}
+{\caption{\filefmt{sample-multi1.pdf} (pages~5 to 8)}}
+{fig:sample-multi1.pdf2}
+\end{figure}
+
+\filesection{sample-multi2.tex}
+
+This example is an alternative approach to
+\exfile{sample-multi1.tex}. Instead of using dual entry types to
+define entries that appear in both a glossary and the index, this
+example makes use of \csopt{record-label-prefix} to reselect the
+recorded entries for the index. This is more complicated but it
+allows the entries that have natural word ordering to use a locale
+sort method while the entries that are symbolic can use one of the
+letter-number sort methods.
+
+This document uses some additional \ext{bib} files to the previous
+example, so it has extra glossaries, which all need to be defined:
+\begin{codeenv}
+\cs{newglossary*}\marg{bacteria}\marg{Bacteria}
+\cs{newglossary*}\marg{markuplanguage}\marg{Markup Languages}
+\cs{newglossary*}\marg{vegetable}\marg{Vegetables}
+\cs{newglossary*}\marg{mineral}\marg{Minerals}
+\cs{newglossary*}\marg{animal}\marg{Animals}
+\cs{newglossary*}\marg{chemical}\marg{Chemical Formula}
+\cs{newglossary*}\marg{baseunit}\marg{SI Units}
+\cs{newglossary*}\marg{measurement}\marg{Measurements}
+\cs{newglossary*}\marg{film}\marg{Films}
+\cs{newglossary*}\marg{book}\marg{Books}
+\cs{newglossary*}\marg{person}\marg{People}
+\cs{newglossary*}\marg{mediacontrol}\marg{Media Control Symbols}
+\cs{newglossary*}\marg{information}\marg{Information Symbols}
+\cs{newglossary*}\marg{weather}\marg{Weather Symbols}
+\end{codeenv}
+Note that this is a total of 15~glossaries (including the
+\code{index}). With the basic \ics{cs.makeglossaries} method, this would
+require 16 write registers (including the write register used to
+create the indexing style file), and a total of $15\times3 + 1 = 46$
+associated files. (This doesn't include the standard \ext{aux} file
+and the \ext{out} file created by \sty{hyperref}.) With \bibgls, no
+additional write registers are required and the number of associated
+\bibgls\ files is equal to the number of resource commands plus the
+transcript file (in this example, $9+1=10$).
+
+Since this document requires \exfile{people.bib}, \exfile{books.bib}
+and \exfile{films.bib} it also requires the files that
+supply the definitions of the custom commands
+(\exfile{no-interpret-preamble.bib} and either
+\exfile{interpret-preamble.bib} or \exfile{interpret-preamble2.bib})
+to ensure the custom commands are provided both for the document and
+for \bibgls's interpreter.
+
+The first resource set to be loaded simply reads
+\exfile{no-interpret-preamble.bib} with the preamble interpreter
+switched off:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[no-interpret-preamble]{src},
+ \csopt[false]{interpret-preamble}
+}
+\end{codeenv}
+This ensures that \LaTeX\ can pick up the provided commands and
+prevents them from being added to the interpreter.
+
+The \exfile{people.bib} file is the next to be loaded with
+\exfile{interpret-preamble.bib}. This is loaded separately from the
+other resources as this needs the \field{name} field to be copied to
+\field{first} (if not already set), as in the
+\exfile{sample-people.tex} file. By having a separate resource set,
+this setting doesn't affect the other entries. I've also converted
+the date fields so that I can customise the format in the document.
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[interpret-preamble,people]{src},
+ \csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{born}=\field{user1},
+ \fieldfmt{died}=\field{user2},
+ \fieldfmt{othername}=\field{user3}
+ ]{field-aliases},
+ \csopt[\field{name}=\marg{\field{first}}]{replicate-fields},
+ \csopt[person]{type},
+ \csopt[false]{save-locations}
+ \csopt[\field{user1},\field{user2}]{date-fields},
+ \csopt[d MMM y G]{date-field-format}
+}
+\end{codeenv}
+As with the \exfile{sample-people.tex} document, I need to use the
+\longarg{break-space} switch to convert the \idx{nbspchar} to a
+normal breakable space so that it matches the given format. I've
+loaded the \sty{datetime2} package:\footnote{The
+\styoptfmt{en-GB} option to \sty{datetime2} also requires that
+\styfmt{datetime2-english} must be installed.}
+\begin{verbatim}
+\usepackage[en-GB]{datetime2}
+\end{verbatim}
+so that I can use \ics{DTMdisplaydate} to adjust the formatting:
+\begin{codeenv}
+\cs{newcommand}*\marg{\gls{bibglsdate}}[7]\marg{\cs{DTMdisplaydate}\marg{\idx{param}1}\marg{\idx{param}2}\marg{\idx{param}3}\marg{\idx{param}4}}
+\end{codeenv}
+This needs to go before the \idx{resourceset} is loaded. Note that
+the \styoptfmt{en-GB} option identifies the document locale as
+\code{en-GB} (since there are no language packages loaded).
+
+Note that unlike \exfile{sample-people.tex} which had
+\csopt[people]{category}, this document obtains the \field{category} field
+from the custom \fieldfmt{identifier} field, which in this case
+has the value \code{person}. This means that the category hooks from
+\exfile{sample-people.tex} need to be renamed to reflect the
+different category label:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postlinkhook{person}}{\comment{}
+ \cs{glsxtrifwasfirstuse}
+ \marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glslabel}}\comment{}
+ \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\strut
+\cs{newcommand}*\marg{\postnamehook{person}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user3}}\marg{\cs{glscurrententrylabel}}\comment{}
+ \marg{\cs{space}(\cs{glscurrentfieldvalue})}\comment{}
+ \marg{}\comment{}
+}
+\strut
+\cs{newcommand}*\marg{\postdeschook{person}}\marg{\comment{}
+ \cs{ifglshasfield}\marg{\field{user1}}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{born}
+ \cs{space}(\cs{glscurrentfieldvalue}\cs{comma}-{}-\cs{comma}\comment{}
+ \cs{ifglshasfield}\marg{\field{user2}}\marg{\cs{glscurrententrylabel}}
+ \marg{\comment{died}
+ \cs{glscurrentfieldvalue}
+ }\comment{}
+ \marg{}\comment{}
+ )\comment{}
+ }\comment{}
+ \marg{}\comment{}
+}
+\end{codeenv}
+The other \ext{bib} files that require locale sorting can now be
+loaded, but remember that the abbreviation style settings must be
+set first since this resource set includes abbreviations:
+\begin{codeenv}
+\cs{setabbreviationstyle}\oarg{bacteria}\marg{\abbrstyle{long-only-short-only}}
+\cs{setabbreviationstyle}\oarg{markuplanguage}\marg{\abbrstyle{long-short-desc}}
+\strut
+\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
+ \cs{protect}\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}\cs{space}
+ \glsxtrparen{\glslongfont{\the\glslongtok}}%
+}
+\end{codeenv}
+Now the resource set can be loaded:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[bacteria,markuplanguages,vegetables,
+ minerals,animals,books,films]{src},
+ \csopt[\fieldfmt{identifier}=\field{category}]{field-aliases},
+ \csopt[same as category]{type},
+ \csopt[false]{save-locations}
+}
+\end{codeenv}
+The semantic markup command and attributes are as for
+\exfile{sample-multi1.tex}:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{bacteriafont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{textformat}}\marg{bacteriafont}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossnamefont}}\marg{bacteriafont}
+\cs{glssetcategoryattribute}\marg{bacteria}\marg{\catattr{glossdescfont}}\marg{bacteriafont}
+\cs{glssetcategoryattribute}\marg{markuplanguage}\marg{\catattr{glossdesc}}\marg{firstuc}
+\end{codeenv}
+Similarly for the books:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{bookfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{textformat}}\marg{bookfont}
+\cs{glssetcategoryattribute}\marg{book}\marg{\catattr{glossnamefont}}\marg{bookfont}
+\end{codeenv}
+(as for \exfile{sample-media.tex}) and for films:
+\begin{codeenv}
+\cs{newcommand}\marg{\cmd{filmfont}}[1]\marg{\cs{emph}\marg{\idx{param}1}}
+\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{textformat}}\marg{filmfont}
+\cs{glssetcategoryattribute}\marg{film}\marg{\catattr{glossnamefont}}\marg{filmfont}
+\end{codeenv}
+
+Next come the chemical formulae:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[chemicalformula]{src},
+ \csopt[chemical=symbol]{entry-type-aliases},
+ \csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{formula}=\field{name},
+ \fieldfmt{chemicalname}=\field{description}
+ ]{field-aliases},
+ \csopt[chemical]{type},
+ \csopt{set-widest},
+ \csopt[letternumber-case]{sort},
+ \csopt[\field{name}]{symbol-sort-fallback},
+ \csopt[false]{save-locations}
+}
+\end{codeenv}
+and the \idxpl{SIunit}, which are now combined into a single
+glossary:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[baseunits,derivedunits]{src},
+ \csopt[\fieldfmt{measurement}=\field{symbol},\fieldfmt{unit}=\field{symbol}]{entry-type-aliases},
+ \csopt[
+ \fieldfmt{unitname}=\field{description},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{name}
+ ]{field-aliases},
+ \csopt[measurement]{category},
+ \csopt[measurement]{type},
+ \csopt{set-widest},
+ \csopt[\field{name}]{symbol-sort-fallback},
+ \csopt[false]{save-locations}
+}
+\end{codeenv}
+Here the \field{name} field is obtained from the custom
+\fieldfmt{measurement} field. Since this contains a word, the
+default locale sort is appropriate. I've locally redefined
+\ics{glsxtralttreeSymbolDescLocation} to place the symbol in
+parentheses after the description:
+\begin{codeenv}
+\cs{printunsrtglossary*}\oarg{\printglossopt[measurement]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}}
+\marg{\comment{}
+ \cs{renewcommand}\marg{\cs{glsxtralttreeSymbolDescLocation}}[2]\marg{\comment{}
+ \cs{glossentrydesc}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\marg{\cs{space}(\cs{glossentrysymbol}\marg{\idx{param}1})}\marg{}\comment{}
+ \cs{glspostdescription}
+ \cs{glsxtrAltTreePar}
+ }\comment{}
+}
+\end{codeenv}
+
+The base units are replicated in the \code{baseunit} glossary, this
+time with the \field{name} field obtained from the custom
+\fieldfmt{unitsymbol} field. This means that I need to find a way to
+prevent duplicate labels. The simplest method is to use
+\csopt{duplicate-label-suffix}:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[baseunits]{src},
+ \csopt[unit=symbol]{entry-type-aliases},
+ \csopt[
+ \fieldfmt{unitname}=\field{description},
+ \fieldfmt{unitsymbol}=\field{name}
+ ]{field-aliases},
+ \csopt[measurement]{category},
+ \csopt[baseunit]{type},
+ \csopt[.copy]{duplicate-label-suffix},
+ \csopt[\field{name}]{symbol-sort-fallback},
+ \csopt[false]{save-locations}
+}
+\end{codeenv}
+I can't use \csopt{set-widest} here as it won't pick up the modified
+label and will instead use the label from the original entry.
+Instead I've used \cs{glsFindWidestTopLevelName} to find it:
+\begin{codeenv}
+\cs{printunsrtglossary*}\oarg{\printglossopt[baseunit]{type},\printglossopt[alttree]{style},\printglossopt{nogroupskip}}
+\marg{\comment{}
+ \cs{glsFindWidestTopLevelName}\oarg{baseunit}\comment{}
+}
+\end{codeenv}
+
+The text symbols from \exfile{miscsymbols.bib} are all loaded in a
+single \idx{resourceset}, where the \field{type} field can be
+obtained from the \field{category}, which in turns is obtained from
+the custom \fieldfmt{identifier} field. Since \bibgls\ doesn't
+recognise any of the symbol commands, I'm sorting according to the
+\field{description} field. (Even if \bibgls\ could determine a
+Unicode value for each of the symbols, sorting by the description
+makes more sense in this case.)
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[miscsymbols]{src},
+ \csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{icon}=\field{name},
+ \fieldfmt{icondescription}=\field{description}
+ ]{field-aliases},
+ \csopt[icon=symbol]{entry-type-aliases},
+ \csopt[same as category]{type},
+ \csopt[\field{description}]{sort-field},
+ \csopt[false]{save-locations},
+ \csopt{set-widest}
+}
+\end{codeenv}
+
+Finally, all recorded and cross-referenced terms are needed for the
+index. This includes entries that have already been defined in the
+earlier \idxpl{resourceset} (so a guard against duplicates is
+necessary) but it also includes entries from the \exfile{terms.bib}
+file that haven't yet been dealt with. I'd like the index to start
+with a \idx{symbolgroup} containing the icons from
+\exfile{miscsymbols.bib}. This needs to be dealt with separately from
+the rest of the index to keep them together in a single group:
+\begin{codeenv}
+\gls{GlsXtrLoadResources}\oarg{
+ \csopt[miscsymbols]{src},
+ \csopt[recorded no deps]{selection},
+ \csopt[.copy]{duplicate-label-suffix},
+ \csopt[icon=index]{entry-type-aliases},
+ \csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{icondescription}=\field{symbol},
+ \fieldfmt{icon}=\field{name}
+ ]{field-aliases},
+ \csopt[index]{type},
+ \csopt[\field{symbol}]{sort-field},
+ \csopt[glssymbols]{group}
+}
+\end{codeenv}
+Since I know that there are no parents or cross-references in this
+set of entries I've used \csopt[recorded no deps]{selection} to skip
+the dependency checks. In this \idx{resourceset}, the \field{name}
+field has the symbol command (obtained from the custom
+\fieldfmt{icon} field), and the \field{symbol} field has the symbol
+description (obtained from the custom \fieldfmt{icondescription}
+field), which is used as the sort field. I've set the \field{group}
+label to \code{glssymbols}, which keeps all these entries in a
+single group and the title will be obtained from
+\ics{glssymbolsgroupname}.
+
+Before loading the final \idx{resourceset} \ics{glsxtrlongshortdescname} needs
+to be changed
+so that the abbreviations using the \abbrstyle{long-short-desc}
+style (that is, the abbreviations with the \field{category} set to
+\code{markuplanguage}) have the \field{name} field set to
+\meta{long} (\meta{short}):
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrlongshortdescname}}\marg{\comment{}
+ \cs{protect}\cs{glslongfont}\marg{\cs{the}\cs{glslongtok}}\cs{space}
+ \cs{glsxtrparen}\marg{\cs{glsabbrvfont}\marg{\cs{the}\cs{glsshorttok}}}\comment{}
+}
+\end{codeenv}
+The \abbrstyle{long-only-short-only} style has a similar command,
+but it was only introduced to \sty{glossaries-extra} version 1.25:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\ics{glsxtronlyname}}{\comment{}
+ \cs{protect}\cs{glsabbrvonlyfont}\marg{\cs{the}\cs{glslongtok}}\comment{}
+}
+\end{codeenv}
+
+The abbreviations all need to be sorted according to the long form:
+\begin{codeenv}
+\csopt[\field{long}]{abbreviation-sort-fallback}
+\end{codeenv}
+The custom entry types and fields again need to be aliased
+\begin{codeenv}
+\csopt[
+ chemical=index,
+ measurement=entry,
+ unit=dualentry,
+ icon=index
+]{entry-type-aliases},
+\csopt[
+ \fieldfmt{identifier}=\field{category},
+ \fieldfmt{formula}=\field{symbol},
+ \fieldfmt{chemicalname}=\field{name},
+ \fieldfmt{unitname}=\field{description},
+ \fieldfmt{unitsymbol}=\field{symbol},
+ \fieldfmt{measurement}=\field{name},
+ \fieldfmt{icon}=\field{symbol},
+ \fieldfmt{icondescription}=\field{name}
+ ]{field-aliases}
+\end{codeenv}
+The chemical formulae and icons are now defined using
+\atentry{index} with the \field{name} field set to a word form
+(chemical name and icon description). This means
+they're appropriate for alphabetical sorting. (Both \atentry{entry}
+and \atentry{symbol} require the \field{description} field, which is
+why I've aliased \atentryfmt{chemical} and \atentryfmt{icon}
+to \atentry{index} here.) The custom \atentryfmt{measurement} entry
+type has a \field{description} field (obtained from
+\fieldfmt{unitname}), so that's aliased to \atentry{entry} as again
+the \field{name} field is suitable for alphabetical sorting.
+
+I've aliased \atentryfmt{unit} to \atentry{dualentry}
+rather than \atentry{symbol} as I want both the unit name and the
+measurement in the index and I've combined their location lists:
+\begin{codeenv}
+\csopt[both]{combine-dual-locations}
+\end{codeenv}
+Both primary and dual entries need to go in the \code{index}
+glossary:
+\begin{codeenv}
+\csopt[index]{type},
+\csopt[index]{dual-type}
+\end{codeenv}
+
+All \ext{bib} files used in the previous \idxpl{resourceset} are needed
+as well as the \exfile{terms.bib} file:
+\begin{codeenv}
+\csopt[terms,bacteria,markuplanguages,vegetables,minerals,
+ animals,chemicalformula,baseunits,derivedunits,people,
+ films,books,miscsymbols]{src}
+\end{codeenv}
+but this time I also want to select entries that haven't been
+recorded but have a cross-reference to a recorded entry:
+\begin{codeenv}
+\csopt{selection}[recorded and deps and see]
+\end{codeenv}
+Again it's necessary to provide a way to avoid duplicate entry
+labels, which can be done with
+\begin{codeenv}
+\csopt[.copy]{duplicate-label-suffix},
+\end{codeenv}
+as above. However, this will cause the cross-references (from the
+\field{alias} fields) to link to the glossary rather than the index.
+This may or may not confuse the reader. For consistency, it may be
+more suitable to have the cross-reference in the index link to the
+aliased entry in the index rather than in the glossary. I've
+therefore instead used:
+\begin{codeenv}
+ \csopt[idx.]{label-prefix},
+ \csopt[idx.]{record-label-prefix},
+\end{codeenv}
+This means that the entries defined in \exfile{terms.bib} need to be
+referenced with this prefix.
+
+All instances of \cs{gls} will link to the original entry, so all
+entries except for those in the \exfile{terms.bib} file will link to
+the relevant glossary. Those in the \exfile{terms.bib} file will
+link to the index. It's possible to disable the hyperlinks for those
+entries, but the reader may find it useful to jump to the index to
+look up other locations for that entry in the document.
+
+To deal with the identical book and film titles, I'm again using the
+\field{category} to resolve identical sort values:
+\begin{codeenv}
+\csopt[\field{category}]{identical-sort-action}
+\end{codeenv}
+For the people who have a \field{first} field, I've decided that
+this would be more appropriate for the index as it's more compact
+than the \field{name}, so here I've done the reverse to earlier and copied the
+\field{first} field (if supplied) into the \field{name} field, but
+since the \field{name} field is already provided the override
+setting needs to be on:
+\begin{codeenv}
+\csopt{replicate-override},
+\csopt[\field{first}=\field{name}]{replicate-fields}
+\end{codeenv}
+As with \exfile{sample-people.tex} I've provided some custom
+commands to make it easier to locally redefine \gls{sortname} and
+\gls{sortvonname}:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cmd{swaptwo}}[2]\marg{\idx{param}2, \idx{param}1}
+\cs{newcommand}*\marg{\cmd{swapthree}}[3]\marg{\idx{param}2 \idx{param}3, \idx{param}1}
+\end{codeenv}
+I've redefined \ics{glsxtrbookindexname} in a similar manner to
+\exfile{sample-multi1.tex} but it has some modifications:
+\begin{codeenv}
+\cs{renewcommand}*\marg{\cs{glsxtrbookindexname}}[1]\marg{\comment{}
+ \cs{glossentryname}\marg{\idx{param}1}\comment{}
+ \cs{ifglshassymbol}\marg{\idx{param}1}\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{chemical}\comment{}
+ \marg{, \cs{glossentrysymbol}\marg{\idx{param}1}}\comment{}
+ \marg{\cs{space}(\cs{glossentrynameother}\marg{\idx{param}1}\marg{\field{symbol}})}\comment{}
+ }\comment{}
+ \marg{\comment{}
+ \cs{glsifcategory}\marg{\idx{param}1}\marg{film}\comment{}
+ \marg{\cs{cs.space}(film)}\comment{}
+ \marg{}\comment{}
+ }\comment{}
+}
+\end{codeenv}
+This appends \qt{(film)} to film names. I've chosen this method
+rather than using the \idx{postnamehook} as I only want this in the
+index and not in the list of films.
+
+For some of the entries that are referenced in the document, I've
+appended information in parentheses:
+\begin{codeenv}
+\cs{gls}\marg{Al2SO43} (\ics{glsdesc}\marg{Al2SO43})
+\end{codeenv}
+This is all right for odd instances, but if this always needs to be done
+on first use, then it's better to use the \idx{postlinkhook}, which
+is what I've done for the icons for comparison:
+\begin{codeenv}
+\cs{newcommand}*\marg{\postlinkhook{mediacontrol}}\marg{\comment{}
+ \ics{glsxtrpostlinkAddDescOnFirstUse}
+}
+\strut
+\cs{newcommand}*\marg{\postlinkhook{information}}\marg{\comment{}
+ \cs{glsxtrpostlinkAddDescOnFirstUse}
+}
+\strut
+\cs{newcommand}*\marg{\postlinkhook{weather}}\marg{\comment{}
+ \cs{glsxtrpostlinkAddDescOnFirstUse}
+}
+\end{codeenv}
+
+I've also provided some custom commands to make it easier to reference
+entries without worrying about the prefixes:
+\begin{codeenv}
+\cs{newcommand}\marg{\csfmt{unit}}\marg{\ics{glssymbol}}
+\cs{newcommand}\marg{\csfmt{measurement}}\marg{\cs{gls}}
+\gls{glsxtrnewgls}\marg{film.}\marg{\csfmt{film}}
+\end{codeenv}
+
+As with \exfile{sample-multi1.tex}, it would be useful to include
+the page where the entries are defined in their corresponding lists.
+Again this can be done by redefining the general purpose
+non-category post-name hook \ics{glsextrapostnamehook}:
+\begin{codeenv}
+\cs{newcommand}*\marg{\cs{glsextrapostnamehook}}[1]\marg{\comment{}
+ \cs{glsadd}\oarg{\glsaddopt[\encap{hyperbf}]{format}}\marg{\idx{param}1}\comment{}
+}
+\end{codeenv}
+This needs resetting before the index, since it's redundant to
+record an entry in the index. This will require an extra
+\bibgls+\LaTeX\ system call as this code can't be performed until
+the glossaries have been created.
+
+The complete document code is listed below. The document build is:
+\begin{verbatim}
+pdflatex sample-multi2
+bib2gls --group --break-space sample-multi2
+pdflatex sample-multi2
+bib2gls --group --break-space sample-multi2
+pdflatex sample-multi2
+\end{verbatim}
+The resulting document is shown in \figureref{fig:sample-multi2.pdf},
+\figureref{fig:sample-multi2.pdf2} and \figureref{fig:sample-multi2.pdf3}.
+
+\lstinputlisting[firstline=5]{../examples/sample-multi2.tex}
+
+\begin{figure}
+\figcontents
+{\pdftwocol{../examples/sample-multi2.pdf}{4}}
+{\caption{\filefmt{sample-multi2.pdf} (pages~1 to~4)}}
+{fig:sample-multi2.pdf}
+\end{figure}
+
+\begin{figure}
+\figcontents
+{\pdftwocol[5]{../examples/sample-multi2.pdf}{8}}
+{\caption{\filefmt{sample-multi2.pdf} (pages~5 to 8)}}
+{fig:sample-multi2.pdf2}
+\end{figure}
+
+\begin{figure}
+\figcontents
+{\pdftwocol[9]{../examples/sample-multi2.pdf}{12}}
+{\caption{\filefmt{sample-multi2.pdf} (pages~9 and 12)}}
+{fig:sample-multi2.pdf3}
+\end{figure}
+
+\printstyoptsummary
+\printcommandsummary
+%\printcommandtopic
+
+\bibliographystyle{plain}
+\bibliography{bib2gls-cite}
+
+\renewcommand*{\glsxtrbookindexsubname}[1]{%
+ \glsifcategory{#1}{command}%
+ {%
+ \glsxtrifhasfield{useri}{#1}%
+ {\glossentrynameother{#1}{useri}}%
+ {\glossentryname{#1}}%
+ }%
+ {\glossentryname{#1}}%
+}
+\renewcommand*{\glsxtrbookindexprelocation}[1]{%
+ \glsxtrifhasfield{location}{#1}%
+ {\nobreak\cleaders\hbox to .44em{\hss\textcolor{lightgray}{.}\hss}\hfill}%
+ {\glsxtrprelocation}%
+}
+\renewcommand{\printunsrtglossaryentryprocesshook}[1]{%
+ \glsxtrifhasfield*{progenitor}{#1}{\printunsrtglossaryskipentry}{}%
+}
+\renewcommand*{\unicodecategoryfmt}[1]{\textsf{#1}}
+\printunsrtglossary[type=index]
+\end{document}